@kouji-ui/core 0.0.4 → 0.1.1

package/src/spinner/spinner.spec.ts

@@ -0,0 +1,262 @@
+import { render } from '@testing-library/angular';
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import { KjSpinner } from './spinner';
+
+/**
+ * Flush microtasks + the rAF that backs `afterNextRender` so the directive
+ * has a chance to read host attributes and the `prefers-reduced-motion`
+ * media query.
+ */
+async function flushAfterNextRender(): Promise<void> {
+  await new Promise<void>((resolve) => setTimeout(resolve, 0));
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+/**
+ * Stub `window.matchMedia` for a deterministic `prefers-reduced-motion`
+ * value during a test. Returns the listener registered by the directive so
+ * the test can simulate a runtime change of the user preference.
+ */
+function stubMatchMedia(initial: boolean): {
+  fire: (matches: boolean) => void;
+  restore: () => void;
+} {
+  const original = window.matchMedia;
+  let listener: ((e: MediaQueryListEvent) => void) | null = null;
+  const mql: Partial<MediaQueryList> = {
+    matches: initial,
+    media: '(prefers-reduced-motion: reduce)',
+    addEventListener: ((_type: string, l: EventListener) => {
+      listener = l as (e: MediaQueryListEvent) => void;
+    }) as MediaQueryList['addEventListener'],
+    removeEventListener: (() => {
+      listener = null;
+    }) as MediaQueryList['removeEventListener'],
+    addListener: () => {},
+    removeListener: () => {},
+    onchange: null,
+    dispatchEvent: () => true,
+  };
+  (window as unknown as { matchMedia: (q: string) => MediaQueryList }).matchMedia = () =>
+    mql as MediaQueryList;
+  return {
+    fire: (matches: boolean) => {
+      (mql as { matches: boolean }).matches = matches;
+      listener?.({ matches } as MediaQueryListEvent);
+    },
+    restore: () => {
+      window.matchMedia = original;
+    },
+  };
+}
+
+describe('KjSpinner', () => {
+  let mm: ReturnType<typeof stubMatchMedia>;
+
+  beforeEach(() => {
+    mm = stubMatchMedia(false);
+  });
+
+  afterEach(() => {
+    mm.restore();
+  });
+
+  describe('a11y contract', () => {
+    it('sets role="status" on the host', async () => {
+      const { container } = await render(`<span kjSpinner></span>`, {
+        imports: [KjSpinner],
+      });
+      await flushAfterNextRender();
+      expect(container.querySelector('span')).toHaveAttribute('role', 'status');
+    });
+
+    it('sets aria-live="polite" and aria-atomic="true"', async () => {
+      const { container } = await render(`<span kjSpinner></span>`, {
+        imports: [KjSpinner],
+      });
+      await flushAfterNextRender();
+      const host = container.querySelector('span')!;
+      expect(host).toHaveAttribute('aria-live', 'polite');
+      expect(host).toHaveAttribute('aria-atomic', 'true');
+    });
+
+    it('applies default aria-label="Loading" when no consumer label is provided', async () => {
+      const { container } = await render(`<span kjSpinner></span>`, {
+        imports: [KjSpinner],
+      });
+      await flushAfterNextRender();
+      expect(container.querySelector('span')).toHaveAttribute('aria-label', 'Loading');
+    });
+
+    it('consumer kjAriaLabel input wins over the default', async () => {
+      const { container } = await render(
+        `<span kjSpinner kjAriaLabel="Sending"></span>`,
+        { imports: [KjSpinner] },
+      );
+      await flushAfterNextRender();
+      expect(container.querySelector('span')).toHaveAttribute('aria-label', 'Sending');
+    });
+
+    it('does not override a consumer-authored aria-label attribute on the host', async () => {
+      const { container } = await render(
+        `<span kjSpinner aria-label="Saving draft"></span>`,
+        { imports: [KjSpinner] },
+      );
+      await flushAfterNextRender();
+      expect(container.querySelector('span')).toHaveAttribute('aria-label', 'Saving draft');
+    });
+
+    it('does not set aria-label when host carries aria-labelledby', async () => {
+      const { container } = await render(
+        `<span id="lbl">Loading users</span>
+         <span kjSpinner aria-labelledby="lbl"></span>`,
+        { imports: [KjSpinner] },
+      );
+      await flushAfterNextRender();
+      const host = container.querySelector('span[kjSpinner]')!;
+      expect(host).not.toHaveAttribute('aria-label');
+      expect(host).toHaveAttribute('aria-labelledby', 'lbl');
+    });
+  });
+
+  describe('data-animation reflection', () => {
+    it('defaults to data-animation="spin"', async () => {
+      const { container } = await render(`<span kjSpinner></span>`, {
+        imports: [KjSpinner],
+      });
+      await flushAfterNextRender();
+      expect(container.querySelector('span')).toHaveAttribute('data-animation', 'spin');
+    });
+
+    it('reflects kjAnimation="dots"', async () => {
+      const { container } = await render(
+        `<span kjSpinner kjAnimation="dots"></span>`,
+        { imports: [KjSpinner] },
+      );
+      await flushAfterNextRender();
+      expect(container.querySelector('span')).toHaveAttribute('data-animation', 'dots');
+    });
+
+    it('reflects kjAnimation="pulse"', async () => {
+      const { container } = await render(
+        `<span kjSpinner kjAnimation="pulse"></span>`,
+        { imports: [KjSpinner] },
+      );
+      await flushAfterNextRender();
+      expect(container.querySelector('span')).toHaveAttribute('data-animation', 'pulse');
+    });
+
+    it('reflects kjAnimation="bars"', async () => {
+      const { container } = await render(
+        `<span kjSpinner kjAnimation="bars"></span>`,
+        { imports: [KjSpinner] },
+      );
+      await flushAfterNextRender();
+      expect(container.querySelector('span')).toHaveAttribute('data-animation', 'bars');
+    });
+  });
+
+  describe('data-reduced-motion mirrors prefers-reduced-motion', () => {
+    it('omits data-reduced-motion when the user preference is not set', async () => {
+      const { container } = await render(`<span kjSpinner></span>`, {
+        imports: [KjSpinner],
+      });
+      await flushAfterNextRender();
+      expect(container.querySelector('span')).not.toHaveAttribute('data-reduced-motion');
+    });
+
+    it('reflects data-reduced-motion="true" when the media query matches at mount', async () => {
+      mm.restore();
+      mm = stubMatchMedia(true);
+      const { container } = await render(`<span kjSpinner></span>`, {
+        imports: [KjSpinner],
+      });
+      await flushAfterNextRender();
+      expect(container.querySelector('span')).toHaveAttribute('data-reduced-motion', 'true');
+    });
+
+    it('updates data-reduced-motion when the media query changes at runtime', async () => {
+      const { container, fixture } = await render(`<span kjSpinner></span>`, {
+        imports: [KjSpinner],
+      });
+      await flushAfterNextRender();
+      const host = container.querySelector('span')!;
+      expect(host).not.toHaveAttribute('data-reduced-motion');
+
+      mm.fire(true);
+      fixture.detectChanges();
+      expect(host).toHaveAttribute('data-reduced-motion', 'true');
+
+      mm.fire(false);
+      fixture.detectChanges();
+      expect(host).not.toHaveAttribute('data-reduced-motion');
+    });
+
+    it('does not throw when window.matchMedia is unavailable (SSR-style)', async () => {
+      mm.restore();
+      const original = window.matchMedia;
+      // Simulate non-browser env at the time afterNextRender runs.
+      (window as unknown as { matchMedia: undefined }).matchMedia = undefined;
+      try {
+        const { container } = await render(`<span kjSpinner></span>`, {
+          imports: [KjSpinner],
+        });
+        await flushAfterNextRender();
+        expect(container.querySelector('span')).not.toHaveAttribute('data-reduced-motion');
+      } finally {
+        window.matchMedia = original;
+        mm = stubMatchMedia(false);
+      }
+    });
+  });
+
+  describe('KjVariant + KjSize composition', () => {
+    it('reflects default data-variant="neutral" from KJ_SPINNER_DEFAULTS', async () => {
+      const { container } = await render(`<span kjSpinner></span>`, {
+        imports: [KjSpinner],
+      });
+      await flushAfterNextRender();
+      expect(container.querySelector('span')).toHaveAttribute('data-variant', 'neutral');
+    });
+
+    it('reflects default data-size="md" from KJ_SPINNER_DEFAULTS', async () => {
+      const { container } = await render(`<span kjSpinner></span>`, {
+        imports: [KjSpinner],
+      });
+      await flushAfterNextRender();
+      expect(container.querySelector('span')).toHaveAttribute('data-size', 'md');
+    });
+
+    it('forwards kjVariant input to data-variant (composed via hostDirectives)', async () => {
+      const { container } = await render(
+        `<span kjSpinner kjVariant="primary"></span>`,
+        { imports: [KjSpinner] },
+      );
+      await flushAfterNextRender();
+      expect(container.querySelector('span')).toHaveAttribute('data-variant', 'primary');
+    });
+
+    it('forwards kjSize input to data-size (composed via hostDirectives)', async () => {
+      const { container } = await render(
+        `<span kjSpinner kjSize="xs"></span>`,
+        { imports: [KjSpinner] },
+      );
+      await flushAfterNextRender();
+      expect(container.querySelector('span')).toHaveAttribute('data-size', 'xs');
+    });
+
+    it('warns on unknown variant in dev mode', async () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      try {
+        await render(`<span kjSpinner kjVariant="bogus"></span>`, {
+          imports: [KjSpinner],
+        });
+        await flushAfterNextRender();
+        expect(warn).toHaveBeenCalled();
+      } finally {
+        warn.mockRestore();
+      }
+    });
+  });
+});

