@human-kit/svelte-components 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/table/README.md

@@ -0,0 +1,143 @@
+<!-- markdownlint-disable MD010 -->
+
+# Table
+
+## Description
+
+`Table` is a headless interactive table primitive with grid-style keyboard navigation, row selection, explicit sortable header triggers, and a composable part-based API.
+
+All public Table part prop types are exported from the table barrel, including `TableRootProps`, `TableColumnProps`, `TableHeaderProps`, `TableBodyProps`, `TableFooterProps`, `TableRowProps`, `TableColumnHeaderCellProps`, `TableSortTriggerProps`, `TableColumnResizerProps`, `TableCellProps`, `TableEmptyStateProps`, `TableCheckboxProps`, and `TableCheckboxIndicatorProps`.
+
+## Anatomy
+
+```svelte
+<Table.Root aria-label="Users table">
+	<Table.Header>
+		<Table.Row>
+			<Table.Column id="selection">
+				<Table.ColumnHeaderCell>
+					<Table.Checkbox>
+						<Table.CheckboxIndicator>
+							<CheckIcon />
+						</Table.CheckboxIndicator>
+					</Table.Checkbox>
+				</Table.ColumnHeaderCell>
+			</Table.Column>
+			<Table.Column id="email" isRowHeader>
+				<Table.ColumnHeaderCell>Email</Table.ColumnHeaderCell>
+			</Table.Column>
+			<Table.Column id="group">
+				<Table.ColumnHeaderCell>
+					<Table.SortTrigger>
+						{#snippet children({ sortDirection })}
+							<button
+								type="button"
+								aria-label={`Group sort button. ${sortDirection ?? 'not sorted'}.`}
+							>
+								Sort group
+							</button>
+						{/snippet}
+					</Table.SortTrigger>
+				</Table.ColumnHeaderCell>
+			</Table.Column>
+			<Table.Column id="size" minWidth={120}>
+				<Table.ColumnHeaderCell>
+					Size
+					<Table.ColumnResizer />
+				</Table.ColumnHeaderCell>
+			</Table.Column>
+		</Table.Row>
+	</Table.Header>
+
+	<Table.Body>
+		<Table.Row id="danilo">
+			<Table.Cell>
+				<Table.Checkbox>
+					<Table.CheckboxIndicator>
+						<CheckIcon />
+					</Table.CheckboxIndicator>
+				</Table.Checkbox>
+			</Table.Cell>
+			<Table.Cell>danilo@example.com</Table.Cell>
+			<Table.Cell>Developer</Table.Cell>
+		</Table.Row>
+		<Table.EmptyState>No users found.</Table.EmptyState>
+	</Table.Body>
+
+	<Table.Footer>
+		<Table.Row>
+			<Table.Cell />
+			<Table.Cell>Total</Table.Cell>
+			<Table.Cell>1 user</Table.Cell>
+		</Table.Row>
+	</Table.Footer>
+</Table.Root>
+```
+
+- `Table.Root`
+- `Table.Column`
+- `Table.Header`
+- `Table.Body`
+- `Table.EmptyState`
+- `Table.Footer`
+- `Table.Row`
+- `Table.ColumnHeaderCell`
+- `Table.SortTrigger`
+- `Table.ColumnResizer`
+- `Table.Checkbox`
+- `Table.CheckboxIndicator`
+- `Table.Cell`
+
+## Usage guidelines
+
+- Use `Table.Root` as the stateful container for focus, selection, and sorting state.
+- Use `selectionBehavior="toggle"` to allow deselecting an already selected row, or `selectionBehavior="replace"` to keep selected rows selected when pressed again.
+- `Table.Column` is a logical-only wrapper for column metadata; it does not render DOM by itself and should wrap a single `Table.ColumnHeaderCell`.
+- Wrap each header cell in `Table.Column` so the table can register stable column metadata.
+- Add `Table.ColumnResizer` inside `Table.ColumnHeaderCell` to make the owning `Table.Column` resizable.
+- Provide `aria-label` or `aria-labelledby` on `Table.Root`.
+- Use `selectedKeys` / `onSelectionChange` for controlled row selection.
+- Use `defaultSelectedKeys` for uncontrolled initial row selection.
+- Use `sortDescriptor` / `onSortChange` for controlled sorting state.
+- Use `defaultSortDescriptor` for uncontrolled initial sort state.
+- Use `hiddenColumns` for controlled column visibility when consumers need to show or hide columns without changing the table markup.
+- Use `defaultHiddenColumns` for uncontrolled initial column visibility.
+- Use `columnWidths` / `onColumnWidthsChange` for controlled column width state. Width specs can be px, `%`, or `fr`.
+- Use `defaultColumnWidths` and `Table.Column.defaultWidth` to seed uncontrolled initial widths that can still be resized by the user.
+- Use `Table.Column.width` when a column should stay fixed at an explicit width. Fixed-width columns ignore resize attempts even if a `Table.ColumnResizer` is composed.
+- In resizable tables, unspecified columns behave like an implicit `1fr` width before interaction. On the first real resize, visible columns are materialized to px; the trailing column absorbs the delta until its minimum width, and further growth overflows the table horizontally.
+- Setting `sortDescriptor` back to `undefined` clears the controlled sort state, matching React Aria Table semantics.
+- Set `Table.Column.textValue` when the spoken column label should differ from the column id; `Table.Root` uses it for polite sort announcements.
+- Use `Table.EmptyState` inside `Table.Body` instead of conditionally rendering freeform body content.
+- Use `Table.Checkbox` when you need explicit selection UI inside cells instead of relying only on row or cell presses.
+- Use `Table.CheckboxIndicator` to compose your own visual affordance for checked and indeterminate states.
+- `Table.Checkbox` auto-hides in header cells unless `selectionMode="multiple"`, and auto-hides everywhere when `selectionMode="none"`.
+- Hidden columns are excluded from grid navigation, visible column counts, and active resize behavior, but their registered widths are preserved so they can be restored when shown again.
+- Dedicated utility columns like selection checkboxes should usually set an explicit `width`, `minWidth`, and `maxWidth` on `Table.Column` so sibling resizes do not redistribute their space.
+- When `selectionMode` changes to `none`, the component clears any existing row selection internally.
+- v1 leaves text selection and `Ctrl+C` behavior browser-native; the table does not implement custom copy handling or force a text-selection policy.
+- In `replace` mode, clicking outside the table clears focus but does not clear selection.
+- In body rows, pressing `ArrowLeft` before the first cell or `ArrowRight` after the last cell moves focus to the row itself. Repeating that same horizontal arrow loops back into the opposite edge cell of the same row.
+- `Table.Checkbox` is the supported interactive control inside table cells for explicit row selection in v1.
+
+## Composition contract
+
+- DOM-rendering parts: `Table.Root`, `Table.Header`, `Table.Body`, `Table.Footer`, `Table.Row`, `Table.Cell`, `Table.ColumnHeaderCell`, `Table.ColumnResizer`, `Table.Checkbox`, `Table.CheckboxIndicator`, and `Table.EmptyState` all render DOM.
+- Metadata-only part: `Table.Column` does not render its own element. It only registers the public column input for the surrounding header composition.
+- Sorting: `Table.SortTrigger` is the public opt-in for sortable columns. Rendering it inside `Table.ColumnHeaderCell` makes the owning `Table.Column` sortable and toggles `Table.Root.sortDescriptor`.
+- `Table.SortTrigger.children` can consume a `sortDirection` render state so the nested button can expose stateful labels or visuals without reading the root descriptor directly.
+- Resizing: `Table.ColumnResizer` is the only public opt-in for resizing. Rendering it inside a `Table.ColumnHeaderCell` enables resizing for the owning `Table.Column`.
+- Public input types: import the `Table*Props` types you need from `@human-kit/svelte-components/table` or the main package barrel instead of deriving contracts from component internals.
+- Internal normalized state: table context stores normalized column metadata internally as `TableColumnMetadata`. That metadata is not the public input contract for wrappers or consumers.
+
+## Accessibility
+
+- `Table.Root` renders an interactive `grid` over native table markup.
+- Keyboard navigation uses roving `tabindex` across header and body cells.
+- Body rows can also become the active focus target when horizontal navigation moves past the start or end of a row, and repeated left/right navigation loops back into the opposite edge cell.
+- `Table.Checkbox` can receive DOM focus directly while still participating in the table's roving-focus grid.
+- First-column body cells become `rowheader` when their associated column has `isRowHeader`.
+- Disabled rows remain rendered and non-selectable, but are skipped by focus navigation.
+- `Table.SortTrigger` wires a nested trigger button, while the header cell remains the roving-focus target for arrow-key grid navigation.
+- Sort changes are mirrored into a polite live region so screen readers announce direction changes more reliably than `aria-sort` alone.
+- Column resize handles are keyboard accessible separators. Press `Enter` to enter resize mode, use the horizontal arrow keys to resize, `Home` to jump to the minimum width, `End` to auto-fit to content width, and press `Enter` again to exit resize mode while keeping focus on the handle.

