@kouji-ui/components 0.1.1

package/src/skeleton/skeleton.css

@@ -0,0 +1,111 @@
+/* ─────────────────────────────────────────────────────────────
+   .kj-skeleton — component-layer tokens + structural CSS
+   The directive lands `aria-hidden="true"` and reflects
+   `data-shape` / `data-animation` on the host. CSS owns the
+   shimmer / pulse keyframes and the reduced-motion override —
+   per `skeleton.md`, the directive deliberately does *not*
+   detect `prefers-reduced-motion` itself; theme CSS does, here.
+   ──────────────────────────────────────────────────────────── */
+
+@layer kj.component {
+  .kj-skeleton {
+    /* component knobs — themes/users can override any of these */
+    --kj-skeleton-bg:           var(--kj-bg-elevated, color-mix(in oklab, var(--kj-fg-default, #000) 12%, transparent));
+    --kj-skeleton-highlight:    var(--kj-bg-surface, color-mix(in oklab, var(--kj-fg-default, #000) 5%, transparent));
+    --kj-skeleton-radius:       var(--kj-radius-field, 0.375rem);
+    --kj-skeleton-line-height:  1em;
+    --kj-skeleton-line-radius:  0.25rem;
+    --kj-skeleton-shimmer-duration: 1.4s;
+    --kj-skeleton-pulse-duration:   1.6s;
+
+    display: block;
+    background-color: var(--kj-skeleton-bg);
+    border-radius: var(--kj-skeleton-radius);
+    /* Sized by consumer-supplied width/height. Default to a sensible
+       rectangle so a bare <kj-skeleton/> still paints something. */
+    inline-size: 100%;
+    block-size: 1rem;
+    overflow: hidden;
+    position: relative;
+  }
+
+  /* ── Shape routing ──────────────────────────────────────────────────── */
+
+  .kj-skeleton[data-shape="circle"] {
+    border-radius: 50%;
+    aspect-ratio: 1 / 1;
+  }
+
+  .kj-skeleton[data-shape="text"],
+  .kj-skeleton.kj-skeleton--line {
+    block-size: var(--kj-skeleton-line-height);
+    border-radius: var(--kj-skeleton-line-radius);
+  }
+
+  /* The text-block host is a layout container — it doesn't paint itself,
+     it stacks N child .kj-skeleton--line elements. Drop the default
+     paint chrome so only the lines are visible. */
+  .kj-skeleton[data-shape="text-block"] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--kj-space-sm, 0.5rem);
+    background-color: transparent;
+    border-radius: 0;
+    inline-size: 100%;
+    block-size: auto;
+    overflow: visible;
+  }
+
+  /* ── Animation routing ──────────────────────────────────────────────── */
+
+  /* Shimmer: a moving highlight gradient sweeps left-to-right. */
+  .kj-skeleton[data-animation="shimmer"]::after {
+    content: "";
+    position: absolute;
+    inset: 0;
+    background: linear-gradient(
+      90deg,
+      transparent 0%,
+      var(--kj-skeleton-highlight) 50%,
+      transparent 100%
+    );
+    transform: translateX(-100%);
+    animation: kj-skeleton-shimmer var(--kj-skeleton-shimmer-duration) linear infinite;
+  }
+
+  /* The text-block host doesn't paint, so its ::after sweep would be a
+     ghost. Suppress it; each child line runs its own shimmer. */
+  .kj-skeleton[data-shape="text-block"][data-animation="shimmer"]::after {
+    content: none;
+  }
+
+  .kj-skeleton[data-animation="pulse"] {
+    animation: kj-skeleton-pulse var(--kj-skeleton-pulse-duration) ease-in-out infinite;
+  }
+
+  .kj-skeleton[data-animation="none"]::after {
+    content: none;
+  }
+
+  @keyframes kj-skeleton-shimmer {
+    0%   { transform: translateX(-100%); }
+    100% { transform: translateX(100%);  }
+  }
+
+  @keyframes kj-skeleton-pulse {
+    0%, 100% { opacity: 1;   }
+    50%      { opacity: 0.55; }
+  }
+
+  /* ── Reduced motion ─────────────────────────────────────────────────── */
+  /* Per skeleton.md: when the OS sets the preference, theme CSS pins the
+     animation off regardless of `kjSkeletonAnimation`. The directive
+     deliberately does not detect the media query — this rule is the
+     enforcement layer. */
+  @media (prefers-reduced-motion: reduce) {
+    .kj-skeleton,
+    .kj-skeleton::after {
+      animation: none !important;
+    }
+  }
+}

package/src/skeleton/skeleton.playground.ts

@@ -0,0 +1,80 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { KjSkeletonComponent } from './skeleton';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+type KjSkeletonShape = 'rectangle' | 'circle' | 'text' | 'text-block';
+type KjSkeletonAnimation = 'shimmer' | 'pulse' | 'none';
+
+const shape = signal<KjSkeletonShape>('rectangle');
+const animation = signal<KjSkeletonAnimation>('shimmer');
+const width = signal<string>('12rem');
+const height = signal<string>('3rem');
+const lines = signal<number>(3);
+
+@Component({
+  selector: 'kj-skeleton-playground',
+  standalone: true,
+  imports: [KjSkeletonComponent],
+  template: `
+    <kj-skeleton
+      [kjSkeletonShape]="shape()"
+      [kjSkeletonAnimation]="animation()"
+      [kjWidth]="width()"
+      [kjHeight]="height()"
+      [kjLines]="lines()"
+    />
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjSkeletonPlaygroundDemo {
+  protected readonly shape = shape;
+  protected readonly animation = animation;
+  protected readonly width = width;
+  protected readonly height = height;
+  protected readonly lines = lines;
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjSkeletonPlaygroundDemo,
+  state: {
+    shape: shape as unknown as ReturnType<typeof signal>,
+    animation: animation as unknown as ReturnType<typeof signal>,
+    width: width as unknown as ReturnType<typeof signal>,
+    height: height as unknown as ReturnType<typeof signal>,
+    lines: lines as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    {
+      kind: 'chips',
+      name: 'shape',
+      label: 'shape',
+      options: ['rectangle', 'circle', 'text', 'text-block'],
+    },
+    {
+      kind: 'chips',
+      name: 'animation',
+      label: 'animation',
+      options: ['shimmer', 'pulse', 'none'],
+    },
+    { kind: 'text', name: 'width', label: 'width' },
+    { kind: 'text', name: 'height', label: 'height' },
+    { kind: 'number', name: 'lines', label: 'lines (text-block)', min: 1, max: 10 },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      shape: string;
+      animation: string;
+      width: string;
+      height: string;
+      lines: number;
+    };
+    const attrs: string[] = [
+      `kjSkeletonShape="${s.shape}"`,
+      `kjSkeletonAnimation="${s.animation}"`,
+    ];
+    if (s.width) attrs.push(`kjWidth="${s.width}"`);
+    if (s.height) attrs.push(`kjHeight="${s.height}"`);
+    if (s.shape === 'text-block') attrs.push(`[kjLines]="${s.lines}"`);
+    return `<kj-skeleton\n  ${attrs.join('\n  ')}\n/>`;
+  },
+};

package/src/skeleton/skeleton.spec.ts

@@ -0,0 +1,126 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { describe, expect, test, beforeEach } from 'vitest';
+import type { KjSkeletonAnimation, KjSkeletonShape } from '@kouji-ui/core';
+import { KjSkeletonComponent } from './skeleton';
+
+@Component({
+  standalone: true,
+  imports: [KjSkeletonComponent],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `<kj-skeleton
+    [kjSkeletonShape]="shape"
+    [kjSkeletonAnimation]="animation"
+    [kjWidth]="width"
+    [kjHeight]="height"
+    [kjLines]="lines"
+  />`,
+})
+class HostComponent {
+  shape: KjSkeletonShape = 'rectangle';
+  animation: KjSkeletonAnimation = 'shimmer';
+  width: string | undefined = undefined;
+  height: string | undefined = undefined;
+  lines = 3;
+}
+
+describe('KjSkeletonComponent', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({ imports: [HostComponent] });
+  });
+
+  test('renders the host with the .kj-skeleton class', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const host = fixture.nativeElement.querySelector('kj-skeleton');
+    expect(host).not.toBeNull();
+    expect(host!.classList.contains('kj-skeleton')).toBe(true);
+  });
+
+  test('composed directive sets aria-hidden="true" on the host', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const host = fixture.nativeElement.querySelector('kj-skeleton')!;
+    expect(host.getAttribute('aria-hidden')).toBe('true');
+  });
+
+  test('reflects default shape "rectangle" via data-shape', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const host = fixture.nativeElement.querySelector('kj-skeleton')!;
+    expect(host.getAttribute('data-shape')).toBe('rectangle');
+  });
+
+  test('reflects default animation "shimmer" via data-animation', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const host = fixture.nativeElement.querySelector('kj-skeleton')!;
+    expect(host.getAttribute('data-animation')).toBe('shimmer');
+  });
+
+  test('forwards kjSkeletonShape to the composed directive (data-shape)', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.shape = 'circle';
+    fixture.detectChanges();
+    const host = fixture.nativeElement.querySelector('kj-skeleton')!;
+    expect(host.getAttribute('data-shape')).toBe('circle');
+  });
+
+  test('forwards kjSkeletonAnimation to the composed directive (data-animation)', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.animation = 'pulse';
+    fixture.detectChanges();
+    const host = fixture.nativeElement.querySelector('kj-skeleton')!;
+    expect(host.getAttribute('data-animation')).toBe('pulse');
+  });
+
+  test('applies kjWidth and kjHeight as inline styles on the host', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.width = '12rem';
+    fixture.componentInstance.height = '2rem';
+    fixture.detectChanges();
+    const host = fixture.nativeElement.querySelector('kj-skeleton')! as HTMLElement;
+    expect(host.style.width).toBe('12rem');
+    expect(host.style.height).toBe('2rem');
+  });
+
+  test('text-block shape renders N child line skeletons (default 3)', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.shape = 'text-block';
+    fixture.detectChanges();
+    const host = fixture.nativeElement.querySelector('kj-skeleton')!;
+    expect(host.getAttribute('data-shape')).toBe('text-block');
+    const lines = host.querySelectorAll('.kj-skeleton--line');
+    expect(lines.length).toBe(3);
+  });
+
+  test('text-block honours kjLines and renders the last line at 60% width', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.shape = 'text-block';
+    fixture.componentInstance.lines = 4;
+    fixture.detectChanges();
+    const host = fixture.nativeElement.querySelector('kj-skeleton')!;
+    const lines = host.querySelectorAll('.kj-skeleton--line') as NodeListOf<HTMLElement>;
+    expect(lines.length).toBe(4);
+    expect(lines[lines.length - 1].style.width).toBe('60%');
+    expect(lines[0].style.width).toBe('100%');
+  });
+
+  test('text-block child lines reflect data-shape="text" via the composed directive', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.shape = 'text-block';
+    fixture.detectChanges();
+    const host = fixture.nativeElement.querySelector('kj-skeleton')!;
+    const firstLine = host.querySelector('.kj-skeleton--line')!;
+    expect(firstLine.getAttribute('data-shape')).toBe('text');
+    expect(firstLine.getAttribute('aria-hidden')).toBe('true');
+  });
+
+  test('non-text-block shapes do not render line children', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.shape = 'rectangle';
+    fixture.detectChanges();
+    const host = fixture.nativeElement.querySelector('kj-skeleton')!;
+    expect(host.querySelectorAll('.kj-skeleton--line').length).toBe(0);
+  });
+});

package/src/skeleton/skeleton.ts

@@ -0,0 +1,155 @@
+import { ChangeDetectionStrategy, Component, ViewEncapsulation, computed, input } from '@angular/core';
+import { KjSkeleton, type KjSkeletonAnimation, type KjSkeletonShape } from '@kouji-ui/core';
+
+/**
+ * Styled wrapper around the headless `KjSkeleton` directive.
+ *
+ * Composes `KjSkeleton` via `hostDirectives` with `kj`-prefixed input
+ * aliasing (`kjSkeletonShape`, `kjSkeletonAnimation`). The directive's
+ * host bindings — `aria-hidden="true"`, `data-shape`, `data-animation` —
+ * land directly on the `<kj-skeleton>` host so theme CSS in
+ * `skeleton.css` paints the surface, runs the shimmer / pulse keyframes,
+ * and honours `prefers-reduced-motion` against the same element. The
+ * wrapper deliberately keeps a real (non-`display: contents`) host
+ * because the host *is* the painted skeleton.
+ *
+ * For the `text-block` shape the wrapper expands its inner template into
+ * N stacked text-shaped child skeletons (default 3, last at 60% width)
+ * since multi-line composition can't be carried by a single element. The
+ * outer host still reflects `data-shape="text-block"` so themes can opt
+ * out of the rectangle paint when stacking lines.
+ *
+ * The wrapper has no `<ng-content/>` — projecting real content into a
+ * skeleton is a bug, not a feature. The parent region carries the
+ * loading semantics (`aria-busy`, `role="status"` live region); the
+ * skeleton itself stays silent.
+ *
+ * @example
+ * ```html
+ * <kj-skeleton kjSkeletonShape="text" kjWidth="12rem" />
+ * <kj-skeleton kjSkeletonShape="circle" kjWidth="40px" kjHeight="40px" />
+ * <kj-skeleton kjSkeletonShape="text-block" [kjLines]="4" />
+ * ```
+ * @doc-example Default
+ *   A single rectangle placeholder — the bare-minimum recipe.
+ *   @doc-file skeleton.example.ts
+ * @doc-example Usage
+ *   A walkthrough of the most common usages — avatar + lines and card
+ *   preview. Use this as the copy-paste starting point.
+ *   @doc-file skeleton.usage.example.ts
+ * @doc-example Shapes
+ *   `rectangle`, `circle`, `text`, `text-block` — pick the cadence that fits.
+ *   @doc-file skeleton.shapes.example.ts
+ * @doc-example Animations
+ *   `shimmer`, `pulse`, `none` — collapse under `prefers-reduced-motion`.
+ *   @doc-file skeleton.animations.example.ts
+ * @doc-example Card
+ *   A complete card composition while data is loading.
+ *   @doc-file skeleton.card.example.ts
+ *
+ * @doc-aria
+ *   aria-hidden="true" — Set on the skeleton host (decorative; semantics live on the parent region)
+ *   data-shape         — Mirrors the shape preset for theme hooks
+ *   data-animation     — Mirrors the animation preset for theme hooks
+ *
+ * @doc-touch
+ *   The skeleton is non-interactive — no touch target rules apply. The
+ *   parent region should carry `aria-busy="true"` while loading.
+ *
+ * @doc-a11y
+ *   The wrapper sets `aria-hidden="true"` so the placeholder is invisible
+ *   to AT. The parent region owns the loading semantics — typically a
+ *   `role="status"` live region with `aria-busy="true"` while the data is
+ *   in-flight. Animations collapse under `prefers-reduced-motion: reduce`.
+ *
+ * @doc-related spinner,progress-bar,empty-state
+ *
+ * @doc-css-var
+ *   --kj-skeleton-bg                 — Surface background of the placeholder block.
+ *   --kj-skeleton-highlight          — Highlight gradient color used by the shimmer sweep.
+ *   --kj-skeleton-radius             — Corner radius for rectangle/text shapes.
+ *   --kj-skeleton-line-height        — Per-line block size for text and text-block shapes.
+ *   --kj-skeleton-line-radius        — Corner radius applied to text lines.
+ *   --kj-skeleton-shimmer-duration   — One-sweep duration of the shimmer animation.
+ *   --kj-skeleton-pulse-duration     — One-cycle duration of the pulse animation.
+ *
+ * @doc-category Library/Feedback
+ * @doc
+ * @doc-name skeleton
+ * @doc-description Themed loading placeholder with rectangle, circle, text, and text-block shapes.
+ * @doc-is-main
+ */
+@Component({
+  selector: 'kj-skeleton',
+  standalone: true,
+  hostDirectives: [
+    {
+      directive: KjSkeleton,
+      inputs: ['kjSkeletonShape', 'kjSkeletonAnimation'],
+    },
+  ],
+  imports: [KjSkeleton],
+  template: `
+    @if (isTextBlock()) {
+      @for (line of lineWidths(); track $index) {
+        <span
+          kjSkeleton
+          class="kj-skeleton kj-skeleton--line"
+          [kjSkeletonShape]="'text'"
+          [kjSkeletonAnimation]="kjSkeletonAnimation()"
+          [style.width]="line"
+        ></span>
+      }
+    }
+  `,
+  styleUrl: './skeleton.css',
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    'class': 'kj-skeleton',
+    '[style.width]': 'kjWidth()',
+    '[style.height]': 'kjHeight()',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjSkeletonComponent {
+  /**
+   * Visual shape preset. Aliased onto the composed `KjSkeleton` directive,
+   * which reflects the value to `data-shape` on this host element.
+   */
+  readonly kjSkeletonShape = input<KjSkeletonShape>('rectangle');
+
+  /**
+   * Animation preset. Aliased onto the composed `KjSkeleton` directive,
+   * which reflects the value to `data-animation` on this host element.
+   */
+  readonly kjSkeletonAnimation = input<KjSkeletonAnimation>('shimmer');
+
+  /** Optional inline width applied as `style.width` on the host. */
+  readonly kjWidth = input<string | undefined>(undefined);
+
+  /** Optional inline height applied as `style.height` on the host. */
+  readonly kjHeight = input<string | undefined>(undefined);
+
+  /**
+   * Number of lines rendered when `kjSkeletonShape === 'text-block'`.
+   * Ignored for every other shape. Defaults to 3, with the last line at
+   * 60% width to match typographic cadence.
+   */
+  readonly kjLines = input<number>(3);
+
+  /** True when the wrapper should render its multi-line text-block template. */
+  protected readonly isTextBlock = computed(() => this.kjSkeletonShape() === 'text-block');
+
+  /**
+   * Pre-computed widths for the `text-block` line cadence: every line is
+   * `100%` except the last (when more than one line), which is `60%`.
+   */
+  protected readonly lineWidths = computed<readonly string[]>(() => {
+    const count = Math.max(1, Math.floor(this.kjLines()));
+    const widths: string[] = [];
+    for (let i = 0; i < count; i++) {
+      widths.push(i === count - 1 && count > 1 ? '60%' : '100%');
+    }
+    return widths;
+  });
+}

package/src/skeleton/skeleton.usage.example.ts

@@ -0,0 +1,49 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjSkeletonComponent } from './skeleton';
+
+/**
+ * A walkthrough of the most common skeleton usages — a circle avatar
+ * placeholder paired with stacked text lines, and a wider rectangle for a
+ * card preview. Use this as the copy-paste starting point for loading rows.
+ */
+@Component({
+  selector: 'kj-skeleton-usage-example',
+  standalone: true,
+  imports: [KjSkeletonComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-xl);
+      }
+      .row {
+        display: flex;
+        align-items: center;
+        gap: var(--kj-space-md);
+      }
+      .stack {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-xs);
+        flex: 1;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div class="row" aria-busy="true" role="status">
+      <kj-skeleton kjSkeletonShape="circle" kjWidth="2.5rem" kjHeight="2.5rem" />
+      <div class="stack">
+        <kj-skeleton kjSkeletonShape="text" kjWidth="60%" />
+        <kj-skeleton kjSkeletonShape="text" kjWidth="40%" />
+      </div>
+    </div>
+
+    <div aria-busy="true" role="status">
+      <kj-skeleton kjSkeletonShape="rectangle" kjWidth="100%" kjHeight="8rem" />
+      <kj-skeleton kjSkeletonShape="text-block" [kjLines]="3" />
+    </div>
+  `,
+})
+export class KjSkeletonUsageExample {}

package/src/slider/_examples/index.ts

@@ -0,0 +1,7 @@
+// AUTO-GENERATED by scripts/migrate-examples.mjs
+// One barrel per component folder — used by the docs app as a lazy chunk.
+export { KjSliderExample } from './slider.example';
+export { KjSliderFormattedExample } from './slider.formatted.example';
+export { KjSliderRangeExample } from './slider.range.example';
+export { KjSliderVerticalExample } from './slider.vertical.example';
+export { KjSliderWithMarksExample } from './slider.with-marks.example';

package/src/slider/_examples/slider.example.ts

@@ -0,0 +1,41 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjSliderComponent } from '../slider';
+
+/**
+ * Default usage example for KjSliderComponent.
+ *
+ * Demonstrates a single-thumb slider with the standard `0–100` range.
+ * Pointer drag, click-to-jump, and Arrow / Page / Home / End keyboard
+ * controls are wired by the directive layer.
+ */
+@Component({
+  selector: 'kj-slider-example',
+  standalone: true,
+  imports: [KjSliderComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+      .row {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-sm);
+      }
+      .value {
+        font: 0.875rem var(--kj-font-mono, monospace);
+        color: var(--kj-fg-default);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div class="row">
+      <kj-slider [(kjValue)]="volume" kjAriaLabel="Volume" />
+      <span class="value">Value: {{ volume() }}</span>
+    </div>
+  `,
+})
+export class KjSliderExample {
+  readonly volume = signal<number>(40);
+}

package/src/slider/_examples/slider.formatted.example.ts

@@ -0,0 +1,53 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjSliderComponent } from '../slider';
+
+/**
+ * `kjDisplayWith` formats the value for `aria-valuetext`, so screen
+ * readers announce `"$ 55.00"` instead of just `"55"`. Here we format a
+ * percentage with `Intl.NumberFormat`.
+ */
+@Component({
+  selector: 'kj-slider-formatted-example',
+  standalone: true,
+  imports: [KjSliderComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+      .row {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-sm);
+      }
+      .value {
+        font: 0.875rem var(--kj-font-mono, monospace);
+        color: var(--kj-fg-default);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div class="row">
+      <kj-slider
+        [(kjValue)]="cpu"
+        [kjMin]="0"
+        [kjMax]="100"
+        [kjStep]="1"
+        [kjDisplayWith]="formatPercent"
+        kjAriaLabel="CPU utilisation"
+      />
+      <span class="value">{{ formatPercent(cpu(), 0) }}</span>
+    </div>
+  `,
+})
+export class KjSliderFormattedExample {
+  readonly cpu = signal<number>(42);
+
+  /** Formats `42` as `"42 %"` using Intl.NumberFormat. */
+  readonly formatPercent = (value: number, _thumbIndex: number): string =>
+    new Intl.NumberFormat(undefined, {
+      style: 'percent',
+      maximumFractionDigits: 0,
+    }).format(value / 100);
+}

package/src/slider/_examples/slider.range.example.ts

@@ -0,0 +1,48 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjSliderComponent } from '../slider';
+
+/**
+ * Range mode: two thumbs bound to `[(kjRange)]` as a `[number, number]`
+ * tuple. `kjMinDistance` enforces a minimum gap; thumbs cannot cross by
+ * default. Each thumb has its own accessible label so screen readers can
+ * distinguish them.
+ */
+@Component({
+  selector: 'kj-slider-range-example',
+  standalone: true,
+  imports: [KjSliderComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+      .row {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-sm);
+      }
+      .value {
+        font: 0.875rem var(--kj-font-mono, monospace);
+        color: var(--kj-fg-default);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div class="row">
+      <kj-slider
+        [(kjRange)]="price"
+        [kjMin]="0"
+        [kjMax]="500"
+        [kjStep]="5"
+        [kjMinDistance]="20"
+        kjStartAriaLabel="Lowest price"
+        kjEndAriaLabel="Highest price"
+      />
+      <span class="value">\${{ price()[0] }} – \${{ price()[1] }}</span>
+    </div>
+  `,
+})
+export class KjSliderRangeExample {
+  readonly price = signal<[number, number]>([100, 350]);
+}