package/src/spinner/spinner.ts

@@ -0,0 +1,129 @@
+import {
+  DestroyRef,
+  Directive,
+  ElementRef,
+  afterNextRender,
+  computed,
+  inject,
+  input,
+  signal,
+} from '@angular/core';
+import { KjSize, KjVariant, bindPresets } from '../presets';
+import { KJ_SPINNER_CONFIG, KjSpinnerAnimation } from './config';
+
+/**
+ * Marks an element as a kouji indeterminate spinner. Owns the small
+ * accessibility contract (`role="status"`, default `aria-label="Loading"`,
+ * `prefers-reduced-motion` reflection) and reflects `data-animation`,
+ * `data-variant`, and `data-size` for the theme to render the visual glyph.
+ *
+ * The host element is consumer-supplied — usually a `<span kjSpinner>`. The
+ * directive itself emits no markup; the surrounding wrapper / template is
+ * responsible for the visually-hidden label fallback when no consumer label
+ * is provided. The directive does set `aria-label` to the default when
+ * neither `aria-label` nor `aria-labelledby` is already on the host.
+ *
+ * **Indeterminate-only.** A determinate "x of y" indicator is a Progress
+ * Bar — different role, different ARIA contract; do not bend Spinner to fit.
+ *
+ * @example
+ * ```html
+ * <span kjSpinner></span>
+ * <span kjSpinner kjAnimation="dots" kjAriaLabel="Sending"></span>
+ * ```
+ * @doc-category Core/Feedback
+ * @doc
+ * @doc-name spinner
+ * @doc-description Marks an element as an indeterminate loading indicator with the right accessibility role and label.
+ * @doc-is-main
+ */
+@Directive({
+  selector: '[kjSpinner]',
+  standalone: true,
+  exportAs: 'kjSpinner',
+  hostDirectives: [
+    { directive: KjVariant, inputs: ['kjVariant'] },
+    { directive: KjSize, inputs: ['kjSize'] },
+  ],
+  providers: [...bindPresets(KJ_SPINNER_CONFIG)],
+  host: {
+    role: 'status',
+    'aria-live': 'polite',
+    'aria-atomic': 'true',
+    '[attr.data-animation]': 'kjAnimation()',
+    '[attr.data-reduced-motion]': 'reducedMotion() ? "true" : null',
+    '[attr.aria-label]': 'ariaLabelAttr()',
+  },
+})
+export class KjSpinner {
+  private readonly el = inject<ElementRef<HTMLElement>>(ElementRef);
+  private readonly config = inject(KJ_SPINNER_CONFIG);
+
+  /**
+   * Animation shape preset. Reflects `data-animation`. Default `'spin'`.
+   * Themes own the keyframes for each value.
+   */
+  readonly kjAnimation = input<KjSpinnerAnimation>(
+    (this.config.defaults.animation as KjSpinnerAnimation) ?? 'spin',
+  );
+
+  /**
+   * Accessible name announced by AT. Bound to `aria-label` when the host has
+   * no `aria-label` attribute and no `aria-labelledby` attribute already set
+   * (so a consumer-authored `aria-labelledby` wins, and a consumer-authored
+   * `aria-label` is not double-bound).
+   */
+  readonly kjAriaLabel = input<string>(this.config.defaults.ariaLabel ?? 'Loading');
+
+  /** True when the host had a consumer-authored `aria-labelledby` at mount. */
+  protected readonly hasAriaLabelledBy: boolean;
+
+  /**
+   * Captured value of the consumer-authored `aria-label` HTML attribute at
+   * mount, or `null` if none was set. We re-emit it through the host
+   * binding so Angular doesn't strip the original (a host `[attr.aria-label]`
+   * binding always wins over the static attribute, so leaving the binding
+   * unconditional but echoing the captured value preserves the consumer
+   * intent).
+   */
+  protected readonly nativeAriaLabel: string | null;
+
+  /**
+   * Reflects the user's `prefers-reduced-motion` preference. The directive
+   * does not animate anything itself — it mirrors the boolean as
+   * `data-reduced-motion="true"` and themes own the alternate keyframe.
+   */
+  protected readonly reducedMotion = signal<boolean>(false);
+
+  protected readonly ariaLabelAttr = computed(() => {
+    if (this.hasAriaLabelledBy) return null;
+    if (this.nativeAriaLabel !== null) return this.nativeAriaLabel;
+    return this.kjAriaLabel();
+  });
+
+  constructor() {
+    const destroyRef = inject(DestroyRef);
+
+    // Read consumer-authored aria attributes synchronously in the
+    // constructor — by the time `afterNextRender` runs, Angular's host
+    // binding for `[attr.aria-label]` has already overwritten the original
+    // attribute with the computed default, which would make the detection
+    // see kouji's own value and ignore the consumer's.
+    const host = this.el.nativeElement;
+    this.hasAriaLabelledBy = host.hasAttribute('aria-labelledby');
+    this.nativeAriaLabel = host.getAttribute('aria-label');
+
+    afterNextRender(() => {
+      // SSR-safe: matchMedia is only present in a real browser. The
+      // server-rendered HTML carries no `data-reduced-motion`; the post-
+      // hydrate read sets it on the client when the preference is active.
+      if (typeof window !== 'undefined' && typeof window.matchMedia === 'function') {
+        const mql = window.matchMedia('(prefers-reduced-motion: reduce)');
+        this.reducedMotion.set(mql.matches);
+        const onChange = (e: MediaQueryListEvent) => this.reducedMotion.set(e.matches);
+        mql.addEventListener('change', onChange);
+        destroyRef.onDestroy(() => mql.removeEventListener('change', onChange));
+      }
+    });
+  }
+}

