@kouji-ui/components 0.1.1

package/src/list/list.css

@@ -0,0 +1,166 @@
+/* ─────────────────────────────────────────────────────────────
+   .kj-list — component-layer tokens + structural CSS
+   The list root carries layout (flex direction, gap) and reads
+   `data-orientation` / `data-divided` / `data-hoverable` from the
+   composed `KjList` directive to flip variants. Per-row chrome is
+   driven by `data-active` / `data-disabled` on `<kj-list-item>`.
+   ──────────────────────────────────────────────────────────── */
+
+@layer kj.component {
+  .kj-list {
+    --kj-list-bg:           transparent;
+    --kj-list-fg:           var(--kj-fg-default);
+    --kj-list-border-color: var(--kj-border-default);
+    --kj-list-radius:       var(--kj-radius-box);
+    --kj-list-row-gap:      0;
+    --kj-list-row-padding-x: var(--kj-space-md);
+    --kj-list-row-padding-y: var(--kj-space-sm);
+    --kj-list-row-radius:   var(--kj-radius-field);
+    --kj-list-row-min-h:    2.75rem; /* 44px — WCAG 2.5.5 */
+
+    display: flex;
+    flex-direction: column;
+    gap: var(--kj-list-row-gap);
+    background: var(--kj-list-bg);
+    color: var(--kj-list-fg);
+    border-radius: var(--kj-list-radius);
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  /* Horizontal axis flips flex-direction. The `data-orientation` mirror is
+     emitted by `KjList` so themes do not need the JS-level orientation. */
+  .kj-list[data-orientation='horizontal'] {
+    flex-direction: row;
+    flex-wrap: wrap;
+  }
+
+  /* Sizes — drive row density via the row-padding / min-height tokens. */
+  .kj-list[data-size='xs'] {
+    --kj-list-row-padding-y: 0.125rem;
+    --kj-list-row-padding-x: var(--kj-space-sm);
+    --kj-list-row-min-h:    1.5rem;
+  }
+  .kj-list[data-size='sm'] {
+    --kj-list-row-padding-y: 0.25rem;
+    --kj-list-row-padding-x: var(--kj-space-sm);
+    --kj-list-row-min-h:    2rem;
+  }
+  .kj-list[data-size='lg'] {
+    --kj-list-row-padding-y: var(--kj-space-md);
+    --kj-list-row-padding-x: var(--kj-space-lg);
+    --kj-list-row-min-h:    3rem;
+  }
+
+  /* Variants — chrome on the container itself. */
+  .kj-list[data-variant='bordered'] {
+    border: var(--kj-border) solid var(--kj-list-border-color);
+    overflow: hidden;
+  }
+  .kj-list[data-variant='flat'] {
+    border: 0;
+    --kj-list-bg: transparent;
+  }
+
+  /* Per-row layout. Rows are flex containers so consumers can drop in
+     leading icons / trailing badges without juggling spans. */
+  .kj-list-item {
+    display: flex;
+    align-items: center;
+    gap: var(--kj-space-sm);
+    padding: var(--kj-list-row-padding-y) var(--kj-list-row-padding-x);
+    min-height: var(--kj-list-row-min-h);
+    border-radius: var(--kj-list-row-radius);
+    color: inherit;
+    /* Transition only state-tied properties so the active / hover flip is
+       buttery without animating layout. */
+    transition: background-color var(--kj-transition),
+                color var(--kj-transition),
+                opacity var(--kj-transition);
+  }
+
+  /* One projected link/button: move row padding onto it so the clickable box
+     matches the full row (padding on the host sat outside the hit target).
+     Use `nth-child(1 of …)` / `nth-last-child(1 of …)` so whitespace text
+     nodes between the host and the control do not break `:only-child`. */
+  .kj-list-item:has(
+    > :where(a, button):nth-child(1 of :where(a, button)):nth-last-child(1 of :where(a, button))
+  ) {
+    padding: 0;
+    align-items: stretch;
+    min-height: 0;
+  }
+
+  /* Divided rows — between-row border via `:not(:last-child)` so the final
+     row stays clean. The `data-divided` mirror lives on the root. */
+  .kj-list[data-divided] .kj-list-item {
+    border-radius: 0;
+  }
+  .kj-list[data-divided][data-orientation='vertical'] .kj-list-item:not(:last-child) {
+    border-bottom: var(--kj-border) solid var(--kj-list-border-color);
+  }
+  .kj-list[data-divided][data-orientation='horizontal'] .kj-list-item:not(:last-child) {
+    border-right: var(--kj-border) solid var(--kj-list-border-color);
+  }
+
+  /* Hoverable rows. Cascade order matters: the `:hover` rule comes BEFORE
+     the `[data-active]` rule so the active row wins when both are true. */
+  .kj-list[data-hoverable] .kj-list-item:hover {
+    background: color-mix(in oklab, var(--kj-fg-default) 6%, transparent);
+    cursor: pointer;
+  }
+
+  /* Active row — current location in a nav. Painted via background tint plus
+     a left bar (≥3:1 against background per WCAG 1.4.11). */
+  .kj-list-item[data-active] {
+    background: color-mix(in oklab, var(--kj-bg-primary) 12%, transparent);
+    color: var(--kj-fg-primary);
+    box-shadow: inset 3px 0 0 0 var(--kj-bg-primary);
+  }
+  .kj-list[data-orientation='horizontal'] .kj-list-item[data-active] {
+    box-shadow: inset 0 -3px 0 0 var(--kj-bg-primary);
+  }
+
+  /* Disabled row — dim the chrome and any projected interactive child.
+     Keyboard reachability is the projected child's responsibility. */
+  .kj-list-item[data-disabled] {
+    opacity: 0.45;
+    cursor: not-allowed;
+  }
+  .kj-list-item[data-disabled] :where(a, button) {
+    pointer-events: none;
+  }
+
+  /* Shared styles for interactive children */
+  .kj-list-item > :where(a, button) {
+    display: flex;
+    align-items: center;
+    gap: var(--kj-space-sm);
+    color: inherit;
+    text-decoration: none;
+    background: none;
+    border: 0;
+    padding: 0;
+    font: inherit;
+    cursor: pointer;
+  }
+
+  .kj-list-item:has(
+    > :where(a, button):nth-child(1 of :where(a, button)):nth-last-child(1 of :where(a, button))
+  )
+    > :where(a, button) {
+    flex: 1 1 auto;
+    align-self: stretch;
+    min-width: 0;
+    min-height: var(--kj-list-row-min-h);
+    padding: var(--kj-list-row-padding-y) var(--kj-list-row-padding-x);
+    box-sizing: border-box;
+  }
+
+  .kj-list-item > :where(a, button):focus-visible {
+    outline: 2px solid var(--kj-fg-primary);
+    outline-offset: 2px;
+    border-radius: var(--kj-list-row-radius);
+  }
+}

package/src/list/list.playground.ts

@@ -0,0 +1,90 @@
+import { ChangeDetectionStrategy, Component, computed, signal } from '@angular/core';
+import { KjListComponent, KjListItemComponent } from './list';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+/**
+ * Playground state — module-scope signals. Compound knobs: item count and
+ * an active-index selector accompany the structural divided / hoverable /
+ * arrow-navigation toggles.
+ */
+const itemCount = signal<3 | 5 | 7>(5);
+const divided = signal(true);
+const hoverable = signal(true);
+const arrowNavigation = signal(false);
+const activeIndex = signal<0 | 1 | 2 | 3 | 4 | 5 | 6 | -1>(0);
+
+const ITEMS = ['Profile', 'Notifications', 'Billing', 'Security', 'Connected apps', 'Plan', 'Danger zone'] as const;
+
+@Component({
+  selector: 'kj-list-playground',
+  standalone: true,
+  imports: [KjListComponent, KjListItemComponent],
+  styles: [`:host { display: block; max-width: 360px; }`],
+  template: `
+    <kj-list
+      ariaLabel="Account settings"
+      [divided]="divided()"
+      [hoverable]="hoverable()"
+      [arrowNavigation]="arrowNavigation()"
+    >
+      @for (item of visibleItems(); track item; let i = $index) {
+        <kj-list-item [active]="i === activeIndex()">{{ item }}</kj-list-item>
+      }
+    </kj-list>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjListPlaygroundDemo {
+  protected readonly itemCount = itemCount;
+  protected readonly divided = divided;
+  protected readonly hoverable = hoverable;
+  protected readonly arrowNavigation = arrowNavigation;
+  protected readonly activeIndex = activeIndex;
+
+  protected readonly visibleItems = computed(() =>
+    ITEMS.slice(0, itemCount()),
+  );
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjListPlaygroundDemo,
+  state: {
+    itemCount: itemCount as unknown as ReturnType<typeof signal>,
+    divided: divided as unknown as ReturnType<typeof signal>,
+    hoverable: hoverable as unknown as ReturnType<typeof signal>,
+    arrowNavigation: arrowNavigation as unknown as ReturnType<typeof signal>,
+    activeIndex: activeIndex as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    { kind: 'chips', name: 'itemCount', label: 'items', options: [3, 5, 7] },
+    {
+      kind: 'chips',
+      name: 'activeIndex',
+      label: 'active row',
+      options: [-1, 0, 1, 2, 3, 4],
+    },
+    { kind: 'toggle', name: 'divided', label: 'divided' },
+    { kind: 'toggle', name: 'hoverable', label: 'hoverable' },
+    { kind: 'toggle', name: 'arrowNavigation', label: 'arrow navigation' },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      itemCount: number;
+      divided: boolean;
+      hoverable: boolean;
+      arrowNavigation: boolean;
+      activeIndex: number;
+    };
+    const attrs: string[] = ['ariaLabel="Account settings"'];
+    if (s.divided) attrs.push('[divided]="true"');
+    if (s.hoverable) attrs.push('[hoverable]="true"');
+    if (s.arrowNavigation) attrs.push('[arrowNavigation]="true"');
+    const rows = Array.from(ITEMS.slice(0, s.itemCount))
+      .map((label, i) => {
+        const active = i === s.activeIndex ? ' [active]="true"' : '';
+        return `  <kj-list-item${active}>${label}</kj-list-item>`;
+      })
+      .join('\n');
+    return `<kj-list\n  ${attrs.join('\n  ')}\n>\n${rows}\n</kj-list>`;
+  },
+};

package/src/list/list.spec.ts

@@ -0,0 +1,121 @@
+import { Component } from '@angular/core';
+import { render } from '@testing-library/angular';
+
+import { KjListComponent, KjListItemComponent } from './list';
+
+const imports = [KjListComponent, KjListItemComponent];
+
+/**
+ * Allow Angular's signal-driven host bindings and `effect()`s to settle
+ * before the assertions read host attributes. Mirrors the helper used by the
+ * sibling `<kj-avatar-group>` spec.
+ */
+async function flush(): Promise<void> {
+  await new Promise<void>((resolve) => setTimeout(resolve, 0));
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+describe('KjListComponent', () => {
+  it('renders projected <kj-list-item> children with the wrapper class', async () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `
+        <kj-list ariaLabel="Recent files">
+          <kj-list-item>One</kj-list-item>
+          <kj-list-item>Two</kj-list-item>
+          <kj-list-item>Three</kj-list-item>
+        </kj-list>`,
+    })
+    class Host {}
+
+    const { container } = await render(Host);
+    await flush();
+
+    const listEl = container.querySelector('kj-list') as HTMLElement;
+    expect(listEl).toBeTruthy();
+    expect(listEl.classList.contains('kj-list')).toBe(true);
+
+    const items = container.querySelectorAll('kj-list-item');
+    expect(items).toHaveLength(3);
+    items.forEach((item) => {
+      expect((item as HTMLElement).classList.contains('kj-list-item')).toBe(true);
+    });
+  });
+
+  it('forwards aliased inputs (orientation, divided, hoverable) to the underlying directive', async () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `
+        <kj-list ariaLabel="Story rail" orientation="horizontal" [divided]="true" [hoverable]="true">
+          <kj-list-item>A</kj-list-item>
+          <kj-list-item>B</kj-list-item>
+        </kj-list>`,
+    })
+    class Host {}
+
+    const { container } = await render(Host);
+    await flush();
+
+    const listEl = container.querySelector('kj-list') as HTMLElement;
+    // The directive emits the data-* mirrors that themes read for chrome.
+    expect(listEl.getAttribute('data-orientation')).toBe('horizontal');
+    expect(listEl.hasAttribute('data-divided')).toBe(true);
+    expect(listEl.hasAttribute('data-hoverable')).toBe(true);
+    // Default `as="ul"` → directive emits role="list" (defeats Safari's
+    // `list-style: none` voice-stripping heuristic).
+    expect(listEl.getAttribute('role')).toBe('list');
+    expect(listEl.getAttribute('aria-label')).toBe('Story rail');
+  });
+
+  it('forwards aliased item inputs (active, disabled) to the per-row directive', async () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `
+        <kj-list ariaLabel="L">
+          <kj-list-item [active]="true">A</kj-list-item>
+          <kj-list-item [disabled]="true">B</kj-list-item>
+        </kj-list>`,
+    })
+    class Host {}
+
+    const { container } = await render(Host);
+    await flush();
+
+    const items = container.querySelectorAll('kj-list-item');
+    expect(items[0].hasAttribute('data-active')).toBe(true);
+    expect(items[0].hasAttribute('data-disabled')).toBe(false);
+    expect(items[1].hasAttribute('data-active')).toBe(false);
+    expect(items[1].hasAttribute('data-disabled')).toBe(true);
+    // The list-item host is a `<kj-list-item>` (not `<li>`) — the directive
+    // must emit role="listitem" to pair with the container's role="list".
+    expect(items[0].getAttribute('role')).toBe('listitem');
+    expect(items[1].getAttribute('role')).toBe('listitem');
+  });
+
+  it('produces a navigation landmark when as="nav"', async () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `
+        <kj-list as="nav" ariaLabel="Primary">
+          <kj-list-item><a href="#a">A</a></kj-list-item>
+          <kj-list-item><a href="#b">B</a></kj-list-item>
+        </kj-list>`,
+    })
+    class Host {}
+
+    const { container } = await render(Host);
+    await flush();
+
+    const listEl = container.querySelector('kj-list') as HTMLElement;
+    // The wrapper layers `role="navigation"` on the host so the list doubles
+    // as a landmark; the underlying directive omits its `role="list"` in this
+    // mode (a landmark cannot also be a list).
+    expect(listEl.getAttribute('role')).toBe('navigation');
+    expect(listEl.getAttribute('aria-label')).toBe('Primary');
+  });
+});

package/src/list/list.ts

@@ -0,0 +1,227 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ViewEncapsulation,
+  booleanAttribute,
+  computed,
+  input,
+} from '@angular/core';
+import { KjList, KjListRow, type KjListAs, type KjListOrientation } from '@kouji-ui/core';
+
+/**
+ * Themed wrapper around the headless `KjList` directive. Re-maps the directive's
+ * `kj`-prefixed inputs to terse public names (`orientation`, `divided`,
+ * `hoverable`, `arrowNavigation`, `wrap`) and surfaces the `as` declaration so
+ * theme CSS can paint chrome (divider rules, hover highlight, orientation flex
+ * direction) off the standard `data-*` mirrors emitted by the directive.
+ *
+ * The wrapper host is the list root: composing `KjList` via `hostDirectives`
+ * means `<kj-list>` itself carries `role="list"` (or omits it when
+ * `as="nav"`, where the wrapper opts the host into the `navigation` landmark
+ * via `role="navigation"`).
+ *
+ * **Active vs. selected discipline.** The wrapper paints `data-active` on the
+ * row chrome but never infers ARIA. Consumers set `aria-current="page"` (or
+ * `step`, `date`, `true`) on the projected `<a>` / `<button>` because the
+ * right token depends on the consumer's domain — it is never a List concern.
+ *
+ * @example Settings list with leading icons
+ * ```html
+ * <kj-list ariaLabel="Account settings" divided hoverable>
+ *   <kj-list-item>Profile</kj-list-item>
+ *   <kj-list-item>Notifications</kj-list-item>
+ *   <kj-list-item>Billing</kj-list-item>
+ * </kj-list>
+ * ```
+ *
+ * @example Sidebar nav with active row
+ * ```html
+ * <kj-list as="nav" arrowNavigation ariaLabel="Primary">
+ *   <kj-list-item active="true">
+ *     <a href="/home" aria-current="page">Home</a>
+ *   </kj-list-item>
+ *   <kj-list-item>
+ *     <a href="/settings">Settings</a>
+ *   </kj-list-item>
+ * </kj-list>
+ * ```
+ *
+ * @doc-example Default
+ *   A settings list with five rows — anchors the chrome (no dividers, no hover).
+ *   @doc-file list.example.ts
+ * @doc-example Usage
+ *   Common list shapes — divided, hoverable, and a nav landmark — assembled
+ *   as a copy-paste starting point.
+ *   @doc-file list.usage.example.ts
+ * @doc-example Divided
+ *   `[divided]="true"` paints between-row separators via theme CSS.
+ *   @doc-file list.divided.example.ts
+ * @doc-example Nav landmark
+ *   `as="nav"` opts the host into the `navigation` landmark with a label.
+ *   @doc-file list.nav.example.ts
+ * @doc-example Interactive rows
+ *   Rows project `<a>` / `<button>` children that own focus and activation.
+ *   @doc-file list.interactive.example.ts
+ * @doc-example With icons and badges
+ *   Icon prefix + trailing badge combo for status-rich rows.
+ *   @doc-file list.with-icons.example.ts
+ *
+ * @doc-keyboard
+ *   Tab        — Moves focus to the next interactive child (the row itself is not focusable)
+ *   Arrow up|down — Moves focus across rows when [arrowNavigation]="true" (roving tabindex)
+ *   Home|End   — Jump to the first / last row when [arrowNavigation]="true"
+ *
+ * @doc-aria
+ *   role         — "list" by default; "navigation" when as="nav"
+ *   aria-label   — Bound from [ariaLabel]; required when as="nav"
+ *   aria-labelledby — Bound from [ariaLabelledby] when an external heading labels the list
+ *   data-active  — Mirrors a list-item's [active] for theme CSS; consumers wire aria-current separately
+ *   data-disabled— Mirrors a list-item's [disabled] for theme CSS
+ *
+ * @doc-touch
+ *   `--kj-list-row-min-h` defaults to 44 px so each row already meets WCAG
+ *   2.5.5 when the row hosts an interactive child.
+ *
+ * @doc-a11y
+ *   The list never infers `aria-current` — consumers set the right token
+ *   (`page` / `step` / `date` / `true`) on the projected `<a>` or
+ *   `<button>` because the meaning is domain-specific. Disabled rows paint
+ *   chrome via `data-disabled`; the projected child still owns its own
+ *   `tabindex` / `aria-disabled` discipline.
+ *
+ * @doc-related divider,menubar,breadcrumb,card
+ *
+ * @doc-css-var
+ *   --kj-list-bg             — Background fill of the list container.
+ *   --kj-list-fg             — Foreground (text) color of the list.
+ *   --kj-list-border-color   — Border color for bordered + divided variants.
+ *   --kj-list-radius         — Outer corner radius of the list container.
+ *   --kj-list-row-gap        — Gap between rows. Zero by default (rows touch).
+ *   --kj-list-row-padding-x  — Horizontal padding inside each row. Sizes override.
+ *   --kj-list-row-padding-y  — Vertical padding inside each row. Sizes override.
+ *   --kj-list-row-radius     — Corner radius applied to each row's chrome.
+ *   --kj-list-row-min-h      — Minimum row height. Default 44px (WCAG 2.5.5).
+ *
+ * @doc-category Library/Data display
+ * @doc
+ * @doc-name list
+ * @doc-description Themed list surface for settings panels, sidebar navigation, and data feeds.
+ * @doc-is-main
+ */
+@Component({
+  selector: 'kj-list',
+  standalone: true,
+  hostDirectives: [
+    {
+      directive: KjList,
+      inputs: [
+        'kjAs: as',
+        'kjOrientation: orientation',
+        'kjDivided: divided',
+        'kjHoverable: hoverable',
+        'kjArrowNavigation: arrowNavigation',
+        'kjListWrap: wrap',
+      ],
+    },
+  ],
+  template: `<ng-content />`,
+  styleUrl: './list.css',
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    'class': 'kj-list',
+    '[attr.role]': 'roleAttr()',
+    '[attr.aria-label]': 'ariaLabel() || null',
+    '[attr.aria-labelledby]': 'ariaLabelledby() || null',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjListComponent {
+  /**
+   * Declares which semantic element the consumer wants the list to behave as.
+   * The wrapper does not literally swap host tags (the host stays
+   * `<kj-list>`), but the directive uses `as` to decide whether to emit
+   * `role="list"`, and the wrapper layers a `role="navigation"` on top when
+   * `as="nav"` so the host doubles as a landmark.
+   */
+  readonly as = input<KjListAs>('ul');
+
+  /** List axis. Drives `data-orientation` on the host for theme CSS. */
+  readonly orientation = input<KjListOrientation>('vertical');
+
+  /** Whether the list draws between-row borders. CSS-only effect. */
+  readonly divided = input(false, { transform: booleanAttribute });
+
+  /** Whether rows highlight on hover. Off by default — purely informational lists should not hint at interactivity. */
+  readonly hoverable = input(false, { transform: booleanAttribute });
+
+  /** Opt-in roving-tabindex group for sidebar-nav-list use cases. Mirrors the accordion arrow-nav pattern. */
+  readonly arrowNavigation = input(false, { transform: booleanAttribute });
+
+  /** Whether arrow-key navigation wraps at the ends. Only meaningful when `arrowNavigation` is `true`. */
+  readonly wrap = input(true, { transform: booleanAttribute });
+
+  /** Accessible name for the list. Required for `as="nav"` (landmark naming rule). */
+  readonly ariaLabel = input<string | undefined>(undefined);
+
+  /** Accessible name reference for the list. Use when an existing heading labels the list. */
+  readonly ariaLabelledby = input<string | undefined>(undefined);
+
+  /**
+   * @internal Computed role for the wrapper host. When `as="nav"`, the host
+   * acts as the navigation landmark; otherwise it stays a plain `role="list"`.
+   * The wrapper owns this binding (rather than letting the composed `KjList`
+   * directive emit it) because Angular gives the component-level host binding
+   * priority over a host-directive's binding on the same attribute, so the
+   * directive's value would otherwise be silently shadowed.
+   */
+  protected readonly roleAttr = computed<string | null>(() =>
+    this.as() === 'nav' ? 'navigation' : 'list',
+  );
+}
+
+/**
+ * Per-row wrapper around the headless `KjListItem` directive. Re-maps
+ * `kjActive` / `kjDisabled` to terse public names and ensures the row chrome
+ * (active highlight, disabled dim) reads off the same `data-*` attributes the
+ * core directive emits.
+ *
+ * The list-item host is **not** a focus stop. Keyboard reachability lives on
+ * the projected interactive child (`<a>`, `<button>`). Disabling the row is a
+ * two-layer story: `disabled` on `<kj-list-item>` paints the chrome via
+ * `data-disabled`, and the projected child wires its own `aria-disabled` /
+ * `tabindex` discipline (e.g. via `KjDisabled` on a button).
+ *
+ * @doc-category Library/Data display
+ * @doc
+ * @doc-name list
+ */
+@Component({
+  selector: 'kj-list-item',
+  standalone: true,
+  hostDirectives: [
+    {
+      directive: KjListRow,
+      inputs: ['kjActive: active', 'kjDisabled: disabled'],
+    },
+  ],
+  template: `<ng-content />`,
+  encapsulation: ViewEncapsulation.None,
+  host: { class: 'kj-list-item' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjListItemComponent {
+  /**
+   * Whether the row is the current/active selection (e.g. the current page in
+   * a sidebar nav). Reflects to `data-active=""` on the host. Consumers must
+   * also set the appropriate `aria-current` token on the projected
+   * link/button.
+   */
+  readonly active = input(false, { transform: booleanAttribute });
+
+  /**
+   * Whether the row is disabled. Reflects to `data-disabled=""` on the host so
+   * theme CSS can dim the chrome. Does not block keyboard reachability — that
+   * belongs to the projected interactive child.
+   */
+  readonly disabled = input(false, { transform: booleanAttribute });
+}

package/src/list/list.usage.example.ts

@@ -0,0 +1,45 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { KjListComponent, KjListItemComponent } from './list';
+
+/**
+ * Common list shapes — a divided+hoverable settings list and a sidebar-nav
+ * landmark with an active row. Copy-paste starting point.
+ */
+@Component({
+  selector: 'kj-list-usage-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [KjListComponent, KjListItemComponent],
+  styles: [`
+    :host { display: grid; gap: var(--kj-space-lg); grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); }
+    h4 { margin: 0 0 var(--kj-space-sm); font: 600 var(--kj-text-sm)/1.4 var(--kj-font-sans); color: var(--kj-fg-muted); }
+    a { color: inherit; text-decoration: none; }
+  `],
+  template: `
+    <section>
+      <h4>Settings</h4>
+      <kj-list ariaLabel="Account settings" [divided]="true" [hoverable]="true">
+        <kj-list-item>Profile</kj-list-item>
+        <kj-list-item>Notifications</kj-list-item>
+        <kj-list-item>Billing</kj-list-item>
+        <kj-list-item>Security</kj-list-item>
+      </kj-list>
+    </section>
+
+    <section>
+      <h4>Sidebar nav</h4>
+      <kj-list as="nav" [arrowNavigation]="true" ariaLabel="Primary navigation">
+        <kj-list-item [active]="true">
+          <a href="/home" aria-current="page">Home</a>
+        </kj-list-item>
+        <kj-list-item>
+          <a href="/projects">Projects</a>
+        </kj-list-item>
+        <kj-list-item>
+          <a href="/settings">Settings</a>
+        </kj-list-item>
+      </kj-list>
+    </section>
+  `,
+})
+export class KjListUsageExample {}

package/src/menubar/_examples/index.ts

@@ -0,0 +1,6 @@
+// AUTO-GENERATED by scripts/migrate-examples.mjs
+// One barrel per component folder — used by the docs app as a lazy chunk.
+export { KjMenubarDisabledItemExample } from './menubar.disabled-item.example';
+export { KjMenubarExample } from './menubar.example';
+export { KjMenubarWithShortcutsExample } from './menubar.with-shortcuts.example';
+export { KjMenubarWithSubmenuExample } from './menubar.with-submenu.example';

package/src/menubar/_examples/menubar.disabled-item.example.ts

@@ -0,0 +1,23 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { KjMenubarComponent, KjMenubarItemComponent } from '../menubar';
+
+/**
+ * Menubar with a disabled top-level item. `[kjDisabled]="true"` drops the
+ * item from the keyboard cycle, dims it, and prevents activation.
+ */
+@Component({
+  selector: 'kj-menubar-disabled-item-example',
+  standalone: true,
+  imports: [KjMenubarComponent, KjMenubarItemComponent],
+  styles: [`:host { display: block; }`],
+  template: `
+    <kj-menubar kjAriaLabel="Application">
+      <kj-menubar-item>File</kj-menubar-item>
+      <kj-menubar-item>Edit</kj-menubar-item>
+      <kj-menubar-item [kjDisabled]="true">View</kj-menubar-item>
+      <kj-menubar-item>Help</kj-menubar-item>
+    </kj-menubar>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjMenubarDisabledItemExample {}