@kouji-ui/components 0.1.1

package/src/table/_examples/table.playground.ts

@@ -0,0 +1,154 @@
+import { ChangeDetectionStrategy, Component, signal, type WritableSignal } from '@angular/core';
+import { kjColumn, type KjColumnDef } from '@kouji-ui/core';
+import { KjTableComponent } from '../table';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: 'admin' | 'editor' | 'viewer';
+}
+
+const PLAYGROUND_ROWS: 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' },
+  { id: '6', name: 'Finn Hayes', email: 'finn@example.com', role: 'viewer' },
+];
+
+const PLAYGROUND_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' }),
+];
+
+/**
+ * Playground state — module-scope signals. The demo component reads them via
+ * its template; the snippet fn reads them via the engine-supplied `values`
+ * arg; the engine writes them via {@link PLAYGROUND.state}.
+ */
+const density = signal<'compact' | 'standard' | 'comfortable'>('standard');
+const variant = signal<'bordered' | 'striped' | 'clean'>('bordered');
+const loading = signal(false);
+const enableFilters = signal(false);
+const enableResize = signal(false);
+const enableRowPinning = signal(false);
+const virtual = signal<'true' | 'false' | 'auto'>('auto');
+const selectionMode = signal<'none' | 'single' | 'multi'>('none');
+
+function virtualValue(v: 'true' | 'false' | 'auto'): boolean | 'auto' {
+  if (v === 'true') return true;
+  if (v === 'false') return false;
+  return 'auto';
+}
+
+@Component({
+  selector: 'kj-table-playground',
+  standalone: true,
+  imports: [KjTableComponent],
+  template: `
+    <kj-table
+      [kjData]="rows"
+      [kjColumns]="cols"
+      [kjGetRowId]="getRowId"
+      [kjDensity]="density()"
+      [kjVariant]="variant()"
+      [kjLoading]="loading()"
+      [kjEnableFilters]="enableFilters()"
+      [kjEnableResize]="enableResize()"
+      [kjEnableRowPinning]="enableRowPinning()"
+      [kjVirtual]="virtualResolved()"
+      [kjSelectionMode]="selectionMode()"
+    />
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjTablePlayground {
+  protected readonly rows = PLAYGROUND_ROWS;
+  protected readonly cols = PLAYGROUND_COLS;
+  protected readonly getRowId = (row: User): string => row.id;
+
+  protected readonly density = density;
+  protected readonly variant = variant;
+  protected readonly loading = loading;
+  protected readonly enableFilters = enableFilters;
+  protected readonly enableResize = enableResize;
+  protected readonly enableRowPinning = enableRowPinning;
+  protected readonly selectionMode = selectionMode;
+
+  protected readonly virtualResolved = (): boolean | 'auto' => virtualValue(virtual());
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjTablePlayground,
+  state: {
+    density: density as unknown as WritableSignal<unknown>,
+    variant: variant as unknown as WritableSignal<unknown>,
+    loading: loading as unknown as WritableSignal<unknown>,
+    enableFilters: enableFilters as unknown as WritableSignal<unknown>,
+    enableResize: enableResize as unknown as WritableSignal<unknown>,
+    enableRowPinning: enableRowPinning as unknown as WritableSignal<unknown>,
+    virtual: virtual as unknown as WritableSignal<unknown>,
+    selectionMode: selectionMode as unknown as WritableSignal<unknown>,
+  },
+  controls: [
+    {
+      kind: 'chips',
+      name: 'density',
+      label: 'density',
+      options: ['compact', 'standard', 'comfortable'],
+    },
+    {
+      kind: 'chips',
+      name: 'variant',
+      label: 'variant',
+      options: ['bordered', 'striped', 'clean'],
+    },
+    {
+      kind: 'chips',
+      name: 'virtual',
+      label: 'virtual',
+      options: ['true', 'false', 'auto'],
+    },
+    {
+      kind: 'chips',
+      name: 'selectionMode',
+      label: 'selection mode',
+      options: ['none', 'single', 'multi'],
+    },
+    { kind: 'toggle', name: 'loading', label: 'loading' },
+    { kind: 'toggle', name: 'enableFilters', label: 'filters' },
+    { kind: 'toggle', name: 'enableResize', label: 'resize' },
+    { kind: 'toggle', name: 'enableRowPinning', label: 'row pinning' },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      density: string;
+      variant: string;
+      loading: boolean;
+      enableFilters: boolean;
+      enableResize: boolean;
+      enableRowPinning: boolean;
+      virtual: string;
+      selectionMode: string;
+    };
+    const attrs: string[] = [
+      `kjDensity="${s.density}"`,
+      `kjVariant="${s.variant}"`,
+      `kjSelectionMode="${s.selectionMode}"`,
+    ];
+    if (s.virtual !== 'auto') {
+      attrs.push(`[kjVirtual]="${s.virtual}"`);
+    } else {
+      attrs.push(`kjVirtual="auto"`);
+    }
+    if (s.loading) attrs.push('[kjLoading]="true"');
+    if (s.enableFilters) attrs.push('[kjEnableFilters]="true"');
+    if (s.enableResize) attrs.push('[kjEnableResize]="true"');
+    if (s.enableRowPinning) attrs.push('[kjEnableRowPinning]="true"');
+    return `<kj-table\n  [kjData]="rows()"\n  [kjColumns]="cols"\n  ${attrs.join('\n  ')}\n/>`;
+  },
+};

package/src/table/_examples/table.row-pinning.example.ts

@@ -0,0 +1,71 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  afterNextRender,
+  signal,
+  viewChild,
+} from '@angular/core';
+import { kjColumn, type KjColumnDef } from '@kouji-ui/core';
+import { KjTableComponent } from '../table';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: string;
+}
+
+/**
+ * Row pinning — `[kjEnableRowPinning]="true"` splits the table body into
+ * top / center / bottom buckets. Rows `1` and `2` are pinned to the top and
+ * row `5` is pinned to the bottom via TanStack's `setRowPinning(...)` API,
+ * called inside `afterNextRender` so the underlying table instance exists.
+ *
+ */
+@Component({
+  selector: 'kj-table-row-pinning-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [KjTableComponent],
+  styles: [`:host { display: block; }`],
+  template: `
+    <kj-table
+      [kjData]="rows()"
+      [kjColumns]="cols"
+      [kjGetRowId]="getRowId"
+      [kjEnableRowPinning]="true"
+    />
+  `,
+})
+export class KjTableRowPinningExample {
+  protected readonly getRowId = (r: User): string => r.id;
+
+  protected readonly cols: KjColumnDef<User>[] = [
+    kjColumn<User>({ accessorKey: 'id',    header: 'ID' }),
+    kjColumn<User>({ accessorKey: 'name',  header: 'Name' }),
+    kjColumn<User>({ accessorKey: 'email', header: 'Email' }),
+    kjColumn<User>({ accessorKey: 'role',  header: 'Role' }),
+  ];
+
+  protected readonly rows = signal<User[]>([
+    { id: '1', name: 'Alice Chen', email: 'alice@example.com', role: 'admin'  },
+    { id: '2', name: 'Bob Lin',    email: 'bob@example.com',   role: 'editor' },
+    { id: '3', name: 'Carla Diaz', email: 'carla@example.com', role: 'viewer' },
+    { id: '4', name: 'Dan Park',   email: 'dan@example.com',   role: 'editor' },
+    { id: '5', name: 'Eve Tran',   email: 'eve@example.com',   role: 'admin'  },
+    { id: '6', name: 'Frank Ng',   email: 'frank@example.com', role: 'viewer' },
+  ]);
+
+  private readonly tableCmp = viewChild.required(KjTableComponent);
+
+  constructor() {
+    // `KjTableState` doesn't include rowPinning, so we drive it through the
+    // TanStack instance directly once the view has been created.
+    afterNextRender(() => {
+      this.tableCmp().tableRef().table().setRowPinning({
+        top: ['1', '2'],
+        bottom: ['5'],
+      });
+    });
+  }
+}

package/src/table/_examples/table.selection.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';
+import { KjTableToolbarComponent, KjBulkAction } from '../table-toolbar';
+import { KjTableStatusBarComponent } from '../table-status-bar';
+import { KjButtonComponent } from '../../button/button';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: 'admin' | 'editor' | 'viewer';
+  joined: string;
+}
+
+/**
+ * Multi-row selection — `kjSelectionMode="multi"` enables row-toggle interaction
+ * (click + Space / Shift+click). The status bar shows the selected count and the
+ * toolbar reveals a bulk-action button once any row is selected.
+ */
+@Component({
+  selector: 'kj-table-selection-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [
+    KjTableComponent,
+    KjTableToolbarComponent,
+    KjTableStatusBarComponent,
+    KjBulkAction,
+    KjButtonComponent,
+  ],
+  styles: [`:host { display: block; }`],
+  template: `
+    <kj-table
+      [kjData]="rows()"
+      [kjColumns]="cols"
+      [kjGetRowId]="getRowId"
+      kjSelectionMode="multi"
+    >
+      <kj-table-toolbar kjToolbar>
+        <kj-button kjBulkAction kjVariant="destructive" kjSize="sm">Delete selected</kj-button>
+      </kj-table-toolbar>
+      <kj-table-status-bar />
+    </kj-table>
+  `,
+})
+export class KjTableSelectionExample {
+  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' },
+    { id: '6',  name: 'Frank Hughes', email: 'frank@example.com',  role: 'viewer', joined: '2024-06-12' },
+    { id: '7',  name: 'Grace Ito',    email: 'grace@example.com',  role: 'admin',  joined: '2024-07-04' },
+    { id: '8',  name: 'Henry Jones',  email: 'henry@example.com',  role: 'editor', joined: '2024-08-19' },
+  ]);
+
+  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'   }),
+    kjColumn<User>({ id: 'joined', accessorKey: 'joined', header: 'Joined' }),
+  ];
+
+  protected readonly getRowId = (row: User): string => row.id;
+}

package/src/table/_examples/table.server-mode.example.ts

@@ -0,0 +1,120 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { kjColumn, kjTableResource, type KjColumnDef, type KjTableState } from '@kouji-ui/core';
+import { KjTableComponent } from '../table';
+import { KjTableToolbarComponent } from '../table-toolbar';
+import { KjTablePaginationComponent } from '../table-pagination';
+import { KjTableStatusBarComponent } from '../table-status-bar';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: 'admin' | 'editor' | 'viewer';
+}
+
+const ROLES: User['role'][] = ['admin', 'editor', 'viewer'];
+
+const ALL_USERS: User[] = Array.from({ length: 200 }, (_, i) => ({
+  id: String(i + 1),
+  name: `User ${i + 1}`,
+  email: `user${i + 1}@example.com`,
+  role: ROLES[i % ROLES.length]!,
+}));
+
+const INITIAL_STATE: KjTableState = {
+  sorting: [],
+  columnFilters: [],
+  globalFilter: '',
+  pagination: { pageIndex: 0, pageSize: 25 },
+  rowSelection: {},
+  columnSizing: {},
+  columnVisibility: {},
+  columnOrder: [],
+  columnPinning: { left: [], right: [] },
+  expanded: {},
+  grouping: [],
+  density: 'standard',
+};
+
+/**
+ * Server-mode table — `kjTableResource()` wires the table's reactive state
+ * (sorting, filter, pagination) into an async loader. Each interaction round-
+ * trips through the 400 ms simulated endpoint and the table reflects loading
+ * + total-row state via the toolbar, status bar and pagination slot.
+ */
+@Component({
+  selector: 'kj-table-server-mode-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [
+    KjTableComponent,
+    KjTableToolbarComponent,
+    KjTablePaginationComponent,
+    KjTableStatusBarComponent,
+  ],
+  styles: [`
+    :host { display: block; }
+    /* Container-driven height: the table fills 480px and its body scrolls
+       internally — toolbar / status bar / pagination stay pinned above
+       and below the scrolling row area. */
+    kj-table { height: 480px; }
+  `],
+  template: `
+    <kj-table
+      [kjColumns]="cols"
+      [kjResource]="resource"
+      [kjGetRowId]="getRowId"
+      (stateChange)="onStateChange($event)"
+    >
+      <kj-table-toolbar kjToolbar />
+      <kj-table-status-bar />
+      <kj-table-pagination kjSize="xs" [kjPageSizes]="[10, 25, 50]" />
+    </kj-table>
+  `,
+})
+export class KjTableServerModeExample {
+  protected readonly state = signal<KjTableState>(INITIAL_STATE);
+
+  protected readonly resource = kjTableResource<User>({
+    stateSignal: this.state,
+    loader: async ({ state }) => {
+      await new Promise<void>((r) => setTimeout(r, 400));
+      let rows = ALL_USERS;
+      const filter = state.globalFilter.toLowerCase();
+      if (filter) {
+        rows = rows.filter(
+          (u) =>
+            u.name.toLowerCase().includes(filter) ||
+            u.email.toLowerCase().includes(filter) ||
+            u.role.toLowerCase().includes(filter),
+        );
+      }
+      const sort = state.sorting[0];
+      if (sort) {
+        const key = sort.id as keyof User;
+        rows = [...rows].sort((a, b) => {
+          const av = String(a[key] ?? '');
+          const bv = String(b[key] ?? '');
+          return sort.desc ? bv.localeCompare(av) : av.localeCompare(bv);
+        });
+      }
+      const start = state.pagination.pageIndex * state.pagination.pageSize;
+      return {
+        rows: rows.slice(start, start + state.pagination.pageSize),
+        rowCount: rows.length,
+      };
+    },
+  });
+
+  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 onStateChange(next: KjTableState): void {
+    this.state.set(next);
+  }
+}

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

@@ -0,0 +1,49 @@
+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;
+}
+
+/**
+ * Sortable columns — click a sortable header to toggle ASC / DESC / unsorted.
+ * The `role` column has `enableSorting: false` to show the opt-out.
+ */
+@Component({
+  selector: 'kj-table-sortable-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [KjTableComponent],
+  styles: [`:host { display: block; }`],
+  template: `
+    <kj-table [kjData]="rows()" [kjColumns]="cols" [kjGetRowId]="getRowId" />
+  `,
+})
+export class KjTableSortableExample {
+  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' },
+    { id: '6',  name: 'Frank Hughes',email: 'frank@example.com',  role: 'viewer', joined: '2024-06-12' },
+    { id: '7',  name: 'Grace Ito',   email: 'grace@example.com',  role: 'admin',  joined: '2024-07-04' },
+    { id: '8',  name: 'Henry Jones', email: 'henry@example.com',  role: 'editor', joined: '2024-08-19' },
+    { id: '9',  name: 'Iris Kim',    email: 'iris@example.com',   role: 'viewer', joined: '2024-09-01' },
+    { id: '10', name: 'Jack Liu',    email: 'jack@example.com',   role: 'editor', joined: '2024-10-25' },
+  ]);
+
+  protected readonly cols: KjColumnDef<User>[] = [
+    kjColumn<User>({ id: 'name',   accessorKey: 'name',   header: 'Name',   enableSorting: true  }),
+    kjColumn<User>({ id: 'email',  accessorKey: 'email',  header: 'Email',  enableSorting: true  }),
+    kjColumn<User>({ id: 'role',   accessorKey: 'role',   header: 'Role',   enableSorting: false }),
+    kjColumn<User>({ id: 'joined', accessorKey: 'joined', header: 'Joined', enableSorting: true  }),
+  ];
+
+  protected readonly getRowId = (row: User): string => row.id;
+}

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

@@ -0,0 +1,64 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { kjColumn } from '@kouji-ui/core';
+import { KjTableComponent } from '../table';
+
+interface User {
+  readonly id: string;
+  readonly name: string;
+  readonly email: string;
+  readonly role: string;
+}
+
+const ROWS: User[] = [
+  { id: '1', name: 'Alice', email: 'alice@x.io', role: 'Admin'  },
+  { id: '2', name: 'Bob',   email: 'bob@x.io',   role: 'Editor' },
+  { id: '3', name: 'Carol', email: 'carol@x.io', role: 'Viewer' },
+  { id: '4', name: 'Dan',   email: 'dan@x.io',   role: 'Viewer' },
+];
+
+/**
+ * The same table stacked three times under `bordered`, `striped`, and `clean`
+ * variants to compare how the theme tokens render each style. The variant
+ * value is reflected on the host as `[attr.data-variant]`.
+ *
+ */
+@Component({
+  selector: 'kj-table-theming-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [KjTableComponent],
+  styles: [`
+    :host { display: block; }
+    section { margin-bottom: 1rem; }
+    h4 {
+      margin: 0 0 0.25rem;
+      font-size: 0.75rem;
+      font-weight: 600;
+      letter-spacing: 0.05em;
+      text-transform: uppercase;
+      color: var(--kj-base-color-text-subtle, #666);
+    }
+  `],
+  template: `
+    @for (v of variants; track v) {
+      <section>
+        <h4>{{ v }}</h4>
+        <kj-table
+          [kjData]="data()"
+          [kjColumns]="cols"
+          [kjVariant]="v"
+        />
+      </section>
+    }
+  `,
+})
+export class KjTableThemingExample {
+  protected readonly variants = ['bordered', 'striped', 'clean'] as const;
+  protected readonly data = signal<User[]>(ROWS);
+
+  protected readonly cols = [
+    kjColumn<User>({ accessorKey: 'name',  header: 'Name'  }),
+    kjColumn<User>({ accessorKey: 'email', header: 'Email' }),
+    kjColumn<User>({ accessorKey: 'role',  header: 'Role'  }),
+  ];
+}

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

@@ -0,0 +1,90 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { kjColumn, type KjColumnDef } from '@kouji-ui/core';
+import { KjTableComponent } from '../table';
+import { KjTableToolbarComponent } from '../table-toolbar';
+import { KjTablePaginationComponent } from '../table-pagination';
+import { KjTableStatusBarComponent } from '../table-status-bar';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: 'admin' | 'editor' | 'viewer';
+  joined: string;
+}
+
+const FIRST_NAMES = [
+  'Alice', 'Bob', 'Carol', 'Dan', 'Eve', 'Frank', 'Grace', 'Henry', 'Iris', 'Jack',
+  'Kara', 'Liam', 'Maya', 'Noah', 'Olive', 'Pat', 'Quinn', 'Ravi', 'Sage', 'Tia',
+  'Uma', 'Vik', 'Wren', 'Xander', 'Yara', 'Zane',
+];
+const LAST_NAMES = [
+  'Chen', 'Diaz', 'Evans', 'Fischer', 'Garcia', 'Hughes', 'Ito', 'Jones', 'Kim', 'Liu',
+  'Mendes', 'Novak', 'Ortiz', 'Park', 'Quintero', 'Rao', 'Singh', 'Tanaka', 'Ueda', 'Vega',
+];
+const ROLES: User['role'][] = ['admin', 'editor', 'viewer'];
+
+/**
+ * 80 deterministic users — enough rows that pagination's next/prev land
+ * un-disabled at the default `pageSize: 25` (4 pages), so the footer reads
+ * as an interactive control instead of a static row count.
+ */
+function buildUsers(): User[] {
+  const out: User[] = [];
+  for (let i = 1; i <= 80; i++) {
+    const fn = FIRST_NAMES[i % FIRST_NAMES.length]!;
+    const ln = LAST_NAMES[(i * 7) % LAST_NAMES.length]!;
+    const month = String(((i - 1) % 12) + 1).padStart(2, '0');
+    const day = String(((i * 3) % 28) + 1).padStart(2, '0');
+    out.push({
+      id: String(i),
+      name: `${fn} ${ln}`,
+      email: `${fn.toLowerCase()}.${ln.toLowerCase()}@example.com`,
+      role: ROLES[i % ROLES.length]!,
+      joined: `2024-${month}-${day}`,
+    });
+  }
+  return out;
+}
+
+/**
+ * Full host API — bordered variant, compact density, toolbar slot, pagination,
+ * status bar, and a stable row id. The canonical reference layout.
+ */
+@Component({
+  selector: 'kj-table-usage-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [
+    KjTableComponent,
+    KjTableToolbarComponent,
+    KjTablePaginationComponent,
+    KjTableStatusBarComponent,
+  ],
+  styles: [`:host { display: block; }`],
+  template: `
+    <kj-table
+      [kjData]="rows()"
+      [kjColumns]="cols"
+      [kjGetRowId]="getRowId"
+      kjDensity="compact"
+      kjVariant="bordered"
+    >
+      <kj-table-toolbar kjToolbar />
+      <kj-table-status-bar />
+      <kj-table-pagination [kjPageSizes]="[5, 10, 25]" />
+    </kj-table>
+  `,
+})
+export class KjTableUsageExample {
+  protected readonly rows = signal<User[]>(buildUsers());
+
+  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'   }),
+    kjColumn<User>({ id: 'joined', accessorKey: 'joined', header: 'Joined' }),
+  ];
+
+  protected readonly getRowId = (row: User): string => row.id;
+}