@kouji-ui/components 0.1.1

package/src/playground-types.ts

@@ -0,0 +1,47 @@
+/**
+ * Re-export of the playground type module from the docs app — lives at
+ * `@kouji-ui/components/playground-types` so per-component playground files
+ * inside this package can import `PlaygroundFile` / `ControlSpec` without a
+ * back-reference into the docs workspace.
+ *
+ * The source of truth lives at:
+ *   apps/docs/src/app/pages/component-doc/playground-types.ts
+ *
+ * Keeping the types here as a *copy* (not a re-export) avoids a circular
+ * dependency: docs → components → docs.
+ */
+import type { Type, WritableSignal } from '@angular/core';
+
+export type ControlSpec =
+  | {
+      kind: 'chips';
+      name: string;
+      label: string;
+      options: readonly (string | number)[];
+    }
+  | {
+      kind: 'toggle';
+      name: string;
+      label: string;
+    }
+  | {
+      kind: 'text';
+      name: string;
+      label: string;
+      placeholder?: string;
+    }
+  | {
+      kind: 'number';
+      name: string;
+      label: string;
+      min?: number;
+      max?: number;
+      step?: number;
+    };
+
+export interface PlaygroundFile {
+  readonly component: Type<unknown>;
+  readonly state: Record<string, WritableSignal<unknown>>;
+  readonly controls: readonly ControlSpec[];
+  readonly snippet: (values: Record<string, unknown>) => string;
+}

package/src/popover/_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 { KjPopoverCancellableExample } from './popover.cancellable.example';
+export { KjPopoverExample } from './popover.example';
+export { KjPopoverModalExample } from './popover.modal.example';
+export { KjPopoverSidesExample } from './popover.sides.example';
+export { KjPopoverWithFormExample } from './popover.with-form.example';

package/src/popover/_examples/popover.cancellable.example.ts

@@ -0,0 +1,20 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjPopoverTrigger, KjPopoverContent, KjPopoverTitle, KjPopoverClose } from '@kouji-ui/core';
+import { KjButtonComponent } from '../../button/button';
+
+// TODO(wrapper-overlay): cancellable close needs new event hook on overlay primitives.
+@Component({
+  selector: 'kj-popover-cancellable-example',
+  standalone: true,
+  imports: [KjPopoverTrigger, KjPopoverContent, KjPopoverTitle, KjPopoverClose, KjButtonComponent],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-button kjPopoverTrigger #t="kjPopoverTrigger">Edit profile</kj-button>
+    <kj-popover-content [kjFor]="t">
+      <h3 kjPopoverTitle>Edit profile</h3>
+      <p>Pretend there is a form here.</p>
+      <kj-button kjPopoverClose>Close</kj-button>
+    </kj-popover-content>
+  `,
+})
+export class KjPopoverCancellableExample {}

package/src/popover/_examples/popover.example.ts

@@ -0,0 +1,20 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjPopoverTrigger, KjPopoverContent, KjPopoverTitle, KjPopoverClose } from '@kouji-ui/core';
+import { KjButtonComponent } from '../../button/button';
+
+// TODO(wrapper-overlay): re-skin via wrapper layer once styled overlay components land.
+@Component({
+  selector: 'kj-popover-example',
+  standalone: true,
+  imports: [KjPopoverTrigger, KjPopoverContent, KjPopoverTitle, KjPopoverClose, KjButtonComponent],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-button kjPopoverTrigger #t="kjPopoverTrigger">Open popover</kj-button>
+    <kj-popover-content [kjFor]="t">
+      <h3 kjPopoverTitle>Notification settings</h3>
+      <p>Control how and when you receive notifications.</p>
+      <kj-button kjPopoverClose>Close</kj-button>
+    </kj-popover-content>
+  `,
+})
+export class KjPopoverExample {}

package/src/popover/_examples/popover.modal.example.ts

