@kouji-ui/components 0.1.1

package/src/accordion/accordion.playground.ts

@@ -0,0 +1,119 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import {
+  KjAccordionComponent,
+  KjAccordionItemComponent,
+  KjAccordionContentComponent,
+} from './accordion';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+/**
+ * Playground state — module-scope signals. Knobs let the user change the
+ * accordion's behaviour mode, item count, default open value, and disable
+ * the middle item to demonstrate skip behaviour in keyboard navigation.
+ */
+const type = signal<'single' | 'multiple'>('single');
+const itemCount = signal<3 | 4 | 5>(3);
+const openValue = signal<'none' | 'one' | 'two' | 'three'>('none');
+const arrowNavigation = signal(false);
+const disableMiddle = signal(false);
+
+const ITEMS: ReadonlyArray<{ value: string; label: string; body: string }> = [
+  { value: 'one', label: 'What is kouji-ui?', body: 'A headless-first component library for Angular.' },
+  { value: 'two', label: 'Is it free?', body: 'Yes — MIT licensed.' },
+  { value: 'three', label: 'Does it support theming?', body: 'Themes are CSS-variable driven; swap tokens at the host element.' },
+  { value: 'four', label: 'Is it accessible?', body: 'WAI-ARIA APG patterns are baked in; targets WCAG 2.1 AAA.' },
+  { value: 'five', label: 'How do I install?', body: 'pnpm add @kouji-ui/components @kouji-ui/core.' },
+];
+
+@Component({
+  selector: 'kj-accordion-playground',
+  standalone: true,
+  imports: [
+    KjAccordionComponent,
+    KjAccordionItemComponent,
+    KjAccordionContentComponent,
+  ],
+  template: `
+    <kj-accordion
+      [type]="type()"
+      [arrowNavigation]="arrowNavigation()"
+      [value]="resolvedValue()"
+    >
+      @for (item of visibleItems(); track item.value; let i = $index) {
+        <kj-accordion-item
+          [value]="item.value"
+          [label]="item.label"
+          [disabled]="disableMiddle() && i === 1"
+        >
+          <kj-accordion-content>{{ item.body }}</kj-accordion-content>
+        </kj-accordion-item>
+      }
+    </kj-accordion>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjAccordionPlaygroundDemo {
+  protected readonly type = type;
+  protected readonly itemCount = itemCount;
+  protected readonly openValue = openValue;
+  protected readonly arrowNavigation = arrowNavigation;
+  protected readonly disableMiddle = disableMiddle;
+
+  protected visibleItems(): typeof ITEMS {
+    return ITEMS.slice(0, itemCount());
+  }
+
+  protected resolvedValue(): string | string[] {
+    const v = openValue();
+    if (type() === 'multiple') return v === 'none' ? [] : [v];
+    return v === 'none' ? '' : v;
+  }
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjAccordionPlaygroundDemo,
+  state: {
+    type: type as unknown as ReturnType<typeof signal>,
+    itemCount: itemCount as unknown as ReturnType<typeof signal>,
+    openValue: openValue as unknown as ReturnType<typeof signal>,
+    arrowNavigation: arrowNavigation as unknown as ReturnType<typeof signal>,
+    disableMiddle: disableMiddle as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    { kind: 'chips', name: 'type', label: 'type', options: ['single', 'multiple'] },
+    { kind: 'chips', name: 'itemCount', label: 'items', options: [3, 4, 5] },
+    {
+      kind: 'chips',
+      name: 'openValue',
+      label: 'open',
+      options: ['none', 'one', 'two', 'three'],
+    },
+    { kind: 'toggle', name: 'arrowNavigation', label: 'arrow navigation' },
+    { kind: 'toggle', name: 'disableMiddle', label: 'disable middle item' },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      type: string;
+      itemCount: number;
+      openValue: string;
+      arrowNavigation: boolean;
+      disableMiddle: boolean;
+    };
+    const attrs: string[] = [`type="${s.type}"`];
+    if (s.arrowNavigation) attrs.push('[arrowNavigation]="true"');
+    if (s.openValue !== 'none') {
+      attrs.push(
+        s.type === 'multiple'
+          ? `[value]="['${s.openValue}']"`
+          : `value="${s.openValue}"`,
+      );
+    }
+    const items = ITEMS.slice(0, s.itemCount)
+      .map((item, i) => {
+        const disabled = s.disableMiddle && i === 1 ? ' [disabled]="true"' : '';
+        return `  <kj-accordion-item value="${item.value}" label="${item.label}"${disabled}>\n    <kj-accordion-content>${item.body}</kj-accordion-content>\n  </kj-accordion-item>`;
+      })
+      .join('\n');
+    return `<kj-accordion\n  ${attrs.join('\n  ')}\n>\n${items}\n</kj-accordion>`;
+  },
+};

package/src/accordion/accordion.spec.ts

@@ -0,0 +1,117 @@
+import { Component, signal } from '@angular/core';
+import { fireEvent, render } from '@testing-library/angular';
+
+import {
+  KjAccordionComponent,
+  KjAccordionContentComponent,
+  KjAccordionItemComponent,
+  KjAccordionTriggerComponent,
+} from './accordion';
+
+const imports = [
+  KjAccordionComponent,
+  KjAccordionItemComponent,
+  KjAccordionTriggerComponent,
+  KjAccordionContentComponent,
+];
+
+async function flush(): Promise<void> {
+  await new Promise<void>((resolve) => setTimeout(resolve, 0));
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+describe('KjAccordionComponent', () => {
+  it('renders the wrapper class on the host', async () => {
+    const { container } = await render(
+      `<kj-accordion>
+        <kj-accordion-item value="a" label="A"><kj-accordion-content>A body</kj-accordion-content></kj-accordion-item>
+      </kj-accordion>`,
+      { imports },
+    );
+    const root = container.querySelector('kj-accordion') as HTMLElement;
+    expect(root.classList.contains('kj-accordion')).toBe(true);
+  });
+
+  it('forwards `type="multiple"` to the directive (both items can open)', async () => {
+    const { container } = await render(
+      `<kj-accordion type="multiple">
+        <kj-accordion-item value="a" label="A"><kj-accordion-content>A</kj-accordion-content></kj-accordion-item>
+        <kj-accordion-item value="b" label="B"><kj-accordion-content>B</kj-accordion-content></kj-accordion-item>
+      </kj-accordion>`,
+      { imports },
+    );
+    const triggers = container.querySelectorAll<HTMLButtonElement>('button.kj-accordion-trigger');
+    fireEvent.click(triggers[0]);
+    fireEvent.click(triggers[1]);
+    expect(triggers[0]).toHaveAttribute('aria-expanded', 'true');
+    expect(triggers[1]).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  it('wires aria-controls / aria-labelledby through the wrapper', async () => {
+    const { container } = await render(
+      `<kj-accordion>
+        <kj-accordion-item value="x" label="X"><kj-accordion-content>Body</kj-accordion-content></kj-accordion-item>
+      </kj-accordion>`,
+      { imports },
+    );
+    const trigger = container.querySelector<HTMLElement>('button.kj-accordion-trigger')!;
+    const content = container.querySelector<HTMLElement>('.kj-accordion-content')!;
+    expect(content.getAttribute('role')).toBe('region');
+    expect(trigger.getAttribute('aria-controls')).toBe(content.id);
+    expect(content.getAttribute('aria-labelledby')).toBe(trigger.id);
+  });
+
+  it('two-way `[(value)]` round-trips through `kjValue`', async () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `
+        <kj-accordion [(value)]="open">
+          <kj-accordion-item value="a" label="A"><kj-accordion-content>A</kj-accordion-content></kj-accordion-item>
+          <kj-accordion-item value="b" label="B"><kj-accordion-content>B</kj-accordion-content></kj-accordion-item>
+        </kj-accordion>`,
+    })
+    class Host {
+      readonly open = signal<string>('a');
+    }
+
+    const { container, fixture } = await render(Host);
+    await flush();
+    const triggers = container.querySelectorAll<HTMLButtonElement>('button.kj-accordion-trigger');
+    expect(triggers[0]).toHaveAttribute('aria-expanded', 'true');
+    fireEvent.click(triggers[1]);
+    fixture.detectChanges();
+    expect(fixture.componentInstance.open()).toBe('b');
+    expect(triggers[1]).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  it('item `disabled` propagates via `kjItemDisabled` (toggle is a no-op)', async () => {
+    const { container } = await render(
+      `<kj-accordion>
+        <kj-accordion-item value="locked" label="Locked" disabled>
+          <kj-accordion-content>Body</kj-accordion-content>
+        </kj-accordion-item>
+      </kj-accordion>`,
+      { imports },
+    );
+    const trigger = container.querySelector<HTMLElement>('button.kj-accordion-trigger')!;
+    expect(trigger).toHaveAttribute('aria-disabled', 'true');
+    fireEvent.click(trigger);
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it('arrow-key navigation moves focus when `arrowNavigation` is set', async () => {
+    const { container } = await render(
+      `<kj-accordion arrowNavigation>
+        <kj-accordion-item value="a" label="A"><kj-accordion-content>A</kj-accordion-content></kj-accordion-item>
+        <kj-accordion-item value="b" label="B"><kj-accordion-content>B</kj-accordion-content></kj-accordion-item>
+      </kj-accordion>`,
+      { imports },
+    );
+    const triggers = container.querySelectorAll<HTMLButtonElement>('button.kj-accordion-trigger');
+    triggers[0].focus();
+    fireEvent.keyDown(triggers[0], { key: 'ArrowDown' });
+    expect(document.activeElement).toBe(triggers[1]);
+  });
+});

package/src/accordion/accordion.ts

@@ -0,0 +1,153 @@
+import { Component, ChangeDetectionStrategy, ViewEncapsulation, input } from '@angular/core';
+import { KjAccordion, KjAccordionItem, KjAccordionTrigger, KjAccordionContent } from '@kouji-ui/core';
+
+/**
+ * Root accordion container.
+ *
+ * Applies `KjAccordion` via `hostDirectives` so the `KJ_ACCORDION` provider lives
+ * on the `<kj-accordion>` host element — projected `<kj-accordion-item>` children
+ * find it in their element-injector chain.
+ *
+ * @doc-example Default
+ *   The default playground — single-open accordion with two items.
+ *   @doc-file accordion.default.example.ts
+ * @doc-example Usage
+ *   The common shape: labelled items, controlled value, and arrow-key
+ *   navigation. Use this as the copy-paste starting point.
+ *   @doc-file accordion.usage.example.ts
+ * @doc-example Multiple open
+ *   `type="multiple"` lets users expand several panels at once. Bind an array
+ *   of open ids to `[(value)]`.
+ *   @doc-file accordion.multiple.example.ts
+ * @doc-example Disabled item
+ *   Mark an item `disabled` to skip it in tab order and arrow navigation.
+ *   @doc-file accordion.disabled.example.ts
+ * @doc-example Rich content
+ *   Project anything inside `<kj-accordion-content>` — paragraphs, lists, forms.
+ *   @doc-file accordion.rich-content.example.ts
+ * @doc-example Arrow navigation
+ *   `arrowNavigation` enables APG roving focus across triggers.
+ *   @doc-file accordion.arrow-nav.example.ts
+ * @doc-example Controlled value
+ *   Two-way bind `[(value)]` to drive open state from a signal or form.
+ *   @doc-file accordion.value.example.ts
+ *
+ * @doc-keyboard
+ *   Enter|Space   — Toggles the focused trigger's panel
+ *   Tab           — Moves focus to the next trigger (default) or out of the accordion (roving mode)
+ *   ArrowDown     — When `arrowNavigation`, moves focus to the next trigger (clamps at the end)
+ *   ArrowUp       — When `arrowNavigation`, moves focus to the previous trigger (clamps at the start)
+ *   Home          — When `arrowNavigation`, moves focus to the first trigger
+ *   End           — When `arrowNavigation`, moves focus to the last trigger
+ *
+ * @doc-aria
+ *   aria-expanded   — Reflected on each trigger; flips with the panel's open state
+ *   aria-controls   — Trigger references its panel id
+ *   aria-labelledby — Panel references its trigger id
+ *   aria-disabled   — Reflected when an item is disabled
+ *   role            — Panel host carries `region` so it's a navigable landmark
+ *
+ * @doc-css-var
+ *   --kj-accordion-bg          — Background fill of the accordion shell. Inherits --kj-bg-body.
+ *   --kj-accordion-border      — Border color around the shell and between items. Inherits --kj-border-default.
+ *   --kj-accordion-radius      — Outer corner radius. Inherits --kj-radius-box.
+ *
+ * @doc-touch
+ *   Triggers render real `<button>` elements that span the row width — easily
+ *   clears WCAG 2.5.5 ≥ 44×44 on the default size.
+ *
+ * @doc-a11y
+ *   Implements the WAI-ARIA APG Accordion pattern. Triggers are real
+ *   `<button>` hosts (Enter / Space activation, native focus ring). Roving
+ *   focus is opt-in via `arrowNavigation`; without it Tab walks through every
+ *   trigger sequentially.
+ *
+ * @doc-related card,tabs,dropdown-menu
+ *
+ * @doc-category Library/Data display
+ * @doc
+ * @doc-name accordion
+ * @doc-description Themed accordion for collapsible content sections with single or multi-open panels and keyboard navigation.
+ * @doc-is-main
+ */
+@Component({
+  selector: 'kj-accordion',
+  standalone: true,
+  hostDirectives: [{
+    directive: KjAccordion,
+    inputs: ['kjType: type', 'kjValue: value', 'kjArrowNavigation: arrowNavigation'],
+    outputs: ['kjValueChange: valueChange'],
+  }],
+  template: `<ng-content />`,
+  styleUrl: './accordion.css',
+  encapsulation: ViewEncapsulation.None,
+  host: { class: 'kj-accordion' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjAccordionComponent {}
+
+/**
+ * Click target that toggles the parent item.
+ * @doc
+ * @doc-name accordion
+ */
+@Component({
+  selector: 'kj-accordion-trigger',
+  standalone: true,
+  imports: [KjAccordionTrigger],
+  template: `<button type="button" kjAccordionTrigger class="kj-accordion-trigger" [disabled]="disabled()" [attr.aria-disabled]="disabled() ? 'true' : null"><ng-content /></button>`,
+  encapsulation: ViewEncapsulation.None,
+  host: { style: 'display: contents;' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjAccordionTriggerComponent {
+  readonly disabled = input(false);
+}
+
+/**
+ * Single accordion item. Bind a unique `value`.
+ *
+ * When `label` is provided the trigger is rendered internally — users only need
+ * to project `<kj-accordion-content>`. When `label` is omitted, project a
+ * `<kj-accordion-trigger>` manually for full control.
+ * @doc
+ * @doc-name accordion
+ */
+@Component({
+  selector: 'kj-accordion-item',
+  standalone: true,
+  hostDirectives: [{
+    directive: KjAccordionItem,
+    inputs: ['kjItemValue: value', 'kjItemDisabled: disabled'],
+  }],
+  imports: [KjAccordionTriggerComponent],
+  template: `
+    @if (label()) {
+      <kj-accordion-trigger [disabled]="disabled()">{{ label() }}</kj-accordion-trigger>
+    }
+    <ng-content />
+  `,
+  encapsulation: ViewEncapsulation.None,
+  host: { class: 'kj-accordion-item' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjAccordionItemComponent {
+  readonly label = input<string | undefined>(undefined);
+  readonly disabled = input(false);
+}
+
+/**
+ * Body shown when the parent item is expanded.
+ * @doc
+ * @doc-name accordion
+ */
+@Component({
+  selector: 'kj-accordion-content',
+  standalone: true,
+  imports: [KjAccordionContent],
+  template: `<div kjAccordionContent class="kj-accordion-content"><ng-content /></div>`,
+  encapsulation: ViewEncapsulation.None,
+  host: { style: 'display: contents;' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjAccordionContentComponent {}

package/src/accordion/accordion.usage.example.ts

@@ -0,0 +1,38 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import {
+  KjAccordionComponent,
+  KjAccordionItemComponent,
+  KjAccordionContentComponent,
+} from './accordion';
+
+/**
+ * Common accordion shape — labelled items, controlled value, arrow-key roving.
+ * Use this as the copy-paste starting point for new screens.
+ */
+@Component({
+  selector: 'kj-accordion-usage-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [
+    KjAccordionComponent,
+    KjAccordionItemComponent,
+    KjAccordionContentComponent,
+  ],
+  styles: [`:host { display: block; }`],
+  template: `
+    <kj-accordion [value]="open()" (valueChange)="open.set($any($event))" arrowNavigation>
+      <kj-accordion-item value="install" label="Installation">
+        <kj-accordion-content>Run pnpm add @kouji-ui/components and import the providers.</kj-accordion-content>
+      </kj-accordion-item>
+      <kj-accordion-item value="theme" label="Theming">
+        <kj-accordion-content>Wire a preset (default, retro, neon) through provideKjTheme.</kj-accordion-content>
+      </kj-accordion-item>
+      <kj-accordion-item value="a11y" label="Accessibility">
+        <kj-accordion-content>Every directive is keyboard-first and ships WCAG 2.1 AAA contracts.</kj-accordion-content>
+      </kj-accordion-item>
+    </kj-accordion>
+  `,
+})
+export class KjAccordionUsageExample {
+  readonly open = signal<string>('install');
+}

package/src/accordion/accordion.value.example.ts

@@ -0,0 +1,60 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import {
+  KjAccordionComponent,
+  KjAccordionItemComponent,
+  KjAccordionContentComponent,
+} from './accordion';
+
+/**
+ * Two-way bound `value` driving an external signal. Click the buttons above
+ * the accordion to open or close items programmatically — the signal and the
+ * component stay in sync because `[(value)]` round-trips through `kjValue`.
+ */
+@Component({
+  selector: 'kj-accordion-value-example',
+  standalone: true,
+  imports: [KjAccordionComponent, KjAccordionItemComponent, KjAccordionContentComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+      .controls {
+        display: flex;
+        gap: var(--kj-space-sm);
+        margin-bottom: var(--kj-space-md);
+      }
+      button {
+        padding: 0.25rem 0.75rem;
+        border: 1px solid var(--kj-border-default);
+        border-radius: var(--kj-radius-field);
+        cursor: pointer;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div class="controls">
+      <button type="button" (click)="open.set('overview')">Open overview</button>
+      <button type="button" (click)="open.set('billing')">Open billing</button>
+      <button type="button" (click)="open.set('')">Close all</button>
+      <span style="margin-left:auto; font: 0.875rem var(--kj-font-mono);"
+        >value = "{{ open() }}"</span
+      >
+    </div>
+    <kj-accordion [(value)]="open">
+      <kj-accordion-item value="overview" label="Overview">
+        <kj-accordion-content>Account snapshot, recent activity.</kj-accordion-content>
+      </kj-accordion-item>
+      <kj-accordion-item value="billing" label="Billing">
+        <kj-accordion-content>Invoices and payment methods.</kj-accordion-content>
+      </kj-accordion-item>
+      <kj-accordion-item value="security" label="Security">
+        <kj-accordion-content>Sessions, MFA, recovery codes.</kj-accordion-content>
+      </kj-accordion-item>
+    </kj-accordion>
+  `,
+})
+export class KjAccordionValueExample {
+  readonly open = signal<string>('overview');
+}

