@kouji-ui/components 0.1.1

package/src/speed-dial/speed-dial.ts

@@ -0,0 +1,257 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ViewEncapsulation,
+  booleanAttribute,
+  input,
+} from '@angular/core';
+import {
+  KjButton,
+  KjSpeedDial,
+  KjSpeedDialAction,
+  KjSpeedDialActions,
+  KjSpeedDialTrigger,
+  type KjSpeedDialDirection,
+} from '@kouji-ui/core';
+
+/** Where to anchor the Speed Dial within its scroll container. */
+export type KjSpeedDialPosition =
+  | 'bottom-right'
+  | 'bottom-left'
+  | 'top-right'
+  | 'top-left'
+  | 'static';
+
+/**
+ * Styled wrapper around the headless `KjSpeedDial` directive.
+ *
+ * Renders a viewport-anchored floating action button (FAB) that, when clicked,
+ * fans out a cluster of action buttons — composed from `<kj-speed-dial-trigger>`
+ * and one or more `<kj-speed-dial-action>` children inside a
+ * `<kj-speed-dial-actions>` container. Theme tokens drive the FAB's circular
+ * shape, elevation, and the cluster's fan-out animation.
+ *
+ * `kjPosition` controls the anchor: `'bottom-right'` (default) places the FAB
+ * fixed to the bottom-right of the viewport. Use `'static'` to embed inline.
+ *
+ * @example
+ * ```html
+ * <kj-speed-dial kjDirection="up" kjPosition="bottom-right">
+ *   <kj-speed-dial-trigger kjAriaLabel="Open menu">+</kj-speed-dial-trigger>
+ *   <kj-speed-dial-actions>
+ *     <kj-speed-dial-action kjAriaLabel="Edit">E</kj-speed-dial-action>
+ *     <kj-speed-dial-action kjAriaLabel="Share">S</kj-speed-dial-action>
+ *   </kj-speed-dial-actions>
+ * </kj-speed-dial>
+ * ```
+ *
+ * @doc-example Default
+ *   The default playground — bottom-right anchored FAB fanning up.
+ *   @doc-file speed-dial.example.ts
+ * @doc-example Usage
+ *   A walkthrough of the most common speed-dial usages — direction, position,
+ *   disabled state, and per-action handlers. Copy-paste starting point.
+ *   @doc-file speed-dial.usage.example.ts
+ * @doc-example Directions
+ *   `kjDirection` controls the fan-out axis — `up`, `down`, `left`, `right`.
+ *   @doc-file speed-dial.directions.example.ts
+ * @doc-example With tooltips
+ *   Pair each action with a `<kj-tooltip-content>` for label-on-hover.
+ *   @doc-file speed-dial.with-tooltips.example.ts
+ * @doc-example Disabled
+ *   `[kjDisabled]="true"` on the root disables the trigger and all actions.
+ *   @doc-file speed-dial.disabled.example.ts
+ *
+ * @doc-keyboard
+ *   Enter|Space — Opens the dial when on the trigger; activates the focused action
+ *   ArrowKeys   — Move focus along the fan-out axis between trigger and actions
+ *   Escape      — Closes the dial and returns focus to the trigger
+ *   Tab         — Single tab stop on the trigger (roving tabindex inside)
+ *
+ * @doc-aria
+ *   role="menu"     — applied to `<kj-speed-dial-actions>` while open
+ *   role="menuitem" — applied to each `<kj-speed-dial-action>`
+ *   aria-haspopup   — set on the trigger to "menu"
+ *   aria-expanded   — reflects the open/closed state on the trigger
+ *   aria-label      — required on icon-only trigger and actions (dev-mode warns)
+ *   data-position   — mirrors `kjPosition` on the host for CSS hooks
+ *
+ * @doc-touch
+ *   Trigger defaults to `kjSize="lg"` (48px) — meets WCAG 2.5.5 (≥ 44×44).
+ *   Actions default to `kjSize="md"` (40px) — bump to `lg` for touch-first layouts.
+ *
+ * @doc-a11y
+ *   Implements the WAI-ARIA Menu Button APG pattern. Roving tabindex keeps the
+ *   trigger as a single Tab stop; arrow keys move focus through the open
+ *   action cluster. Focus returns to the trigger on close. Activating an
+ *   action closes the dial by default (`kjCloseOnActivate`).
+ *
+ * @doc-related dropdown-menu,tooltip,button-group
+ *
+ * @doc-css-var
+ *   --kj-speed-dial-gap           — Gap between the trigger and the action cluster.
+ *   --kj-speed-dial-edge          — Distance from the viewport edge when fixed-positioned.
+ *   --kj-speed-dial-trigger-size  — Width/height of the circular FAB trigger.
+ *   --kj-speed-dial-action-size   — Width/height of each fan-out action button.
+ *   --kj-speed-dial-shadow        — Elevation shadow shared by the trigger and actions.
+ *   --kj-speed-dial-stagger       — Per-action delay applied to the fan-out animation.
+ *   --kj-speed-dial-duration      — Transition duration for the trigger and fan-out motion.
+ *
+ * @doc-category Library/Actions
+ * @doc
+ * @doc-name speed-dial
+ * @doc-description Themed floating action button that fans out a cluster of secondary actions on activation.
+ * @doc-is-main
+ */
+@Component({
+  selector: 'kj-speed-dial',
+  standalone: true,
+  hostDirectives: [
+    {
+      directive: KjSpeedDial,
+      inputs: [
+        'kjDirection',
+        'kjOpen',
+        'kjDisabled',
+        'kjOpenOnHover',
+      ],
+      outputs: ['kjOpenChange'],
+    },
+  ],
+  template: `<ng-content />`,
+  styleUrl: './speed-dial.css',
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    class: 'kj-speed-dial',
+    '[attr.data-position]': 'kjPosition()',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjSpeedDialComponent {
+  /** Anchor for the dial. Default `'bottom-right'`. */
+  readonly kjPosition = input<KjSpeedDialPosition>('bottom-right');
+}
+
+/**
+ * Styled wrapper around `KjSpeedDialTrigger`.
+ *
+ * Renders a real `<button kjButton kjSpeedDialTrigger>` so the trigger inherits
+ * the kouji button presets (variant, size, focus ring, capture-phase disabled
+ * suppression) plus the speed-dial menu-button ARIA wiring.
+ *
+ * @doc-category Library/Actions
+ * @doc
+ * @doc-name speed-dial
+ */
+@Component({
+  selector: 'kj-speed-dial-trigger',
+  standalone: true,
+  imports: [KjButton, KjSpeedDialTrigger],
+  template: `
+    <button
+      type="button"
+      kjButton
+      kjSpeedDialTrigger
+      class="kj-speed-dial-trigger"
+      [kjVariant]="kjVariant()"
+      [kjSize]="kjSize()"
+      [kjDisabled]="kjDisabled()"
+      [attr.aria-label]="kjAriaLabel()"
+    >
+      <ng-content />
+    </button>
+  `,
+  styleUrl: './speed-dial.css',
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    class: 'kj-speed-dial-trigger-host',
+    style: 'display: contents;',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjSpeedDialTriggerComponent {
+  /** Button variant preset. */
+  readonly kjVariant = input('default');
+  /** Button size preset. */
+  readonly kjSize = input('lg');
+  /** Disable the trigger. */
+  readonly kjDisabled = input(false, { transform: booleanAttribute });
+  /** Required when the trigger has icon-only contents (it usually does). */
+  readonly kjAriaLabel = input<string | undefined>(undefined);
+}
+
+/**
+ * Styled wrapper around `KjSpeedDialActions` — the cluster container.
+ *
+ * Place inside `<kj-speed-dial>` and put one or more
+ * `<kj-speed-dial-action>` children inside it. The container itself carries
+ * `role="menu"` and is hidden when collapsed.
+ *
+ * @doc-category Library/Actions
+ * @doc
+ * @doc-name speed-dial
+ */
+@Component({
+  selector: 'kj-speed-dial-actions',
+  standalone: true,
+  hostDirectives: [KjSpeedDialActions],
+  template: `<ng-content />`,
+  styleUrl: './speed-dial.css',
+  encapsulation: ViewEncapsulation.None,
+  host: { class: 'kj-speed-dial-actions' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjSpeedDialActionsComponent {}
+
+/**
+ * Styled wrapper around `KjSpeedDialAction`.
+ *
+ * Renders a real `<button kjButton kjSpeedDialAction>` so the action inherits
+ * the kouji button presets and `role="menuitem"`. Activating an action closes
+ * the dial unless `[kjCloseOnActivate]="false"`.
+ *
+ * @doc-category Library/Actions
+ * @doc
+ * @doc-name speed-dial
+ */
+@Component({
+  selector: 'kj-speed-dial-action',
+  standalone: true,
+  imports: [KjButton, KjSpeedDialAction],
+  template: `
+    <button
+      type="button"
+      kjButton
+      kjSpeedDialAction
+      class="kj-speed-dial-action"
+      [kjVariant]="kjVariant()"
+      [kjSize]="kjSize()"
+      [kjDisabled]="kjDisabled()"
+      [kjCloseOnActivate]="kjCloseOnActivate()"
+      [attr.aria-label]="kjAriaLabel()"
+    >
+      <ng-content />
+    </button>
+  `,
+  styleUrl: './speed-dial.css',
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    class: 'kj-speed-dial-action-host',
+    style: 'display: contents;',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjSpeedDialActionComponent {
+  /** Button variant preset. Defaults to `outline`. */
+  readonly kjVariant = input('outline');
+  /** Button size preset. Defaults to `md` (one step smaller than the trigger). */
+  readonly kjSize = input('md');
+  /** Disable the action. */
+  readonly kjDisabled = input(false, { transform: booleanAttribute });
+  /** Whether activating closes the dial. Default `true`. */
+  readonly kjCloseOnActivate = input(true, { transform: booleanAttribute });
+  /** Required when the action has icon-only contents. */
+  readonly kjAriaLabel = input<string | undefined>(undefined);
+}
+
+export type { KjSpeedDialDirection };

package/src/spinner/_examples/index.ts

@@ -0,0 +1,8 @@
+// AUTO-GENERATED by scripts/migrate-examples.mjs
+// One barrel per component folder — used by the docs app as a lazy chunk.
+export { KjSpinnerAnimationsExample } from './spinner.animations.example';
+export { KjSpinnerExample } from './spinner.example';
+export { KjSpinnerInButtonExample } from './spinner.in-button.example';
+export { KjSpinnerSizesExample } from './spinner.sizes.example';
+export { KjSpinnerUsageExample } from './spinner.usage.example';
+export { KjSpinnerVariantsExample } from './spinner.variants.example';

package/src/spinner/_examples/spinner.animations.example.ts

@@ -0,0 +1,54 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjSpinnerComponent } from '../spinner';
+
+/**
+ * Animation shape presets — `spin` (rotating arc, default), `dots`
+ * (three pulsing dots), `pulse` (single fading circle), `bars`
+ * (vertical bars rising/falling) — side by side at the same size so
+ * the visual character of each shape is directly comparable.
+ */
+@Component({
+  selector: 'kj-spinner-animations-example',
+  standalone: true,
+  imports: [KjSpinnerComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        gap: var(--kj-space-xl);
+        align-items: center;
+      }
+      figure {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        gap: var(--kj-space-sm);
+        margin: 0;
+      }
+      figcaption {
+        font-size: var(--kj-text-sm);
+        color: var(--kj-fg-default);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <figure>
+      <kj-spinner kjAnimation="spin" kjSize="lg" kjAriaLabel="Loading (spin)" />
+      <figcaption>spin</figcaption>
+    </figure>
+    <figure>
+      <kj-spinner kjAnimation="dots" kjSize="lg" kjAriaLabel="Loading (dots)" />
+      <figcaption>dots</figcaption>
+    </figure>
+    <figure>
+      <kj-spinner kjAnimation="pulse" kjSize="lg" kjAriaLabel="Loading (pulse)" />
+      <figcaption>pulse</figcaption>
+    </figure>
+    <figure>
+      <kj-spinner kjAnimation="bars" kjSize="lg" kjAriaLabel="Loading (bars)" />
+      <figcaption>bars</figcaption>
+    </figure>
+  `,
+})
+export class KjSpinnerAnimationsExample {}

package/src/spinner/_examples/spinner.example.ts

@@ -0,0 +1,26 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjSpinnerComponent } from '../spinner';
+
+/**
+ * Default usage example for KjSpinnerComponent. Renders a single
+ * `<kj-spinner>` with the shipped defaults — `spin` animation,
+ * `md` size, `neutral` variant (inherits `currentColor`), and the
+ * default `aria-label="Loading"`.
+ */
+@Component({
+  selector: 'kj-spinner-example',
+  standalone: true,
+  imports: [KjSpinnerComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `<kj-spinner />`,
+})
+export class KjSpinnerExample {}

package/src/spinner/_examples/spinner.in-button.example.ts

@@ -0,0 +1,51 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjButtonComponent } from '../../button/button';
+import { KjSpinnerComponent } from '../spinner';
+
+/**
+ * Spinner composed inside a `<kj-button>` for the loading-state pattern.
+ * The button toggles a busy signal on click; the spinner appears next to
+ * the label and inherits the button's text colour (the `neutral` variant
+ * resolves to `currentColor` in shipped themes, so the spinner is
+ * automatically the on-primary colour when the button itself is primary).
+ */
+@Component({
+  selector: 'kj-spinner-in-button-example',
+  standalone: true,
+  imports: [KjButtonComponent, KjSpinnerComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        gap: var(--kj-space-md);
+        align-items: center;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-button (click)="run()" [kjDisabled]="busy()">
+      @if (busy()) {
+        <kj-spinner kjSize="sm" kjAriaLabel="Saving" />
+      }
+      {{ busy() ? 'Saving…' : 'Save' }}
+    </kj-button>
+
+    <kj-button kjVariant="ghost" (click)="run()" [kjDisabled]="busy()">
+      @if (busy()) {
+        <kj-spinner kjSize="sm" kjAnimation="dots" kjAriaLabel="Sending" />
+      }
+      {{ busy() ? 'Sending…' : 'Send' }}
+    </kj-button>
+  `,
+})
+export class KjSpinnerInButtonExample {
+  readonly busy = signal(false);
+
+  async run() {
+    if (this.busy()) return;
+    this.busy.set(true);
+    await new Promise((r) => setTimeout(r, 1500));
+    this.busy.set(false);
+  }
+}

package/src/spinner/_examples/spinner.sizes.example.ts

@@ -0,0 +1,31 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjSpinnerComponent } from '../spinner';
+
+/**
+ * Size presets — `xs` / `sm` / `md` / `lg` — laid out in a row so the
+ * progression is immediately visible. There is intentionally no `xl`:
+ * a spinner that big almost always wants a determinate Progress Bar
+ * instead.
+ */
+@Component({
+  selector: 'kj-spinner-sizes-example',
+  standalone: true,
+  imports: [KjSpinnerComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        gap: var(--kj-space-lg);
+        align-items: center;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-spinner kjSize="xs" kjAriaLabel="Loading (xs)" />
+    <kj-spinner kjSize="sm" kjAriaLabel="Loading (sm)" />
+    <kj-spinner kjSize="md" kjAriaLabel="Loading (md)" />
+    <kj-spinner kjSize="lg" kjAriaLabel="Loading (lg)" />
+  `,
+})
+export class KjSpinnerSizesExample {}

package/src/spinner/_examples/spinner.usage.example.ts

@@ -0,0 +1,45 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjSpinnerComponent } from '../spinner';
+
+/**
+ * A walkthrough of the most common spinner usages — default, size + variant,
+ * a different animation glyph, and an inline placement next to copy.
+ */
+@Component({
+  selector: 'kj-spinner-usage-example',
+  standalone: true,
+  imports: [KjSpinnerComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-md);
+      }
+      .row {
+        display: flex;
+        gap: var(--kj-space-lg);
+        align-items: center;
+      }
+      .inline {
+        display: inline-flex;
+        gap: var(--kj-space-xs);
+        align-items: center;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div class="row">
+      <kj-spinner kjAriaLabel="Loading" />
+      <kj-spinner kjSize="lg" kjVariant="primary" kjAriaLabel="Saving" />
+      <kj-spinner kjAnimation="dots" kjAriaLabel="Connecting" />
+    </div>
+
+    <p class="inline">
+      <kj-spinner kjSize="sm" kjAriaLabel="Loading inline" />
+      <span>Fetching latest data…</span>
+    </p>
+  `,
+})
+export class KjSpinnerUsageExample {}

package/src/spinner/_examples/spinner.variants.example.ts

@@ -0,0 +1,34 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjSpinnerComponent } from '../spinner';
+
+/**
+ * Colour variants — `neutral` (the default, inherits `currentColor`),
+ * `primary`, `success`, `warning`, `error`, `info` — laid out in a row.
+ * The `neutral` instance picks up the host's text colour, demonstrating
+ * the "spinner inside a coloured surface inherits its parent" contract.
+ */
+@Component({
+  selector: 'kj-spinner-variants-example',
+  standalone: true,
+  imports: [KjSpinnerComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        gap: var(--kj-space-lg);
+        align-items: center;
+        flex-wrap: wrap;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-spinner kjVariant="neutral" kjAriaLabel="Loading (neutral)" />
+    <kj-spinner kjVariant="primary" kjAriaLabel="Loading (primary)" />
+    <kj-spinner kjVariant="success" kjAriaLabel="Loading (success)" />
+    <kj-spinner kjVariant="warning" kjAriaLabel="Loading (warning)" />
+    <kj-spinner kjVariant="error" kjAriaLabel="Loading (error)" />
+    <kj-spinner kjVariant="info" kjAriaLabel="Loading (info)" />
+  `,
+})
+export class KjSpinnerVariantsExample {}

package/src/spinner/index.ts

@@ -0,0 +1 @@
+export * from './spinner';

package/src/spinner/spinner.css

@@ -0,0 +1,161 @@
+/* ─────────────────────────────────────────────────────────────
+   .kj-spinner — component-layer tokens + structural CSS
+
+   The directive owns role/label/data-attribute reflection. The CSS
+   below renders the visual glyph via the inner `.kj-spinner__glyph`
+   element (kept `aria-hidden="true"` in the template so AT only sees
+   the host's `role="status"` + `aria-label`). Variant + size + animation
+   routing all happens through `data-*` attributes on the wrapper host.
+   ──────────────────────────────────────────────────────────── */
+
+@layer kj.component {
+  .kj-spinner {
+    --kj-spinner-size:     1.25rem; /* md default */
+    --kj-spinner-color:    currentColor; /* neutral resolves to currentColor */
+    --kj-spinner-track:    color-mix(in srgb, currentColor 20%, transparent);
+    --kj-spinner-duration: 0.7s;
+
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--kj-spinner-size);
+    block-size: var(--kj-spinner-size);
+    color: var(--kj-spinner-color);
+    /* Keep the glyph centred without offering a hit-target — spinners are
+       not interactive. */
+    pointer-events: none;
+  }
+
+  /* Sizes — circular shapes use --kj-spinner-size for both axes. Linear
+     shapes (dots / bars) override inline-size on the host below. */
+  .kj-spinner[data-size="xs"] { --kj-spinner-size: 0.75rem; }
+  .kj-spinner[data-size="sm"] { --kj-spinner-size: 1rem; }
+  .kj-spinner[data-size="md"] { --kj-spinner-size: 1.25rem; }
+  .kj-spinner[data-size="lg"] { --kj-spinner-size: 1.75rem; }
+
+  /* Variant routing — neutral inherits currentColor (matches the
+     daisyUI / lucide convention so a spinner inside a primary button
+     picks up the button's text colour). */
+  .kj-spinner[data-variant="neutral"]   { --kj-spinner-color: currentColor; }
+  .kj-spinner[data-variant="primary"]   { --kj-spinner-color: var(--kj-fg-primary); }
+  .kj-spinner[data-variant="secondary"] { --kj-spinner-color: var(--kj-fg-default); }
+  .kj-spinner[data-variant="success"]   { --kj-spinner-color: var(--kj-fg-success, #16a34a); }
+  .kj-spinner[data-variant="warning"]   { --kj-spinner-color: var(--kj-fg-warning, #d97706); }
+  .kj-spinner[data-variant="error"]     { --kj-spinner-color: var(--kj-fg-danger, #dc2626); }
+  .kj-spinner[data-variant="info"]      { --kj-spinner-color: var(--kj-fg-info, #2563eb); }
+
+  /* Glyph host — themes can repaint the inner element per data-animation. */
+  .kj-spinner__glyph {
+    display: inline-block;
+    inline-size: 100%;
+    block-size: 100%;
+  }
+
+  /* ── Animation: spin (default) — rotating arc ─────────────────────── */
+  .kj-spinner[data-animation="spin"] .kj-spinner__glyph {
+    border: 2px solid var(--kj-spinner-track);
+    border-block-start-color: var(--kj-spinner-color);
+    border-radius: 50%;
+    animation: kj-spinner-spin var(--kj-spinner-duration) linear infinite;
+  }
+
+  /* ── Animation: pulse — single fading circle ──────────────────────── */
+  .kj-spinner[data-animation="pulse"] .kj-spinner__glyph {
+    background: var(--kj-spinner-color);
+    border-radius: 50%;
+    animation: kj-spinner-pulse calc(var(--kj-spinner-duration) * 2) ease-in-out infinite;
+  }
+
+  /* ── Animation: dots — three pulsing dots side by side ────────────── */
+  .kj-spinner[data-animation="dots"] {
+    /* Linear shape — width is auto, height is the size token. */
+    inline-size: auto;
+  }
+  .kj-spinner[data-animation="dots"] .kj-spinner__glyph {
+    display: inline-flex;
+    gap: calc(var(--kj-spinner-size) * 0.25);
+    inline-size: auto;
+    block-size: 100%;
+  }
+  .kj-spinner[data-animation="dots"] .kj-spinner__glyph::before,
+  .kj-spinner[data-animation="dots"] .kj-spinner__glyph::after,
+  .kj-spinner[data-animation="dots"] .kj-spinner__glyph {
+    /* Each dot via pseudo + the glyph itself acts as a flex container. */
+  }
+  .kj-spinner[data-animation="dots"] .kj-spinner__glyph::before,
+  .kj-spinner[data-animation="dots"] .kj-spinner__glyph::after {
+    content: "";
+    inline-size: calc(var(--kj-spinner-size) * 0.3);
+    block-size: calc(var(--kj-spinner-size) * 0.3);
+    background: var(--kj-spinner-color);
+    border-radius: 50%;
+    animation: kj-spinner-dots calc(var(--kj-spinner-duration) * 2) ease-in-out infinite;
+  }
+  .kj-spinner[data-animation="dots"] .kj-spinner__glyph {
+    background: transparent;
+  }
+  /* Middle dot rendered via box-shadow on ::before for a 3-dot row without
+     extra DOM. The two pseudos animate offset; the middle dot is the glyph
+     element's own background dot. */
+  .kj-spinner[data-animation="dots"] .kj-spinner__glyph::after {
+    animation-delay: calc(var(--kj-spinner-duration) * 0.4);
+  }
+
+  /* ── Animation: bars — vertical bars rising/falling ───────────────── */
+  .kj-spinner[data-animation="bars"] {
+    inline-size: auto;
+  }
+  .kj-spinner[data-animation="bars"] .kj-spinner__glyph {
+    display: inline-flex;
+    align-items: stretch;
+    gap: calc(var(--kj-spinner-size) * 0.15);
+    inline-size: auto;
+    block-size: 100%;
+  }
+  .kj-spinner[data-animation="bars"] .kj-spinner__glyph::before,
+  .kj-spinner[data-animation="bars"] .kj-spinner__glyph::after {
+    content: "";
+    inline-size: calc(var(--kj-spinner-size) * 0.2);
+    background: var(--kj-spinner-color);
+    border-radius: calc(var(--kj-spinner-size) * 0.05);
+    animation: kj-spinner-bars calc(var(--kj-spinner-duration) * 1.6) ease-in-out infinite;
+    transform-origin: center;
+  }
+  .kj-spinner[data-animation="bars"] .kj-spinner__glyph::after {
+    animation-delay: calc(var(--kj-spinner-duration) * 0.4);
+  }
+
+  /* ── Reduced motion — directive sets `data-reduced-motion="true"` ──── */
+  /* WCAG 2.3.3 (AAA): swap continuous rotation for a slow opacity pulse. */
+  .kj-spinner[data-reduced-motion="true"] .kj-spinner__glyph,
+  .kj-spinner[data-reduced-motion="true"] .kj-spinner__glyph::before,
+  .kj-spinner[data-reduced-motion="true"] .kj-spinner__glyph::after {
+    animation: kj-spinner-reduced-motion 1.6s ease-in-out infinite !important;
+  }
+}
+
+/* Keyframes live outside the cascade layer so consumers can't accidentally
+   defeat them with a higher-priority unlayered rule. */
+@keyframes kj-spinner-spin {
+  to { transform: rotate(360deg); }
+}
+
+@keyframes kj-spinner-pulse {
+  0%, 100% { opacity: 0.35; transform: scale(0.85); }
+  50%      { opacity: 1;    transform: scale(1); }
+}
+
+@keyframes kj-spinner-dots {
+  0%, 80%, 100% { transform: scale(0.4); opacity: 0.4; }
+  40%           { transform: scale(1);   opacity: 1; }
+}
+
+@keyframes kj-spinner-bars {
+  0%, 40%, 100% { transform: scaleY(0.4); }
+  20%           { transform: scaleY(1); }
+}
+
+@keyframes kj-spinner-reduced-motion {
+  0%, 100% { opacity: 0.45; }
+  50%      { opacity: 1; }
+}