feat(design): create DaffSpinnerComponent to replace DaffLoadingIconComponent (#4316)

xelaint · web-flow · commit 4a14372b705b · 2026-02-03T12:10:01.000-05:00
diff --git a/libs/design-examples/spinner/ng-package.json b/libs/design-examples/spinner/ng-package.json
@@ -0,0 +1,7 @@
+{
+  "$schema": "../../../node_modules/ng-packagr/ng-entrypoint.schema.json",
+  "lib": {
+    "entryFile": "src/index.ts",
+    "styleIncludePaths": ["../../src/scss"]
+  }
+} 
diff --git a/libs/design-examples/spinner/src/examples.ts b/libs/design-examples/spinner/src/examples.ts
@@ -0,0 +1,9 @@
+import { SpinnerColorsExampleComponent } from './spinner-colors/spinner-colors.component';
+import { SpinnerSizesExampleComponent } from './spinner-sizes/spinner-sizes.component';
+import { SpinnerWithLabelExampleComponent } from './spinner-with-label/spinner-with-label.component';
+
+export const SPINNER_EXAMPLES = [
+  SpinnerColorsExampleComponent,
+  SpinnerSizesExampleComponent,
+  SpinnerWithLabelExampleComponent,
+];
diff --git a/libs/design-examples/spinner/src/index.ts b/libs/design-examples/spinner/src/index.ts
@@ -0,0 +1 @@
+export * from './public_api';
diff --git a/libs/design-examples/spinner/src/public_api.ts b/libs/design-examples/spinner/src/public_api.ts
@@ -0,0 +1,4 @@
+export { SPINNER_EXAMPLES } from './examples';
+export { SpinnerColorsExampleComponent } from './spinner-colors/spinner-colors.component';
+export { SpinnerSizesExampleComponent } from './spinner-sizes/spinner-sizes.component';
+export { SpinnerWithLabelExampleComponent } from './spinner-with-label/spinner-with-label.component';
diff --git a/libs/design-examples/spinner/src/spinner-colors/spinner-colors.component.html b/libs/design-examples/spinner/src/spinner-colors/spinner-colors.component.html
@@ -0,0 +1,12 @@
+<daff-spinner [color]="colorControl.value"></daff-spinner>
+
+<select [formControl]="colorControl">
+	<option value="">Default</option>
+	<option value="primary">Primary</option>
+	<option value="secondary">Secondary</option>
+	<option value="tertiary">Tertiary</option>
+	<option value="theme">Theme</option>
+	<option value="theme-contrast">Theme Contrast</option>
+	<option value="light">Light</option>
+	<option value="dark">Dark</option>
+</select>
diff --git a/libs/design-examples/spinner/src/spinner-colors/spinner-colors.component.ts b/libs/design-examples/spinner/src/spinner-colors/spinner-colors.component.ts
@@ -0,0 +1,33 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+} from '@angular/core';
+import {
+  FormControl,
+  ReactiveFormsModule,
+} from '@angular/forms';
+
+import { DaffPalette } from '@daffodil/design';
+import { DAFF_SPINNER_COMPONENTS } from '@daffodil/design/spinner';
+
+@Component({
+  selector: 'spinner-colors-example',
+  templateUrl: './spinner-colors.component.html',
+  styles: [`
+    :host {
+      display: flex;
+      flex-direction: column;
+      align-items: flex-start;
+      gap: 1rem;
+    }`],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [
+    DAFF_SPINNER_COMPONENTS,
+    ReactiveFormsModule,
+  ],
+})
+export class SpinnerColorsExampleComponent {
+  color: DaffPalette = 'primary';
+
+  colorControl: FormControl = new FormControl('');
+}
diff --git a/libs/design-examples/spinner/src/spinner-sizes/spinner-sizes.component.html b/libs/design-examples/spinner/src/spinner-sizes/spinner-sizes.component.html
@@ -0,0 +1,10 @@
+<daff-spinner [size]="sizeControl.value"></daff-spinner>
+
+<select [formControl]="sizeControl">
+	<option value="">Default</option>
+	<option value="xs">Extra small</option>
+	<option value="sm">Small</option>
+	<option value="md">Medium</option>
+	<option value="lg">Large</option>
+	<option value="xl">Extra large</option>
+</select>
diff --git a/libs/design-examples/spinner/src/spinner-sizes/spinner-sizes.component.ts b/libs/design-examples/spinner/src/spinner-sizes/spinner-sizes.component.ts
@@ -0,0 +1,30 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+} from '@angular/core';
+import {
+  FormControl,
+  ReactiveFormsModule,
+} from '@angular/forms';
+
+import { DAFF_SPINNER_COMPONENTS } from '@daffodil/design/spinner';
+
+@Component({
+  selector: 'spinner-sizes-example',
+  templateUrl: './spinner-sizes.component.html',
+  styles: [`
+    :host {
+      display: flex;
+      flex-direction: column;
+      align-items: flex-start;
+      gap: 1rem;
+    }`],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [
+    DAFF_SPINNER_COMPONENTS,
+    ReactiveFormsModule,
+  ],
+})
+export class SpinnerSizesExampleComponent {
+  sizeControl: FormControl = new FormControl('');
+}
diff --git a/libs/design-examples/spinner/src/spinner-with-label/spinner-with-label.component.html b/libs/design-examples/spinner/src/spinner-with-label/spinner-with-label.component.html
@@ -0,0 +1,3 @@
+<daff-spinner>
+	<daff-spinner-label>Test</daff-spinner-label>
+</daff-spinner>
diff --git a/libs/design-examples/spinner/src/spinner-with-label/spinner-with-label.component.ts b/libs/design-examples/spinner/src/spinner-with-label/spinner-with-label.component.ts
@@ -0,0 +1,18 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+} from '@angular/core';
+import { ReactiveFormsModule } from '@angular/forms';
+
+import { DAFF_SPINNER_COMPONENTS } from '@daffodil/design/spinner';
+
+@Component({
+  selector: 'spinner-with-label-example',
+  templateUrl: './spinner-with-label.component.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [
+    DAFF_SPINNER_COMPONENTS,
+    ReactiveFormsModule,
+  ],
+})
+export class SpinnerWithLabelExampleComponent {}
diff --git a/libs/design-examples/tsconfig.json b/libs/design-examples/tsconfig.json
@@ -85,6 +85,9 @@
       "@daffodil/design-examples/select": [
         "libs/design-examples/select/src"
       ],
