@kouji-ui/components 0.1.1 → 0.1.2

package/src/spinner/spinner.playground.ts

@@ -1,68 +0,0 @@
-import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
-import { KjSpinnerComponent } from './spinner';
-import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
-
-/**
- * Playground state — module-scope signals.
- */
-const variant = signal<'neutral' | 'primary' | 'success' | 'warning' | 'error' | 'info'>('neutral');
-const size = signal<'xs' | 'sm' | 'md' | 'lg'>('md');
-const animation = signal<'spin' | 'dots' | 'bars'>('spin');
-const ariaLabel = signal('Loading');
-
-@Component({
-  selector: 'kj-spinner-playground',
-  standalone: true,
-  imports: [KjSpinnerComponent],
-  template: `
-    <kj-spinner
-      [kjVariant]="variant()"
-      [kjSize]="size()"
-      [kjAnimation]="animation()"
-      [kjAriaLabel]="ariaLabel()"
-    />
-  `,
-  changeDetection: ChangeDetectionStrategy.OnPush,
-})
-export class KjSpinnerPlaygroundDemo {
-  protected readonly variant = variant;
-  protected readonly size = size;
-  protected readonly animation = animation;
-  protected readonly ariaLabel = ariaLabel;
-}
-
-export const PLAYGROUND: PlaygroundFile = {
-  component: KjSpinnerPlaygroundDemo,
-  state: {
-    variant: variant as unknown as ReturnType<typeof signal>,
-    size: size as unknown as ReturnType<typeof signal>,
-    animation: animation as unknown as ReturnType<typeof signal>,
-    ariaLabel: ariaLabel as unknown as ReturnType<typeof signal>,
-  },
-  controls: [
-    {
-      kind: 'chips',
-      name: 'variant',
-      label: 'variant',
-      options: ['neutral', 'primary', 'success', 'warning', 'error', 'info'],
-    },
-    { kind: 'chips', name: 'size', label: 'size', options: ['xs', 'sm', 'md', 'lg'] },
-    { kind: 'chips', name: 'animation', label: 'animation', options: ['spin', 'dots', 'bars'] },
-    { kind: 'text', name: 'ariaLabel', label: 'aria label' },
-  ],
-  snippet: (values) => {
-    const s = values as {
-      variant: string;
-      size: string;
-      animation: string;
-      ariaLabel: string;
-    };
-    const attrs: string[] = [
-      `kjVariant="${s.variant}"`,
-      `kjSize="${s.size}"`,
-      `kjAnimation="${s.animation}"`,
-      `kjAriaLabel="${s.ariaLabel}"`,
-    ];
-    return `<kj-spinner\n  ${attrs.join('\n  ')}\n/>`;
-  },
-};

package/src/spinner/spinner.spec.ts

