@kouji-ui/components 0.1.1

package/src/table/_examples/table.empty-and-error.example.ts

@@ -0,0 +1,112 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { kjColumn, kjTableResource, type KjColumnDef, type KjTableState } from '@kouji-ui/core';
+import { KjTableComponent } from '../table';
+import { KjButtonComponent } from '../../button/button';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+const INITIAL_STATE: KjTableState = {
+  sorting: [],
+  columnFilters: [],
+  globalFilter: '',
+  pagination: { pageIndex: 0, pageSize: 25 },
+  rowSelection: {},
+  columnSizing: {},
+  columnVisibility: {},
+  columnOrder: [],
+  columnPinning: { left: [], right: [] },
+  expanded: {},
+  grouping: [],
+  density: 'standard',
+};
+
+/**
+ * Empty and error states — two tables side by side.
+ *
+ * Left: empty data with a custom `kjEmpty` slot that prompts the user to add
+ *   a row.
+ * Right: a resource-backed table whose loader rejects, surfacing a custom
+ *   `kjError` slot with a retry button.
+ */
+@Component({
+  selector: 'kj-table-empty-and-error-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [KjTableComponent, KjButtonComponent],
+  styles: [`
+    :host { display: grid; gap: 1.5rem; grid-template-columns: 1fr; }
+    @media (min-width: 60rem) { :host { grid-template-columns: 1fr 1fr; } }
+    .kj-empty, .kj-error {
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      gap: 0.5rem;
+      padding: 1rem;
+      text-align: center;
+    }
+    .kj-empty p, .kj-error p { margin: 0; }
+  `],
+  template: `
+    <section>
+      <h3>Empty</h3>
+      <kj-table [kjData]="emptyRows" [kjColumns]="cols">
+        <div kjEmpty class="kj-empty">
+          <p>No users found.</p>
+          <kj-button kjVariant="default" kjSize="sm" (click)="addUser()">
+            Add user
+          </kj-button>
+        </div>
+      </kj-table>
+      @if (added()) {
+        <p aria-live="polite">Pretend we just opened an "add user" dialog.</p>
+      }
+    </section>
+
+    <section>
+      <h3>Error</h3>
+      <kj-table [kjColumns]="cols" [kjResource]="failingResource">
+        <div kjError class="kj-error" role="alert">
+          <p>Failed to load.</p>
+          <kj-button kjVariant="outline" kjSize="sm" (click)="retry()">
+            Try again
+          </kj-button>
+        </div>
+      </kj-table>
+      @if (retried()) {
+        <p aria-live="polite">Retry clicked — wired in real apps via reload().</p>
+      }
+    </section>
+  `,
+})
+export class KjTableEmptyAndErrorExample {
+  protected readonly emptyRows: User[] = [];
+  protected readonly added = signal(false);
+  protected readonly retried = signal(false);
+  protected readonly state = signal<KjTableState>(INITIAL_STATE);
+
+  protected readonly cols: KjColumnDef<User>[] = [
+    kjColumn<User>({ id: 'name', accessorKey: 'name', header: 'Name' }),
+    kjColumn<User>({ id: 'email', accessorKey: 'email', header: 'Email' }),
+  ];
+
+  protected readonly failingResource = kjTableResource<User>({
+    stateSignal: this.state,
+    loader: async () => {
+      await new Promise<void>((r) => setTimeout(r, 250));
+      throw new Error('Network error: could not load users.');
+    },
+  });
+
+  protected addUser(): void {
+    this.added.set(true);
+  }
+
+  protected retry(): void {
+    this.retried.set(true);
+    this.failingResource.reload();
+  }
+}

package/src/table/_examples/table.example.ts

