@kouji-ui/core 0.0.4 → 0.1.1

package/src/progress-bar/progress-bar.spec.ts

@@ -0,0 +1,423 @@
+import { Component, signal } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { render } from '@testing-library/angular';
+import { axe, toHaveNoViolations } from 'jest-axe';
+import { describe, expect, it, vi } from 'vitest';
+
+import { KjProgressBar } from './progress-bar';
+import { KjProgressBarFill } from './progress-bar-fill';
+import { provideKjProgressBar } from './config';
+
+expect.extend(toHaveNoViolations);
+
+const imports = [KjProgressBar, KjProgressBarFill];
+
+/**
+ * Flush microtasks + the rAF that backs `afterNextRender` so the directive
+ * has a chance to subscribe to the reduced-motion media query.
+ */
+async function flush(): Promise<void> {
+  await new Promise<void>((resolve) => setTimeout(resolve, 0));
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+describe('KjProgressBar', () => {
+  describe('determinate mode', () => {
+    it('sets aria-valuenow from kjValue', async () => {
+      const { container } = await render(
+        `<div kjProgressBar [kjValue]="42" aria-label="Upload"></div>`,
+        { imports },
+      );
+      await flush();
+      const host = container.querySelector('[kjProgressBar]')!;
+      expect(host).toHaveAttribute('aria-valuenow', '42');
+    });
+
+    it('rounds aria-valuenow so sub-integer jitter does not churn the attribute', async () => {
+      const { container } = await render(
+        `<div kjProgressBar [kjValue]="47.4" aria-label="Upload"></div>`,
+        { imports },
+      );
+      await flush();
+      const host = container.querySelector('[kjProgressBar]')!;
+      expect(host).toHaveAttribute('aria-valuenow', '47');
+    });
+
+    it('sets role="progressbar" on the host', async () => {
+      const { container } = await render(
+        `<div kjProgressBar [kjValue]="50" aria-label="Upload"></div>`,
+        { imports },
+      );
+      await flush();
+      expect(container.querySelector('[kjProgressBar]')).toHaveAttribute(
+        'role',
+        'progressbar',
+      );
+    });
+
+    it('omits data-indeterminate when value is a number', async () => {
+      const { container } = await render(
+        `<div kjProgressBar [kjValue]="20" aria-label="x"></div>`,
+        { imports },
+      );
+      await flush();
+      expect(
+        container.querySelector('[kjProgressBar]'),
+      ).not.toHaveAttribute('data-indeterminate');
+    });
+  });
+
+  describe('indeterminate mode', () => {
+    it('omits aria-valuenow when kjValue is null', async () => {
+      const { container } = await render(
+        `<div kjProgressBar [kjValue]="null" aria-label="Loading"></div>`,
+        { imports },
+      );
+      await flush();
+      const host = container.querySelector('[kjProgressBar]')!;
+      // APG-correct: indeterminate must NOT carry aria-valuenow at all.
+      expect(host.hasAttribute('aria-valuenow')).toBe(false);
+    });
+
+    it('omits aria-valuenow by default (kjValue defaults to null)', async () => {
+      const { container } = await render(
+        `<div kjProgressBar aria-label="Loading"></div>`,
+        { imports },
+      );
+      await flush();
+      const host = container.querySelector('[kjProgressBar]')!;
+      expect(host.hasAttribute('aria-valuenow')).toBe(false);
+    });
+
+    it('reflects data-indeterminate="true" when kjValue is null', async () => {
+      const { container } = await render(
+        `<div kjProgressBar [kjValue]="null" aria-label="Loading"></div>`,
+        { imports },
+      );
+      await flush();
+      expect(container.querySelector('[kjProgressBar]')).toHaveAttribute(
+        'data-indeterminate',
+        'true',
+      );
+    });
+
+    it('still emits aria-valuemin and aria-valuemax', async () => {
+      const { container } = await render(
+        `<div kjProgressBar [kjValue]="null" aria-label="Loading"></div>`,
+        { imports },
+      );
+      await flush();
+      const host = container.querySelector('[kjProgressBar]')!;
+      expect(host).toHaveAttribute('aria-valuemin', '0');
+      expect(host).toHaveAttribute('aria-valuemax', '100');
+    });
+  });
+
+  describe('min / max defaults & overrides', () => {
+    it('defaults aria-valuemin to 0 and aria-valuemax to 100', async () => {
+      const { container } = await render(
+        `<div kjProgressBar [kjValue]="50" aria-label="x"></div>`,
+        { imports },
+      );
+      await flush();
+      const host = container.querySelector('[kjProgressBar]')!;
+      expect(host).toHaveAttribute('aria-valuemin', '0');
+      expect(host).toHaveAttribute('aria-valuemax', '100');
+    });
+
+    it('reflects custom min / max for absolute units', async () => {
+      const { container } = await render(
+        `<div kjProgressBar [kjMin]="0" [kjMax]="2500000" [kjValue]="1200000" aria-label="bytes"></div>`,
+        { imports },
+      );
+      await flush();
+      const host = container.querySelector('[kjProgressBar]')!;
+      expect(host).toHaveAttribute('aria-valuemin', '0');
+      expect(host).toHaveAttribute('aria-valuemax', '2500000');
+      expect(host).toHaveAttribute('aria-valuenow', '1200000');
+    });
+  });
+
+  describe('clamping out-of-range values', () => {
+    it('clamps below kjMin', async () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const { container } = await render(
+        `<div kjProgressBar [kjValue]="-20" aria-label="x"></div>`,
+        { imports },
+      );
+      await flush();
+      const host = container.querySelector('[kjProgressBar]')!;
+      expect(host).toHaveAttribute('aria-valuenow', '0');
+      warn.mockRestore();
+    });
+
+    it('clamps above kjMax', async () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const { container } = await render(
+        `<div kjProgressBar [kjValue]="150" aria-label="x"></div>`,
+        { imports },
+      );
+      await flush();
+      const host = container.querySelector('[kjProgressBar]')!;
+      expect(host).toHaveAttribute('aria-valuenow', '100');
+      warn.mockRestore();
+    });
+
+    it('clamps within custom min / max', async () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const { container } = await render(
+        `<div kjProgressBar [kjMin]="10" [kjMax]="20" [kjValue]="5" aria-label="x"></div>`,
+        { imports },
+      );
+      await flush();
+      const host = container.querySelector('[kjProgressBar]')!;
+      expect(host).toHaveAttribute('aria-valuenow', '10');
+      warn.mockRestore();
+    });
+  });
+
+  describe('aria-valuetext', () => {
+    it('reflects kjAriaValuetext when set', async () => {
+      const { container } = await render(
+        `<div kjProgressBar [kjValue]="60" kjAriaValuetext="Step 3 of 5" aria-label="x"></div>`,
+        { imports },
+      );
+      await flush();
+      const host = container.querySelector('[kjProgressBar]')!;
+      expect(host).toHaveAttribute('aria-valuetext', 'Step 3 of 5');
+      // Visual fraction is still 60% even though SR reads the phrasing.
+      expect(host).toHaveAttribute('aria-valuenow', '60');
+    });
+
+    it('omits aria-valuetext when not set', async () => {
+      const { container } = await render(
+        `<div kjProgressBar [kjValue]="60" aria-label="x"></div>`,
+        { imports },
+      );
+      await flush();
+      const host = container.querySelector('[kjProgressBar]')!;
+      expect(host.hasAttribute('aria-valuetext')).toBe(false);
+    });
+  });
+
+  describe('variant + size composition (KjVariant / KjSize)', () => {
+    it('reflects default data-variant from KJ_PROGRESS_BAR_DEFAULTS (primary)', async () => {
+      const { container } = await render(
+        `<div kjProgressBar [kjValue]="50" aria-label="x"></div>`,
+        { imports },
+      );
+      await flush();
+      expect(container.querySelector('[kjProgressBar]')).toHaveAttribute(
+        'data-variant',
+        'primary',
+      );
+    });
+
+    it('reflects default data-size from KJ_PROGRESS_BAR_DEFAULTS (md)', async () => {
+      const { container } = await render(
+        `<div kjProgressBar [kjValue]="50" aria-label="x"></div>`,
+        { imports },
+      );
+      await flush();
+      expect(container.querySelector('[kjProgressBar]')).toHaveAttribute(
+        'data-size',
+        'md',
+      );
+    });
+
+    it('forwards kjVariant via hostDirectives', async () => {
+      const { container } = await render(
+        `<div kjProgressBar [kjValue]="50" [kjVariant]="'success'" aria-label="x"></div>`,
+        { imports },
+      );
+      await flush();
+      expect(container.querySelector('[kjProgressBar]')).toHaveAttribute(
+        'data-variant',
+        'success',
+      );
+    });
+
+    it('forwards kjSize via hostDirectives', async () => {
+      const { container } = await render(
+        `<div kjProgressBar [kjValue]="50" [kjSize]="'lg'" aria-label="x"></div>`,
+        { imports },
+      );
+      await flush();
+      expect(container.querySelector('[kjProgressBar]')).toHaveAttribute(
+        'data-size',
+        'lg',
+      );
+    });
+
+    it('provideKjProgressBar at TestBed scope flows into directive defaults', async () => {
+      TestBed.configureTestingModule({
+        providers: [
+          provideKjProgressBar({
+            variants: ['primary', 'success', 'warning', 'error', 'brand'],
+            defaults: { variant: 'brand', size: 'lg' },
+          }),
+        ],
+      });
+      const { container } = await render(
+        `<div kjProgressBar [kjValue]="50" aria-label="x"></div>`,
+        { imports },
+      );
+      await flush();
+      const host = container.querySelector('[kjProgressBar]')!;
+      expect(host).toHaveAttribute('data-variant', 'brand');
+      expect(host).toHaveAttribute('data-size', 'lg');
+    });
+  });
+
+  describe('reduced-motion reflection', () => {
+    it('reflects data-reduced-motion="reduce" when matchMedia matches', async () => {
+      const original = window.matchMedia;
+      const listeners = new Set<(e: MediaQueryListEvent) => void>();
+      const mql: Partial<MediaQueryList> = {
+        matches: true,
+        media: '(prefers-reduced-motion: reduce)',
+        addEventListener: ((_t: string, cb: EventListener) => {
+          listeners.add(cb as (e: MediaQueryListEvent) => void);
+        }) as MediaQueryList['addEventListener'],
+        removeEventListener: ((_t: string, cb: EventListener) => {
+          listeners.delete(cb as (e: MediaQueryListEvent) => void);
+        }) as MediaQueryList['removeEventListener'],
+      };
+      window.matchMedia = (() => mql as MediaQueryList) as typeof window.matchMedia;
+
+      try {
+        const { container } = await render(
+          `<div kjProgressBar [kjValue]="50" aria-label="x"></div>`,
+          { imports },
+        );
+        await flush();
+        expect(container.querySelector('[kjProgressBar]')).toHaveAttribute(
+          'data-reduced-motion',
+          'reduce',
+        );
+      } finally {
+        window.matchMedia = original;
+      }
+    });
+
+    it('omits data-reduced-motion when matchMedia does not match', async () => {
+      const original = window.matchMedia;
+      const mql: Partial<MediaQueryList> = {
+        matches: false,
+        media: '(prefers-reduced-motion: reduce)',
+        addEventListener: () => {},
+        removeEventListener: () => {},
+      };
+      window.matchMedia = (() => mql as MediaQueryList) as typeof window.matchMedia;
+
+      try {
+        const { container } = await render(
+          `<div kjProgressBar [kjValue]="50" aria-label="x"></div>`,
+          { imports },
+        );
+        await flush();
+        expect(
+          container.querySelector('[kjProgressBar]'),
+        ).not.toHaveAttribute('data-reduced-motion');
+      } finally {
+        window.matchMedia = original;
+      }
+    });
+  });
+
+  describe('KjProgressBarFill child', () => {
+    it('reflects --kj-progress-fraction from the parent context', async () => {
+      const { container } = await render(
+        `<div kjProgressBar [kjValue]="40" aria-label="x">
+           <div kjProgressBarFill data-testid="fill"></div>
+         </div>`,
+        { imports },
+      );
+      await flush();
+      const fill = container.querySelector('[kjProgressBarFill]') as HTMLElement;
+      // 40 / (100 - 0) = 0.4 — the fill mirrors the parent fraction so themes
+      // can scaleX(var(--kj-progress-fraction)) on the named inner element.
+      expect(fill.style.getPropertyValue('--kj-progress-fraction')).toBe('0.4');
+    });
+
+    it('reflects data-indeterminate on the fill when parent is indeterminate', async () => {
+      const { container } = await render(
+        `<div kjProgressBar [kjValue]="null" aria-label="x">
+           <div kjProgressBarFill></div>
+         </div>`,
+        { imports },
+      );
+      await flush();
+      const fill = container.querySelector('[kjProgressBarFill]') as HTMLElement;
+      expect(fill).toHaveAttribute('data-indeterminate', 'true');
+    });
+
+    it('omits data-indeterminate on the fill in determinate mode', async () => {
+      const { container } = await render(
+        `<div kjProgressBar [kjValue]="50" aria-label="x">
+           <div kjProgressBarFill></div>
+         </div>`,
+        { imports },
+      );
+      await flush();
+      const fill = container.querySelector('[kjProgressBarFill]') as HTMLElement;
+      expect(fill).not.toHaveAttribute('data-indeterminate');
+    });
+
+    it('updates fraction reactively when the parent value changes', async () => {
+      @Component({
+        standalone: true,
+        imports,
+        template: `
+          <div kjProgressBar [kjValue]="value()" aria-label="x">
+            <div kjProgressBarFill data-testid="fill"></div>
+          </div>
+        `,
+      })
+      class Host {
+        readonly value = signal<number | null>(20);
+      }
+      const { fixture } = await render(Host);
+      await flush();
+      const fill = fixture.nativeElement.querySelector(
+        '[kjProgressBarFill]',
+      ) as HTMLElement;
+      expect(fill.style.getPropertyValue('--kj-progress-fraction')).toBe('0.2');
+
+      fixture.componentInstance.value.set(80);
+      fixture.detectChanges();
+      await flush();
+      expect(fill.style.getPropertyValue('--kj-progress-fraction')).toBe('0.8');
+
+      fixture.componentInstance.value.set(null);
+      fixture.detectChanges();
+      await flush();
+      expect(fill).toHaveAttribute('data-indeterminate', 'true');
+    });
+  });
+
+  describe('a11y audits', () => {
+    it('determinate progress bar passes axe', async () => {
+      const { container } = await render(
+        `<div kjProgressBar [kjValue]="50" aria-label="Upload progress">
+           <div kjProgressBarFill></div>
+         </div>`,
+        { imports },
+      );
+      await flush();
+      expect(await axe(container)).toHaveNoViolations();
+    });
+
+    it('indeterminate progress bar passes axe', async () => {
+      const { container } = await render(
+        `<div kjProgressBar [kjValue]="null" aria-label="Loading">
+           <div kjProgressBarFill></div>
+         </div>`,
+        { imports },
+      );
+      await flush();
+      expect(await axe(container)).toHaveNoViolations();
+    });
+  });
+});