@@ -1,184 +0,0 @@
-import { Component, ChangeDetectionStrategy } from '@angular/core';
-import { TestBed } from '@angular/core/testing';
-import { describe, expect, test, beforeEach } from 'vitest';
-import { KjSpinnerComponent } from './spinner';
-
-/**
- * Flush microtasks + the rAF that backs `afterNextRender` so the composed
- * `KjSpinner` directive has a chance to read host attributes and the
- * `prefers-reduced-motion` media query before assertions run.
- */
-async function flushAfterNextRender(): Promise<void> {
-  await new Promise<void>((resolve) => setTimeout(resolve, 0));
-  await Promise.resolve();
-  await Promise.resolve();
-}
-
-@Component({
-  standalone: true,
-  imports: [KjSpinnerComponent],
-  changeDetection: ChangeDetectionStrategy.Eager,
-  template: `<kj-spinner />`,
-})
-class DefaultHost {}
-
-@Component({
-  standalone: true,
-  imports: [KjSpinnerComponent],
-  changeDetection: ChangeDetectionStrategy.Eager,
-  template: `<kj-spinner
-    [kjAnimation]="animation"
-    [kjVariant]="variant"
-    [kjSize]="size"
-    [kjAriaLabel]="label"
-  />`,
-})
-class ConfigurableHost {
-  animation: 'spin' | 'dots' | 'pulse' | 'bars' = 'spin';
-  variant = 'neutral';
-  size = 'md';
-  label = 'Loading';
-}
-
-@Component({
-  standalone: true,
-  imports: [KjSpinnerComponent],
-  changeDetection: ChangeDetectionStrategy.Eager,
-  template: `
-    <span id="busy-lbl">Loading users</span>
-    <kj-spinner aria-labelledby="busy-lbl" />
-  `,
-})
-class LabelledByHost {}
-
-describe('KjSpinnerComponent', () => {
-  beforeEach(() => {
-    TestBed.configureTestingModule({});
-  });
-
-  describe('directive composition', () => {
-    test('hosts the KjSpinner directive on the kj-spinner element', async () => {
-      const fixture = TestBed.createComponent(DefaultHost);
-      fixture.detectChanges();
-      await flushAfterNextRender();
-      fixture.detectChanges();
-
-      const host = fixture.nativeElement.querySelector('kj-spinner') as HTMLElement;
-      // hostDirectives composition lands the directive's host bindings on the
-      // wrapper's host element — role / aria-live / aria-atomic are the
-      // canonical fingerprint of KjSpinner being applied.
-      expect(host).not.toBeNull();
-      expect(host.getAttribute('role')).toBe('status');
-      expect(host.getAttribute('aria-live')).toBe('polite');
-      expect(host.getAttribute('aria-atomic')).toBe('true');
-      expect(host.classList.contains('kj-spinner')).toBe(true);
-    });
-
-    test('renders the inner aria-hidden glyph element', async () => {
-      const fixture = TestBed.createComponent(DefaultHost);
-      fixture.detectChanges();
-      await flushAfterNextRender();
-      fixture.detectChanges();
-
-      const glyph = fixture.nativeElement.querySelector(
-        'kj-spinner .kj-spinner__glyph',
-      ) as HTMLElement;
-      expect(glyph).not.toBeNull();
-      expect(glyph.getAttribute('aria-hidden')).toBe('true');
-    });
-  });
-
-  describe('default aria-label', () => {
-    test('applies "Loading" as the default aria-label on the host', async () => {
-      const fixture = TestBed.createComponent(DefaultHost);
-      fixture.detectChanges();
-      await flushAfterNextRender();
-      fixture.detectChanges();
-
-      const host = fixture.nativeElement.querySelector('kj-spinner') as HTMLElement;
-      expect(host.getAttribute('aria-label')).toBe('Loading');
-    });
-
-    test('forwards a custom kjAriaLabel input to the host aria-label', async () => {
-      const fixture = TestBed.createComponent(ConfigurableHost);
-      fixture.componentInstance.label = 'Saving draft';
-      fixture.detectChanges();
-      await flushAfterNextRender();
-      fixture.detectChanges();
-
-      const host = fixture.nativeElement.querySelector('kj-spinner') as HTMLElement;
-      expect(host.getAttribute('aria-label')).toBe('Saving draft');
-    });
-
-    test('renders the visually-hidden label copy when no aria-labelledby is authored', async () => {
-      const fixture = TestBed.createComponent(ConfigurableHost);
-      fixture.componentInstance.label = 'Sending message';
-      fixture.detectChanges();
-      await flushAfterNextRender();
-      fixture.detectChanges();
-
-      const hidden = fixture.nativeElement.querySelector(
-        'kj-spinner span[kjVisuallyHidden]',
-      ) as HTMLElement;
-      expect(hidden).not.toBeNull();
-      expect(hidden.textContent?.trim()).toBe('Sending message');
-    });
-
-    test('skips the visually-hidden label when consumer authors aria-labelledby', async () => {
-      const fixture = TestBed.createComponent(LabelledByHost);
-      fixture.detectChanges();
-      await flushAfterNextRender();
-      fixture.detectChanges();
-
-      const hidden = fixture.nativeElement.querySelector('kj-spinner span[kjVisuallyHidden]');
-      expect(hidden).toBeNull();
-      const host = fixture.nativeElement.querySelector('kj-spinner') as HTMLElement;
-      expect(host.getAttribute('aria-labelledby')).toBe('busy-lbl');
-    });
-  });
-
-  describe('data-animation reflection', () => {
-    test('defaults to data-animation="spin"', async () => {
-      const fixture = TestBed.createComponent(DefaultHost);
-      fixture.detectChanges();
-      await flushAfterNextRender();
-      fixture.detectChanges();
-
-      const host = fixture.nativeElement.querySelector('kj-spinner') as HTMLElement;
-      expect(host.getAttribute('data-animation')).toBe('spin');
-    });
-
-    test('reflects kjAnimation="dots"', async () => {
-      const fixture = TestBed.createComponent(ConfigurableHost);
-      fixture.componentInstance.animation = 'dots';
-      fixture.detectChanges();
-      await flushAfterNextRender();
-      fixture.detectChanges();
-
-      const host = fixture.nativeElement.querySelector('kj-spinner') as HTMLElement;
-      expect(host.getAttribute('data-animation')).toBe('dots');
-    });
-
-    test('reflects kjAnimation="pulse"', async () => {
-      const fixture = TestBed.createComponent(ConfigurableHost);
-      fixture.componentInstance.animation = 'pulse';
-      fixture.detectChanges();
-      await flushAfterNextRender();
-      fixture.detectChanges();
-
-      const host = fixture.nativeElement.querySelector('kj-spinner') as HTMLElement;
-      expect(host.getAttribute('data-animation')).toBe('pulse');
-    });
-
-    test('reflects kjAnimation="bars"', async () => {
-      const fixture = TestBed.createComponent(ConfigurableHost);
-      fixture.componentInstance.animation = 'bars';
-      fixture.detectChanges();
-      await flushAfterNextRender();
-      fixture.detectChanges();
-
-      const host = fixture.nativeElement.querySelector('kj-spinner') as HTMLElement;
-      expect(host.getAttribute('data-animation')).toBe('bars');
-    });
-  });
-});