@@ -0,0 +1,45 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { kjColumn, type KjColumnDef } from '@kouji-ui/core';
+import { KjTableComponent } from '../table';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: 'admin' | 'editor' | 'viewer';
+  joined: string;
+}
+
+/**
+ * Default table — three columns, five rows, no options. The minimal
+ * copy-paste starting point.
+ * @doc-example
+ * @doc-name table
+ */
+@Component({
+  selector: 'kj-table-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [KjTableComponent],
+  styles: [`:host { display: block; }`],
+  template: `
+    <kj-table [kjData]="rows()" [kjColumns]="cols" [kjGetRowId]="getRowId" />
+  `,
+})
+export class KjTableExample {
+  protected readonly rows = signal<User[]>([
+    { id: '1', name: 'Alice Chen',  email: 'alice@example.com',  role: 'admin',  joined: '2024-01-15' },
+    { id: '2', name: 'Bob Diaz',    email: 'bob@example.com',    role: 'editor', joined: '2024-02-03' },
+    { id: '3', name: 'Carol Evans', email: 'carol@example.com',  role: 'viewer', joined: '2024-03-22' },
+    { id: '4', name: 'Dan Fischer', email: 'dan@example.com',    role: 'editor', joined: '2024-04-10' },
+    { id: '5', name: 'Eve Garcia',  email: 'eve@example.com',    role: 'admin',  joined: '2024-05-30' },
+  ]);
+
+  protected readonly cols: KjColumnDef<User>[] = [
+    kjColumn<User>({ id: 'name',  accessorKey: 'name',  header: 'Name'  }),
+    kjColumn<User>({ id: 'email', accessorKey: 'email', header: 'Email' }),
+    kjColumn<User>({ id: 'role',  accessorKey: 'role',  header: 'Role'  }),
+  ];
+
+  protected readonly getRowId = (row: User): string => row.id;
+}

package/src/table/_examples/table.export.example.ts

@@ -0,0 +1,82 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { kjColumn, type KjColumnDef } from '@kouji-ui/core';
+import { KjTableComponent } from '../table';
+import {
+  KjTableToolbarComponent,
+  type KjTableExportFormat,
+} from '../table-toolbar';
+import { copyToClipboard, downloadString, exportCsv, exportJson } from '../table-export';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: 'admin' | 'editor' | 'viewer';
+}
+
+const COLUMN_IDS = ['name', 'email', 'role'] as const;
+
+/**
+ * Export — the toolbar's export menu emits `(export)` with `'csv' | 'json' |
+ * 'clipboard'`. Wire it to the table rows: CSV / JSON downloads via
+ * `downloadString`, clipboard copy via `copyToClipboard`.
+ */
+@Component({
+  selector: 'kj-table-export-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [KjTableComponent, KjTableToolbarComponent],
+  styles: [`
+    :host { display: block; }
+    .kj-export-status { display: block; margin-block-start: 0.5rem; font-size: 0.875rem; }
+  `],
+  template: `
+    <kj-table [kjData]="rows()" [kjColumns]="cols" [kjGetRowId]="getRowId">
+      <kj-table-toolbar (export)="onExport($event)" />
+    </kj-table>
+    <span class="kj-export-status" aria-live="polite">{{ status() }}</span>
+  `,
+})
+export class KjTableExportExample {
+  protected readonly status = signal('Pick a format from the Export menu.');
+
+  protected readonly rows = signal<User[]>([
+    { id: '1', name: 'Alice Chen', email: 'alice@example.com', role: 'admin' },
+    { id: '2', name: 'Bob Diaz', email: 'bob@example.com', role: 'editor' },
+    { id: '3', name: 'Carol Evans', email: 'carol@example.com', role: 'viewer' },
+    { id: '4', name: 'Dan Fischer', email: 'dan@example.com', role: 'editor' },
+    { id: '5', name: 'Eve Garcia', email: 'eve@example.com', role: 'admin' },
+  ]);
+
+  protected readonly cols: KjColumnDef<User>[] = [
+    kjColumn<User>({ id: 'name', accessorKey: 'name', header: 'Name' }),
+    kjColumn<User>({ id: 'email', accessorKey: 'email', header: 'Email' }),
+    kjColumn<User>({ id: 'role', accessorKey: 'role', header: 'Role' }),
+  ];
+
+  protected readonly getRowId = (row: User): string => row.id;
+
+  protected async onExport(format: KjTableExportFormat): Promise<void> {
+    const rows = this.rows();
+    switch (format) {
+      case 'csv': {
+        const csv = exportCsv({ rows, columns: [...COLUMN_IDS] });
+        downloadString('users.csv', csv, 'text/csv;charset=utf-8');
+        this.status.set('Downloaded users.csv');
+        return;
+      }
+      case 'json': {
+        const json = exportJson({ rows });
+        downloadString('users.json', json, 'application/json');
+        this.status.set('Downloaded users.json');
+        return;
+      }
+      case 'clipboard': {
+        const csv = exportCsv({ rows, columns: [...COLUMN_IDS] });
+        await copyToClipboard(csv);
+        this.status.set('Copied CSV to clipboard');
+        return;
+      }
+    }
+  }
+}