package/src/progress-bar/progress-bar.ts

@@ -0,0 +1,217 @@
+import {
+  DestroyRef,
+  Directive,
+  PLATFORM_ID,
+  Signal,
+  afterNextRender,
+  computed,
+  effect,
+  inject,
+  input,
+  isDevMode,
+  signal,
+} from '@angular/core';
+import { isPlatformBrowser } from '@angular/common';
+
+import { KjSize, KjVariant, bindPresets } from '../presets';
+import { KJ_PROGRESS_BAR_CONFIG } from './config';
+import {
+  KJ_PROGRESS_BAR,
+  KjProgressBarContext,
+} from './progress-bar.context';
+
+/**
+ * Marks an element as a kouji progress bar. Owns `role="progressbar"` and the
+ * full ARIA value contract: `aria-valuemin` / `aria-valuemax` always, the
+ * rounded integer `aria-valuenow` when determinate, and **omits**
+ * `aria-valuenow` when indeterminate (the APG-correct behaviour for
+ * *"working, no measurable progress"*).
+ *
+ * `kjValue: number | null` is the single mode switch — `null` is the explicit
+ * indeterminate sentinel. Out-of-range values clamp to `[kjMin, kjMax]`; the
+ * directive computes the `0..1` fraction (`--kj-progress-fraction`) for the
+ * inner `[kjProgressBarFill]` to read, and rounds the value for AT so a
+ * 47.0 → 47.4 jitter doesn't churn the attribute.
+ *
+ * Variants and sizes are configurable via `provideKjProgressBar(…)`. The
+ * indeterminate stripe animation is theme-owned; the directive only reflects
+ * `data-indeterminate` and `data-reduced-motion` so themes can collapse the
+ * animation under `prefers-reduced-motion: reduce`.
+ *
+ * The progress bar itself is **not** a live region — APG is explicit that a
+ * `role="progressbar"` element should not carry `aria-live`. Milestone
+ * announcements (25%, 50%, …) belong on a sibling `[kjLiveRegion]` composed
+ * at the wrapper layer; the core directive does not own that wiring.
+ *
+ * @example
+ * ```html
+ * <div kjProgressBar [kjValue]="progress()" kjAriaLabel="Upload progress">
+ *   <div kjProgressBarFill></div>
+ * </div>
+ * ```
+ * @doc-category Core/Feedback
+ * @doc
+ * @doc-name progress-bar
+ * @doc-description Marks an element as an accessible progress bar with determinate or indeterminate value.
+ * @doc-is-main
+ */
+@Directive({
+  selector: '[kjProgressBar]',
+  standalone: true,
+  exportAs: 'kjProgressBar',
+  hostDirectives: [
+    { directive: KjVariant, inputs: ['kjVariant'] },
+    { directive: KjSize, inputs: ['kjSize'] },
+  ],
+  providers: [
+    ...bindPresets(KJ_PROGRESS_BAR_CONFIG),
+    { provide: KJ_PROGRESS_BAR, useExisting: KjProgressBar },
+  ],
+  host: {
+    'role': 'progressbar',
+    '[attr.aria-valuemin]': 'min()',
+    '[attr.aria-valuemax]': 'max()',
+    '[attr.aria-valuenow]': 'valuenow()',
+    '[attr.aria-valuetext]': 'kjAriaValuetext() ?? null',
+    '[attr.data-indeterminate]': 'indeterminate() ? "true" : null',
+    '[attr.data-reduced-motion]': 'reducedMotion() ? "reduce" : null',
+    '[style.--kj-progress-fraction]': 'fraction()',
+  },
+})
+export class KjProgressBar implements KjProgressBarContext {
+  private readonly platformId = inject(PLATFORM_ID);
+
+  /**
+   * Current progress value. `null` is the explicit indeterminate sentinel —
+   * the directive omits `aria-valuenow` and reflects `data-indeterminate`.
+   * Out-of-range values clamp to `[kjMin, kjMax]` (with a dev-mode warning).
+   * @default null
+   */
+  readonly kjValue = input<number | null>(null);
+
+  /**
+   * Lower bound, bound to `aria-valuemin`. Most consumers leave this at `0`
+   * and pass a percentage; for absolute units (`bytesUploaded` /
+   * `bytesTotal`), pass both `kjMin` and `kjMax`.
+   * @default 0
+   */
+  readonly kjMin = input<number>(0);
+
+  /**
+   * Upper bound, bound to `aria-valuemax`. Must be `> kjMin` (dev-mode
+   * throw otherwise).
+   * @default 100
+   */
+  readonly kjMax = input<number>(100);
+
+  /**
+   * Human-readable phrasing reflected to `aria-valuetext`. Use for cases
+   * where the raw percentage is less meaningful — `"Step 3 of 5"`,
+   * `"1.2 MB of 2.5 MB"`, `"3 minutes remaining"`. AT typically reads
+   * `aria-valuetext` exclusively when both attributes are set.
+   */
+  readonly kjAriaValuetext = input<string | undefined>(undefined);
+
+  /** True when the user prefers reduced motion. Reflects `data-reduced-motion`. */
+  protected readonly reducedMotion = signal<boolean>(false);
+
+  /** Raw value (passes through `null` for indeterminate). */
+  readonly value: Signal<number | null> = computed(() => this.kjValue());
+
+  /** True iff `kjValue()` is `null`. */
+  readonly indeterminate: Signal<boolean> = computed(
+    () => this.kjValue() === null,
+  );
+
+  readonly min: Signal<number> = computed(() => this.kjMin());
+  readonly max: Signal<number> = computed(() => this.kjMax());
+
+  /**
+   * Clamped value in `[min, max]`, or `null` when indeterminate. Applies
+   * even when the consumer passes `min >= max` (degenerate config —
+   * dev-mode throws but production still flows through with clamping).
+   */
+  readonly clampedValue: Signal<number | null> = computed(() => {
+    const v = this.kjValue();
+    if (v === null) return null;
+    const lo = this.kjMin();
+    const hi = this.kjMax();
+    if (Number.isNaN(v)) return null;
+    return Math.min(Math.max(v, lo), hi);
+  });
+
+  /** `0..1` fraction for CSS, or `null` when indeterminate. */
+  readonly fraction: Signal<number | null> = computed(() => {
+    const v = this.clampedValue();
+    if (v === null) return null;
+    const lo = this.kjMin();
+    const hi = this.kjMax();
+    const span = hi - lo;
+    if (span <= 0) return 0;
+    return (v - lo) / span;
+  });
+
+  /**
+   * Rounded integer for `aria-valuenow`, or `null` when indeterminate. The
+   * rounding stabilises the attribute when consumers drive `kjValue` from a
+   * high-frequency source (rAF-rate observables) — a 47.0 → 47.4 update no
+   * longer triggers an attribute write that some AT engines could announce.
+   */
+  readonly valuenow: Signal<number | null> = computed(() => {
+    const v = this.clampedValue();
+    return v === null ? null : Math.round(v);
+  });
+
+  constructor() {
+    const destroyRef = inject(DestroyRef);
+
+    afterNextRender(() => {
+      if (!isPlatformBrowser(this.platformId)) return;
+      if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return;
+
+      const mql = window.matchMedia('(prefers-reduced-motion: reduce)');
+      this.reducedMotion.set(mql.matches);
+
+      const onChange = (event: MediaQueryListEvent) => {
+        this.reducedMotion.set(event.matches);
+      };
+      mql.addEventListener('change', onChange);
+      destroyRef.onDestroy(() => mql.removeEventListener('change', onChange));
+    });
+
+    if (isDevMode()) {
+      effect(() => {
+        const lo = this.kjMin();
+        const hi = this.kjMax();
+        if (lo >= hi) {
+          throw new Error(
+            `[kj] KjProgressBar: kjMin (${lo}) must be less than kjMax (${hi}).`,
+          );
+        }
+      });
+
+      let outOfRangeWarned = false;
+      effect(() => {
+        const v = this.kjValue();
+        if (v === null) return;
+        const lo = this.kjMin();
+        const hi = this.kjMax();
+        if ((v < lo || v > hi) && !outOfRangeWarned) {
+          outOfRangeWarned = true;
+          console.warn(
+            `[kj] KjProgressBar: kjValue ${v} is outside [${lo}, ${hi}]; clamping.`,
+          );
+        }
+      });
+
+      effect(() => {
+        if (this.kjValue() === null && this.kjAriaValuetext() !== undefined) {
+          console.warn(
+            '[kj] KjProgressBar: kjAriaValuetext is set while kjValue is null (indeterminate). ' +
+              'aria-valuetext describes a value; consider moving the phrasing to a sibling text element.',
+          );
+        }
+      });
+    }
+  }
+}