package/src/accordion/index.ts

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

package/src/alert/_examples/alert.banner.example.ts

@@ -0,0 +1,56 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjButtonComponent } from '../../button/button';
+import {
+  KjAlertActionsComponent,
+  KjAlertComponent,
+  KjAlertDescriptionComponent,
+  KjAlertDismissComponent,
+  KjAlertIconComponent,
+  KjAlertTitleComponent,
+} from '../alert';
+
+/**
+ * Static page-top banner (`kjAlertStatic="true"`). Resolves to
+ * `role="region"` with no `aria-live` — present on initial render, navigable
+ * via the AT region rotor. The directive enforces an accessible name (here
+ * via `aria-labelledby` to the title id, auto-wired by `KjAlertTitle`).
+ */
+@Component({
+  selector: 'kj-alert-banner-example',
+  standalone: true,
+  imports: [
+    KjAlertComponent,
+    KjAlertIconComponent,
+    KjAlertTitleComponent,
+    KjAlertDescriptionComponent,
+    KjAlertActionsComponent,
+    KjAlertDismissComponent,
+    KjButtonComponent,
+  ],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    @if (visible()) {
+      <kj-alert [kjAlertStatic]="true" kjVariant="warning" (kjAlertDismissed)="visible.set(false)">
+        <kj-alert-icon>!</kj-alert-icon>
+        <kj-alert-title>Maintenance scheduled</kj-alert-title>
+        <kj-alert-description>
+          The platform will be unavailable on Saturday from 02:00 to 04:00 UTC.
+        </kj-alert-description>
+        <kj-alert-actions>
+          <kj-button kjVariant="link" kjSize="sm">Status page</kj-button>
+        </kj-alert-actions>
+        <kj-alert-dismiss />
+      </kj-alert>
+    }
+  `,
+})
+export class KjAlertBannerExample {
+  readonly visible = signal(true);
+}

package/src/alert/_examples/alert.dismissible.example.ts

@@ -0,0 +1,53 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjButtonComponent } from '../../button/button';
+import {
+  KjAlertComponent,
+  KjAlertDescriptionComponent,
+  KjAlertDismissComponent,
+  KjAlertIconComponent,
+  KjAlertTitleComponent,
+} from '../alert';
+
+/**
+ * Consumer-managed visibility. The directive itself is stateless — clicking
+ * the dismiss button fires `(kjAlertDismissed)`, the host clears its own
+ * signal, the `@if` unmounts.
+ */
+@Component({
+  selector: 'kj-alert-dismissible-example',
+  standalone: true,
+  imports: [
+    KjAlertComponent,
+    KjAlertIconComponent,
+    KjAlertTitleComponent,
+    KjAlertDescriptionComponent,
+    KjAlertDismissComponent,
+    KjButtonComponent,
+  ],
+  styles: [
+    `
+      :host {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-md);
+        min-height: 10rem;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    @if (visible()) {
+      <kj-alert kjVariant="success" (kjAlertDismissed)="visible.set(false)">
+        <kj-alert-icon>✓</kj-alert-icon>
+        <kj-alert-title>Saved</kj-alert-title>
+        <kj-alert-description>Your changes are saved. Click × to dismiss.</kj-alert-description>
+        <kj-alert-dismiss />
+      </kj-alert>
+    } @else {
+      <kj-button (click)="visible.set(true)">Re-show alert</kj-button>
+    }
+  `,
+})
+export class KjAlertDismissibleExample {
+  readonly visible = signal(true);
+}

package/src/alert/_examples/alert.example.ts

@@ -0,0 +1,40 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import {
+  KjAlertComponent,
+  KjAlertDescriptionComponent,
+  KjAlertIconComponent,
+  KjAlertTitleComponent,
+} from '../alert';
+
+/**
+ * Default usage example for `KjAlertComponent`. Polite info alert with icon,
+ * title, and description. Resolves to `role="status"` + `aria-live="polite"`.
+ */
+@Component({
+  selector: 'kj-alert-example',
+  standalone: true,
+  imports: [
+    KjAlertComponent,
+    KjAlertIconComponent,
+    KjAlertTitleComponent,
+    KjAlertDescriptionComponent,
+  ],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-alert kjVariant="info">
+      <kj-alert-icon>i</kj-alert-icon>
+      <kj-alert-title>Heads up</kj-alert-title>
+      <kj-alert-description>
+        New theme tokens just landed — try the dark variant in your settings.
+      </kj-alert-description>
+    </kj-alert>
+  `,
+})
+export class KjAlertExample {}