package/src/table/_examples/table.filterable.example.ts

@@ -0,0 +1,67 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { kjColumn, type KjColumnDef } from '@kouji-ui/core';
+import { KjTableComponent } from '../table';
+
+interface Row {
+  id: string;
+  name: string;
+  score: number;
+  role: 'admin' | 'editor' | 'viewer';
+  joined: string;
+}
+
+/**
+ * Filter row enabled via `[kjEnableFilters]="true"`. Four columns exercise
+ * the built-in filter UIs — text, number, select, and date.
+ */
+@Component({
+  selector: 'kj-table-filterable-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [KjTableComponent],
+  styles: [`
+    :host { display: block; }
+    /* Container-driven height: the table fills 480px and its body scrolls
+       internally — the filter row stays pinned at the top. */
+    kj-table { height: 480px; }
+  `],
+  template: `
+    <kj-table
+      [kjData]="rows()"
+      [kjColumns]="cols"
+      [kjGetRowId]="getRowId"
+      [kjEnableFilters]="true"
+    />
+  `,
+})
+export class KjTableFilterableExample {
+  protected readonly rows = signal<Row[]>([
+    { id: '1',  name: 'Alice Chen',  score: 92, role: 'admin',  joined: '2024-01-15' },
+    { id: '2',  name: 'Bob Diaz',    score: 71, role: 'editor', joined: '2024-02-03' },
+    { id: '3',  name: 'Carol Evans', score: 88, role: 'viewer', joined: '2024-03-22' },
+    { id: '4',  name: 'Dan Fischer', score: 64, role: 'editor', joined: '2024-04-10' },
+    { id: '5',  name: 'Eve Garcia',  score: 95, role: 'admin',  joined: '2024-05-30' },
+    { id: '6',  name: 'Frank Hughes',score: 58, role: 'viewer', joined: '2024-06-12' },
+    { id: '7',  name: 'Grace Ito',   score: 81, role: 'admin',  joined: '2024-07-04' },
+    { id: '8',  name: 'Henry Jones', score: 76, role: 'editor', joined: '2024-08-19' },
+    { id: '9',  name: 'Iris Kim',    score: 90, role: 'viewer', joined: '2024-09-01' },
+    { id: '10', name: 'Jack Liu',    score: 67, role: 'editor', joined: '2024-10-25' },
+    { id: '11', name: 'Kara Mendes', score: 84, role: 'admin',  joined: '2024-11-08' },
+    { id: '12', name: 'Liam Novak',  score: 73, role: 'viewer', joined: '2024-12-14' },
+  ]);
+
+  protected readonly cols: KjColumnDef<Row>[] = [
+    kjColumn<Row>({ id: 'name',   accessorKey: 'name',   header: 'Name',   kjType: 'text'   }),
+    kjColumn<Row>({ id: 'score',  accessorKey: 'score',  header: 'Score',  kjType: 'number' }),
+    kjColumn<Row>({
+      id: 'role',
+      accessorKey: 'role',
+      header: 'Role',
+      kjType: 'select',
+      kjSelectOptions: ['admin', 'editor', 'viewer'],
+    }),
+    kjColumn<Row>({ id: 'joined', accessorKey: 'joined', header: 'Joined', kjType: 'date'   }),
+  ];
+
+  protected readonly getRowId = (row: Row): string => row.id;
+}

package/src/table/_examples/table.grouping.example.ts