package/src/spinner/spinner.ts

@@ -1,185 +0,0 @@
-import {
-  ChangeDetectionStrategy,
-  Component,
-  ElementRef,
-  ViewEncapsulation,
-  computed,
-  inject,
-  input,
-} from '@angular/core';
-import { KjSpinner, type KjSpinnerAnimation, KjVisuallyHidden } from '@kouji-ui/core';
-
-/**
- * Styled wrapper around the headless `KjSpinner` directive.
- *
- * Composes `KjSpinner` via `hostDirectives` so the wrapper's host element is
- * *the* spinner — `role="status"`, `aria-live="polite"`, `aria-atomic="true"`,
- * the `aria-label` default ("Loading"), `data-animation`, and
- * `data-reduced-motion` all land on `<kj-spinner>` itself. `kjVariant` and
- * `kjSize` are wrapper-level inputs that the host mirrors to `data-variant` /
- * `data-size` (the directive's own nested `KjVariant` / `KjSize` host
- * directives are not transitively exposed through outer composition, so the
- * wrapper takes over the data-attribute reflection at this layer).
- *
- * The template renders an `aria-hidden` glyph element (the visual shape that
- * theme CSS keyframes drive per `data-animation`) and, when no
- * `aria-labelledby` was authored on the host, a `kjVisuallyHidden` label so
- * AT always finds an accessible name.
- *
- * **Indeterminate-only.** The spinner answers "something is happening" — it
- * has no value model. For "x of y" use Progress Bar; for missing-content
- * placeholders use Skeleton.
- *
- * @example
- * ```html
- * <kj-spinner />
- * <kj-spinner kjVariant="primary" kjSize="lg" kjAnimation="dots" kjAriaLabel="Sending" />
- * ```
- * @doc-example Default
- *   The default playground — `spin` animation, `md` size, neutral variant,
- *   default `aria-label="Loading"`.
- *   @doc-file spinner.example.ts
- * @doc-example Usage
- *   A walkthrough of the most common spinner usages — size, variant,
- *   animation glyph, and inline placement next to copy.
- *   @doc-file spinner.usage.example.ts
- * @doc-example Sizes
- *   `xs` / `sm` / `md` / `lg` presets. There is intentionally no `xl` — that
- *   size almost always wants a determinate Progress Bar instead.
- *   @doc-file spinner.sizes.example.ts
- * @doc-example Variants
- *   `neutral` (inherits `currentColor`), `primary`, `success`, `warning`,
- *   `error`, `info`.
- *   @doc-file spinner.variants.example.ts
- * @doc-example Animations
- *   Animation shape preset — `spin`, `dots`, `bars`, etc. Themes own the
- *   keyframes per value.
- *   @doc-file spinner.animations.example.ts
- * @doc-example Inside a button
- *   Embed the spinner inline next to a label to communicate in-flight work.
- *   @doc-file spinner.in-button.example.ts
- *
- * @doc-keyboard
- *   — — Non-interactive. The spinner is purely a status indicator.
- *
- * @doc-aria
- *   role="status"     — set on the host so AT announces it as a live status region
- *   aria-live         — "polite" so the label is read without interrupting the user
- *   aria-atomic       — "true" so the full label is announced on change
- *   aria-label        — Defaults to "Loading"; override per context (e.g. "Sending")
- *   data-animation    — Mirrors the resolved animation for theme hooks
- *   data-variant      — Mirrors the resolved variant for theme hooks
- *   data-size         — Mirrors the resolved size for theme hooks
- *
- * @doc-touch
- *   — — Non-interactive; no touch target required.
- *
- * @doc-a11y
- *   Indeterminate-only — answers "something is happening", with no value model.
- *   Honours `prefers-reduced-motion` via `data-reduced-motion` on the host, so
- *   themes can swap a calmer animation. When the consumer authors
- *   `aria-labelledby` on the host the wrapper skips the visually-hidden label
- *   to avoid double-naming.
- *
- * @doc-related progress-bar,skeleton,toast
- *
- * @doc-css-var
- *   --kj-spinner-size      — Glyph diameter. Sizes (xs/sm/md/lg) override.
- *   --kj-spinner-color     — Foreground color of the glyph. Variants set this; neutral inherits currentColor.
- *   --kj-spinner-track     — Track/background color for the spin arc.
- *   --kj-spinner-duration  — Base animation duration. Other animations scale off this.
- *
- * @doc-category Library/Feedback
- * @doc
- * @doc-name spinner
- * @doc-description Themed indeterminate loading spinner with variant, size, and animation glyph options.
- * @doc-is-main
- */
-@Component({
-  selector: 'kj-spinner',
-  standalone: true,
-  imports: [KjVisuallyHidden],
-  hostDirectives: [
-    {
-      directive: KjSpinner,
-      // KjSpinner's own surface — kjVariant + kjSize live on its nested
-      // KjVariant / KjSize and are not surfaced through this outer
-      // composition; they are re-exposed as wrapper inputs below and wired
-      // straight to the host's data-variant / data-size attributes.
-      inputs: ['kjAnimation', 'kjAriaLabel'],
-    },
-  ],
-  template: `
-    <span class="kj-spinner__glyph" aria-hidden="true"></span>
-    @if (shouldRenderHiddenLabel()) {
-      <span kjVisuallyHidden>{{ kjAriaLabel() }}</span>
-    }
-  `,
-  styleUrl: './spinner.css',
-  encapsulation: ViewEncapsulation.None,
-  host: {
-    'class': 'kj-spinner',
-    '[attr.data-variant]': 'kjVariant()',
-    '[attr.data-size]': 'kjSize()',
-  },
-  changeDetection: ChangeDetectionStrategy.OnPush,
-})
-export class KjSpinnerComponent {
-  /**
-   * Color preset reflected to `data-variant` on the host. Defaults to
-   * `'neutral'`, which resolves to `currentColor` in shipped themes — so a
-   * spinner inside a coloured surface inherits its parent's text colour.
-   */
-  readonly kjVariant = input<string>('neutral');
-
-  /**
-   * Size preset reflected to `data-size` on the host. Defaults to `'md'`.
-   * Sizes ship as `xs | sm | md | lg`; an `xl` is intentionally absent — a
-   * spinner that big almost always wants a determinate Progress Bar instead.
-   */
-  readonly kjSize = input<string>('md');
-
-  /**
-   * Animation shape preset forwarded to `KjSpinner.kjAnimation` via the
-   * composed host directive. Reflects on the host as `data-animation`.
-   * Themes own the keyframes per value.
-   */
-  readonly kjAnimation = input<KjSpinnerAnimation>('spin');
-
-  /**
-   * Accessible name forwarded to `KjSpinner.kjAriaLabel` via the composed
-   * host directive. Default `'Loading'`. Used both as the host's
-   * `aria-label` and as the visually-hidden text rendered inside the
-   * wrapper when no consumer-authored `aria-labelledby` is on the element.
-   */
-  readonly kjAriaLabel = input<string>('Loading');
-
-  private readonly el = inject<ElementRef<HTMLElement>>(ElementRef);
-
-  /**
-   * Snapshotted at construction: did the consumer author `aria-labelledby`
-   * directly on `<kj-spinner>`? If so the accessible name is the referenced
-   * element and we must not project a hidden duplicate. Read in the
-   * constructor — by the time the template renders the directive may have
-   * stamped its own attributes on the host.
-   */
-  private readonly hasAuthoredLabelledBy: boolean;
-
-  /**
-   * `true` when the consumer did **not** author `aria-labelledby` on the
-   * wrapper — i.e. the spinner's accessible name is its `aria-label`. The
-   * wrapper renders a `kjVisuallyHidden` copy of the label as inner text so
-   * AT that prefers content over `aria-label` (or that announces a
-   * `role="status"` region's body on insertion) still has a name to read.
-   * A consumer-authored `aria-labelledby` opts out of that hidden copy to
-   * avoid double-naming the host.
-   */
-  protected readonly shouldRenderHiddenLabel = computed(
-    () => !this.hasAuthoredLabelledBy,
-  );
-
-  constructor() {
-    this.hasAuthoredLabelledBy =
-      this.el.nativeElement.hasAttribute('aria-labelledby');
-  }
-}

