@kouji-ui/components 0.1.1

package/src/table/table.ts

@@ -0,0 +1,1009 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  TemplateRef,
+  Type,
+  ViewEncapsulation,
+  computed,
+  effect,
+  inject,
+  input,
+  model,
+  output,
+  signal,
+  untracked,
+  contentChild,
+} from '@angular/core';
+import { NgTemplateOutlet } from '@angular/common';
+import type { ResourceRef } from '@angular/core';
+import {
+  KjTable,
+  KjTableHeader,
+  KjTableRow,
+  KjTableCell,
+  KjTableKeyboardNav,
+  KjIconDirective,
+  KJ_TABLE_STORAGE,
+  type KjColumnMeta,
+  type KjResourceResult,
+  type KjStorageAdapter,
+  type KjTableState,
+} from '@kouji-ui/core';
+import type { Cell, Column, Header, Row, RowData } from '@tanstack/angular-table';
+import { KjTableVirtual } from './table-virtual';
+import { KjCheckboxComponent } from '../checkbox/checkbox';
+import {
+  KjBooleanEditor,
+  KjDateEditor,
+  KjNumberEditor,
+  KjSelectEditor,
+  KjTextEditor,
+} from './table-editors';
+import {
+  KjDateFilter,
+  KjNumberFilter,
+  KjSelectFilter,
+  KjTextFilter,
+} from './table-filters';
+import { KjCellEditorOutlet } from './table-cell-editor-outlet';
+import { KjFilterCellOutlet } from './table-filter-outlet';
+
+/** Cell-edit payload emitted by `(cellEdit)`. */
+export interface KjCellEditEvent<TData> {
+  readonly row: TData;
+  readonly columnId: string;
+  readonly oldValue: unknown;
+  readonly newValue: unknown;
+}
+
+/** Row click payload. */
+export interface KjRowClickEvent<TData> {
+  readonly row: TData;
+  readonly event: MouseEvent;
+}
+
+const VIRTUAL_AUTO_THRESHOLD = 200;
+
+/** Lookup of column type → built-in editor component. */
+const BUILTIN_EDITORS: Readonly<Record<string, Type<unknown>>> = {
+  text: KjTextEditor,
+  number: KjNumberEditor,
+  date: KjDateEditor,
+  boolean: KjBooleanEditor,
+  select: KjSelectEditor,
+};
+
+/** Lookup of column type → built-in filter UI. */
+const BUILTIN_FILTERS: Readonly<Record<string, Type<unknown>>> = {
+  text: KjTextFilter,
+  number: KjNumberFilter,
+  date: KjDateFilter,
+  select: KjSelectFilter,
+};
+
+/**
+ * Themed root data table built on top of the headless `@kouji-ui/core` table
+ * directives. Wires TanStack-backed `<table>` rendering, ARIA grid semantics,
+ * density / variant tokens, content projection slots (toolbar, side-panel,
+ * empty, error, loading, row-expansion), persistence, virtualization,
+ * resource-backed data, inline editing, and column resizing.
+ *
+ * Three data modes:
+ * - **Static**: pass `kjData` as a plain array.
+ * - **Signal**: pass a signal of rows via `kjData`.
+ * - **Resource**: pass a `ResourceRef<KjResourceResult<T>>` via `kjResource`;
+ *   `kjData` is ignored and loading / error are derived from the resource.
+ *
+ * @example
+ * ```html
+ * <kj-table [kjData]="rows()" [kjColumns]="cols" kjDensity="compact" />
+ * ```
+ *
+ * @doc-example Default [full]
+ *   The smallest possible `<kj-table>` — three columns, five rows.
+ *   @doc-file table.example.ts
+ * @doc-example Usage [full]
+ *   Full host API: density toggle, bordered variant, toolbar / pagination /
+ *   status-bar slots projected.
+ *   @doc-file table.usage.example.ts
+ * @doc-example Sortable [full]
+ *   Click a header to sort; click again to flip direction; third click clears.
+ *   Shift-click a second header to add a secondary sort.
+ *   @doc-file table.sortable.example.ts
+ * @doc-example Filterable [full]
+ *   `[kjEnableFilters]="true"` renders a filter row under each header. Built-in
+ *   text / number / date / select filters pick by `kjType`.
+ *   @doc-file table.filterable.example.ts
+ * @doc-example Selection [full]
+ *   Multi-row selection with status-bar count + bulk-action slot.
+ *   @doc-file table.selection.example.ts
+ * @doc-example Inline editing [full]
+ *   Double-click a cell to mount the matching editor; Enter commits, Escape
+ *   cancels. Listen to `(cellEdit)` and persist yourself.
+ *   @doc-file table.editable.example.ts
+ * @doc-example Column visibility [full]
+ *   Show / hide columns via the toolbar's visibility menu.
+ *   @doc-file table.column-visibility.example.ts
+ * @doc-example Column resize [full]
+ *   `[kjEnableResize]="true"` puts a grab handle on each `<th>` border.
+ *   @doc-file table.column-resize.example.ts
+ * @doc-example Column pinning [full]
+ *   `kjPin: 'left' | 'right'` on a column meta pins it. Unpinned columns
+ *   scroll horizontally between the pinned edges.
+ *   @doc-file table.column-pinning.example.ts
+ * @doc-example Row pinning [full]
+ *   Pin rows top / bottom via TanStack's row-pinning state.
+ *   @doc-file table.row-pinning.example.ts
+ * @doc-example Grouping [full]
+ *   Group by a column; toggle group rows to collapse / expand.
+ *   @doc-file table.grouping.example.ts
+ * @doc-example Master / detail [full]
+ *   `<ng-template #kjRowExpansion let-row>` renders below the expanded row.
+ *   @doc-file table.master-detail.example.ts
+ * @doc-example Virtualized [full]
+ *   `[kjVirtual]="true"` (or `'auto'` past 200 rows) windows the body via
+ *   `@tanstack/virtual-core`.
+ *   @doc-file table.virtualized.example.ts
+ * @doc-example Density [full]
+ *   `compact` / `standard` / `comfortable` adjust row padding.
+ *   @doc-file table.density.example.ts
+ * @doc-example Theming [full]
+ *   `bordered` / `striped` / `clean` variants for visual weight.
+ *   @doc-file table.theming.example.ts
+ * @doc-example Server mode [full]
+ *   `kjTableResource()` wires the table state into an async loader; pagination
+ *   and filtering round-trip through your endpoint.
+ *   @doc-file table.server-mode.example.ts
+ * @doc-example Persistence [full]
+ *   `[kjStorageKey]` + a `KjStorageAdapter` round-trip sort / filter / pinning
+ *   / visibility / density through reload.
+ *   @doc-file table.persistence.example.ts
+ * @doc-example Export [full]
+ *   CSV / JSON / clipboard export via `data-table-export` utilities, wired to
+ *   the toolbar's export menu.
+ *   @doc-file table.export.example.ts
+ * @doc-example Empty and error [full]
+ *   Project `[kjEmpty]` / `[kjError]` slots to override the defaults.
+ *   @doc-file table.empty-and-error.example.ts
+ * @doc-example Keyboard [full]
+ *   Arrow / Home / End / Ctrl+Home/End / PageUp/Down / F2 / Enter / Esc /
+ *   Space / Cmd+A — full WAI-ARIA Grid pattern.
+ *   @doc-file table.keyboard.example.ts
+ *
+ * @doc-category Library/Data display
+ * @doc
+ * @doc-name table
+ * @doc-is-main
+ * @doc-description Themed data table built on TanStack — slots for toolbar, side panel, empty/error/loading; inline editing, filtering, resize, persistence, virtualization, resource-backed data.
+ */
+@Component({
+  selector: 'kj-table',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  // `hostDirectives: [KjTable]` hoists the core directive (and its
+  // `KJ_TABLE` provider) onto the `<kj-table>` host element so projected
+  // content — `<kj-table-toolbar>`, `<kj-table-status-bar>`,
+  // `<kj-table-pagination>` — can `inject(KJ_TABLE)` from its element
+  // injector. The aliased inputs expose the directive surface under
+  // wrapper-friendly names (`kjColumns`, `kjData`, `kjGetRowId`).
+  hostDirectives: [
+    {
+      directive: KjTable,
+      inputs: ['kjTable: kjColumns', 'kjTableData: kjData', 'kjGetRowId'],
+    },
+  ],
+  imports: [
+    KjTableHeader,
+    KjTableRow,
+    KjTableCell,
+    KjTableKeyboardNav,
+    KjTableVirtual,
+    KjIconDirective,
+    KjCheckboxComponent,
+    KjCellEditorOutlet,
+    KjFilterCellOutlet,
+    NgTemplateOutlet,
+  ],
+  host: {
+    // Read density from the hosted directive's signal — both the wrapper's
+    // `kjDensity` input AND the toolbar's density toggle write through to
+    // `KjTable.density` via `setState({ density })`, so a single source of
+    // truth drives the `data-density` host attribute.
+    '[attr.data-density]': 't.state.density()',
+    '[attr.data-variant]': 'kjVariant()',
+    '[attr.data-loading]': 'isLoading() ? "" : null',
+    '[attr.data-error]': 'hasError() ? "" : null',
+  },
+  template: `
+    <div class="kj-table-wrapper">
+      <!-- Toolbar projection: matches either an explicit [kjToolbar] marker
+           OR the styled <kj-table-toolbar> element directly, so users don't
+           have to remember the marker attribute. -->
+      <ng-content select="kj-table-toolbar, [kjToolbar]" />
+
+      <div class="kj-table-body">
+        <table kjTableKeyboardNav
+          role="grid"
+          [attr.aria-rowcount]="aria.rowCount()"
+          [attr.aria-colcount]="aria.colCount()"
+        >
+          <thead>
+            @for (g of t.table().getHeaderGroups(); track g.id) {
+              <tr role="row">
+                @if (showSelectionColumn()) {
+                  <th scope="col" class="kj-table-select-cell">
+                    @if (kjSelectionMode() === 'multi') {
+                      <kj-checkbox
+                        [checked]="t.table().getIsAllPageRowsSelected()"
+                        [indeterminate]="t.table().getIsSomePageRowsSelected()"
+                        (checkedChange)="onSelectAll($event)"
+                        kjAriaLabel="Select all rows"
+                      />
+                    }
+                  </th>
+                }
+                @for (h of g.headers; track h.id) {
+                  <th kjTableHeader
+                    [kjHeader]="h"
+                    scope="col"
+                    [style.width.px]="kjEnableResize() ? h.getSize() : null"
+                    [attr.data-pin]="headerPin(h)"
+                    [attr.data-resizing]="h.column.getIsResizing?.() ? '' : null"
+                    [style.--kj-resize-delta.px]="t.columnSizingInfo().deltaOffset ?? 0"
+                  >
+                    {{ h.column.columnDef.header }}
+                    @if (h.column.getCanSort?.()) {
+                      <i
+                        class="kj-table-sort-indicator"
+                        kjIconSize="sm"
+                        aria-hidden="true"
+                        [kjIcon]="sortIcon(h)"
+                      ></i>
+                    }
+                    @if (kjEnableResize() && h.column.getCanResize?.()) {
+                      <span
+                        class="kj-table-resize-handle"
+                        role="separator"
+                        aria-orientation="vertical"
+                        aria-label="Resize column"
+                        (mousedown)="h.getResizeHandler()($event)"
+                        (touchstart)="h.getResizeHandler()($event)"
+                      ></span>
+                    }
+                  </th>
+                }
+              </tr>
+            }
+            @if (kjEnableFilters()) {
+              <tr role="row" class="kj-table-filter-row">
+                @if (showSelectionColumn()) {
+                  <th scope="col" class="kj-table-select-cell"></th>
+                }
+                @for (g of t.table().getHeaderGroups(); track g.id) {
+                  @for (h of g.headers; track h.id) {
+                    <th scope="col" class="kj-table-filter-cell">
+                      @if (filterTypeFor(h.column); as ft) {
+                        <span
+                          kjFilterCell
+                          class="kj-table-filter-anchor"
+                          [kjColumn]="h.column"
+                          [kjFilter]="filterRendererFor(h.column, ft)"
+                        ></span>
+                      }
+                    </th>
+                  }
+                }
+              </tr>
+            }
+          </thead>
+
+          @if (kjEnableRowPinning() && t.table().getTopRows().length > 0) {
+            <tbody class="kj-table-tbody-pinned" data-pin="top">
+              @for (r of t.table().getTopRows(); track r.id) {
+                <tr kjTableRow [kjRow]="r"
+                    (click)="onRowClick(r, $event)"
+                    (dblclick)="onRowDblClick(r, $event)">
+                  @if (showSelectionColumn()) {
+                    <td class="kj-table-select-cell"
+                        (mousedown)="rememberClickModifiers($event)"
+                        (click)="$event.stopPropagation()">
+                      <kj-checkbox
+                        [checked]="r.getIsSelected()"
+                        (checkedChange)="onRowCheckboxToggle(r)"
+                        kjAriaLabel="Select row"
+                      />
+                    </td>
+                  }
+                  @for (c of r.getVisibleCells(); track c.id) {
+                    <td kjTableCell [kjCell]="c" tabindex="-1"
+                        [class.kj-table-cell--editing]="isEditing(c)"
+                        (click)="onCellClick(c, $event)"
+                        (dblclick)="onCellDblClick(c, $event)"
+                        (keydown)="onCellKeydown(c, $event)">
+                      @if (isEditing(c)) {
+                        <span class="kj-table-cell-ghost" aria-hidden="true">{{ c.getValue() }}</span>
+                        <span
+                          kjCellEditorOutlet
+                          class="kj-table-editor-anchor"
+                          [kjEditor]="editorTypeFor(c)"
+                          [kjValue]="c.getValue()"
+                          [kjMeta]="editorMetaFor(c)"
+                          (commit)="onEditorCommit(c, $event)"
+                          (editCancel)="onEditorCancel()"
+                        ></span>
+                      } @else {
+                        {{ c.getValue() }}
+                      }
+                    </td>
+                  }
+                </tr>
+              }
+            </tbody>
+          }
+
+          @if (shouldVirtualize()) {
+            <tbody
+              kjTableVirtual
+              [kjCount]="centerRows().length"
+              [kjEstimateSize]="kjEstimatedRowSize()"
+              #v="kjTableVirtual"
+            >
+              @if (v.paddingTop() > 0) {
+                <tr aria-hidden="true">
+                  <td [attr.colspan]="aria.colCount()" [style.height.px]="v.paddingTop()"></td>
+                </tr>
+              }
+              @for (vr of v.virtualRows(); track vr.key) {
+                @if (centerRows()[vr.index]; as r) {
+                  <tr kjTableRow [kjRow]="r"
+                      (click)="onRowClick(r, $event)"
+                      (dblclick)="onRowDblClick(r, $event)">
+                    @if (showSelectionColumn()) {
+                      <td class="kj-table-select-cell"
+                          (mousedown)="rememberClickModifiers($event)"
+                          (click)="$event.stopPropagation()">
+                        <kj-checkbox
+                          [checked]="r.getIsSelected()"
+                          (checkedChange)="onRowCheckboxToggle(r)"
+                          kjAriaLabel="Select row"
+                        />
+                      </td>
+                    }
+                    @for (c of r.getVisibleCells(); track c.id) {
+                      <td kjTableCell [kjCell]="c" tabindex="-1"
+                          [class.kj-table-cell--editing]="isEditing(c)"
+                          [style.width.px]="kjEnableResize() ? c.column.getSize() : null"
+                          (click)="onCellClick(c, $event)"
+                          (dblclick)="onCellDblClick(c, $event)"
+                          (keydown)="onCellKeydown(c, $event)">
+                        @if (isEditing(c)) {
+                          <span class="kj-table-cell-ghost" aria-hidden="true">{{ c.getValue() }}</span>
+                          <span
+                            kjCellEditorOutlet
+                            class="kj-table-editor-anchor"
+                            [kjEditor]="editorTypeFor(c)"
+                            [kjValue]="c.getValue()"
+                            [kjMeta]="editorMetaFor(c)"
+                            (commit)="onEditorCommit(c, $event)"
+                            (editCancel)="onEditorCancel()"
+                          ></span>
+                        } @else {
+                          {{ c.getValue() }}
+                        }
+                      </td>
+                    }
+                  </tr>
+                  @if (kjRowExpansionTpl() && r.getIsExpanded?.()) {
+                    <tr class="kj-table-expansion-row">
+                      <td [attr.colspan]="aria.colCount()">
+                        <ng-container
+                          [ngTemplateOutlet]="kjRowExpansionTpl()!"
+                          [ngTemplateOutletContext]="{ $implicit: r.original, row: r.original }"
+                        />
+                      </td>
+                    </tr>
+                  }
+                }
+              }
+              @if (v.paddingBottom() > 0) {
+                <tr aria-hidden="true">
+                  <td [attr.colspan]="aria.colCount()" [style.height.px]="v.paddingBottom()"></td>
+                </tr>
+              }
+            </tbody>
+          } @else {
+            <tbody>
+              @for (r of centerRows(); track r.id) {
+                <tr kjTableRow [kjRow]="r"
+                    [attr.data-row-grouped]="r.getIsGrouped?.() ? '' : null"
+                    (click)="onRowClick(r, $event)"
+                    (dblclick)="onRowDblClick(r, $event)">
+                  @if (showSelectionColumn()) {
+                    <td class="kj-table-select-cell"
+                        (mousedown)="rememberClickModifiers($event)"
+                        (click)="$event.stopPropagation()">
+                      <kj-checkbox
+                        [checked]="r.getIsSelected()"
+                        (checkedChange)="onRowCheckboxToggle(r)"
+                        kjAriaLabel="Select row"
+                      />
+                    </td>
+                  }
+                  @for (c of r.getVisibleCells(); track c.id) {
+                    <td kjTableCell [kjCell]="c" tabindex="-1"
+                        [class.kj-table-cell--editing]="isEditing(c)"
+                        [style.width.px]="kjEnableResize() ? c.column.getSize() : null"
+                        (click)="onCellClick(c, $event)"
+                        (dblclick)="onCellDblClick(c, $event)"
+                        (keydown)="onCellKeydown(c, $event)">
+                      @if (isEditing(c)) {
+                        <span class="kj-table-cell-ghost" aria-hidden="true">{{ c.getValue() }}</span>
+                        <span
+                          kjCellEditorOutlet
+                          class="kj-table-editor-anchor"
+                          [kjEditor]="editorTypeFor(c)"
+                          [kjValue]="c.getValue()"
+                          [kjMeta]="editorMetaFor(c)"
+                          (commit)="onEditorCommit(c, $event)"
+                          (editCancel)="onEditorCancel()"
+                        ></span>
+                      } @else if (c.getIsGrouped?.()) {
+                        <button type="button"
+                                class="kj-table-group-toggle"
+                                [attr.aria-expanded]="r.getIsExpanded?.() ? 'true' : 'false'"
+                                (click)="onGroupToggle(r, $event)">
+                          <span class="kj-table-group-toggle__chevron" aria-hidden="true">›</span>
+                          {{ c.getValue() }}
+                          <span class="kj-table-group-toggle__count">({{ r.subRows?.length ?? 0 }})</span>
+                        </button>
+                      } @else if (c.getIsAggregated?.()) {
+                        {{ c.renderValue() }}
+                      } @else if (c.getIsPlaceholder?.()) {
+                      } @else {
+                        {{ c.getValue() }}
+                      }
+                    </td>
+                  }
+                </tr>
+                @if (kjRowExpansionTpl() && r.getIsExpanded?.() && !r.getIsGrouped?.()) {
+                  <tr class="kj-table-expansion-row">
+                    <td [attr.colspan]="aria.colCount()">
+                      <ng-container
+                        [ngTemplateOutlet]="kjRowExpansionTpl()!"
+                        [ngTemplateOutletContext]="{ $implicit: r.original, row: r.original }"
+                      />
+                    </td>
+                  </tr>
+                }
+              }
+            </tbody>
+          }
+
+          @if (kjEnableRowPinning() && t.table().getBottomRows().length > 0) {
+            <tbody class="kj-table-tbody-pinned" data-pin="bottom">
+              @for (r of t.table().getBottomRows(); track r.id) {
+                <tr kjTableRow [kjRow]="r"
+                    (click)="onRowClick(r, $event)"
+                    (dblclick)="onRowDblClick(r, $event)">
+                  @if (showSelectionColumn()) {
+                    <td class="kj-table-select-cell"
+                        (mousedown)="rememberClickModifiers($event)"
+                        (click)="$event.stopPropagation()">
+                      <kj-checkbox
+                        [checked]="r.getIsSelected()"
+                        (checkedChange)="onRowCheckboxToggle(r)"
+                        kjAriaLabel="Select row"
+                      />
+                    </td>
+                  }
+                  @for (c of r.getVisibleCells(); track c.id) {
+                    <td kjTableCell [kjCell]="c" tabindex="-1">{{ c.getValue() }}</td>
+                  }
+                </tr>
+              }
+            </tbody>
+          }
+        </table>
+
+        <ng-content select="[kjSidePanel]" />
+      </div>
+
+      @if (showEmpty()) {
+        <div class="kj-table-empty" role="status">
+          <ng-content select="[kjEmpty]" />
+        </div>
+      }
+      @if (hasError()) {
+        <div class="kj-table-error" role="alert">
+          <ng-content select="[kjError]" />
+        </div>
+      }
+      @if (isLoading()) {
+        <div class="kj-table-loading"
+             aria-live="polite"
+             aria-busy="true"
+             [attr.data-has-rows]="effectiveData().length > 0 ? '' : null">
+          <ng-content select="[kjLoading]">
+            <span class="kj-table-loading-fallback">Loading…</span>
+          </ng-content>
+        </div>
+      }
+
+      <ng-content />
+    </div>
+  `,
+  styleUrl: './table.css',
+  encapsulation: ViewEncapsulation.Emulated,
+})
+export class KjTableComponent<TData extends RowData = unknown> {
+  // ── Data ────────────────────────────────────────────────────────────────
+  // `kjColumns`, `kjData`, `kjGetRowId` are exposed via `hostDirectives` input
+  // forwarding (see the `@Component` metadata) — bindings on `<kj-table>`
+  // flow straight into the hosted `KjTable` directive. We read them back via
+  // the injected directive instance (`this.t`) when the wrapper needs them.
+
+  /**
+   * Resource-backed data source. When set, rows come from
+   * `kjResource.value().rows`, `kjLoading` is derived from `isLoading()`, and
+   * the error slot renders when `error()` is non-null. The wrapper writes
+   * the resolved rows into the hosted `KjTable.kjTableData` model — the
+   * underlying TanStack instance always sees a single rows source.
+   */
+  readonly kjResource = input<ResourceRef<KjResourceResult<TData> | undefined> | null>(null);
+
+  // ── Theming ─────────────────────────────────────────────────────────────
+  readonly kjDensity = input<'compact' | 'standard' | 'comfortable'>('standard');
+  readonly kjVariant = input<'bordered' | 'striped' | 'clean'>('bordered');
+  /** External "I'm loading" flag, ORed with the resource's `isLoading()`. */
+  readonly kjLoading = input(false);
+
+  // ── Selection ───────────────────────────────────────────────────────────
+  readonly kjSelection = model<Set<string> | string | null>(null);
+  readonly kjSelectionMode = input<'single' | 'multi' | 'none'>('none');
+  /**
+   * Whether the wrapper auto-renders a leading checkbox column. Defaults to
+   * `true` whenever selection is enabled; set `false` to drive selection
+   * purely from row clicks / external state without the column.
+   */
+  readonly kjShowSelectionColumn = input<boolean>(true);
+
+  // ── Persistence ─────────────────────────────────────────────────────────
+  readonly kjStorageKey = input<string | null>(null);
+  readonly kjStorageAdapter = input<KjStorageAdapter | null>(null);
+
+  // ── Virtualization ──────────────────────────────────────────────────────
+  readonly kjVirtual = input<boolean | 'auto'>('auto');
+  readonly kjEstimatedRowSize = input<number>(36);
+
+  // ── Feature toggles ─────────────────────────────────────────────────────
+  readonly kjEnableFilters = input<boolean>(false);
+  readonly kjEnableResize = input<boolean>(false);
+  readonly kjEnableRowPinning = input<boolean>(false);
+  readonly kjEditOnDoubleClick = input<boolean>(true);
+
+  // ── Row expansion template ─────────────────────────────────────────────
+  /** Template for master-detail row expansion. Receives `$implicit = row`. */
+  readonly kjRowExpansionTpl = contentChild<TemplateRef<unknown>>('kjRowExpansion');
+
+  // ── Outputs ─────────────────────────────────────────────────────────────
+  readonly cellEdit = output<KjCellEditEvent<TData>>();
+  readonly stateChange = output<KjTableState>();
+  readonly rowClick = output<KjRowClickEvent<TData>>();
+  readonly rowDoubleClick = output<KjRowClickEvent<TData>>();
+
+  // ── Refs ────────────────────────────────────────────────────────────────
+  /**
+   * The hosted `KjTable` directive instance. Exposed under the legacy
+   * `tableRef()` API for examples that drive the table imperatively
+   * (`tableRef().setState(...)`, `tableRef().setRowPinning(...)`).
+   *
+   * `t` is the template-side alias for the same instance, used everywhere
+   * the template needs the TanStack table proxy (`t.table().getRowModel()`).
+   */
+  protected readonly t = inject(KjTable) as unknown as KjTable<TData>;
+  readonly tableRef = (): KjTable<TData> => this.t;
+
+  // ── Internal state ──────────────────────────────────────────────────────
+  private readonly tokenStorage = inject(KJ_TABLE_STORAGE, { optional: true });
+
+  /** Tracks the cell currently in edit mode by row+column id. */
+  protected readonly editingCell = signal<{ rowId: string; columnId: string } | null>(null);
+
+  // ── Computed ────────────────────────────────────────────────────────────
+  /**
+   * Effective rows driving TanStack:
+   *   - `kjResource` set → unwrap `resource.value().rows`
+   *   - otherwise → use the hosted directive's `kjTableData` model
+   *     (fed by `[kjData]` on the host).
+   */
+  protected readonly effectiveData = computed<TData[]>(() => {
+    const res = this.kjResource();
+    if (res) {
+      // Skip `.value()` when the resource is in error / loading — both throw
+      // or return stale data. The error / loading panes render instead, and
+      // the table model holds whatever the write-through effect last set.
+      if (res.error() != null || res.isLoading()) return [];
+      const v = res.value();
+      const rows = v?.rows;
+      return rows ? Array.from(rows) : [];
+    }
+    return this.t.kjTableData();
+  });
+
+  /**
+   * All center (non-pinned) rows from TanStack.
+   *
+   * When virtualization is active we skip pagination — the virtualizer is the
+   * windowing mechanism, so feeding it a 25-row page (TanStack's default) makes
+   * a 10k dataset look like 25 rows that can't scroll. `getPrePaginationRowModel`
+   * keeps sort + filter applied but returns the full slice.
+   */
+  protected readonly centerRows = computed<Row<TData>[]>(() => {
+    const tbl = this.t.table();
+    if (this.kjEnableRowPinning()) return tbl.getCenterRows();
+    return this.shouldVirtualize()
+      ? tbl.getPrePaginationRowModel().rows
+      : tbl.getRowModel().rows;
+  });
+
+  /**
+   * Whether the leading checkbox column should render. Auto-enables when
+   * selection mode is non-`none` AND the user hasn't opted out.
+   */
+  protected readonly showSelectionColumn = computed<boolean>(
+    () => this.kjSelectionMode() !== 'none' && this.kjShowSelectionColumn(),
+  );
+
+  /**
+   * Captured at mousedown on a select-cell so the subsequent checkbox
+   * `checkedChange` can branch on shift / ctrl/cmd without losing the modifier
+   * state (the keyboard modifiers are only on the originating MouseEvent;
+   * the change event from kj-checkbox doesn't carry them).
+   */
+  private lastClickShift = false;
+  private lastAnchorRowId: string | null = null;
+
+  /** True when the active resource is loading OR `kjLoading` is set. */
+  protected readonly isLoading = computed<boolean>(() => {
+    if (this.kjLoading()) return true;
+    const res = this.kjResource();
+    return res ? res.isLoading() : false;
+  });
+
+  /** True when the active resource is in error state. */
+  protected readonly hasError = computed<boolean>(() => {
+    const res = this.kjResource();
+    return res ? res.error() != null : false;
+  });
+
+  /** True when there are no rows AND we are not loading or errored. */
+  protected readonly showEmpty = computed<boolean>(
+    () => this.effectiveData().length === 0 && !this.isLoading() && !this.hasError(),
+  );
+
+  /**
+   * Whether row virtualization should be enabled. Counts against the
+   * pre-pagination row model so `'auto'` flips on for large datasets that
+   * would otherwise be split across paginated pages.
+   */
+  protected readonly shouldVirtualize = computed<boolean>(() => {
+    const mode = this.kjVirtual();
+    if (mode === true) return true;
+    if (mode === false) return false;
+    return this.t.table().getPrePaginationRowModel().rows.length > VIRTUAL_AUTO_THRESHOLD;
+  });
+
+  protected readonly aria = {
+    rowCount: computed(() => this.effectiveData().length + 1),
+    colCount: computed(() => {
+      const cols = this.t.kjTable();
+      // Approximate: flatten one level of column groups for ARIA.
+      let n = 0;
+      for (const c of cols) {
+        const sub = (c as { columns?: unknown[] }).columns;
+        n += Array.isArray(sub) ? sub.length : 1;
+      }
+      return n;
+    }),
+  };
+
+  constructor() {
+    // Wrapper's `kjDensity` input → hosted directive's density state. Both
+    // the user's external binding AND the toolbar's density toggle write
+    // into `KjTable.density` via `setState`, so a single source of truth
+    // backs the host's `data-density` attribute and the row-padding CSS.
+    //
+    // The internal `t.density()` read is wrapped in `untracked` so the
+    // effect only fires on `kjDensity` input changes — without that, a
+    // toolbar click would update `t.density`, re-trigger this effect, and
+    // get clobbered back to the input value (feedback loop).
+    effect(() => {
+      const next = this.kjDensity();
+      untracked(() => {
+        if (this.t.state.density() !== next) this.t.setState({ density: next });
+      });
+    });
+
+    // Pipe resource rows into the hosted KjTable.kjTableData model so the
+    // single TanStack instance always sees one rows source. When kjResource
+    // is null the user's `[kjData]` binding flows through unchanged.
+    //
+    // `resource.value()` throws when the resource is in an error state
+    // (Angular's contract — read errors live on `.error()`). We guard on
+    // both `error()` and `isLoading()` so the error / loading panes own the
+    // UX while the table model keeps the last-known rows empty.
+    effect(() => {
+      const res = this.kjResource();
+      if (!res) {
+        // No resource → clear the manual-pagination total so the table
+        // falls back to client-side pagination on the user's `[kjData]`.
+        this.t.setRowCount(null);
+        return;
+      }
+      if (res.error() != null) {
+        this.t.kjTableData.set([]);
+        return;
+      }
+      if (res.isLoading()) return;
+      const value = res.value();
+      const rows = value?.rows;
+      this.t.kjTableData.set(rows ? Array.from(rows) as TData[] : []);
+      // Flip into manual-pagination mode and report the remote total
+      // so the pagination footer / status bar see the full dataset
+      // instead of just the current page slice.
+      this.t.setRowCount(value?.rowCount ?? null);
+    });
+
+    // Persistence: on init, read from adapter and seed table state.
+    effect(() => {
+      const key = this.kjStorageKey();
+      if (!key) return;
+      const adapter = this.kjStorageAdapter() ?? this.tokenStorage;
+      if (!adapter) return;
+      const tbl = untracked(() => this.t);
+      if (!tbl) return;
+      const persisted = adapter.read<Partial<KjTableState>>(key);
+      if (persisted) {
+        untracked(() => tbl.setState(persisted));
+      }
+    });
+
+    // Persistence: watch state and write through. Reading `state()` once
+    // is enough — the single signal invalidates on any slice change.
+    effect(() => {
+      const key = this.kjStorageKey();
+      if (!key) return;
+      const adapter = this.kjStorageAdapter() ?? this.tokenStorage;
+      if (!adapter) return;
+      adapter.write(key, this.t.state());
+    });
+
+    // State-change emission.
+    effect(() => {
+      this.stateChange.emit(this.t.state());
+    });
+  }
+
+  // ── Cell-edit handlers ──────────────────────────────────────────────────
+  protected isEditing(cell: Cell<TData, unknown>): boolean {
+    const e = this.editingCell();
+    return !!e && e.rowId === cell.row.id && e.columnId === cell.column.id;
+  }
+
+  protected onCellClick(cell: Cell<TData, unknown>, _event: MouseEvent): void {
+    if (this.kjEditOnDoubleClick()) return;
+    this.tryBeginEdit(cell);
+  }
+
+  protected onCellDblClick(cell: Cell<TData, unknown>, _event: MouseEvent): void {
+    if (!this.kjEditOnDoubleClick()) return;
+    this.tryBeginEdit(cell);
+  }
+
+  protected onCellKeydown(cell: Cell<TData, unknown>, event: KeyboardEvent): void {
+    if (event.key === 'F2') {
+      event.preventDefault();
+      this.tryBeginEdit(cell);
+    } else if (event.key === 'Escape' && this.isEditing(cell)) {
+      this.editingCell.set(null);
+    } else if (event.key === ' ' && !this.isEditing(cell)) {
+      // Space toggles row selection when selection is enabled (WCAG grid pattern).
+      const mode = this.kjSelectionMode();
+      if (mode === 'multi') {
+        event.preventDefault();
+        (cell.row as { toggleSelected?: () => void }).toggleSelected?.();
+      } else if (mode === 'single') {
+        event.preventDefault();
+        this.t.table().setRowSelection({ [cell.row.id]: true });
+      }
+    } else if ((event.ctrlKey || event.metaKey) && (event.key === 'a' || event.key === 'A')) {
+      // Cmd/Ctrl+A — select all (multi mode only).
+      if (this.kjSelectionMode() === 'multi') {
+        event.preventDefault();
+        this.t.table().toggleAllRowsSelected(true);
+      }
+    }
+  }
+
+  private tryBeginEdit(cell: Cell<TData, unknown>): void {
+    const meta = cellMeta(cell.column);
+    if (!meta?.editable) return;
+    this.editingCell.set({ rowId: cell.row.id, columnId: cell.column.id });
+  }
+
+  // ── Row-click handlers ──────────────────────────────────────────────────
+  protected onRowClick(row: Row<TData>, event: MouseEvent): void {
+    // A click that lands on an interactive control inside the row (group
+    // toggle button, inline editor, link, etc.) should not double-toggle
+    // row selection — only bare-row clicks count.
+    const target = event.target as HTMLElement | null;
+    if (target?.closest('button, a, input, select, textarea, .kj-table-editor-anchor')) {
+      this.rowClick.emit({ row: row.original, event });
+      return;
+    }
+    this.applySelectionFromClick(row, event);
+    this.rowClick.emit({ row: row.original, event });
+  }
+
+  protected onRowDblClick(row: Row<TData>, event: MouseEvent): void {
+    this.rowDoubleClick.emit({ row: row.original, event });
+  }
+
+  /**
+   * Toggle / replace row selection based on `kjSelectionMode`:
+   *   - `'multi'`  → plain click toggles this row and moves the anchor.
+   *     Shift-click selects every row between the anchor and here (range).
+   *     Ctrl/Cmd-click toggles this row only (anchor moves, others kept).
+   *   - `'single'` → set this row as the sole selection.
+   *   - `'none'`   → no-op.
+   */
+  private applySelectionFromClick(row: Row<TData>, event: MouseEvent): void {
+    const mode = this.kjSelectionMode();
+    if (mode === 'none') return;
+    const tbl = this.t.table();
+    if (mode === 'single') {
+      tbl.setRowSelection({ [row.id]: true });
+      this.lastAnchorRowId = row.id;
+      return;
+    }
+    // multi
+    if (event.shiftKey && this.lastAnchorRowId !== null) {
+      this.selectRange(this.lastAnchorRowId, row.id, true);
+      return;
+    }
+    (row as { toggleSelected?: () => void }).toggleSelected?.();
+    this.lastAnchorRowId = row.id;
+  }
+
+  /**
+   * Capture the shift modifier from mousedown on a select-cell. The
+   * checkbox's `checkedChange` doesn't carry the originating mouse event,
+   * so we stash the modifier and consume it in `onRowCheckboxToggle`.
+   */
+  protected rememberClickModifiers(event: MouseEvent): void {
+    this.lastClickShift = event.shiftKey;
+  }
+
+  /** Click on a row's checkbox: shift extends from anchor, else plain toggle. */
+  protected onRowCheckboxToggle(row: Row<TData>): void {
+    const wasShift = this.lastClickShift;
+    this.lastClickShift = false;
+    if (wasShift && this.lastAnchorRowId !== null && this.kjSelectionMode() === 'multi') {
+      this.selectRange(this.lastAnchorRowId, row.id, true);
+      return;
+    }
+    (row as { toggleSelected?: () => void }).toggleSelected?.();
+    this.lastAnchorRowId = row.id;
+  }
+
+  /** Header "select all" checkbox change. */
+  protected onSelectAll(checked: boolean): void {
+    this.t.table().toggleAllPageRowsSelected(checked);
+  }
+
+  /**
+   * Set every row between `fromId` and `toId` (inclusive, order-agnostic) to
+   * `selected`. Existing selections OUTSIDE that window are preserved.
+   */
+  private selectRange(fromId: string, toId: string, selected: boolean): void {
+    const rows = this.centerRows();
+    const fromIdx = rows.findIndex((r) => r.id === fromId);
+    const toIdx = rows.findIndex((r) => r.id === toId);
+    if (fromIdx === -1 || toIdx === -1) return;
+    const [start, end] = fromIdx < toIdx ? [fromIdx, toIdx] : [toIdx, fromIdx];
+    const next: Record<string, boolean> = { ...this.t.state.rowSelection() };
+    for (let i = start; i <= end; i++) {
+      next[rows[i].id] = selected;
+    }
+    this.t.table().setRowSelection(next);
+  }
+
+  /**
+   * Toggle a grouped row's expanded state. Wired to the click handler on the
+   * group-cell's toggle button; `stopPropagation` prevents the parent row's
+   * `(click)` from firing a row-click event for what is really a UI control.
+   */
+  protected onGroupToggle(row: Row<TData>, event: MouseEvent): void {
+    event.stopPropagation();
+    (row as { toggleExpanded?: () => void }).toggleExpanded?.();
+  }
+
+  // ── Header helpers ──────────────────────────────────────────────────────
+  protected headerPin(h: Header<TData, unknown>): 'left' | 'right' | null {
+    const p = h.column.getIsPinned?.();
+    return p === 'left' || p === 'right' ? p : null;
+  }
+
+  /**
+   * Lucide icon name for a sortable header's indicator. We read the column's
+   * current sort state directly so the template re-evaluates whenever the
+   * parent sort signal changes (TanStack's table proxy is signal-backed).
+   */
+  protected sortIcon(h: Header<TData, unknown>): 'chevron-up' | 'chevron-down' | 'chevrons-up-down' {
+    const dir = h.column.getIsSorted?.();
+    if (dir === 'asc') return 'chevron-up';
+    if (dir === 'desc') return 'chevron-down';
+    return 'chevrons-up-down';
+  }
+
+  protected filterTypeFor(col: Column<TData, unknown>): string | null {
+    const meta = (col.columnDef.meta as { kj?: KjColumnMeta<TData> } | undefined)?.kj;
+    if (!meta) return null;
+    if (meta.filterable === false) return null;
+    const type = meta.type;
+    if (!type) return null;
+    return type in BUILTIN_FILTERS ? type : null;
+  }
+
+  // ── Template helpers for the editor / filter outlet directives ─────────
+  /** Resolves the editor component for a cell — column `meta.kj.editor`
+   *  override, else the built-in editor that matches `meta.kj.type`. */
+  protected editorTypeFor(cell: Cell<TData, unknown>): Type<unknown> | null {
+    const meta = (cell.column.columnDef.meta as { kj?: KjColumnMeta<TData> } | undefined)?.kj;
+    const custom = meta?.editor as Type<unknown> | undefined;
+    if (custom) return custom;
+    const type = meta?.type;
+    if (!type) return BUILTIN_EDITORS['text']!;
+    return BUILTIN_EDITORS[type] ?? null;
+  }
+
+  /** Build the meta bag handed to the editor through `KJ_EDITOR_CONTRACT`.
+   *  Select options, min/max, custom params travel through here so editors
+   *  don't need imperative input binding from the outlet. */
+  protected editorMetaFor(cell: Cell<TData, unknown>): Record<string, unknown> | undefined {
+    const meta = (cell.column.columnDef.meta as { kj?: KjColumnMeta<TData> } | undefined)?.kj;
+    if (!meta) return undefined;
+    const out: Record<string, unknown> = {};
+    if (meta.selectOptions) out['options'] = meta.selectOptions;
+    return Object.keys(out).length > 0 ? out : undefined;
+  }
+
+  /** Resolves the filter component for a column — `meta.kj.filterUi` override
+   *  else the built-in filter that matches `type`. */
+  protected filterRendererFor(col: Column<TData, unknown>, type: string): Type<unknown> | null {
+    const meta = (col.columnDef.meta as { kj?: KjColumnMeta<TData> } | undefined)?.kj;
+    const custom = meta?.filterUi as Type<unknown> | undefined;
+    return custom ?? BUILTIN_FILTERS[type] ?? null;
+  }
+
+  /** Editor `(commit)` from `KjCellEditorOutlet`: forward + close the editor. */
+  protected onEditorCommit(cell: Cell<TData, unknown>, next: unknown): void {
+    this.cellEdit.emit({
+      row: cell.row.original,
+      columnId: cell.column.id,
+      oldValue: cell.getValue(),
+      newValue: next,
+    });
+    this.editingCell.set(null);
+  }
+
+  /** Editor `(cancel)` from `KjCellEditorOutlet`: just close the editor. */
+  protected onEditorCancel(): void {
+    this.editingCell.set(null);
+  }
+}
+
+// ── helpers ───────────────────────────────────────────────────────────────
+function cellMeta<TData>(col: Column<TData, unknown>): KjColumnMeta<TData> | undefined {
+  return (col.columnDef.meta as { kj?: KjColumnMeta<TData> } | undefined)?.kj;
+}