@@ -0,0 +1,63 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  afterNextRender,
+  signal,
+  viewChild,
+} from '@angular/core';
+import { kjColumn } from '@kouji-ui/core';
+import { KjTableComponent } from '../table';
+
+interface User {
+  readonly id: string;
+  readonly name: string;
+  readonly role: string;
+  readonly status: string;
+}
+
+const ROWS: User[] = [
+  { id: '1', name: 'Alice',  role: 'Admin',   status: 'Active'   },
+  { id: '2', name: 'Bob',    role: 'Admin',   status: 'Inactive' },
+  { id: '3', name: 'Carol',  role: 'Editor',  status: 'Active'   },
+  { id: '4', name: 'Dan',    role: 'Editor',  status: 'Active'   },
+  { id: '5', name: 'Eve',    role: 'Viewer',  status: 'Inactive' },
+  { id: '6', name: 'Frank',  role: 'Viewer',  status: 'Active'   },
+];
+
+/**
+ * Grouped rows by `role`. Initial grouping state is seeded via
+ * `tableRef.setState({ grouping: ['role'] })` after first render, and we
+ * also expand every group so the example demonstrates both the grouped
+ * header row (with toggle + count) AND the leaf rows underneath.
+ */
+@Component({
+  selector: 'kj-table-grouping-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [KjTableComponent],
+  styles: [`:host { display: block; }`],
+  template: `
+    <kj-table [kjData]="data()" [kjColumns]="cols" />
+  `,
+})
+export class KjTableGroupingExample {
+  protected readonly data = signal<User[]>(ROWS);
+
+  protected readonly cols = [
+    kjColumn<User>({ accessorKey: 'role',   header: 'Role',   kjGroup: true }),
+    kjColumn<User>({ accessorKey: 'name',   header: 'Name'   }),
+    kjColumn<User>({ accessorKey: 'status', header: 'Status' }),
+  ];
+
+  private readonly tableRef = viewChild.required(KjTableComponent);
+
+  constructor() {
+    afterNextRender(() => {
+      const tbl = this.tableRef().tableRef();
+      tbl.setState({ grouping: ['role'] });
+      // Expand every group so leaf rows are visible by default; users can
+      // collapse with the chevron toggle on each group row.
+      tbl.table().toggleAllRowsExpanded(true);
+    });
+  }
+}

package/src/table/_examples/table.keyboard.example.ts

@@ -0,0 +1,115 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { kjColumn, type KjColumnDef } from '@kouji-ui/core';
+import { KjTableComponent } from '../table';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: 'admin' | 'editor' | 'viewer';
+}
+
+/**
+ * Keyboard navigation — full WCAG 2.1 grid keymap. Click into the grid and
+ * try the keys listed in the legend. Focus is row-based; cells advertise
+ * `tabindex="-1"` so arrow keys drive movement instead of Tab.
+ *
+ * Internally `KjTableKeyboardNav` resolves cells via Angular's
+ * `contentChildren(KjTableCell)`, so only currently-rendered (visible) cells
+ * participate — virtualized off-window rows + hidden columns are skipped
+ * automatically.
+ */
+@Component({
+  selector: 'kj-table-keyboard-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [KjTableComponent],
+  styles: [`
+    :host { display: block; font-family: var(--kj-font-sans); }
+
+    .keymap {
+      margin-block-end: var(--kj-space-md);
+      padding: var(--kj-space-md) var(--kj-space-lg);
+      border: 1px solid var(--kj-border-default);
+      border-radius: var(--kj-radius-field);
+      background: var(--kj-bg-surface);
+      color: var(--kj-fg-default);
+    }
+    .keymap h3 {
+      margin: 0 0 var(--kj-space-sm);
+      font-family: var(--kj-font-display);
+      font-size: var(--kj-text-sm);
+      font-weight: var(--kj-display-weight, 700);
+      letter-spacing: 0.08em;
+      text-transform: uppercase;
+      color: var(--kj-fg-muted);
+    }
+    .keymap dl {
+      display: grid;
+      grid-template-columns: auto 1fr;
+      gap: var(--kj-space-xs) var(--kj-space-lg);
+      margin: 0;
+      font-size: var(--kj-text-sm);
+    }
+    .keymap dt {
+      font-family: var(--kj-font-mono);
+      color: var(--kj-fg-default);
+    }
+    .keymap dd {
+      margin: 0;
+      color: var(--kj-fg-muted);
+    }
+    kbd {
+      display: inline-block;
+      padding: 1px var(--kj-space-xs);
+      background: var(--kj-bg-field);
+      border: 1px solid var(--kj-border-default);
+      border-radius: var(--kj-radius-selector);
+      font-family: var(--kj-font-mono);
+      font-size: 0.85em;
+      color: var(--kj-fg-default);
+    }
+  `],
+  template: `
+    <aside class="keymap" aria-label="Keyboard shortcuts">
+      <h3>Keyboard shortcuts</h3>
+      <dl>
+        <dt><kbd>↑</kbd> <kbd>↓</kbd> <kbd>←</kbd> <kbd>→</kbd></dt>
+        <dd>Move focus between cells</dd>
+        <dt><kbd>Home</kbd> / <kbd>End</kbd></dt>
+        <dd>Jump to first / last cell in the row</dd>
+        <dt><kbd>Ctrl</kbd>+<kbd>Home</kbd> / <kbd>Ctrl</kbd>+<kbd>End</kbd></dt>
+        <dd>Jump to first / last cell in the grid</dd>
+        <dt><kbd>PageUp</kbd> / <kbd>PageDown</kbd></dt>
+        <dd>Move focus a page of rows at a time</dd>
+        <dt><kbd>F2</kbd> / <kbd>Enter</kbd></dt>
+        <dd>Begin editing the focused cell (if editable)</dd>
+        <dt><kbd>Esc</kbd></dt>
+        <dd>Cancel the active editor</dd>
+        <dt><kbd>Space</kbd></dt>
+        <dd>Toggle row selection</dd>
+        <dt><kbd>Ctrl</kbd>+<kbd>A</kbd> / <kbd>Cmd</kbd>+<kbd>A</kbd></dt>
+        <dd>Select all rows</dd>
+      </dl>
+    </aside>
+
+    <kj-table [kjData]="rows()" [kjColumns]="cols" [kjGetRowId]="getRowId" />
+  `,
+})
+export class KjTableKeyboardExample {
+  protected readonly rows = signal<User[]>([
+    { id: '1', name: 'Alice Chen', email: 'alice@example.com', role: 'admin' },
+    { id: '2', name: 'Bob Diaz', email: 'bob@example.com', role: 'editor' },
+    { id: '3', name: 'Carol Evans', email: 'carol@example.com', role: 'viewer' },
+    { id: '4', name: 'Dan Fischer', email: 'dan@example.com', role: 'editor' },
+    { id: '5', name: 'Eve Garcia', email: 'eve@example.com', role: 'admin' },
+  ]);
+
+  protected readonly cols: KjColumnDef<User>[] = [
+    kjColumn<User>({ id: 'name', accessorKey: 'name', header: 'Name' }),
+    kjColumn<User>({ id: 'email', accessorKey: 'email', header: 'Email' }),
+    kjColumn<User>({ id: 'role', accessorKey: 'role', header: 'Role' }),
+  ];
+
+  protected readonly getRowId = (row: User): string => row.id;
+}

