@frame-kit/ui-ng 0.0.1

package/ui/copyable-field/README.md

@@ -0,0 +1,235 @@
+# fk-copyable-field
+
+A read-only value paired with a copy-to-clipboard button. Use it when a
+user needs to copy a secret, token, ID, URL, or any value that's easier to
+copy than to retype — API keys, OAuth client IDs, session tokens, signed
+URLs, etc.
+
+---
+
+## API
+
+### Inputs
+
+| Input                | Type                | Default                 | Description                                                                |
+| -------------------- | ------------------- | ----------------------- | -------------------------------------------------------------------------- |
+| `value`              | `string`            | _required_              | The text that gets written to the clipboard                                |
+| `label`              | `string \| null`    | `null`                  | Optional label rendered above the field                                    |
+| `size`               | `CopyableFieldSize` | `"md"`                  | Size modifier — `"sm"`, `"md"`, or `"lg"`                                  |
+| `mono`               | `boolean`           | `true`                  | Render the value in a monospace font                                       |
+| `copyAriaLabel`      | `string`            | `"Copy to clipboard"`   | Accessible label for the copy button                                       |
+| `copiedAnnouncement` | `string`            | `"Copied to clipboard"` | Message announced via `role="status"` after a successful copy              |
+| `copiedDuration`     | `number`            | `2000`                  | Milliseconds before the icon reverts and the announcement clears           |
+| `id`                 | `string \| null`    | `null`                  | Optional ID applied to the value element                                   |
+| `ariaLabel`          | `string \| null`    | `null`                  | Accessible label for the value element (use when the label prop is absent) |
+| `className`          | `string`            | `""`                    | Additional CSS classes merged onto the host element                        |
+
+### Outputs
+
+| Output       | Type      | Description                                              |
+| ------------ | --------- | -------------------------------------------------------- |
+| `copied`     | `string`  | Emits the copied value when the clipboard write succeeds |
+| `copyFailed` | `unknown` | Emits the rejection error when the clipboard API rejects |
+
+### Content Projection Slots
+
+| Attribute      | Description                                                                                                      |
+| -------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `fkCopyIcon`   | Optional custom icon shown on the copy button in the idle state. Defaults to an inline clipboard SVG.            |
+| `fkCopiedIcon` | Optional custom icon shown for `copiedDuration` ms after a successful copy. Defaults to an inline checkmark SVG. |
+
+```html
+<fk-copyable-field [value]="apiKey">
+  <fk-icon fkCopyIcon name="clipboard-outline" size="sm" />
+  <fk-icon fkCopiedIcon name="check-outline" size="sm" />
+</fk-copyable-field>
+```
+
+If a slot is not populated, the library renders its own inline SVG —
+consumers don't have to register anything to get a visible button.
+
+---
+
+## Features
+
+- One-click copy to the system clipboard via `navigator.clipboard`
+- Icon swap + screen-reader announcement confirm a successful copy
+- Auto-reverts after `copiedDuration` ms
+- Emits `copied` / `copyFailed` for analytics or custom UX
+- Three sizes (`sm`, `md`, `lg`) and optional monospace value styling
+- Token-driven styling with two-tier fallbacks
+- Renders correctly with no theme file loaded
+
+---
+
+## Quick Start
+
+```html
+<fk-copyable-field label="API key" [value]="apiKey" />
+```
+
+---
+
+## Import
+
+```ts
+import { CopyableFieldComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [CopyableFieldComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Selector
+
+```html
+<fk-copyable-field [value]="..." />
+```
+
+---
+
+## Examples
+
+### Basic API key field
+
+```html
+<fk-copyable-field label="Your new API key" [value]="apiKey" />
+```
+
+### Non-mono (plain text)
+
+```html
+<fk-copyable-field label="Org name" [mono]="false" value="Acme Realty" />
+```
+
+### Size variants
+
+```html
+<fk-copyable-field size="sm" value="sm_value" />
+<fk-copyable-field size="md" value="md_value" />
+<fk-copyable-field size="lg" value="lg_value" />
+```
+
+### Reacting to a successful copy
+
+```html
+<fk-copyable-field label="Client secret" [value]="secret" (copied)="onCopied($event)" (copyFailed)="onCopyFailed($event)" />
+```
+
+### Icon overrides
+
+```html
+<fk-copyable-field [value]="value">
+  <fk-icon fkCopyIcon name="clipboard-outline" size="sm" />
+  <fk-icon fkCopiedIcon name="check-outline" size="sm" />
+</fk-copyable-field>
+```
+
+The projected element just needs the `fkCopyIcon` / `fkCopiedIcon`
+attribute — it doesn't have to be `fk-icon`. Any inline SVG, icon
+component, or even plain text works.
+
+---
+
+## Accessibility
+
+- The copy button is a real `<button>` element with `aria-label` from the
+  `copyAriaLabel` input — keyboard-reachable, Enter / Space activate it
+- After a successful copy, a visually-hidden element with
+  `role="status"` and `aria-live="polite"` announces
+  `copiedAnnouncement` ("Copied to clipboard" by default)
+- Icons are marked `aria-hidden="true"` — all accessible text lives on
+  the button's label
+- Focus ring uses `--fk-focus-ring`
+
+---
+
+## Design Tokens
+
+`fk-copyable-field` is styled entirely through design tokens.
+
+### Component-specific tokens
+
+```
+--fk-copyable-field-gap
+--fk-copyable-field-bg
+--fk-copyable-field-border-color
+--fk-copyable-field-radius
+--fk-copyable-field-value-color
+
+--fk-copyable-field-label-color
+--fk-copyable-field-label-font-size
+--fk-copyable-field-label-font-weight
+--fk-copyable-field-label-gap
+
+--fk-copyable-field-action-color
+--fk-copyable-field-action-color-hover
+--fk-copyable-field-action-bg-hover
+--fk-copyable-field-action-padding
+--fk-copyable-field-action-radius
+
+--fk-copyable-field-padding-sm
+--fk-copyable-field-padding-md
+--fk-copyable-field-padding-lg
+--fk-copyable-field-font-size-sm
+--fk-copyable-field-font-size-md
+--fk-copyable-field-font-size-lg
+--fk-copyable-field-mono-font-family
+```
+
+### Shared tokens
+
+```
+--fk-rhythm-1
+--fk-rhythm-2
+--fk-rhythm-3
+--fk-rhythm-4
+--fk-color-text
+--fk-color-muted
+--fk-color-border
+--fk-color-surface-muted
+--fk-color-surface-dim
+--fk-font-family-mono
+--fk-typography-caption-font-size
+--fk-typography-small-font-size
+--fk-typography-body-font-size
+--fk-font-weight-medium
+--fk-radius-md
+--fk-radius-sm
+--fk-focus-ring
+```
+
+### Customizing Tokens
+
+```scss
+:root {
+  --fk-copyable-field-bg: #0f1626;
+  --fk-copyable-field-border-color: #1e2a44;
+  --fk-copyable-field-value-color: #e6edf7;
+  --fk-copyable-field-action-color: #8b98b5;
+}
+```
+
+---
+
+## Behavior Notes
+
+- Uses `navigator.clipboard.writeText(value)`; when the API is unavailable
+  or the user denies clipboard permission, `copyFailed` fires with the
+  caught error and the button's icon does not swap
+- The "copied" state is local to the component — rapidly clicking the
+  button resets the revert timer so the confirmation always stays for
+  `copiedDuration` ms after the most recent click
+- Long values wrap with `word-break: break-all` so the entire value stays
+  visible rather than being truncated
+- The component ships with inline SVG icons for both idle and copied
+  states, so it renders a visible button with no consumer setup. Override
+  either by projecting an element carrying the `fkCopyIcon` or
+  `fkCopiedIcon` attribute

package/ui/data-table/README.md

@@ -0,0 +1,408 @@
+# fk-data-table
+
+A token-driven, responsive data table component for Angular with sorting, virtual scrolling, column resizing, column pinning, multi-row selection (controlled or uncontrolled), and a mobile stacked card view.
+
+---
+
+## API
+
+### Inputs
+
+| Input                     | Type                               | Default        | Description                                                                                          |
+| ------------------------- | ---------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------- |
+| `columns`                 | `ColumnDef<T>[]`                   | `[]`           | Column definitions describing headers, accessors, and behavior                                       |
+| `rows`                    | `T[]`                              | `[]`           | Data rows to render                                                                                  |
+| `config`                  | `Partial<TableConfig<T>>`          | `{}`           | Table configuration merged with defaults                                                             |
+| `loading`                 | `boolean`                          | `false`        | Shows a loading overlay                                                                              |
+| `sortState`               | `SortState \| null`                | `null`         | Controlled sort state; `null` uses internal state                                                    |
+| `filterState`             | `FilterState \| null`              | `null`         | Controlled filter state; `null` uses internal state                                                  |
+| `pageState`               | `PageState \| null`                | `null`         | Controlled page state; `null` uses internal state                                                    |
+| `rowSelection`            | `boolean`                          | `false`        | Render a leading (or trailing) checkbox column with multi-row selection                              |
+| `selectedKeys`            | `Set<unknown> \| null`             | `null`         | Controlled selection set; `null` uses internal state. Table never mutates the input — emits new Sets |
+| `getRowId`                | `(row: T) => unknown` \| `null`    | `null`         | Required when `rowSelection` is `true`. Returns each row's stable identity key                       |
+| `selectionDisabled`       | `boolean \| ((row: T) => boolean)` | `false`        | Per-row opt-out. Disabled rows can't be selected and are skipped by the header "select all"          |
+| `selectionColumnPosition` | `'start' \| 'end'`                 | `'start'`      | Render the checkbox column at the leading or trailing edge                                           |
+| `selectionLabel`          | `string`                           | `'Select row'` | `aria-label` applied to each row checkbox                                                            |
+| `className`               | `string`                           | `''`           | Additional CSS classes for the host                                                                  |
+| `id`                      | `string \| null`                   | `null`         | Optional ID for the host element                                                                     |
+| `ariaLabel`               | `string \| null`                   | `null`         | ARIA label for the table                                                                             |
+
+### Outputs
+
+| Output            | Type                 | Description                                                                          |
+| ----------------- | -------------------- | ------------------------------------------------------------------------------------ |
+| `sortChange`      | `SortState`          | Emitted when a sortable column header is clicked                                     |
+| `filterChange`    | `FilterState`        | Emitted when filter state changes                                                    |
+| `pageChange`      | `PageState`          | Emitted when page state changes                                                      |
+| `rowClick`        | `TableRowContext<T>` | Emitted when a row is clicked (excludes checkbox clicks)                             |
+| `selectionChange` | `Set<unknown>`       | Emitted on every selection change. The Set is brand-new — the input is never mutated |
+| `columnResize`    | `ColumnResizeEvent`  | Emitted when a resizable column is resized                                           |
+
+### ColumnDef
+
+| Property         | Type                             | Default    | Description                                                    |
+| ---------------- | -------------------------------- | ---------- | -------------------------------------------------------------- |
+| `id`             | `string`                         | _required_ | Unique column identifier                                       |
+| `header`         | `string`                         | _required_ | Header text                                                    |
+| `accessor`       | `keyof T \| (row: T) => unknown` | _required_ | Key or function to extract cell value from a row               |
+| `sortAccessor`   | `(row: T) => unknown`            | —          | Custom accessor used for sorting instead of `accessor`         |
+| `width`          | `string`                         | —          | Explicit column width (e.g. `'200px'`)                         |
+| `minWidth`       | `string`                         | —          | Minimum column width                                           |
+| `maxWidth`       | `string`                         | —          | Maximum column width                                           |
+| `flex`           | `number`                         | —          | Flex value for virtual/div-based render path                   |
+| `sortable`       | `boolean`                        | —          | Enable sorting on this column                                  |
+| `align`          | `'start' \| 'center' \| 'end'`   | `'start'`  | Text alignment                                                 |
+| `truncate`       | `boolean`                        | —          | Truncate cell text with ellipsis                               |
+| `visible`        | `boolean`                        | `true`     | Whether the column is visible                                  |
+| `cellRenderer`   | `TemplateRef`                    | —          | Custom cell template; context: `{ $implicit: value, row: T }`  |
+| `headerRenderer` | `TemplateRef`                    | —          | Custom header template; context: `{ $implicit: ColumnDef<T> }` |
+| `priority`       | `number`                         | —          | Priority for responsive column hiding (lower = kept longer)    |
+| `hideBelow`      | `'sm' \| 'md' \| 'lg'`           | —          | Hide this column below the specified breakpoint                |
+| `mobileLabel`    | `string`                         | —          | Label used in the stacked mobile card view                     |
+| `resizable`      | `boolean`                        | —          | Enable drag-to-resize on this column                           |
+| `pinnable`       | `boolean`                        | —          | Mark column as eligible for pinning                            |
+| `pinned`         | `'start' \| 'end' \| null`       | `null`     | Pin column to the start or end of the table                    |
+
+### TableConfig
+
+| Property                  | Type                                          | Default                                                        | Description                                             |
+| ------------------------- | --------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------- |
+| `responsiveMode`          | `'auto' \| 'scroll' \| 'stack' \| 'priority'` | `'auto'`                                                       | How the table adapts at smaller viewports               |
+| `forceScroll`             | `boolean`                                     | `false`                                                        | Always use horizontal scroll instead of responsive mode |
+| `stickyHeader`            | `boolean`                                     | `true`                                                         | Stick the header row to the top on scroll               |
+| `showHeader`              | `boolean`                                     | `true`                                                         | Render the header row                                   |
+| `rowExpansion`            | `boolean`                                     | `false`                                                        | Enable row expansion                                    |
+| `emptyMessage`            | `string`                                      | `'No data available'`                                          | Message shown when no rows exist                        |
+| `trackBy`                 | `(index: number, row: T) => unknown`          | `(index) => index`                                             | Track-by function for row rendering                     |
+| `virtualization`          | `boolean \| 'auto'`                           | `'auto'`                                                       | Virtual scrolling mode                                  |
+| `virtualizationThreshold` | `number`                                      | `200`                                                          | Row count threshold for auto-activating virtualization  |
+| `rowHeight`               | `number`                                      | `48`                                                           | Fixed row height in px (required for virtual scrolling) |
+| `overscan`                | `number`                                      | `10`                                                           | Extra rows rendered above/below the viewport            |
+| `breakpoints`             | `{ sm: string; md: string }`                  | `{ sm: '(max-width: 35.999em)', md: '(max-width: 47.999em)' }` | Media query strings for responsive breakpoints          |
+
+> **Note:** `rowSelection` was previously a `TableConfig` flag but is now a top-level component input alongside the other selection inputs. Selection-related configuration is grouped on the component API for discoverability.
+
+---
+
+## Features
+
+- Sortable columns with tri-state cycling (asc → desc → none)
+- **Multi-row selection** with controlled or uncontrolled state
+- **Page-local select-all** header checkbox with `checked` / `unchecked` / `indeterminate` states
+- **Per-row selection-disabled** support via boolean or `(row) => boolean` predicate
+- **Selection column position** — leading (default) or trailing
+- Virtual scrolling for large datasets (auto-activates above threshold)
+- Responsive column hiding by priority or breakpoint
+- Stacked mobile card view with expand/collapse — checkbox surfaces above each card
+- Column resizing via drag handle
+- Column pinning (sticky start/end)
+- Custom cell and header templates via `TemplateRef`
+- Controlled or uncontrolled state for sort, filter, pagination, and selection
+- Loading overlay
+- Empty state message
+- Sticky header
+- Token-driven styling with dark mode support
+
+---
+
+## Quick Start
+
+```html
+<fk-data-table [columns]="columns" [rows]="rows" (rowClick)="onRowClick($event)" />
+```
+
+---
+
+## Import
+
+```ts
+import { DataTableComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-orders',
+  imports: [DataTableComponent],
+  templateUrl: './orders.component.html',
+})
+export class OrdersComponent {
+  columns: ColumnDef<Order>[] = [
+    { id: 'address', header: 'Address', accessor: 'address', sortable: true },
+    { id: 'status', header: 'Status', accessor: 'status' },
+    { id: 'price', header: 'Price', accessor: 'price', align: 'end' },
+  ];
+
+  rows: Order[] = [];
+}
+```
+
+---
+
+## Selector
+
+```html
+<fk-data-table></fk-data-table>
+```
+
+---
+
+## Examples
+
+### Sorting
+
+```html
+<fk-data-table [columns]="columns" [rows]="rows" (sortChange)="onSort($event)" />
+```
+
+Mark columns as sortable in the column definition:
+
+```ts
+{ id: "price", header: "Price", accessor: "price", sortable: true }
+```
+
+### Controlled sort (server-side)
+
+```html
+<fk-data-table [columns]="columns" [rows]="rows" [sortState]="currentSort" (sortChange)="fetchSorted($event)" />
+```
+
+When `sortState` is provided, the table delegates sorting to the consumer and does not sort internally.
+
+### Row selection — uncontrolled
+
+The simplest case. The table manages selection internally; the consumer just opts in.
+
+```html
+<fk-data-table [columns]="columns" [rows]="rows" [rowSelection]="true" [getRowId]="getRowId" (selectionChange)="onSelection($event)" />
+```
+
+```ts
+getRowId = (row: Order) => row.id;
+
+onSelection(keys: Set<unknown>): void {
+  console.log("Selected ids:", [...keys]);
+}
+```
+
+### Row selection — controlled (server-side pagination friendly)
+
+When the parent owns the truth, pass `selectedKeys` and update it on every `selectionChange`. Selections persist across pagination because the state lives in the parent.
+
+```ts
+readonly selection = signal<Set<unknown>>(new Set());
+readonly getRowId = (row: Order) => row.id;
+
+onSelection(next: Set<unknown>): void {
+  this.selection.set(next);  // emit a brand-new Set
+}
+```
+
+```html
+<fk-data-table [columns]="columns" [rows]="rows" [rowSelection]="true" [selectedKeys]="selection()" [getRowId]="getRowId" (selectionChange)="onSelection($event)" />
+```
+
+The table never mutates the `Set` you pass in — every selection action emits a brand-new instance.
+
+### Row selection — disabled rows
+
+Disable selection on specific rows (e.g. archived, locked). The header "select all" automatically skips them.
+
+```html
+<fk-data-table [columns]="columns" [rows]="rows" [rowSelection]="true" [getRowId]="getRowId" [selectionDisabled]="isLocked" />
+```
+
+```ts
+isLocked = (row: Order) => row.status === 'Closed';
+```
+
+`selectionDisabled` accepts a boolean (disable everything) or a `(row) => boolean` predicate. The header still flips to fully checked when **all eligible rows are selected** — disabled rows aren't counted against the all-selected check.
+
+### Selection column on the right
+
+```html
+<fk-data-table [columns]="columns" [rows]="rows" [rowSelection]="true" [getRowId]="getRowId" selectionColumnPosition="end" />
+```
+
+### Loading
+
+```html
+<fk-data-table [columns]="columns" [rows]="rows" [loading]="isLoading" />
+```
+
+### Empty state
+
+```html
+<fk-data-table [columns]="columns" [rows]="[]" [config]="{ emptyMessage: 'No records found' }" />
+```
+
+### Virtual scrolling
+
+Virtual scrolling activates automatically when row count exceeds `virtualizationThreshold` (default 200). Force it on or off:
+
+```html
+<fk-data-table [columns]="columns" [rows]="largeDataset" [config]="{ virtualization: true, rowHeight: 48 }" />
+```
+
+### Responsive mode
+
+```html
+<!-- Auto: switches between table and stack based on viewport -->
+<fk-data-table [columns]="columns" [rows]="rows" [config]="{ responsiveMode: 'auto' }" />
+
+<!-- Stack: always render mobile cards -->
+<fk-data-table [columns]="columns" [rows]="rows" [config]="{ responsiveMode: 'stack' }" />
+
+<!-- Priority: hide lower-priority columns first -->
+<fk-data-table [columns]="columns" [rows]="rows" [config]="{ responsiveMode: 'priority' }" />
+```
+
+Use `hideBelow` and `priority` on column definitions to control responsive visibility:
+
+```ts
+{ id: "notes", header: "Notes", accessor: "notes", hideBelow: "md", priority: 3 }
+```
+
+### Column resizing
+
+```html
+<fk-data-table [columns]="columns" [rows]="rows" (columnResize)="onResize($event)" />
+```
+
+Enable per column:
+
+```ts
+{ id: "address", header: "Address", accessor: "address", width: "200px", resizable: true }
+```
+
+### Column pinning
+
+```ts
+columns: ColumnDef<Order>[] = [
+  { id: "id", header: "ID", accessor: "id", width: "80px", pinned: "start" },
+  { id: "address", header: "Address", accessor: "address" },
+  { id: "status", header: "Status", accessor: "status" },
+  { id: "actions", header: "", accessor: () => "", width: "60px", pinned: "end" },
+];
+```
+
+Pinned columns stick to the left or right edge when scrolling horizontally.
+
+### Custom cell template
+
+```html
+<ng-template #statusCell let-value let-row="row">
+  <fk-badge [variant]="row.status === 'active' ? 'success' : 'neutral'"> {{ value }} </fk-badge>
+</ng-template>
+```
+
+```ts
+{ id: "status", header: "Status", accessor: "status", cellRenderer: statusCell }
+```
+
+---
+
+## Accessibility
+
+- The standard render path uses semantic `<table>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, and `<td>` elements
+- The virtual render path uses `role="table"`, `role="rowgroup"`, `role="row"`, `role="columnheader"`, and `role="cell"` on divs
+- Sortable columns announce sort direction via `aria-sort` (`ascending`, `descending`, or unset)
+- `aria-label` is forwarded to the table element
+- Loading overlay uses `aria-live="polite"`
+- Column resize handles are mouse/touch operated and add `cursor: col-resize` during drag
+- **Selection checkboxes** carry an `aria-label` derived from `selectionLabel` (default `"Select row"`); the header checkbox alternates between `"Select all on page"` and `"Deselect all on page"` based on its current state
+- **Indeterminate state** is set programmatically on the header checkbox when some-but-not-all visible rows are selected (standard browser behavior)
+- **Disabled rows** apply the native `disabled` attribute on their checkboxes — keyboard navigation and screen readers treat them correctly
+- **Click event propagation** is stopped on checkbox clicks so `rowClick` only fires for "real" row clicks, not selection toggles
+
+---
+
+## Design Tokens
+
+`fk-data-table` uses the following design tokens:
+
+```scss
+// Head
+--fk-data-table-head-bg
+--fk-data-table-head-color
+--fk-data-table-head-font-weight
+--fk-data-table-head-font-size
+--fk-data-table-head-hover-color
+
+// Body
+--fk-data-table-body-bg
+--fk-data-table-body-color
+--fk-data-table-body-font-size
+
+// Layout
+--fk-data-table-border-width
+--fk-data-table-border-radius
+--fk-data-table-border-color
+--fk-data-table-cell-padding
+--fk-data-table-row-hover-bg
+--fk-data-table-viewport-height
+
+// Empty & Loading
+--fk-data-table-empty-padding
+--fk-data-table-empty-color
+--fk-data-table-loading-bg
+--fk-data-table-loading-color
+
+// Resize
+--fk-data-table-resize-handle-width
+--fk-data-table-resize-handle-color
+
+// Pinning
+--fk-data-table-pin-offset
+
+// Row selection
+--fk-data-table-selection-cell-width
+--fk-data-table-row-selected-bg
+--fk-data-table-row-selected-hover-bg
+--fk-data-table-checkbox-size
+--fk-data-table-checkbox-border-color
+--fk-data-table-checkbox-radius
+--fk-data-table-checkbox-bg
+--fk-data-table-checkbox-hover-border-color
+--fk-data-table-checkbox-checked-bg
+--fk-data-table-checkbox-checked-border-color
+--fk-data-table-checkbox-icon-color
+```
+
+### Customizing Tokens
+
+Override tokens in your application's global stylesheet or a scoped selector:
+
+```css
+:root {
+  --fk-data-table-head-bg: #f1f5f9;
+  --fk-data-table-border-color: #e2e8f0;
+  --fk-data-table-row-hover-bg: #f8fafc;
+  --fk-data-table-row-selected-bg: #dbeafe;
+}
+```
+
+Or scope overrides to a specific context:
+
+```css
+.dark-theme fk-data-table {
+  --fk-data-table-head-bg: #1e293b;
+  --fk-data-table-head-color: #94a3b8;
+  --fk-data-table-body-bg: #0f172a;
+  --fk-data-table-body-color: #e2e8f0;
+  --fk-data-table-border-color: #334155;
+}
+```
+
+---
+
+## Behavior Notes
+
+- When `virtualization` is `'auto'`, the table switches to virtual scrolling when `rows.length` exceeds `virtualizationThreshold`.
+- Virtual scrolling requires a fixed `rowHeight`. The standard path does not enforce fixed heights.
+- When `responsiveMode` is `'auto'`, the table switches to a stacked card view on small viewports and a standard table on larger ones.
+- Column resizing is performed outside Angular's zone for performance. The `columnResize` event fires once on drag end.
+- Pinning uses `position: sticky` and requires explicit `width` or `minWidth` on pinned columns for offset calculation.
+- Passing `sortState`, `filterState`, `pageState`, or `selectedKeys` switches the corresponding concern to controlled mode — the table will not manage that state internally.
+- **Selection scope is page-local** — the header checkbox selects/deselects only the rows currently visible on the page, not the entire dataset. Existing selections on other pages persist when the controlled `selectedKeys` is held by the parent.
+- **`getRowId` is required** when `rowSelection` is `true`. Without it, the table falls back to row-reference equality which silently breaks across server-side pagination (each fetch returns brand-new objects). The component logs a `console.error` in dev when this combination is misconfigured.
+- **The `selectedKeys` input is never mutated.** Every selection action returns a brand-new `Set` via `selectionChange`. The parent owns the next state.