package/src/stepper/_examples/index.ts

@@ -1,8 +0,0 @@
-// AUTO-GENERATED by scripts/migrate-examples.mjs
-// One barrel per component folder — used by the docs app as a lazy chunk.
-export { KjStepperExample } from './stepper.example';
-export { KjStepperNonLinearExample } from './stepper.non-linear.example';
-export { KjStepperOptionalStepExample } from './stepper.optional-step.example';
-export { KjStepperUsageExample } from './stepper.usage.example';
-export { KjStepperVerticalExample } from './stepper.vertical.example';
-export { KjStepperWithErrorExample } from './stepper.with-error.example';

package/src/stepper/_examples/stepper.example.ts

@@ -1,62 +0,0 @@
-import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
-import {
-  KjStepperComponent,
-  KjStepComponent,
-  KjStepLabelComponent,
-  KjStepContentComponent,
-  KjStepperNextComponent,
-  KjStepperPreviousComponent,
-} from '../stepper';
-
-/**
- * Default 3-step linear stepper. Demonstrates the canonical Account → Profile →
- * Confirm flow with `kjLinear` advancement gated by per-step completion.
- */
-@Component({
-  selector: 'kj-stepper-example',
-  standalone: true,
-  imports: [
-    KjStepperComponent,
-    KjStepComponent,
-    KjStepLabelComponent,
-    KjStepContentComponent,
-    KjStepperNextComponent,
-    KjStepperPreviousComponent,
-  ],
-  styles: [
-    `
-      :host {
-        display: block;
-      }
-      .actions {
-        display: flex;
-        gap: var(--kj-space-sm);
-        margin-top: var(--kj-space-lg);
-      }
-    `,
-  ],
-  changeDetection: ChangeDetectionStrategy.Eager,
-  template: `
-    <kj-stepper [(kjActiveStep)]="active" [kjLinear]="true">
-      <kj-step [kjStepCompleted]="active() > 0">
-        <kj-step-label>Account</kj-step-label>
-        <kj-step-content>Create your account.</kj-step-content>
-      </kj-step>
-      <kj-step [kjStepCompleted]="active() > 1">
-        <kj-step-label>Profile</kj-step-label>
-        <kj-step-content>Tell us about yourself.</kj-step-content>
-      </kj-step>
-      <kj-step>
-        <kj-step-label>Confirm</kj-step-label>
-        <kj-step-content>Review and submit.</kj-step-content>
-      </kj-step>
-      <div class="actions">
-        <kj-stepper-previous>Back</kj-stepper-previous>
-        <kj-stepper-next>Continue</kj-stepper-next>
-      </div>
-    </kj-stepper>
-  `,
-})
-export class KjStepperExample {
-  readonly active = signal(0);
-}