package/src/table/_examples/table.master-detail.example.ts

@@ -0,0 +1,102 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  signal,
+  viewChild,
+} from '@angular/core';
+import { kjColumn } from '@kouji-ui/core';
+import { KjTableComponent, type KjRowClickEvent } from '../table';
+
+interface User {
+  readonly id: string;
+  readonly name: string;
+  readonly email: string;
+  readonly lastLogin: string;
+  readonly permissions: readonly string[];
+}
+
+const ROWS: User[] = [
+  {
+    id: '1',
+    name: 'Alice',
+    email: 'alice@example.com',
+    lastLogin: '2026-05-16 09:14',
+    permissions: ['read', 'write', 'admin'],
+  },
+  {
+    id: '2',
+    name: 'Bob',
+    email: 'bob@example.com',
+    lastLogin: '2026-05-15 17:42',
+    permissions: ['read'],
+  },
+  {
+    id: '3',
+    name: 'Carol',
+    email: 'carol@example.com',
+    lastLogin: '2026-05-17 08:01',
+    permissions: ['read', 'write'],
+  },
+];
+
+/**
+ * Master-detail: clicking a row toggles a detail panel rendered via the
+ * `<ng-template #kjRowExpansion>` slot. The implicit context is the row's
+ * original data, exposed here through the `let-row` micro-syntax.
+ *
+ */
+@Component({
+  selector: 'kj-table-master-detail-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [KjTableComponent],
+  styles: [`
+    :host { display: block; }
+    .kj-detail {
+      padding: 0.75rem 1rem;
+      background: var(--kj-base-color-surface-subtle, #f6f8fa);
+      font-size: 0.875rem;
+    }
+    .kj-detail dl {
+      margin: 0;
+      display: grid;
+      grid-template-columns: max-content 1fr;
+      gap: 0.25rem 0.75rem;
+    }
+    .kj-detail dt { font-weight: 600; }
+    .kj-detail dd { margin: 0; }
+  `],
+  template: `
+    <kj-table
+      [kjData]="data()"
+      [kjColumns]="cols"
+      [kjGetRowId]="getRowId"
+      (rowClick)="onRowClick($any($event))"
+    >
+      <ng-template #kjRowExpansion let-row>
+        <div class="kj-detail">
+          <dl>
+            <dt>Last login</dt><dd>{{ row.lastLogin }}</dd>
+            <dt>Permissions</dt><dd>{{ row.permissions.join(', ') }}</dd>
+          </dl>
+        </div>
+      </ng-template>
+    </kj-table>
+  `,
+})
+export class KjTableMasterDetailExample {
+  protected readonly data = signal<User[]>(ROWS);
+  protected readonly getRowId = (row: User): string => row.id;
+
+  private readonly tableRef = viewChild.required(KjTableComponent);
+
+  protected readonly cols = [
+    kjColumn<User>({ accessorKey: 'name',  header: 'Name'  }),
+    kjColumn<User>({ accessorKey: 'email', header: 'Email' }),
+  ];
+
+  protected onRowClick(e: KjRowClickEvent<User>): void {
+    const row = this.tableRef().tableRef().table().getRow(e.row.id);
+    row?.toggleExpanded();
+  }
+}