package/src/stepper/index.ts

@@ -0,0 +1,15 @@
+export {
+  KjStepper,
+  KjStep,
+  KjStepLabel,
+  KjStepContent,
+  KjStepperNext,
+  KjStepperPrevious,
+  KjStepperReset,
+} from './stepper';
+export {
+  KJ_STEPPER,
+  KJ_STEP,
+  type KjStepperContext,
+  type KjStepContext,
+} from './stepper.context';

package/src/stepper/stepper.context.ts

@@ -0,0 +1,63 @@
+import { InjectionToken, Signal } from '@angular/core';
+
+/** Per-step context exposed to `KjStepLabel` and `KjStepContent`. */
+export interface KjStepContext {
+  /** 0-based index in the parent stepper's step set. */
+  readonly index: Signal<number>;
+  /** True when this step is the active one. */
+  readonly active: Signal<boolean>;
+  /** True when this step has been completed (consumer-set via `kjStepCompleted`). */
+  readonly completed: Signal<boolean>;
+  /** True when this step is in an error state (consumer-set via `kjStepError`). */
+  readonly error: Signal<boolean>;
+  /** True when this step is optional (does not gate linear advancement). */
+  readonly optional: Signal<boolean>;
+  /** True when this step is reachable in the current mode. */
+  readonly reachable: Signal<boolean>;
+  /** True when this step is explicitly disabled by the consumer. */
+  readonly disabled: Signal<boolean>;
+  /** Optional consumer-supplied semantic key, used by `goToKey()`. */
+  readonly key: Signal<string | undefined>;
+  /** Stable id for `aria-labelledby` wiring. */
+  readonly labelId: Signal<string>;
+  /** Stable id for the content region. */
+  readonly contentId: Signal<string>;
+  /** Activate this step (subject to linear-mode gating). */
+  activate(): void;
+}
+
+/** Stepper-root context exposed to step / label / content / command directives. */
+export interface KjStepperContext {
+  /** Active step index (0-based). */
+  readonly activeStep: Signal<number>;
+  /** Total number of registered steps. */
+  readonly totalSteps: Signal<number>;
+  /** @internal — read-only view of registered steps in registration order. */
+  readonly steps: Signal<readonly KjStepContext[]>;
+  /** Linear-mode flag. */
+  readonly linear: Signal<boolean>;
+  /** Orientation. */
+  readonly orientation: Signal<'horizontal' | 'vertical'>;
+  /** True when `next()` will succeed. */
+  readonly canAdvance: Signal<boolean>;
+  /** True when `previous()` will succeed. */
+  readonly canRetreat: Signal<boolean>;
+  /** Imperative navigation. */
+  next(): void;
+  previous(): void;
+  goTo(index: number): void;
+  goToKey(key: string): void;
+  reset(): void;
+  /** @internal — `KjStep` registers / unregisters here. */
+  register(step: KjStepContext): void;
+  /** @internal */
+  unregister(step: KjStepContext): void;
+  /** @internal — `KjStep` reports its reachability under linear gating. */
+  isReachable(index: number): boolean;
+}
+
+/** Injection token for the root stepper directive. */
+export const KJ_STEPPER = new InjectionToken<KjStepperContext>('KjStepper');
+
+/** Injection token for an individual step directive. */
+export const KJ_STEP = new InjectionToken<KjStepContext>('KjStep');