@@ -0,0 +1,22 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjPopoverTrigger, KjPopoverContent, KjPopoverTitle, KjPopoverClose } from '@kouji-ui/core';
+import { KjButtonComponent } from '../../button/button';
+
+// TODO(wrapper-overlay): modal flag flows via core overlay-panel inputs.
+@Component({
+  selector: 'kj-popover-modal-example',
+  standalone: true,
+  imports: [KjPopoverTrigger, KjPopoverContent, KjPopoverTitle, KjPopoverClose, KjButtonComponent],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-button kjPopoverTrigger #t="kjPopoverTrigger" kjVariant="destructive"
+      >Delete account</kj-button
+    >
+    <kj-popover-content [kjFor]="t" [kjTrap]="true">
+      <h3 kjPopoverTitle>Delete account?</h3>
+      <p>This action is permanent.</p>
+      <kj-button kjPopoverClose kjVariant="destructive">Delete</kj-button>
+    </kj-popover-content>
+  `,
+})
+export class KjPopoverModalExample {}

package/src/popover/_examples/popover.sides.example.ts

@@ -0,0 +1,37 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjPopoverTrigger, KjPopoverContent, KjPopoverTitle, KjPopoverArrow } from '@kouji-ui/core';
+import { KjButtonComponent } from '../../button/button';
+
+// TODO(wrapper-overlay): re-skin sides demo.
+@Component({
+  selector: 'kj-popover-sides-example',
+  standalone: true,
+  imports: [KjPopoverTrigger, KjPopoverContent, KjPopoverTitle, KjPopoverArrow, KjButtonComponent],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-button kjPopoverTrigger #top="kjPopoverTrigger">Top</kj-button>
+    <kj-popover-content [kjFor]="top" kjSide="top"
+      ><h3 kjPopoverTitle>Top</h3>
+      <span kjPopoverArrow></span
+    ></kj-popover-content>
+
+    <kj-button kjPopoverTrigger #right="kjPopoverTrigger">Right</kj-button>
+    <kj-popover-content [kjFor]="right" kjSide="right"
+      ><h3 kjPopoverTitle>Right</h3>
+      <span kjPopoverArrow></span
+    ></kj-popover-content>
+
+    <kj-button kjPopoverTrigger #bottom="kjPopoverTrigger">Bottom</kj-button>
+    <kj-popover-content [kjFor]="bottom" kjSide="bottom"
+      ><h3 kjPopoverTitle>Bottom</h3>
+      <span kjPopoverArrow></span
+    ></kj-popover-content>
+
+    <kj-button kjPopoverTrigger #left="kjPopoverTrigger">Left</kj-button>
+    <kj-popover-content [kjFor]="left" kjSide="left"
+      ><h3 kjPopoverTitle>Left</h3>
+      <span kjPopoverArrow></span
+    ></kj-popover-content>
+  `,
+})
+export class KjPopoverSidesExample {}

package/src/popover/_examples/popover.with-form.example.ts

