@kouji-ui/components 0.1.1

package/src/progress-bar/progress-bar.css

@@ -0,0 +1,113 @@
+/* ─────────────────────────────────────────────────────────────
+   .kj-progress-bar — component-layer tokens + structural CSS
+   The directive owns the value math + ARIA contract. The theme
+   only renders track + fill. Variant tokens flip the fill colour;
+   size tokens flip the bar height. The indeterminate stripe is a
+   pure CSS animation, neutralised under prefers-reduced-motion.
+   ──────────────────────────────────────────────────────────── */
+
+@layer kj.component {
+  .kj-progress-bar {
+    /* component knobs — themes/users can override any of these */
+    --kj-progress-bar-track:        var(--kj-bg-field);
+    --kj-progress-bar-fill:         var(--kj-bg-primary);
+    --kj-progress-bar-radius:       9999px;
+    --kj-progress-bar-height:       0.5rem; /* md default — 8px */
+    --kj-progress-bar-transition:   200ms ease-out;
+    --kj-progress-bar-indeterminate-duration: 1.6s;
+
+    display: block;
+    position: relative;
+    width: 100%;
+    height: var(--kj-progress-bar-height);
+    background: var(--kj-progress-bar-track);
+    border-radius: var(--kj-progress-bar-radius);
+    overflow: hidden;
+  }
+
+  /* ── Sizes ── (data-size mirrored by KjSize host directive) */
+  .kj-progress-bar[data-size="xs"] { --kj-progress-bar-height: 0.125rem; } /* 2px */
+  .kj-progress-bar[data-size="sm"] { --kj-progress-bar-height: 0.25rem; }  /* 4px */
+  .kj-progress-bar[data-size="md"] { --kj-progress-bar-height: 0.5rem; }   /* 8px */
+  .kj-progress-bar[data-size="lg"] { --kj-progress-bar-height: 0.75rem; }  /* 12px */
+
+  /* ── Variants ── (data-variant mirrored by KjVariant host directive) */
+  .kj-progress-bar[data-variant="primary"] { --kj-progress-bar-fill: var(--kj-bg-primary); }
+  .kj-progress-bar[data-variant="success"] { --kj-progress-bar-fill: var(--kj-bg-success); }
+  .kj-progress-bar[data-variant="warning"] { --kj-progress-bar-fill: var(--kj-bg-warning); }
+  .kj-progress-bar[data-variant="error"]   { --kj-progress-bar-fill: var(--kj-bg-danger); }
+
+  /* ── Fill (determinate) ──
+     The directive sets --kj-progress-fraction (0..1) on the host AND on the
+     fill. Reading from the fill is one selector hop shorter and lets us scope
+     the transition cleanly. */
+  .kj-progress-bar__fill {
+    display: block;
+    width: 100%;
+    height: 100%;
+    background: var(--kj-progress-bar-fill);
+    border-radius: inherit;
+    transform-origin: left center;
+    transform: scaleX(var(--kj-progress-fraction, 0));
+    /* Transition the fill width on value changes — but never the colour, so
+       a variant flip mid-flight is instantaneous. */
+    transition: transform var(--kj-progress-bar-transition);
+  }
+
+  /* RTL: the fill grows from the right edge. */
+  [dir="rtl"] .kj-progress-bar__fill {
+    transform-origin: right center;
+  }
+
+  /* ── Fill (indeterminate) ──
+     When data-indeterminate="true", abandon the scaleX(fraction) transform
+     and run a stripe that travels left → right. The stripe is a 50%-wide
+     coloured band on a transparent track, which gives a clean "working"
+     read on every theme without needing the track itself to animate. */
+  .kj-progress-bar__fill[data-indeterminate="true"] {
+    transform: none;
+    background: linear-gradient(
+      90deg,
+      transparent 0%,
+      var(--kj-progress-bar-fill) 50%,
+      transparent 100%
+    );
+    background-size: 50% 100%;
+    background-repeat: no-repeat;
+    animation: kj-progress-bar-indeterminate
+      var(--kj-progress-bar-indeterminate-duration) linear infinite;
+  }
+
+  @keyframes kj-progress-bar-indeterminate {
+    from { background-position: -50% 0; }
+    to   { background-position: 150% 0; }
+  }
+
+  /* ── Reduced motion ──
+     APG / WCAG 2.3.3: animations from interactions must respect
+     prefers-reduced-motion. The directive reflects data-reduced-motion;
+     we also honour the media query directly so the rule kicks in even if
+     the directive's media-query subscription hasn't run yet (SSR, very
+     early paint). The indeterminate stripe collapses to a static, dimmed
+     fill — still visible as "something is happening", just not moving. */
+  .kj-progress-bar[data-reduced-motion="reduce"] .kj-progress-bar__fill,
+  .kj-progress-bar[data-reduced-motion="reduce"] .kj-progress-bar__fill[data-indeterminate="true"] {
+    animation: none;
+    transition: none;
+  }
+  .kj-progress-bar[data-reduced-motion="reduce"] .kj-progress-bar__fill[data-indeterminate="true"] {
+    background: var(--kj-progress-bar-fill);
+    opacity: 0.6;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .kj-progress-bar__fill {
+      transition: none;
+    }
+    .kj-progress-bar__fill[data-indeterminate="true"] {
+      animation: none;
+      background: var(--kj-progress-bar-fill);
+      opacity: 0.6;
+    }
+  }
+}

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