package/dist/table/SELECTION_CHECKBOX_PLAN.md

@@ -0,0 +1,234 @@
+<!-- markdownlint-disable MD013 MD033 MD056 MD060 -->
+
+# Table Selection Checkbox Plan
+
+## Goal
+
+Document the intended design for `Table.Checkbox` and `Table.CheckboxIndicator` parts that integrate with the existing table selection model without adding a separate high-level selection API.
+
+The component should be composable, predictable, and aligned with the current `Table` architecture:
+
+- part-based composition
+- centralized state in `Table.Root`
+- typed context contracts
+- Svelte 5 runes
+- keyboard navigation consistent with the current grid model
+
+## Confirmed Decisions
+
+- Public names: `Table.Checkbox` and `Table.CheckboxIndicator`
+- Composition model: the consumer places it manually inside `Table.Cell` and `Table.ColumnHeaderCell`
+- Focus target: the checkbox itself, not the table cell
+- Body behavior: toggles the row selection state and reflects it visually
+- Header behavior: acts as select-all / deselect-all only in `selectionMode="multiple"`
+- Header partial state: must support indeterminate state
+- Auto-visibility:
+  - when `selectionMode="none"`, all selection checkboxes should disappear
+  - when `selectionMode="single"`, body checkboxes stay visible but the header checkbox should disappear
+- The component should own its auto-hide behavior instead of pushing this responsibility to the consumer
+
+## Non-Goals
+
+- Do not add a separate slot-based table selection API for v1
+- Do not require a dedicated selection column abstraction
+- Do not reuse the generic `Checkbox.Root` implementation blindly if it complicates table focus/navigation integration
+- Do not make row selection depend on clicking the full row when explicit checkbox UI is present
+
+## Proposed Public Anatomy
+
+```svelte
+<Table.Root selectionMode="multiple" bind:selectedKeys>
+	<Table.Header>
+		<Table.Row>
+			<Table.Column id="selection">
+				<Table.ColumnHeaderCell>
+					<Table.Checkbox>
+						<Table.CheckboxIndicator>
+							<CheckIcon />
+						</Table.CheckboxIndicator>
+					</Table.Checkbox>
+				</Table.ColumnHeaderCell>
+			</Table.Column>
+
+			<Table.Column id="email" isRowHeader>
+				<Table.ColumnHeaderCell>Email</Table.ColumnHeaderCell>
+			</Table.Column>
+		</Table.Row>
+	</Table.Header>
+
+	<Table.Body>
+		{#each rows as row (row.id)}
+			<Table.Row id={row.id}>
+				<Table.Cell>
+					<Table.Checkbox>
+						<Table.CheckboxIndicator>
+							<CheckIcon />
+						</Table.CheckboxIndicator>
+					</Table.Checkbox>
+				</Table.Cell>
+				<Table.Cell>{row.email}</Table.Cell>
+			</Table.Row>
+		{/each}
+	</Table.Body>
+</Table.Root>
+```
+
+## Why This Shape
+
+- It preserves the existing `Table` mental model: columns, header cells, body cells, footer cells.
+- It avoids a parallel API such as `selection` slots or special root props that would only exist for one specific control.
+- It keeps selection UI opt-in and composable.
+- It allows consumers to position the checkbox column exactly where they need it.
+
+## Section-Based Behavior
+
+The component behavior depends on where it is rendered.
+
+| Location                 | `selectionMode="none"` | `selectionMode="single"` | `selectionMode="multiple"`   |
+| ------------------------ | ---------------------- | ------------------------ | ---------------------------- |
+| `Table.ColumnHeaderCell` | hidden                 | hidden                   | visible, select-all checkbox |
+| `Table.Cell` in body row | hidden                 | visible, row toggle      | visible, row toggle          |
+| footer cell              | hidden                 | hidden                   | hidden                       |
+
+## Behavior Details
+
+### Body Checkbox
+
+- Renders only inside body rows when `selectionMode` is not `none`
+- Checked state mirrors whether the current row is selected
+- Disabled state mirrors whether the current row is disabled
+- Clicking it toggles the row through the same selection pipeline used by the table
+- Keyboard interaction should behave like a table navigation target, not like an isolated form field
+
+### Header Checkbox
+
+- Renders only inside header cells when `selectionMode="multiple"`
+- Checked when all selectable rows are selected
+- Indeterminate when some selectable rows are selected but not all
+- Unchecked when no selectable rows are selected
+- Clicking it selects all selectable rows or clears the current selection
+- Disabled when there are no selectable rows
+
+## Focus Model
+
+The current table uses a roving tabindex model on cells. For `Table.Checkbox`, the desired behavior is different:
+
+- the checkbox should receive DOM focus directly
+- the table should still treat that checkbox as the focus target for the parent cell's grid position
+- arrow-key navigation must continue to work from the checkbox
+
+This implies a focus-delegation mechanism from `Table.Cell` to a child control.
+
+### Proposed Focus Delegation
+
+- `Table.Cell` keeps owning the grid key and participation in layout/focus bookkeeping
+- a child control can register itself as the focus delegate for that cell
+- when the table moves focus to that cell, the registered delegate receives DOM focus
+- when the delegate receives focus, it synchronizes the table's focused-cell state
+
+This is preferable to making the checkbox a completely separate navigable entity because it preserves the current grid architecture.
+
+## Keyboard Expectations
+
+When a `Table.Checkbox` is focused:
+
+- `Space` toggles selection
+- `Enter` toggles selection
+- `ArrowUp` / `ArrowDown` move within the table grid
+- `ArrowLeft` / `ArrowRight` move within the table grid
+- `Home` / `End` move to row boundaries
+- `Ctrl/Cmd + Home` and `Ctrl/Cmd + End` use the existing table-wide navigation behavior
+- `Ctrl/Cmd + A` keeps the current multiple-selection behavior
+
+The checkbox should not become a keyboard dead-end inside the table.
+
+## State Requirements in `TableContext`
+
+To support the header checkbox cleanly, the table context should expose a small amount of additional selection state:
+
+- a way to determine whether all selectable rows are selected
+- a way to determine whether some selectable rows are selected
+- a way to clear the current selection without changing `selectionMode`
+
+One reasonable shape is:
+
+```ts
+type TableSelectionCheckboxState = 'none' | 'some' | 'all';
+
+getSelectionCheckboxState(): TableSelectionCheckboxState;
+deselectAllRows(): void;
+```
+
+This should build on the existing ordered selectable row computation rather than duplicating selection rules in the component.
+
+## Accessibility Expectations
+
+- The checkbox should expose `role="checkbox"`
+- `aria-checked` should be:
+  - `"true"` when checked
+  - `"false"` when unchecked
+  - `"mixed"` when indeterminate
+- Disabled state should map to `aria-disabled`
+- The header checkbox should have an accessible label like `Select all rows`
+- Row checkboxes should have an accessible label like `Select row` or a consumer-provided label if the row content needs more specificity
+
+## Rendering Strategy
+
+The component does not need to be a full form checkbox.
+
+Because this control is tightly coupled to the table's grid navigation and selection logic, a lightweight table-specific implementation is likely more appropriate than directly wrapping the generic checkbox component. The generic checkbox has different responsibilities, including form integration, that are not required here.
+
+## Open Questions
+
+### Structural Validation
+
+If consumers place `Table.Checkbox` manually, it becomes easier to create invalid layouts accidentally.
+
+Examples:
+
+- header includes a selection checkbox column but body rows do not
+- some rows render fewer cells than others
+- the checkbox is placed in a footer cell where it has no behavior
+
+We should consider adding dev-time validation for mismatched column/cell counts and possibly invalid placement.
+
+### Labeling API
+
+The initial implementation can ship with sensible default labels, but we may want to support explicit labels later for highly customized row content.
+
+### Generic Focus Delegates
+
+If focus delegation is added for this part, it should be designed as a reusable mechanism rather than a one-off checkbox hack.
+
+## Implementation Outline
+
+### Phase 1: Context and Focus Plumbing
+
+- extend table selection helpers for header checkbox state
+- add `deselectAllRows()`
+- add focus delegation support from cells to nested controls
+
+### Phase 2: New Part
+
+- add `packages/svelte/src/lib/table/selection-checkbox/`
+- implement `table-selection-checkbox.svelte`
+- export it from `index.parts.ts` and `index.ts`
+
+### Phase 3: Tests
+
+- body checkbox renders and toggles correctly
+- header checkbox auto-hides correctly by selection mode
+- header checkbox supports checked / mixed / unchecked states
+- disabled rows stay disabled
+- focus lands on the checkbox instead of the parent cell
+- arrow navigation still works when the checkbox has focus
+
+### Phase 4: Documentation and Demo
+
+- add part README if the part becomes public
+- update table README anatomy
+- update the docs demo with a selection checkbox column
+
+## Summary
+
+`Table.Checkbox` should be a small, composable part that plugs into the existing table selection model rather than a new selection subsystem. `Table.CheckboxIndicator` keeps the visuals fully consumer-controlled. The key implementation challenge is not checkbox visuals, but integrating direct checkbox focus with the table's current roving-focus grid behavior.