@@ -0,0 +1,38 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjPopoverTrigger, KjPopoverContent, KjPopoverTitle, KjPopoverClose } from '@kouji-ui/core';
+import { KjButtonComponent } from '../../button/button';
+import { KjInputComponent } from '../../input/input';
+import { KjFieldComponent, KjFieldLabelComponent } from '../../field/field';
+
+@Component({
+  selector: 'kj-popover-with-form-example',
+  standalone: true,
+  imports: [
+    KjPopoverTrigger,
+    KjPopoverContent,
+    KjPopoverTitle,
+    KjPopoverClose,
+    KjButtonComponent,
+    KjInputComponent,
+    KjFieldComponent,
+    KjFieldLabelComponent,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-button kjPopoverTrigger #t="kjPopoverTrigger">Edit profile</kj-button>
+    <kj-popover-content [kjFor]="t">
+      <h3 kjPopoverTitle>Edit profile</h3>
+      <kj-field>
+        <kj-field-label>Display name</kj-field-label>
+        <kj-input placeholder="Jane Doe" />
+      </kj-field>
+      <div
+        style="display: flex; gap: var(--kj-space-sm); justify-content: flex-end; margin-top: var(--kj-space-md);"
+      >
+        <kj-button kjPopoverClose kjVariant="ghost">Cancel</kj-button>
+        <kj-button kjPopoverClose>Save</kj-button>
+      </div>
+    </kj-popover-content>
+  `,
+})
+export class KjPopoverWithFormExample {}

package/src/popover/index.ts

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

package/src/popover/popover.css

@@ -0,0 +1,71 @@
+@layer kj.component {
+  /* The wrapper hosts use display: contents — they don't add a box. The
+     panel is portal-mounted to <body> by the underlying directive; the
+     `.kj-popover-content` class lands on the panel via `kjPanelClass`. */
+
+  .kj-popover-content {
+    --kj-popover-bg:           var(--kj-bg-elevated);
+    --kj-popover-fg:           var(--kj-fg-default);
+    --kj-popover-border-color: var(--kj-border-default);
+    --kj-popover-radius:       var(--kj-radius-box);
+    --kj-popover-padding-x:    var(--kj-space-md);
+    --kj-popover-padding-y:    var(--kj-space-md);
+    --kj-popover-shadow:       var(--kj-shadow-md, 0 12px 32px rgb(0 0 0 / 0.18));
+    --kj-popover-arrow-size:   8px;
+
+    /* Layout — the directive applies position: fixed and writes top/left. */
+    display: block;
+    box-sizing: border-box;
+    max-width: min(28rem, calc(100vw - 2rem));
+    background: var(--kj-popover-bg);
+    color: var(--kj-popover-fg);
+    border: var(--kj-border) solid var(--kj-popover-border-color);
+    border-radius: var(--kj-popover-radius);
+    padding: var(--kj-popover-padding-y) var(--kj-popover-padding-x);
+    font: 0.875rem / 1.5 var(--kj-font-sans);
+    box-shadow: var(--kj-popover-shadow);
+    pointer-events: auto;
+    z-index: 1000;
+    word-wrap: break-word;
+  }
+
+  .kj-popover-content[hidden] { display: none; }
+
+  .kj-popover-title {
+    display: block;
+    font-size: 0.9375rem;
+    font-weight: 600;
+    margin: 0 0 var(--kj-space-xs);
+    color: var(--kj-fg-default);
+  }
+
+  /* Arrow positioning relative to the panel's resolved data-side. */
+  .kj-popover-arrow {
+    position: absolute;
+    width: var(--kj-popover-arrow-size, 8px);
+    height: var(--kj-popover-arrow-size, 8px);
+    background: var(--kj-popover-bg, var(--kj-bg-elevated));
+    border: var(--kj-border) solid var(--kj-popover-border-color, var(--kj-border-default));
+    transform: rotate(45deg);
+  }
+
+  .kj-popover-content[data-side="top"]    .kj-popover-arrow { bottom: calc(var(--kj-popover-arrow-size) / -2); left: 50%; margin-left: calc(var(--kj-popover-arrow-size) / -2); border-top-color: transparent; border-left-color: transparent; }
+  .kj-popover-content[data-side="bottom"] .kj-popover-arrow { top:    calc(var(--kj-popover-arrow-size) / -2); left: 50%; margin-left: calc(var(--kj-popover-arrow-size) / -2); border-bottom-color: transparent; border-right-color: transparent; }
+  .kj-popover-content[data-side="left"]   .kj-popover-arrow { right:  calc(var(--kj-popover-arrow-size) / -2); top:  50%; margin-top:  calc(var(--kj-popover-arrow-size) / -2); border-left-color: transparent; border-bottom-color: transparent; }
+  .kj-popover-content[data-side="right"]  .kj-popover-arrow { left:   calc(var(--kj-popover-arrow-size) / -2); top:  50%; margin-top:  calc(var(--kj-popover-arrow-size) / -2); border-right-color: transparent; border-top-color: transparent; }
+
+  /* Modal-mode body scroll lock. Multiple stacked modals coordinate via
+     a counter in KjOverlayService; this just hides body overflow when the
+     attribute is present. */
+  body[data-kj-scroll-lock="true"] {
+    overflow: hidden;
+  }
+
+  @media (prefers-reduced-motion: no-preference) {
+    .kj-popover-content {
+      transition: opacity 140ms ease-out, transform 140ms ease-out;
+    }
+    .kj-popover-content[data-state="closed"] { opacity: 0; transform: scale(0.98); }
+    .kj-popover-content[data-state="open"]   { opacity: 1; transform: scale(1); }
+  }
+}

package/src/popover/popover.playground.ts

@@ -0,0 +1,86 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import {
+  KjPopoverTrigger,
+  KjPopoverContent,
+  KjPopoverTitle,
+  KjPopoverClose,
+} from './popover';
+import { KjButtonComponent } from '../button/button';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+type KjPopoverSide = 'top' | 'right' | 'bottom' | 'left';
+type KjPopoverAlign = 'start' | 'center' | 'end';
+
+const triggerLabel = signal<string>('Open popover');
+const title = signal<string>('Notification settings');
+const body = signal<string>('Control how and when you receive notifications.');
+const side = signal<KjPopoverSide>('bottom');
+const align = signal<KjPopoverAlign>('center');
+const showClose = signal(true);
+
+@Component({
+  selector: 'kj-popover-playground',
+  standalone: true,
+  imports: [
+    KjButtonComponent,
+    KjPopoverTrigger,
+    KjPopoverContent,
+    KjPopoverTitle,
+    KjPopoverClose,
+  ],
+  template: `
+    <kj-button kjPopoverTrigger #t="kjPopoverTrigger">{{ triggerLabel() }}</kj-button>
+    <kj-popover-content
+      [kjFor]="t"
+      [kjSide]="side()"
+      [kjAlign]="align()"
+    >
+      <h3 kjPopoverTitle>{{ title() }}</h3>
+      <p>{{ body() }}</p>
+      @if (showClose()) {
+        <kj-button kjPopoverClose>Close</kj-button>
+      }
+    </kj-popover-content>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjPopoverPlaygroundDemo {
+  protected readonly triggerLabel = triggerLabel;
+  protected readonly title = title;
+  protected readonly body = body;
+  protected readonly side = side;
+  protected readonly align = align;
+  protected readonly showClose = showClose;
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjPopoverPlaygroundDemo,
+  state: {
+    triggerLabel: triggerLabel as unknown as ReturnType<typeof signal>,
+    title: title as unknown as ReturnType<typeof signal>,
+    body: body as unknown as ReturnType<typeof signal>,
+    side: side as unknown as ReturnType<typeof signal>,
+    align: align as unknown as ReturnType<typeof signal>,
+    showClose: showClose as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    { kind: 'text', name: 'triggerLabel', label: 'trigger label' },
+    { kind: 'text', name: 'title', label: 'title' },
+    { kind: 'text', name: 'body', label: 'body' },
+    { kind: 'chips', name: 'side', label: 'side', options: ['top', 'right', 'bottom', 'left'] },
+    { kind: 'chips', name: 'align', label: 'align', options: ['start', 'center', 'end'] },
+    { kind: 'toggle', name: 'showClose', label: 'show close button' },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      triggerLabel: string;
+      title: string;
+      body: string;
+      side: string;
+      align: string;
+      showClose: boolean;
+    };
+    const closeMarkup = s.showClose ? `\n  <kj-button kjPopoverClose>Close</kj-button>` : '';
+    return `<kj-button kjPopoverTrigger #t="kjPopoverTrigger">${s.triggerLabel}</kj-button>\n<kj-popover-content [kjFor]="t" kjSide="${s.side}" kjAlign="${s.align}">\n  <h3 kjPopoverTitle>${s.title}</h3>\n  <p>${s.body}</p>${closeMarkup}\n</kj-popover-content>`;
+  },
+};

package/src/popover/popover.spec.ts

@@ -0,0 +1,5 @@
+import { describe, it } from 'vitest';
+
+describe('KjPopover (wrapper)', () => {
+  it.todo('rewrite for new overlay API (KjPopoverTrigger / KjPopoverContent primitives)');
+});

package/src/popover/popover.ts

@@ -0,0 +1,94 @@
+import { ChangeDetectionStrategy, Component, ViewEncapsulation } from '@angular/core';
+import {
+  KjPopoverTrigger,
+  KjPopoverContent,
+  KjPopoverArrow,
+  KjPopoverClose,
+  KjPopoverTitle,
+} from '@kouji-ui/core';
+
+export {
+  KjPopoverTrigger,
+  KjPopoverContent,
+  KjPopoverArrow,
+  KjPopoverClose,
+  KjPopoverTitle,
+} from '@kouji-ui/core';
+
+/**
+ * Click-triggered popover. Compose `[kjPopoverTrigger]` + `<kj-popover-content [kjFor]="t">`
+ * with optional `[kjPopoverTitle]` heading and `[kjPopoverClose]` button. The
+ * wrapper itself only projects content — its purpose is to host the docs tags.
+ *
+ * @doc
+ * @doc-name popover
+ * @doc-is-main
+ * @doc-example Default
+ *   A trigger button + content panel — the bare-minimum recipe.
+ *   @doc-file popover.example.ts
+ * @doc-example Usage
+ *   A walkthrough of the most common usages — info panel, side-pinned, and
+ *   modal confirmation. Use this as the copy-paste starting point.
+ *   @doc-file popover.usage.example.ts
+ * @doc-example Sides
+ *   `kjSide="top|right|bottom|left"` pins the panel relative to the trigger.
+ *   @doc-file popover.sides.example.ts
+ * @doc-example Modal
+ *   `[kjTrap]="true"` traps focus inside the panel until it closes.
+ *   @doc-file popover.modal.example.ts
+ * @doc-example Cancellable
+ *   `[kjPopoverClose]` on a button dismisses the panel and restores focus.
+ *   @doc-file popover.cancellable.example.ts
+ * @doc-example With form
+ *   Embed inputs inside the panel — focus returns to the trigger on close.
+ *   @doc-file popover.with-form.example.ts
+ *
+ * @doc-keyboard
+ *   Enter|Space     — Opens the popover from the trigger
+ *   Escape          — Closes the popover and returns focus to the trigger
+ *   Tab             — Moves focus through the panel; cycles inside when [kjTrap]="true"
+ *   Shift+Tab       — Reverse-cycles focus
+ *
+ * @doc-aria
+ *   aria-haspopup   — Set to "dialog" on the trigger
+ *   aria-expanded   — Reflects the open/closed state on the trigger
+ *   aria-controls   — Links the trigger to the panel id
+ *   role="dialog"   — On the panel (provided via the overlay primitive)
+ *   aria-labelledby — Wire to `[kjPopoverTitle]` heading id for an accessible name
+ *
+ * @doc-touch
+ *   Trigger buttons inherit `kj-button` sizing — use `kjSize="md"` or larger
+ *   to satisfy WCAG 2.5.5 (44×44). The panel itself is not a touch target.
+ *
+ * @doc-a11y
+ *   The panel is portalled to `document.body` so it escapes clipping
+ *   ancestors while staying linked via `aria-controls`. Focus is returned
+ *   to the trigger on close, and outside clicks dismiss by default. For
+ *   destructive confirmations, set `[kjTrap]="true"` so the user must
+ *   commit or cancel via a visible affordance.
+ *
+ * @doc-related dialog,tooltip,dropdown-menu
+ *
+ * @doc-css-var
+ *   --kj-popover-bg            — Panel background fill. Inherits --kj-bg-elevated.
+ *   --kj-popover-fg            — Panel foreground (text) color.
+ *   --kj-popover-border-color  — Panel border color. Inherits --kj-border-default.
+ *   --kj-popover-radius        — Panel corner radius. Inherits --kj-radius-box.
+ *   --kj-popover-padding-x     — Horizontal padding inside the panel.
+ *   --kj-popover-padding-y     — Vertical padding inside the panel.
+ *   --kj-popover-shadow        — Drop shadow under the panel. Inherits --kj-shadow-md.
+ *   --kj-popover-arrow-size    — Edge length of the optional arrow indicator.
+ *
+ * @doc-category Library/Overlay
+ */
+@Component({
+  selector: 'kj-popover',
+  standalone: true,
+  imports: [KjPopoverTrigger, KjPopoverContent, KjPopoverArrow, KjPopoverClose, KjPopoverTitle],
+  template: `<ng-content />`,
+  styleUrl: './popover.css',
+  encapsulation: ViewEncapsulation.None,
+  host: { style: 'display: contents;' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjPopoverComponent {}

package/src/popover/popover.usage.example.ts

@@ -0,0 +1,48 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjPopoverTrigger, KjPopoverContent, KjPopoverTitle, KjPopoverClose } from '@kouji-ui/core';
+import { KjButtonComponent } from '../button/button';
+
+/**
+ * A walkthrough of the most common popover usages — a default info panel, a
+ * side-pinned variant, and a modal confirmation. Use this as the copy-paste
+ * starting point for inline contextual UI.
+ */
+@Component({
+  selector: 'kj-popover-usage-example',
+  standalone: true,
+  imports: [KjPopoverTrigger, KjPopoverContent, KjPopoverTitle, KjPopoverClose, KjButtonComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        gap: var(--kj-space-md);
+        flex-wrap: wrap;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-button kjPopoverTrigger #info="kjPopoverTrigger">Settings</kj-button>
+    <kj-popover-content [kjFor]="info">
+      <h3 kjPopoverTitle>Notification settings</h3>
+      <p>Control how and when you receive notifications.</p>
+      <kj-button kjPopoverClose>Done</kj-button>
+    </kj-popover-content>
+
+    <kj-button kjPopoverTrigger #right="kjPopoverTrigger" kjVariant="ghost">Help</kj-button>
+    <kj-popover-content [kjFor]="right" kjSide="right">
+      <h3 kjPopoverTitle>Quick tip</h3>
+      <p>Use ⌘K to open the command palette.</p>
+    </kj-popover-content>
+
+    <kj-button kjPopoverTrigger #danger="kjPopoverTrigger" kjVariant="destructive"
+      >Delete</kj-button
+    >
+    <kj-popover-content [kjFor]="danger" [kjTrap]="true">
+      <h3 kjPopoverTitle>Delete this item?</h3>
+      <p>This action cannot be undone.</p>
+      <kj-button kjPopoverClose kjVariant="destructive">Delete</kj-button>
+    </kj-popover-content>
+  `,
+})
+export class KjPopoverUsageExample {}

package/src/progress-bar/_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 { KjProgressBarExample } from './progress-bar.example';
+export { KjProgressBarIndeterminateExample } from './progress-bar.indeterminate.example';
+export { KjProgressBarSizesExample } from './progress-bar.sizes.example';
+export { KjProgressBarVariantsExample } from './progress-bar.variants.example';
+export { KjProgressBarWithLabelExample } from './progress-bar.with-label.example';

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

@@ -0,0 +1,22 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjProgressBarComponent } from '../progress-bar';
+
+/**
+ * Default usage example for KjProgressBarComponent.
+ * A determinate bar at 50%, with an accessible label.
+ */
+@Component({
+  selector: 'kj-progress-bar-example',
+  standalone: true,
+  imports: [KjProgressBarComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: ` <kj-progress-bar [kjValue]="50" kjAriaLabel="Upload progress" /> `,
+})
+export class KjProgressBarExample {}

package/src/progress-bar/_examples/progress-bar.indeterminate.example.ts

@@ -0,0 +1,23 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjProgressBarComponent } from '../progress-bar';
+
+/**
+ * Indeterminate progress bar — `kjValue` is `null`, the bar shows the
+ * CSS-animated stripe, and `aria-valuenow` is omitted from the DOM
+ * (APG-correct for *"working, no measurable progress"*).
+ */
+@Component({
+  selector: 'kj-progress-bar-indeterminate-example',
+  standalone: true,
+  imports: [KjProgressBarComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: ` <kj-progress-bar kjAriaLabel="Loading" /> `,
+})
+export class KjProgressBarIndeterminateExample {}

package/src/progress-bar/_examples/progress-bar.sizes.example.ts

@@ -0,0 +1,29 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjProgressBarComponent } from '../progress-bar';
+
+/**
+ * Size gallery — `xs`, `sm`, `md`, `lg`. Size only changes the bar height;
+ * the value math and ARIA contract are identical across sizes.
+ */
+@Component({
+  selector: 'kj-progress-bar-sizes-example',
+  standalone: true,
+  imports: [KjProgressBarComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-md);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-progress-bar [kjValue]="50" kjSize="xs" kjAriaLabel="Extra small" />
+    <kj-progress-bar [kjValue]="50" kjSize="sm" kjAriaLabel="Small" />
+    <kj-progress-bar [kjValue]="50" kjSize="md" kjAriaLabel="Medium" />
+    <kj-progress-bar [kjValue]="50" kjSize="lg" kjAriaLabel="Large" />
+  `,
+})
+export class KjProgressBarSizesExample {}

package/src/progress-bar/_examples/progress-bar.variants.example.ts

@@ -0,0 +1,30 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjProgressBarComponent } from '../progress-bar';
+
+/**
+ * Variant gallery — `primary`, `success`, `warning`, `error` at 50%.
+ * Variant communicates *kind* (success/error/etc.); the fill *length* is
+ * what communicates progress. Colour is never the only signal.
+ */
+@Component({
+  selector: 'kj-progress-bar-variants-example',
+  standalone: true,
+  imports: [KjProgressBarComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-md);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-progress-bar [kjValue]="50" kjVariant="primary" kjAriaLabel="Primary" />
+    <kj-progress-bar [kjValue]="50" kjVariant="success" kjAriaLabel="Success" />
+    <kj-progress-bar [kjValue]="50" kjVariant="warning" kjAriaLabel="Warning" />
+    <kj-progress-bar [kjValue]="50" kjVariant="error" kjAriaLabel="Error" />
+  `,
+})
+export class KjProgressBarVariantsExample {}

package/src/progress-bar/_examples/progress-bar.with-label.example.ts

@@ -0,0 +1,30 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjProgressBarComponent } from '../progress-bar';
+
+/**
+ * Human-readable phrasing via `kjAriaValuetext` — the bar visually shows
+ * 60%, but assistive technology reads *"Step 3 of 5"* (APG-recommended for
+ * cases where the raw percentage is less meaningful than a step count or
+ * remaining-time phrasing).
+ */
+@Component({
+  selector: 'kj-progress-bar-with-label-example',
+  standalone: true,
+  imports: [KjProgressBarComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-progress-bar
+      [kjValue]="60"
+      kjAriaValuetext="Step 3 of 5"
+      kjAriaLabel="Onboarding progress"
+    />
+  `,
+})
+export class KjProgressBarWithLabelExample {}

package/src/progress-bar/index.ts

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