@@ -0,0 +1,87 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { KjProgressBarComponent } from './progress-bar';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+const value = signal<number>(60);
+const min = signal<number>(0);
+const max = signal<number>(100);
+const variant = signal<'primary' | 'success' | 'warning' | 'error'>('primary');
+const size = signal<'xs' | 'sm' | 'md' | 'lg'>('md');
+const ariaValuetext = signal<string>('');
+
+@Component({
+  selector: 'kj-progress-bar-playground',
+  standalone: true,
+  imports: [KjProgressBarComponent],
+  styles: [`
+    /* The progress bar itself uses width: 100%, but the flex-centered
+       playground stage shrinks it to content size — give the host a
+       comfortable width so the bar has something to fill. */
+    :host { display: block; width: min(420px, 100%); }
+  `],
+  template: `
+    <kj-progress-bar
+      [kjValue]="value()"
+      [kjMin]="min()"
+      [kjMax]="max()"
+      [kjVariant]="variant()"
+      [kjSize]="size()"
+      [kjAriaValuetext]="ariaValuetext()"
+      kjAriaLabel="Loading progress"
+    />
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjProgressBarPlaygroundDemo {
+  protected readonly value = value;
+  protected readonly min = min;
+  protected readonly max = max;
+  protected readonly variant = variant;
+  protected readonly size = size;
+  protected readonly ariaValuetext = ariaValuetext;
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjProgressBarPlaygroundDemo,
+  state: {
+    value: value as unknown as ReturnType<typeof signal>,
+    min: min as unknown as ReturnType<typeof signal>,
+    max: max as unknown as ReturnType<typeof signal>,
+    variant: variant as unknown as ReturnType<typeof signal>,
+    size: size as unknown as ReturnType<typeof signal>,
+    ariaValuetext: ariaValuetext as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    { kind: 'number', name: 'value', label: 'value' },
+    { kind: 'number', name: 'min', label: 'min' },
+    { kind: 'number', name: 'max', label: 'max' },
+    {
+      kind: 'chips',
+      name: 'variant',
+      label: 'variant',
+      options: ['primary', 'success', 'warning', 'error'],
+    },
+    { kind: 'chips', name: 'size', label: 'size', options: ['xs', 'sm', 'md', 'lg'] },
+    { kind: 'text', name: 'ariaValuetext', label: 'aria-valuetext' },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      value: number;
+      min: number;
+      max: number;
+      variant: string;
+      size: string;
+      ariaValuetext: string;
+    };
+    const attrs: string[] = [
+      `[kjValue]="${s.value}"`,
+      `[kjMin]="${s.min}"`,
+      `[kjMax]="${s.max}"`,
+      `kjVariant="${s.variant}"`,
+      `kjSize="${s.size}"`,
+    ];
+    if (s.ariaValuetext) attrs.push(`kjAriaValuetext="${s.ariaValuetext}"`);
+    attrs.push('kjAriaLabel="Loading progress"');
+    return `<kj-progress-bar\n  ${attrs.join('\n  ')}\n/>`;
+  },
+};

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

@@ -0,0 +1,233 @@
+import { Component, signal } from '@angular/core';
+import { render } from '@testing-library/angular';
+import { describe, expect, it } from 'vitest';
+
+import { KjProgressBarComponent } from './progress-bar';
+
+const imports = [KjProgressBarComponent];
+
+/**
+ * Flush microtasks + the rAF backing `afterNextRender` so the directive has
+ * a chance to subscribe to the reduced-motion signal and write its host
+ * attributes before assertions read them.
+ */
+async function flush(): Promise<void> {
+  await new Promise<void>((resolve) => setTimeout(resolve, 0));
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+/** The wrapper's `<kj-progress-bar>` host renders `display: contents` and
+ *  delegates ARIA + value math to an inner `<div kjProgressBar>`. The inner
+ *  div is what carries `role`, the value attributes, and the data-*
+ *  reflections — that's the assertion target. */
+function getBar(container: ParentNode): HTMLElement {
+  const bar = container.querySelector('div.kj-progress-bar') as HTMLElement;
+  if (!bar) throw new Error('kj-progress-bar inner element not found');
+  return bar;
+}
+
+describe('KjProgressBarComponent', () => {
+  it('renders the wrapper with an inner [kjProgressBar] and a [kjProgressBarFill]', async () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `<kj-progress-bar [kjValue]="50" kjAriaLabel="x" />`,
+    })
+    class Host {}
+
+    const { container } = await render(Host);
+    await flush();
+
+    const wrapper = container.querySelector('kj-progress-bar') as HTMLElement;
+    expect(wrapper).toBeTruthy();
+
+    const bar = getBar(container);
+    expect(bar.getAttribute('role')).toBe('progressbar');
+
+    // Wrapper is responsible for rendering the inner fill so consumers
+    // don't have to remember the two-element shape.
+    const fill = bar.querySelector('.kj-progress-bar__fill') as HTMLElement;
+    expect(fill).toBeTruthy();
+    // Fill is the [kjProgressBarFill] directive host — it reflects the
+    // parent fraction as --kj-progress-fraction (proves wiring is intact).
+    expect(fill.style.getPropertyValue('--kj-progress-fraction')).toBe('0.5');
+  });
+
+  it('forwards kjValue: aliased input drives aria-valuenow when determinate', async () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `<kj-progress-bar [kjValue]="42" kjAriaLabel="Upload" />`,
+    })
+    class Host {}
+
+    const { container } = await render(Host);
+    await flush();
+
+    const bar = getBar(container);
+    expect(bar.getAttribute('role')).toBe('progressbar');
+    expect(bar.getAttribute('aria-valuenow')).toBe('42');
+    expect(bar.getAttribute('aria-valuemin')).toBe('0');
+    expect(bar.getAttribute('aria-valuemax')).toBe('100');
+  });
+
+  it('omits aria-valuenow when kjValue is null (indeterminate)', async () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `<kj-progress-bar [kjValue]="null" kjAriaLabel="Loading" />`,
+    })
+    class Host {}
+
+    const { container } = await render(Host);
+    await flush();
+
+    const bar = getBar(container);
+    // APG-correct: indeterminate must NOT carry aria-valuenow at all.
+    expect(bar.hasAttribute('aria-valuenow')).toBe(false);
+    expect(bar.getAttribute('data-indeterminate')).toBe('true');
+
+    // Bounds attributes are still present in indeterminate mode.
+    expect(bar.getAttribute('aria-valuemin')).toBe('0');
+    expect(bar.getAttribute('aria-valuemax')).toBe('100');
+  });
+
+  it('forwards kjMin / kjMax for absolute units', async () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `
+        <kj-progress-bar
+          [kjMin]="0"
+          [kjMax]="2500000"
+          [kjValue]="1200000"
+          kjAriaLabel="bytes"
+        />
+      `,
+    })
+    class Host {}
+
+    const { container } = await render(Host);
+    await flush();
+
+    const bar = getBar(container);
+    expect(bar.getAttribute('aria-valuemin')).toBe('0');
+    expect(bar.getAttribute('aria-valuemax')).toBe('2500000');
+    expect(bar.getAttribute('aria-valuenow')).toBe('1200000');
+  });
+
+  it('forwards kjAriaValuetext to the host', async () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `<kj-progress-bar [kjValue]="60" kjAriaValuetext="Step 3 of 5" kjAriaLabel="Onboarding" />`,
+    })
+    class Host {}
+
+    const { container } = await render(Host);
+    await flush();
+
+    const bar = getBar(container);
+    expect(bar.getAttribute('aria-valuetext')).toBe('Step 3 of 5');
+    // Visual fraction is still 60% even though SR reads the phrasing.
+    expect(bar.getAttribute('aria-valuenow')).toBe('60');
+  });
+
+  it('forwards kjVariant and kjSize through the composed directives', async () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `<kj-progress-bar [kjValue]="50" kjVariant="success" kjSize="lg" kjAriaLabel="x" />`,
+    })
+    class Host {}
+
+    const { container } = await render(Host);
+    await flush();
+
+    const bar = getBar(container);
+    expect(bar.getAttribute('data-variant')).toBe('success');
+    expect(bar.getAttribute('data-size')).toBe('lg');
+  });
+
+  it('reflects defaults when no variant/size provided (primary, md)', async () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `<kj-progress-bar [kjValue]="50" kjAriaLabel="x" />`,
+    })
+    class Host {}
+
+    const { container } = await render(Host);
+    await flush();
+
+    const bar = getBar(container);
+    expect(bar.getAttribute('data-variant')).toBe('primary');
+    expect(bar.getAttribute('data-size')).toBe('md');
+  });
+
+  it('binds kjAriaLabel to the bar', async () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `<kj-progress-bar [kjValue]="50" kjAriaLabel="Upload progress" />`,
+    })
+    class Host {}
+
+    const { container } = await render(Host);
+    await flush();
+
+    const bar = getBar(container);
+    expect(bar.getAttribute('aria-label')).toBe('Upload progress');
+  });
+
+  it('binds kjAriaLabelledby to the bar', async () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `
+        <span id="upload-heading">Upload</span>
+        <kj-progress-bar [kjValue]="50" kjAriaLabelledby="upload-heading" />
+      `,
+    })
+    class Host {}
+
+    const { container } = await render(Host);
+    await flush();
+
+    const bar = getBar(container);
+    expect(bar.getAttribute('aria-labelledby')).toBe('upload-heading');
+  });
+
+  it('switches between determinate and indeterminate reactively', async () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `<kj-progress-bar [kjValue]="value()" kjAriaLabel="x" />`,
+    })
+    class Host {
+      readonly value = signal<number | null>(30);
+    }
+
+    const { fixture } = await render(Host);
+    await flush();
+
+    const bar = getBar(fixture.nativeElement);
+    expect(bar.getAttribute('aria-valuenow')).toBe('30');
+    expect(bar.hasAttribute('data-indeterminate')).toBe(false);
+
+    fixture.componentInstance.value.set(null);
+    fixture.detectChanges();
+    await flush();
+
+    expect(bar.hasAttribute('aria-valuenow')).toBe(false);
+    expect(bar.getAttribute('data-indeterminate')).toBe('true');
+
+    fixture.componentInstance.value.set(80);
+    fixture.detectChanges();
+    await flush();
+
+    expect(bar.getAttribute('aria-valuenow')).toBe('80');
+    expect(bar.hasAttribute('data-indeterminate')).toBe(false);
+  });
+});

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

@@ -0,0 +1,155 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ViewEncapsulation,
+  input,
+} from '@angular/core';
+import { KjProgressBar, KjProgressBarFill } from '@kouji-ui/core';
+
+/**
+ * Styled wrapper around the headless `KjProgressBar` directive. Composes the
+ * core directive on an inner element and renders the inner
+ * `[kjProgressBarFill]` automatically so consumers don't have to remember
+ * the two-element shape — the component handles both halves.
+ *
+ * `kjValue: number | null` is the single mode switch — pass a number for
+ * determinate mode (the fill scales to the fraction with a CSS transition),
+ * or `null` for indeterminate mode (the fill animates as a CSS-only stripe).
+ * The directive omits `aria-valuenow` in indeterminate mode per APG. The
+ * indeterminate stripe collapses to a static state under
+ * `prefers-reduced-motion: reduce`.
+ *
+ * Variants and sizes are configurable at the directive level via
+ * `provideKjProgressBar(…)`. Defaults: `kjVariant="primary"`, `kjSize="md"`.
+ *
+ * @example
+ * ```html
+ * <kj-progress-bar [kjValue]="progress()" kjAriaLabel="Upload progress" />
+ * ```
+ *
+ * @doc-example Default
+ *   A determinate bar at 50% with an accessible label — the bare-minimum recipe.
+ *   @doc-file progress-bar.example.ts
+ * @doc-example Usage
+ *   A walkthrough of the most common usages — determinate upload,
+ *   indeterminate spinner replacement, and success completion. Use this as
+ *   the copy-paste starting point.
+ *   @doc-file progress-bar.usage.example.ts
+ * @doc-example Indeterminate
+ *   `[kjValue]="null"` runs the CSS-only stripe animation.
+ *   @doc-file progress-bar.indeterminate.example.ts
+ * @doc-example Variants
+ *   `primary` / `success` / `warning` / `error` — pick the semantic color.
+ *   @doc-file progress-bar.variants.example.ts
+ * @doc-example Sizes
+ *   `xs` / `sm` / `md` / `lg` — drives the bar thickness via CSS tokens.
+ *   @doc-file progress-bar.sizes.example.ts
+ * @doc-example With value text
+ *   Pair `kjAriaValuetext` with a visible label for richer SR phrasing.
+ *   @doc-file progress-bar.with-label.example.ts
+ *
+ * @doc-aria
+ *   role="progressbar"   — On the bar host (provided by the directive)
+ *   aria-valuenow        — Reflects the clamped numeric value; omitted in indeterminate mode
+ *   aria-valuemin        — Reflects `kjMin`
+ *   aria-valuemax        — Reflects `kjMax`
+ *   aria-valuetext       — Reflects `kjAriaValuetext` when set
+ *   aria-label           — Wired from `kjAriaLabel` (or use `kjAriaLabelledby`)
+ *   data-variant         — Mirrors the variant for theme hooks
+ *   data-size            — Mirrors the size for theme hooks
+ *   data-indeterminate   — Set when `kjValue` is null
+ *
+ * @doc-touch
+ *   The bar is non-interactive — no touch target rules apply. Pair with a
+ *   labelled cancel button (44×44) when the operation is cancellable.
+ *
+ * @doc-a11y
+ *   Always set `kjAriaLabel` or `kjAriaLabelledby` — a bare percentage
+ *   ("50 percent") with no context is useless to AT users. In indeterminate
+ *   mode the directive omits `aria-valuenow` per APG. The stripe animation
+ *   collapses under `prefers-reduced-motion: reduce`.
+ *
+ * @doc-related skeleton,spinner,toast
+ *
+ * @doc-css-var
+ *   --kj-progress-bar-track                  — Track (unfilled portion) background. Inherits --kj-bg-field.
+ *   --kj-progress-bar-fill                   — Fill color. Variants flip this per data-variant.
+ *   --kj-progress-bar-radius                 — Track and fill corner radius.
+ *   --kj-progress-bar-height                 — Bar thickness. Sizes (xs/sm/md/lg) override.
+ *   --kj-progress-bar-transition             — Transition timing for determinate fill changes.
+ *   --kj-progress-bar-indeterminate-duration — One-cycle duration of the indeterminate stripe.
+ *
+ * @doc-category Library/Feedback
+ * @doc
+ * @doc-name progress-bar
+ * @doc-description Themed determinate or indeterminate progress bar with variant and size tokens.
+ * @doc-is-main
+ */
+@Component({
+  selector: 'kj-progress-bar',
+  standalone: true,
+  imports: [KjProgressBar, KjProgressBarFill],
+  template: `
+    <div
+      kjProgressBar
+      class="kj-progress-bar"
+      [kjValue]="kjValue()"
+      [kjMin]="kjMin()"
+      [kjMax]="kjMax()"
+      [kjAriaValuetext]="kjAriaValuetext()"
+      [kjVariant]="kjVariant()"
+      [kjSize]="kjSize()"
+      [attr.aria-label]="kjAriaLabel() ?? null"
+      [attr.aria-labelledby]="kjAriaLabelledby() ?? null"
+    >
+      <div kjProgressBarFill class="kj-progress-bar__fill"></div>
+    </div>
+  `,
+  styleUrl: './progress-bar.css',
+  encapsulation: ViewEncapsulation.None,
+  host: { 'style': 'display: contents;' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjProgressBarComponent {
+  /**
+   * Current progress value. `null` = indeterminate (the directive omits
+   * `aria-valuenow` and runs the indeterminate stripe). Out-of-range values
+   * clamp to `[kjMin, kjMax]` with a dev-mode warning.
+   * @default null
+   */
+  readonly kjValue = input<number>(0);
+
+  /** Lower bound, bound to `aria-valuemin`. @default 0 */
+  readonly kjMin = input<number>(0);
+
+  /** Upper bound, bound to `aria-valuemax`. Must be `> kjMin`. @default 100 */
+  readonly kjMax = input<number>(100);
+
+  /**
+   * Human-readable phrasing reflected to `aria-valuetext`. Use when the raw
+   * percentage is less meaningful — `"Step 3 of 5"`, `"1.2 MB of 2.5 MB"`.
+   */
+  readonly kjAriaValuetext = input<string>('');
+
+  /**
+   * Variant — one of the configured presets (`primary` | `success` |
+   * `warning` | `error` by default). @default 'primary'
+   */
+  readonly kjVariant = input<string>('primary');
+
+  /**
+   * Size — one of the configured presets (`xs` | `sm` | `md` | `lg` by
+   * default). Drives the bar height. @default 'md'
+   */
+  readonly kjSize = input<string>('md');
+
+  /**
+   * Accessible label for the bar. At least one of `kjAriaLabel` or
+   * `kjAriaLabelledby` must be set — a progress bar without a name announces
+   * as just *"50 percent"*, which is useless to screen-reader users.
+   */
+  readonly kjAriaLabel = input<string>('');
+
+  /** ID reference for the bar's accessible name. See `kjAriaLabel`. */
+  readonly kjAriaLabelledby = input<string>('');
+}

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

@@ -0,0 +1,52 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjProgressBarComponent } from './progress-bar';
+
+/**
+ * A walkthrough of the most common progress-bar usages — a determinate
+ * upload bar with `aria-valuetext`, an indeterminate spinner replacement,
+ * and a success-variant complete state. Use this as the copy-paste starting
+ * point for feedback rows.
+ */
+@Component({
+  selector: 'kj-progress-bar-usage-example',
+  standalone: true,
+  imports: [KjProgressBarComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-lg);
+      }
+      .label {
+        font-size: 0.75rem;
+        color: var(--kj-fg-default);
+        opacity: 0.7;
+        text-transform: uppercase;
+        letter-spacing: 0.04em;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div>
+      <span class="label">Uploading (determinate)</span>
+      <kj-progress-bar
+        [kjValue]="progress()"
+        kjAriaLabel="Upload progress"
+        [kjAriaValuetext]="progress() + ' percent uploaded'"
+      />
+    </div>
+    <div>
+      <span class="label">Working (indeterminate)</span>
+      <kj-progress-bar [kjValue]="null!" kjAriaLabel="Working" />
+    </div>
+    <div>
+      <span class="label">Complete (success)</span>
+      <kj-progress-bar [kjValue]="100" kjVariant="success" kjSize="lg" kjAriaLabel="Done" />
+    </div>
+  `,
+})
+export class KjProgressBarUsageExample {
+  readonly progress = signal<number>(62);
+}