@kouji-ui/core 0.1.1 → 0.1.2

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

@@ -1,423 +0,0 @@
-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

@@ -1,217 +0,0 @@
-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.',
-          );
-        }
-      });
-    }
-  }
-}