package/src/stepper/_examples/stepper.non-linear.example.ts

@@ -1,63 +0,0 @@
-import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
-import {
-  KjStepperComponent,
-  KjStepComponent,
-  KjStepLabelComponent,
-  KjStepContentComponent,
-  KjStepperNextComponent,
-  KjStepperPreviousComponent,
-} from '../stepper';
-
-/**
- * Non-linear stepper. Every header is reachable at any time — useful for
- * settings panels and long-form editors where the steps don't depend on
- * each other.
- */
-@Component({
-  selector: 'kj-stepper-non-linear-example',
-  standalone: true,
-  imports: [
-    KjStepperComponent,
-    KjStepComponent,
-    KjStepLabelComponent,
-    KjStepContentComponent,
-    KjStepperNextComponent,
-    KjStepperPreviousComponent,
-  ],
-  styles: [
-    `
-      :host {
-        display: block;
-      }
-      .actions {
-        display: flex;
-        gap: var(--kj-space-sm);
-        margin-top: var(--kj-space-lg);
-      }
-    `,
-  ],
-  changeDetection: ChangeDetectionStrategy.Eager,
-  template: `
-    <kj-stepper [(kjActiveStep)]="active">
-      <kj-step>
-        <kj-step-label>Profile</kj-step-label>
-        <kj-step-content>Edit your profile.</kj-step-content>
-      </kj-step>
-      <kj-step>
-        <kj-step-label>Notifications</kj-step-label>
-        <kj-step-content>Tune your alerts.</kj-step-content>
-      </kj-step>
-      <kj-step>
-        <kj-step-label>Billing</kj-step-label>
-        <kj-step-content>Update payment.</kj-step-content>
-      </kj-step>
-      <div class="actions">
-        <kj-stepper-previous>Back</kj-stepper-previous>
-        <kj-stepper-next>Next</kj-stepper-next>
-      </div>
-    </kj-stepper>
-  `,
-})
-export class KjStepperNonLinearExample {
-  readonly active = signal(0);
-}