package/dist/table/TODO.md

@@ -0,0 +1,138 @@
+# Table TODO
+
+## Goal
+
+Ship a stable `Table` v1 with keyboard navigation, row selection, sorting, documentation, and reliable accessibility semantics.
+
+## Backlog
+
+### Bugs / Correctness
+
+- [x] [M][P0][Area: Correctness][Owner: Unassigned][Target: Done] Deduplicate sync registration calls — `syncXxxRegistration()` runs both synchronously at mount and inside `$effect`, causing a redundant `notifyLayout()` per part on initial render (Column, Row, Cell, ColumnHeaderCell).
+- [x] [S][P0][Area: Correctness][Owner: Unassigned][Target: Done] Make `cellIndex` in `Table.Cell` reactive — currently captured once via `row.registerCellToken(key)` and never updated if cells are dynamically reordered within a row.
+- [x] [C][P1][Area: Correctness][Owner: Unassigned][Target: Done] Replace module-level monotonic counters (`columnInstanceId`, `rowInstanceId`, etc.) with per-`Table.Root` token generation so SSR and repeated tests do not share global instance state.
+
+### Behavior
+
+- [x] [M][P1][Area: Behavior][Owner: Unassigned][Target: Done] Align row focus state semantics — current row-level `data-focused` behaves more like `focus-within`; either rename/expose a distinct `data-focus-within` contract or implement true row focus semantics.
+- [x] [M][P1][Area: Behavior][Owner: Unassigned][Target: Done] Define and document the text-selection policy when row selection is enabled — keep browser-native behavior or add an explicit opt-in/opt-out API instead of ad hoc styling in examples.
+- [x] [S][P2][Area: Behavior][Owner: Unassigned][Target: Done] Verify that changing `selectionMode` between `multiple`, `single`, and `none` preserves the intended normalization rules in all controlled and uncontrolled flows.
+- [x] [M][P0][Area: Behavior][Owner: Unassigned][Target: Done] Make `Table.ColumnResizer` keyboard interactions run the same resize lifecycle as pointer interactions so width freezing and resize callbacks stay consistent.
+- [x] [M][P1][Area: Behavior][Owner: Unassigned][Target: Done] Allow cancelling an in-progress `Table.ColumnResizer` drag with `Escape`, restoring the starting width instead of forcing the partial drag result.
+
+### Accessibility
+
+- [x] [M][P1][Area: Accessibility][Owner: Unassigned][Target: Done] Enforce accessible name on `Table.Root` — warn in dev when neither `aria-label` nor `aria-labelledby` is provided (WCAG 4.1.2).
+- [x] [M][P1][Area: Accessibility][Owner: Unassigned][Target: Done] Add `aria-disabled` to focusable body cells inside disabled rows — currently only the `<tr>` carries `aria-disabled`, leaving screen readers unaware at the cell level.
+- [x] [M][P0][Area: Accessibility][Owner: Unassigned][Target: Done] Announce committed `Table.ColumnResizer` width changes through a polite live region and expose `aria-valuetext` so keyboard resizing has reliable screen reader feedback.
+- [x] [M][P0][Area: Accessibility][Owner: Unassigned][Target: Done] Move `Table.ColumnResizer` drag handling to Pointer Events so touch, pen, and mouse resizing use the same path.
+- [x] [S][P1][Area: Accessibility][Owner: Unassigned][Target: Done] Make `Table.ColumnResizer` keyboard arrow semantics respect RTL layouts so logical resize controls match the visual direction.
+- [ ] [M][P1][Area: Accessibility][Owner: Unassigned][Target: TBD] Validate screen reader announcements for `rowheader`, `columnheader`, and `aria-sort` across NVDA and VoiceOver.
+- [x] [M][P1][Area: Accessibility][Owner: Unassigned][Target: Done] Resolve footer grid semantics — footer cells live inside `role="grid"` but are unreachable by keyboard; either include footer in navigation or mark `<tfoot>` with `role="none"` to exclude it from the grid.
+- [x] [S][P2][Area: Accessibility][Owner: Unassigned][Target: Done] Add `aria-rowcount` and `aria-colcount` to the grid element for screen reader dimension announcements.
+- [x] [S][P2][Area: Accessibility][Owner: Unassigned][Target: Done] Add an `aria-live="polite"` visually-hidden region to announce sort changes (NVDA/JAWS do not always announce `aria-sort` updates).
+- [x] [S][P2][Area: Accessibility][Owner: Unassigned][Target: Done] Add explicit `role="row"` to the `Table.EmptyState` `<tr>` for strict ARIA parent-child validation (`gridcell` requires `row` parent).
+
+### Performance
+
+- [x] [M][P1][Area: Performance][Owner: Unassigned][Target: Done] Cache `getOrderedRowTokens` result and invalidate on `notifyLayout` — currently re-sorts with `compareDocumentPosition` on every focus move, selection, and row count query.
+- [x] [M][P1][Area: Performance][Owner: Unassigned][Target: Done] Replace repeated linear column-id scans in table resize helpers with an O(1) id-to-token lookup inside `Table.Root` context.
+- [x] [S][P1][Area: Performance][Owner: Unassigned][Target: Done] Batch `Table.ColumnResizer` pointer drag updates with `requestAnimationFrame` so width writes and store updates stay aligned to paint frames.
+- [x] [M][P2][Area: Performance][Owner: Unassigned][Target: Done] Cache `getNavigableCells()` / `getRowsWithCells()` and invalidate on layout changes — currently reconstructs full cell map on every `moveFocus` call.
+- [ ] [S][P2][Area: Performance][Owner: Unassigned][Target: TBD] Migrate version stores from `writable` (svelte/store) to `$state` runes for idiomatic Svelte 5 reactivity and potential batching improvements.
+
+### DX
+
+- [x] [M][P1][Area: DX][Owner: Unassigned][Target: Done] Break the controlled `selectedKeys` feedback loop — the `$effect` that syncs `selectedKeys` to `ctx.setSelection` also fires after internal selection changes via `onSelectionChange`, causing a redundant `notifySelection`.
+- [x] [S][P2][Area: DX][Owner: Unassigned][Target: Done] Remove inline `style="outline: none;"` from Cell and ColumnHeaderCell — it overrides consumer inline styles; let consumers handle focus-visible styling via `data-focus-visible` / `data-focused` attributes instead.
+- [x] [S][P2][Area: DX][Owner: Unassigned][Target: Done] Document `defaultSelectedKeys` and `defaultSortDescriptor` props in the README and docs page.
+- [x] [C][P2][Area: DX][Owner: Unassigned][Target: Done] Export component prop types (`TableRootProps`, `TableRowProps`, `TableCellProps`, etc.) so consumers can type wrapper components.
+- [ ] [C][P2][Area: DX][Owner: Unassigned][Target: TBD] Evaluate whether exposing `context` as a `$bindable` prop on `Table.Root` is necessary or if a narrower public API would be safer.
+- [ ] [C][P3][Area: DX][Owner: Unassigned][Target: TBD] Extract a shared registration helper to eliminate the duplicated sync-then-effect pattern across Column, Row, Cell, and ColumnHeaderCell.
+
+### UX
+
+- [x] [S][P2][Area: UX][Owner: Unassigned][Target: Done] Document the intentional behavior that clicking outside the table does not clear selection in `replace` mode.
+- [ ] [C][P3][Area: UX][Owner: Unassigned][Target: TBD] Consider exposing `cursor` guidance via data attributes so sortable headers get `cursor: pointer` and non-sortable headers get `cursor: default` without custom CSS.
+
+### API Design
+
+- [x] [M][P1][Area: API][Owner: Unassigned][Target: Done] Decide whether controlled clearing of `sortDescriptor` should accept `undefined` explicitly or require an additional API.
+- [x] [S][P2][Area: Behavior][Owner: Unassigned][Target: Done] Confirm whether disabled body rows should remain keyboard-focusable or be skipped by navigation.
+- [ ] [S][P2][Area: API][Owner: Unassigned][Target: TBD] Decide whether `Table.Column` should hard-enforce a single `Table.ColumnHeaderCell` child.
+- [ ] [S][P2][Area: API][Owner: Unassigned][Target: TBD] Decide whether clipboard-related behavior should remain fully browser-native in v1 or be deferred behind a future explicit cell-selection model.
+- [x] [C][P1][Area: API][Owner: Unassigned][Target: Done] Add `onRowAction?: (id: TableSelectionKey) => void` to `Table.Root` and document its collection-level semantics across `selectionMode` and `selectionBehavior`.
+- [x] [C][P1][Area: API][Owner: Unassigned][Target: Done] Add `disabledBehavior?: 'selection' | 'all'` to `Table.Root` with default `'all'`, and document that `'selection'` disables selection while preserving focus and row actions.
+- [x] [S][P1][Area: API][Owner: Unassigned][Target: Done] Treat stable `selectionBehavior?: 'toggle' | 'replace'` support in `Table.Root` as an explicit prerequisite for the row-actions phase rather than an implicit assumption.
+
+### Features
+
+- [ ] [C][P1][Area: Features][Owner: Unassigned][Target: TBD] Add controlled and uncontrolled column filtering APIs — support per-column filters plus a global filter hook so `Table` can cover common data-grid scenarios without forcing consumers to build parallel filter state from scratch.
+- [ ] [C][P1][Area: Features][Owner: Unassigned][Target: TBD] Add column visibility controls — allow columns to be shown/hidden dynamically while preserving keyboard navigation, sort state, selection column layout, and resize state for still-visible columns.
+- [ ] [C][P1][Area: Features][Owner: Unassigned][Target: TBD] Add multi-column sorting — support ordered sort descriptors so users can compose secondary and tertiary sorts instead of being limited to a single active sort key.
+- [ ] [C][P1][Area: Features][Owner: Unassigned][Target: TBD] Add pagination primitives — define a controlled pagination model for large datasets, including page index, page size, and total row count integration without coupling `Table` to a specific data-fetching strategy.
+- [ ] [C][P1][Area: Features][Owner: Unassigned][Target: TBD] Evaluate row virtualization support — provide a path for very large tables while preserving grid semantics, roving tabindex behavior, selection, and resize interactions.
+- [ ] [C][P2][Area: Features][Owner: Unassigned][Target: TBD] Add sticky header and pinned-column support — enable frozen headers and utility columns (selection, row headers, actions) for wide or scroll-heavy tables.
+- [ ] [C][P2][Area: Features][Owner: Unassigned][Target: TBD] Add expandable rows / subrows — support master-detail rows and tree-like disclosure patterns without forcing consumers to break the table's row and cell registration model.
+- [ ] [C][P2][Area: Features][Owner: Unassigned][Target: TBD] Add inline cell and row editing primitives — define an opt-in editing model that can coexist with current focus, selection, and keyboard navigation contracts.
+- [ ] [M][P2][Area: Features][Owner: Unassigned][Target: TBD] Add column action primitives — expose a path for header menus, quick sort/filter actions, and future column management UI without requiring consumers to hand-roll header action composition every time.
+- [ ] [M][P3][Area: Features][Owner: Unassigned][Target: TBD] Add row actions patterns — document or expose a composable pattern for common trailing actions columns so selection, row press, and nested interactive controls do not conflict.
+- [x] [C][P1][Area: Features][Owner: Unassigned][Target: Done] Implement collection-level row actions in `Table.Root` so body rows can trigger `onRowAction` using RAC-style interaction rules without introducing a separate `rowPressBehavior` prop.
+
+### Tests
+
+- [x] [M][P1][Area: Tests][Owner: Unassigned][Target: Done] Add tests for `Home`, `End`, `Ctrl+Home`, and `Ctrl+End` keyboard navigation.
+- [x] [S][P2][Area: Tests][Owner: Unassigned][Target: Done] Add test for full sort cycle via keyboard (ascending → descending) and verify no way to clear sort with keyboard is intentional.
+- [x] [S][P2][Area: Tests][Owner: Unassigned][Target: Done] Add test verifying disabled rows are not selected when arrow-navigated in `replace` mode.
+- [x] [S][P2][Area: Tests][Owner: Unassigned][Target: Done] Add tests covering `selectionMode` transitions after mount, including collapsing multiple selections to one on `single`.
+- [x] [C][P1][Area: Tests][Owner: Unassigned][Target: Done] Add the full row action matrix to `Table.Root` tests: click/action in `selectionMode="none"`, toggle-mode action when selection is empty, toggle-mode selection when selection is active, and replace-mode double-click actions.
+- [x] [M][P1][Area: Tests][Owner: Unassigned][Target: Done] Add keyboard interaction tests proving `Enter` triggers `onRowAction` and `Space` triggers selection when both behaviors are available.
+- [x] [M][P1][Area: Tests][Owner: Unassigned][Target: Done] Add `disabledBehavior` regression tests covering `'selection'` vs `'all'` for row focusability, checkbox disabled state, row action availability, and selection blocking.
+- [x] [S][P1][Area: Tests][Owner: Unassigned][Target: Done] Add an explicit edge-case test proving a disabled row under `disabledBehavior="selection"` still fires `onRowAction` on `Enter` while remaining non-selectable.
+- [x] [S][P1][Area: Tests][Owner: Unassigned][Target: Done] Add a callback-ordering test proving `selectionBehavior="replace"` double click fires `onSelectionChange` before `onRowAction`.
+
+### Docs
+
+- [ ] [C][P2][Area: Docs][Owner: Unassigned][Target: TBD] Add richer styling examples and sorting guidance to the docs page.
+- [x] [C][P3][Area: Docs][Owner: Unassigned][Target: Done] Document that `Table.Column` is a logical-only wrapper (no DOM output) prominently in the README anatomy section.
+- [x] [S][P2][Area: Docs][Owner: Unassigned][Target: Done] Document `selectionMode="none"` normalization behavior and clarify that selection is cleared internally when selection is disabled.
+- [ ] [C][P1][Area: Docs][Owner: Unassigned][Target: TBD] Document row actions vs row selection in the Table README and docs page, including the different pointer rules for `toggle` and `replace` when `onRowAction` is provided.
+- [ ] [M][P1][Area: Docs][Owner: Unassigned][Target: TBD] Document `disabledBehavior="selection"` and clarify that it disables selection only, not row actions or focus.
+- [ ] [S][P1][Area: Docs][Owner: Unassigned][Target: TBD] Call out explicitly that `toggle` mode changes row-click behavior dynamically once an active selection exists, and treat this as an intentional RAC-style model rather than an accidental inconsistency.
+- [ ] [S][P1][Area: Docs][Owner: Unassigned][Target: TBD] Document callback ordering for `replace`-mode double click: `onSelectionChange` fires before `onRowAction`.
+
+### Selection Checkbox
+
+- [ ] [M][P1][Area: Performance][Owner: Unassigned][Target: TBD] Cache `getOrderedSelectableRowIds()` and invalidate on layout/selection changes — currently rebuilds the full selectable-row array on every call to `getSelectionCheckboxState()`, `hasSelectableRows()`, `selectAllRows()`, and `extendSelectionToRow()`, causing O(n) work per selection change.
+- [ ] [M][P1][Area: Accessibility][Owner: Unassigned][Target: TBD] Validate `Table.Checkbox` screen reader announcements across NVDA and VoiceOver — verify that `aria-checked="mixed"` transitions in the header checkbox and row selection toggles are announced correctly.
+- [ ] [M][P1][Area: Correctness][Owner: Unassigned][Target: TBD] Document or resolve `Table.Checkbox` bypass of `pressRow()` — the checkbox always calls `toggleRowSelection()` directly, ignoring `selectionBehavior="replace"` semantics (Shift+click range, Ctrl+click toggle). This is intentional for checkbox UX but undocumented and inconsistent with row-click behavior.
+- [ ] [M][P1][Area: Correctness][Owner: Unassigned][Target: TBD] Add dev-time structural validation for `Table.Checkbox` placement — warn when header includes a selection checkbox column but body rows do not, or when the checkbox is placed in a footer cell where it has no behavior.
+- [x] [M][P1][Area: Correctness][Owner: Unassigned][Target: Done] Ensure `Table.Checkbox` respects `disabledBehavior="selection"` by disabling explicit selection controls without suppressing row actions on the rest of the row.
+
+### Row Actions
+
+- [x] [C][P1][Area: Correctness][Owner: Unassigned][Target: Done] Refactor the current `pressRow()` pipeline so selection and row actions are distinct internal pathways rather than a single selection-oriented press abstraction.
+- [x] [C][P1][Area: Correctness][Owner: Unassigned][Target: Done] Split row disabled-state helpers into selection-disabled vs action-disabled semantics so `disabledBehavior="selection"` does not incorrectly suppress focus or actions.
+- [x] [M][P1][Area: Behavior][Owner: Unassigned][Target: Done] Preserve existing `replace`-mode selection extension (`Shift+Arrow`, `Ctrl/Cmd+Space`, click replace) while layering `onRowAction` on top.
+- [x] [M][P1][Area: Accessibility][Owner: Unassigned][Target: Done] Revisit `aria-disabled` semantics for rows under `disabledBehavior="selection"` so actionable rows are not announced as fully disabled.
+- [x] [M][P1][Area: DX][Owner: Unassigned][Target: Done] Evaluate whether row/cell data attributes should expose actionable and selection-disabled states for styling and debugging once `onRowAction` ships.
+- [x] [S][P1][Area: DX][Owner: Unassigned][Target: Done] Make `data-actionable` part of the required styling contract for actionable rows so consumers can reliably style cursor and affordances.
+
+### Code Quality
+
+- [x] [C][P3][Area: Code Quality][Owner: Unassigned][Target: Done] Remove unused keyboard/click handlers from `Table.Cell` when rendering in footer scope — currently handlers are bound but short-circuit via guards.
+- [x] [M][P2][Area: Code Quality][Owner: Unassigned][Target: Done] Extract shared keyboard handler between `Table.Row` and `Table.Cell` — both components duplicate ~60 lines of nearly identical `handleKeyDown` logic (ArrowUp/Down/Left/Right, Home/End, Ctrl+Home/End, Ctrl+A, Enter, Space) with only minor differences in Home/End targets.
+- [x] [S][P2][Area: Code Quality][Owner: Unassigned][Target: Done] Add a defensive `isRowDisabled` guard inside `pressRow()` in context — currently callers (Row, Cell) check disabled state before calling, but `pressRow` itself does not validate, so a direct call bypasses the check.
+
+### Bugs / Phase 3
+
+- [x] [M][P1][Area: Correctness][Owner: Unassigned][Target: Done] Fix `keyboard-space` ignoring interaction modifiers in `pressRow()` — the `keyboard-space` branch calls `toggleRowSelection(id)` directly, discarding `shiftKey`/`ctrlKey`/`metaKey`. This breaks `Shift+Space` (should extend selection) and `Ctrl+Space` semantics in `replace` + `multiple` mode. Should route through `pressRowSelection(id, interaction)` instead.
+
+### Accessibility / Phase 3
+
+- [x] [S][P2][Area: Accessibility][Owner: Unassigned][Target: Done] Clarify ARIA semantics for rows under `disabledBehavior="selection"` without a checkbox — a selection-disabled but actionable row has no `aria-disabled` (correct) but also no ARIA hint that selection is unavailable; the checkbox disabled state announces it, but rows without a checkbox column have no signal for assistive technology.
+
+### Performance / Phase 3
+
+- [x] [S][P2][Area: Performance][Owner: Unassigned][Target: Done] Use O(1) id-to-token lookup in `isColumnSortable()` — currently iterates all columns with `Array.from(columns.values()).some(...)` instead of using `getColumnRegistrationById(columnId)?.allowsSorting`.
+- [x] [S][P2][Area: Performance][Owner: Unassigned][Target: Done] Cache `getVisibleColumnWidths()` result — it filters `getColumnWidths()` on every call but is used in the render path of `Table.Root` for `managedTableWidth` derivation; should share a cache invalidated alongside `columnWidthsCache`.