package/src/table/_examples/table.persistence.example.ts

@@ -0,0 +1,85 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { inMemoryAdapter, kjColumn, type KjColumnDef, type KjStorageAdapter } from '@kouji-ui/core';
+import { KjTableComponent } from '../table';
+import { KjTableToolbarComponent } from '../table-toolbar';
+import { KjButtonComponent } from '../../button/button';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: 'admin' | 'editor' | 'viewer';
+}
+
+/**
+ * Persistence — pass a stable `kjStorageKey` plus an adapter. The table writes
+ * its state (sorting, filters, pagination, column visibility, density…) to the
+ * adapter on every change and re-hydrates on mount. Click "Remount" to swap
+ * the table via `*ngIf` and watch state restore from the in-memory adapter.
+ * Swap `inMemoryAdapter()` for `localStorageAdapter()` to survive real reloads.
+ */
+@Component({
+  selector: 'kj-table-persistence-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [KjTableComponent, KjTableToolbarComponent, KjButtonComponent],
+  styles: [`
+    :host { display: block; }
+    .kj-actions { display: flex; gap: 0.5rem; margin-block-end: 0.75rem; }
+  `],
+  template: `
+    <div class="kj-actions">
+      <kj-button kjVariant="outline" kjSize="sm" (click)="remount()">
+        Remount table
+      </kj-button>
+      <span aria-live="polite">{{ statusLabel() }}</span>
+    </div>
+
+    @if (mounted()) {
+      <kj-table
+        [kjData]="rows()"
+        [kjColumns]="cols"
+        [kjGetRowId]="getRowId"
+        [kjStorageKey]="'kj.docs.persistence-demo'"
+        [kjStorageAdapter]="adapter"
+      >
+        <kj-table-toolbar />
+      </kj-table>
+    }
+  `,
+})
+export class KjTablePersistenceExample {
+  protected readonly mounted = signal(true);
+  protected readonly statusLabel = signal('Sort / filter / change density, then click Remount.');
+
+  /**
+   * In-memory adapter shared across remounts. Replace with
+   * `localStorageAdapter()` to persist across page reloads.
+   */
+  protected readonly adapter: KjStorageAdapter = inMemoryAdapter();
+
+  protected readonly rows = signal<User[]>([
+    { id: '1', name: 'Alice Chen', email: 'alice@example.com', role: 'admin' },
+    { id: '2', name: 'Bob Diaz', email: 'bob@example.com', role: 'editor' },
+    { id: '3', name: 'Carol Evans', email: 'carol@example.com', role: 'viewer' },
+    { id: '4', name: 'Dan Fischer', email: 'dan@example.com', role: 'editor' },
+    { id: '5', name: 'Eve Garcia', email: 'eve@example.com', role: 'admin' },
+  ]);
+
+  protected readonly cols: KjColumnDef<User>[] = [
+    kjColumn<User>({ id: 'name', accessorKey: 'name', header: 'Name' }),
+    kjColumn<User>({ id: 'email', accessorKey: 'email', header: 'Email' }),
+    kjColumn<User>({ id: 'role', accessorKey: 'role', header: 'Role' }),
+  ];
+
+  protected readonly getRowId = (row: User): string => row.id;
+
+  protected remount(): void {
+    this.mounted.set(false);
+    this.statusLabel.set('Unmounted — state lives in the adapter.');
+    queueMicrotask(() => {
+      this.mounted.set(true);
+      this.statusLabel.set('Remounted — state restored from the adapter.');
+    });
+  }
+}