+      "@daffodil/design-examples/spinner": [
+        "libs/design-examples/spinner/src"
+      ],
       "@daffodil/design-examples/sidebar": [
         "libs/design-examples/sidebar/src"
       ],
diff --git a/libs/design/loading-icon/src/loading-icon/loading-icon.component.ts b/libs/design/loading-icon/src/loading-icon/loading-icon.component.ts
@@ -7,7 +7,7 @@ import {
 import { DaffColorableDirective } from '@daffodil/design';
 
 /**
- * @inheritdoc
+ * @deprecated in favor of `DaffSpinnerComponent`. Deprecated in version 0.91.1. Will be removed in version 0.94.0.
  */
 @Component({
   selector: 'daff-loading-icon',
diff --git a/libs/design/scss/theme.scss b/libs/design/scss/theme.scss
@@ -46,6 +46,7 @@
 @use '../paginator/src/paginator-theme' as paginator;
 @use '../select/src/select-theme' as select;
 @use '../sidebar/src/sidebar-theme' as sidebar;
+@use '../spinner/src/spinner-theme' as spinner;
 @use '../switch/src/switch-theme' as switch;
 @use '../progress-bar/src/progress-bar-theme' as progress-bar;
 @use '../scss/state/skeleton/mixins' as skeleton;
@@ -91,15 +92,18 @@
 	@include select.daff-select-theme($theme);
 	@include native-select.daff-native-select-theme($theme);
 
-	@include loading-icon.daff-loading-icon-theme($theme);
+	@include spinner.daff-spinner-theme($theme);
 	@include progress-bar.daff-progress-bar-theme($theme);
 
 	@include accordion.daff-accordion-theme($theme);
 	@include article.daff-article-theme($theme);
 	@include callout.daff-callout-theme($theme);
 	@include hero.daff-hero-theme($theme);
 	@include list.daff-list-theme($theme);
+
+	// deprecated
 	@include loading-icon.daff-loading-icon-theme($theme);
+
 	@include media-gallery.daff-media-gallery-theme($theme);
 	@include menu.daff-menu-theme($theme);
 	@include modal.daff-modal-theme($theme);
diff --git a/libs/design/spinner/README.md b/libs/design/spinner/README.md
@@ -0,0 +1,57 @@
+# Spinner
+A spinner is an animated indicator that lets users know content or action is being loaded.
+
+## Overview
+Use a spinner to indicate a short, indeterminate loading state. It can appear on its own or paired with a loading message. For longer processes with measurable progress, use the [progress bar](/libs/design/progress-bar/README.md) component.
+
+## Usage
+To use spinner, import `DAFF_SPINNER_COMPONENTS` directly into your custom component:
+
+```ts
+import { DAFF_SPINNER_COMPONENTS } from '@daffodil/design/spinner';
+
+@Component({
+  selector: 'custom-component',
+  templateUrl: './custom-component.component.html',
+  imports: [
+    DAFF_SPINNER_COMPONENTS,
+  ],
+})
+export class CustomComponent {}
+```
+
+## Anatomy
+
+### Label
+Labels are used to describe the loading state and provide context for users. They are optional.
+
+```html
+<daff-spinner>
+  <daff-spinner-label>Loading products...</daff-spinner-label>
+</daff-spinner>
+```
+
+<design-land-example-viewer-container example="spinner-with-label"></design-land-example-viewer-container>
+
+## Features
+
+### Colors
+Use the `color` property to change the color of a spinner.
+
+> Note: `dark`, `light`, and `theme` should be used on appropriate backgrounds for sufficient contrast.
+
+<design-land-example-viewer-container example="spinner-colors"></design-land-example-viewer-container>
+
+### Sizes
+Use the `size` proeprty to change the size of a spinner. The default size is `md`.
+
+<design-land-example-viewer-container example="spinner-sizes"></design-land-example-viewer-container>
+
+## Accessibility
+The spinner has `role="status"` which announces content changes to assistive technologies.
+
+When using `<daff-spinner-label>`, the visible text serves as the accessible name. When no label is provided, the spinner defaults to `aria-label="loading"`. You can customize this with the `aria-label` input:
+
+```html
+<daff-spinner aria-label="Saving changes"></daff-spinner>
+```
diff --git a/libs/design/spinner/ng-package.json b/libs/design/spinner/ng-package.json
@@ -0,0 +1,7 @@
+{
+  "$schema": "../../../node_modules/ng-packagr/ng-entrypoint.schema.json",
+  "lib": {
+    "entryFile": "src/index.ts",
+    "styleIncludePaths": ["../src/scss"]
+  }
+}
diff --git a/libs/design/spinner/src/index.ts b/libs/design/spinner/src/index.ts
@@ -0,0 +1 @@
+export * from './public_api';
diff --git a/libs/design/spinner/src/public_api.ts b/libs/design/spinner/src/public_api.ts
@@ -0,0 +1,3 @@
+export { DaffSpinnerComponent } from './spinner.component';
+export { DaffSpinnerLabelDirective } from './spinner-label/spinner-label.directive';
+export { DAFF_SPINNER_COMPONENTS } from './spinner';
diff --git a/libs/design/spinner/src/specs/usage.spec.ts b/libs/design/spinner/src/specs/usage.spec.ts
@@ -0,0 +1,88 @@
+import {
+  Component,
+  DebugElement,
+} from '@angular/core';
+import {
+  waitForAsync,
+  ComponentFixture,
+  TestBed,
+} from '@angular/core/testing';
+import { By } from '@angular/platform-browser';
+
+import {
+  DAFF_SPINNER_COMPONENTS,
+  DaffSpinnerComponent,
+} from '@daffodil/design/spinner';
+
+@Component({
+  template: '<daff-spinner [aria-label]="ariaLabel"></daff-spinner>',
+  imports: [
+    DaffSpinnerComponent,
+  ],
+})
+class WrapperComponent {
+  ariaLabel: string;
+}
+
+describe('@daffodil/design/spinner | DaffSpinnerComponent | Without DaffSpinnerLabelDirective', () => {
+  let wrapper: WrapperComponent;
+  let de: DebugElement;
+  let fixture: ComponentFixture<WrapperComponent>;
+
+  beforeEach(waitForAsync(() => {
+    TestBed.configureTestingModule({
+      imports: [
+        WrapperComponent,
+      ],
+    })
+      .compileComponents();
+  }));
+
+  beforeEach(() => {
+    fixture = TestBed.createComponent(WrapperComponent);
+    wrapper = fixture.componentInstance;
+    de = fixture.debugElement.query(By.css('daff-spinner'));
+    fixture.detectChanges();
+  });
+
+  it('should set the aria-label attribute to the provided value', () => {
+    wrapper.ariaLabel = 'custom loading message';
+    fixture.detectChanges();
+
+    expect(de.nativeElement.getAttribute('aria-label')).toEqual('custom loading message');
+  });
+});
+
+@Component({
+  template: `<daff-spinner>
+    <daff-spinner-label>Loading content</daff-spinner-label>
+  </daff-spinner>`,
+  imports: [
+    DAFF_SPINNER_COMPONENTS,
+  ],
+})
+class WithLabelWrapperComponent {}
+
+describe('@daffodil/design/spinner | DaffSpinnerComponent | With DaffSpinnerLabelDirective', () => {
+  let de: DebugElement;
+  let fixture: ComponentFixture<WithLabelWrapperComponent>;
+
+  beforeEach(waitForAsync(() => {
+    TestBed.configureTestingModule({
+      imports: [
+        WithLabelWrapperComponent,
+      ],
+    })
+      .compileComponents();
+  }));
+
+  beforeEach(() => {
+    fixture = TestBed.createComponent(WithLabelWrapperComponent);
+    de = fixture.debugElement.query(By.css('daff-spinner'));
+    fixture.detectChanges();
+  });
+
+  it('should not set the aria-label attribute when the <daff-spinner-label> is used', () => {
+    expect(de.nativeElement.getAttribute('aria-label')).toBeNull();
+  });
+});
diff --git a/libs/design/spinner/src/spinner-label/spinner-label.directive.spec.ts b/libs/design/spinner/src/spinner-label/spinner-label.directive.spec.ts
@@ -0,0 +1,47 @@
+import {
+  Component,
+  DebugElement,
+} from '@angular/core';
+import {
+  waitForAsync,
+  ComponentFixture,
+  TestBed,
+} from '@angular/core/testing';
+import { By } from '@angular/platform-browser';
+
+import { DaffSpinnerLabelDirective } from './spinner-label.directive';
+
+@Component({
+  template: `<daff-spinner-label>Label</daff-spinner-label>`,
+  imports: [
+    DaffSpinnerLabelDirective,
+  ],
+})
+
+class WrapperComponent {}
+
+describe('@daffodil/design/spinner | DaffSpinnerLabelDirective', () => {
+  let wrapper: WrapperComponent;
+  let de: DebugElement;
+  let fixture: ComponentFixture<WrapperComponent>;
+
+  beforeEach(waitForAsync(() => {
+    TestBed.configureTestingModule({
+      imports: [
+        WrapperComponent,
+      ],
+    })
+      .compileComponents();
+  }));
+
+  beforeEach(() => {
+    fixture = TestBed.createComponent(WrapperComponent);
+    wrapper = fixture.componentInstance;
+    de = fixture.debugElement.query(By.css('daff-spinner-label'));
+    fixture.detectChanges();
+  });
+
+  it('should create', () => {
+    expect(wrapper).toBeTruthy();
+  });
+});
diff --git a/libs/design/spinner/src/spinner-label/spinner-label.directive.ts b/libs/design/spinner/src/spinner-label/spinner-label.directive.ts
diff --git a/libs/design/spinner/src/spinner-theme.scss b/libs/design/spinner/src/spinner-theme.scss
diff --git a/libs/design/spinner/src/spinner.component.html b/libs/design/spinner/src/spinner.component.html
diff --git a/libs/design/spinner/src/spinner.component.scss b/libs/design/spinner/src/spinner.component.scss
diff --git a/libs/design/spinner/src/spinner.component.spec.ts b/libs/design/spinner/src/spinner.component.spec.ts
diff --git a/libs/design/spinner/src/spinner.component.ts b/libs/design/spinner/src/spinner.component.ts
diff --git a/libs/design/spinner/src/spinner.ts b/libs/design/spinner/src/spinner.ts
diff --git a/libs/design/tsconfig.json b/libs/design/tsconfig.json

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+<daff-spinner>`
	`2`	`+ <daff-spinner-label>Test</daff-spinner-label>`
	`3`	`+</daff-spinner>`