package/src/stepper/_examples/stepper.optional-step.example.ts

@@ -1,62 +0,0 @@
-import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
-import {
-  KjStepperComponent,
-  KjStepComponent,
-  KjStepLabelComponent,
-  KjStepContentComponent,
-  KjStepperNextComponent,
-  KjStepperPreviousComponent,
-} from '../stepper';
-
-/**
- * Linear stepper with an optional middle step. `kjStepOptional` lifts the
- * `linear`-mode advancement gate so the user may skip without satisfying it.
- */
-@Component({
-  selector: 'kj-stepper-optional-step-example',
-  standalone: true,
-  imports: [
-    KjStepperComponent,
-    KjStepComponent,
-    KjStepLabelComponent,
-    KjStepContentComponent,
-    KjStepperNextComponent,
-    KjStepperPreviousComponent,
-  ],
-  styles: [
-    `
-      :host {
-        display: block;
-      }
-      .actions {
-        display: flex;
-        gap: var(--kj-space-sm);
-        margin-top: var(--kj-space-lg);
-      }
-    `,
-  ],
-  changeDetection: ChangeDetectionStrategy.Eager,
-  template: `
-    <kj-stepper [(kjActiveStep)]="active" [kjLinear]="true">
-      <kj-step [kjStepCompleted]="active() > 0">
-        <kj-step-label>Account</kj-step-label>
-        <kj-step-content>Required.</kj-step-content>
-      </kj-step>
-      <kj-step [kjStepOptional]="true">
-        <kj-step-label>Avatar (optional)</kj-step-label>
-        <kj-step-content>Skip if you'd rather upload later.</kj-step-content>
-      </kj-step>
-      <kj-step>
-        <kj-step-label>Confirm</kj-step-label>
-        <kj-step-content>Review and submit.</kj-step-content>
-      </kj-step>
-      <div class="actions">
-        <kj-stepper-previous>Back</kj-stepper-previous>
-        <kj-stepper-next>Continue</kj-stepper-next>
-      </div>
-    </kj-stepper>
-  `,
-})
-export class KjStepperOptionalStepExample {
-  readonly active = signal(0);
-}