package/dist/table/body/README.md

@@ -0,0 +1,39 @@
+<!-- markdownlint-disable MD024 -->
+
+# Table.Body
+
+## API reference
+
+### Table.Body
+
+Name: `Table.Body`
+Description: Body rowgroup for table data rows. It can render authored rows directly, or render item-driven rows with optional fixed-height virtualization. It also exposes empty-state markers when no logical body rows are available.
+
+Public prop type: `TableBodyProps`
+
+| Prop          | Type                        | Default     | Description                                                                                                                          |
+| ------------- | --------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `items`       | `readonly T[]`              | `undefined` | Logical row collection for item-driven mode. When present, `children(item)` renders once per item with `item` inferred from `items`. |
+| `virtualizer` | `TableBodyVirtualizer`      | `undefined` | Optional fixed-height row virtualization config with `rowHeight` and `overscan`.                                                     |
+| `class`       | `string`                    | `''`        | Class names for the `tbody` element.                                                                                                 |
+| `children`    | `Snippet` or `Snippet<[T]>` | `undefined` | Manual body content when `items` is omitted, or `children(item)` in item-driven mode.                                                |
+| `empty`       | `Snippet`                   | `undefined` | Optional empty-state snippet for item-driven mode.                                                                                   |
+
+### TableBodyVirtualizer
+
+Name: `TableBodyVirtualizer`
+Description: Fixed-height body virtualization settings.
+
+| Prop        | Type     | Default | Description                                                    |
+| ----------- | -------- | ------- | -------------------------------------------------------------- |
+| `rowHeight` | `number` | `-`     | Required fixed pixel height used to compute the visible range. |
+| `overscan`  | `number` | `18`    | Extra rows rendered above and below the viewport.              |
+
+### Context utilities
+
+Name: `Table.Body` section context
+Description: Publishes the `body` section scope for descendant rows, cells, and empty state.
+
+| Prop                     | Type                        | Default | Description                      |
+| ------------------------ | --------------------------- | ------- | -------------------------------- |
+| `useTableSectionContext` | `() => TableSectionContext` | `-`     | Reads the current section scope. |

package/dist/table/body/table-body-items-test.svelte

@@ -0,0 +1,45 @@
+<script lang="ts">
+	import { Table } from '../index';
+
+	type DemoRow = {
+		id: string;
+		email: string;
+		group: string;
+	};
+
+	const rows: DemoRow[] = Array.from({ length: 120 }, (_, index) => {
+		const sequence = index + 1;
+		return {
+			id: `row-${String(sequence).padStart(3, '0')}`,
+			email: `user${sequence}@example.com`,
+			group: sequence % 2 === 0 ? 'Admin' : 'Developer'
+		};
+	});
+</script>
+
+<div style="max-height: 240px; overflow: auto;">
+	<Table.Root aria-label="Virtualized users table">
+		<Table.Header>
+			<Table.Row>
+				<Table.Column id="email" isRowHeader textValue="Email">
+					<Table.ColumnHeaderCell>Email</Table.ColumnHeaderCell>
+				</Table.Column>
+				<Table.Column id="group" textValue="Group">
+					<Table.ColumnHeaderCell>Group</Table.ColumnHeaderCell>
+				</Table.Column>
+			</Table.Row>
+		</Table.Header>
+
+		<Table.Body items={rows} virtualizer={{ rowHeight: 32 }}>
+			{#snippet children(row)}
+				<Table.Row id={row.id} data-item-id={row.id}>
+					<Table.Cell>{row.email}</Table.Cell>
+					<Table.Cell>{row.group}</Table.Cell>
+				</Table.Row>
+			{/snippet}
+			{#snippet empty()}
+				<Table.EmptyState>No users found.</Table.EmptyState>
+			{/snippet}
+		</Table.Body>
+	</Table.Root>
+</div>

package/dist/table/body/table-body-items-test.svelte.d.ts

@@ -0,0 +1,18 @@
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const TableBodyItemsTest: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type TableBodyItemsTest = InstanceType<typeof TableBodyItemsTest>;
+export default TableBodyItemsTest;