@human-kit/svelte-components 1.0.0-alpha.3 → 1.0.0-alpha.5

package/dist/table/README.md

@@ -0,0 +1,116 @@
+<!-- markdownlint-disable MD010 -->
+
+# Table
+
+## Description
+
+`Table` is a headless interactive table primitive with grid-style keyboard navigation, row selection, sortable column headers, and a composable part-based API.
+
+## 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" allowsSorting>
+				<Table.ColumnHeaderCell>Group</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.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.
+- Use `defaultColumnWidths`, `Table.Column.defaultWidth`, and `Table.Column.width` to seed explicit widths.
+- 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.
+
+## 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.
+- 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,100 @@
+# 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.
+- [ ] [C][P2][Area: DX][Owner: Unassigned][Target: TBD] 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.
+
+### 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.
+
+### 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`.
+
+### 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.
+
+### 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.
+
+### Code Quality
+
+- [ ] [C][P3][Area: Code Quality][Owner: Unassigned][Target: TBD] Remove unused keyboard/click handlers from `Table.Cell` when rendering in footer scope — currently handlers are bound but short-circuit via guards.

package/dist/table/body/README.md

@@ -0,0 +1,24 @@
+<!-- markdownlint-disable MD024 -->
+
+# Table.Body
+
+## API reference
+
+### Table.Body
+
+Name: `Table.Body`
+Description: Body rowgroup for table data rows. It also exposes empty-state markers when no body rows are registered.
+
+| Prop       | Type      | Default     | Description                                |
+| ---------- | --------- | ----------- | ------------------------------------------ |
+| `class`    | `string`  | `''`        | Class names for the `tbody` element.       |
+| `children` | `Snippet` | `undefined` | Body rows and optional `Table.EmptyState`. |
+
+### 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.svelte

@@ -0,0 +1,25 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { setTableSectionContext, useTableContext } from '../root/context';
+
+	type TableBodyProps = Omit<HTMLAttributes<HTMLTableSectionElement>, 'children'> & {
+		children?: Snippet;
+		class?: string;
+	};
+
+	let { children, class: className = '', ...restProps }: TableBodyProps = $props();
+	setTableSectionContext({ section: 'body' });
+	const table = useTableContext();
+	const layoutVersion = table.layoutVersion;
+	const isEmpty = $derived.by(() => {
+		void $layoutVersion;
+		return table.getBodyRowCount() === 0;
+	});
+</script>
+
+<tbody class={className} data-table-body data-empty={isEmpty || undefined} {...restProps}>
+	{#if children}
+		{@render children()}
+	{/if}
+</tbody>

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

@@ -0,0 +1,9 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+type TableBodyProps = Omit<HTMLAttributes<HTMLTableSectionElement>, 'children'> & {
+    children?: Snippet;
+    class?: string;
+};
+declare const TableBody: import("svelte").Component<TableBodyProps, {}, "">;
+type TableBody = ReturnType<typeof TableBody>;
+export default TableBody;

package/dist/table/cell/README.md

@@ -0,0 +1,25 @@
+<!-- markdownlint-disable MD024 -->
+
+# Table.Cell
+
+## API reference
+
+### Table.Cell
+
+Name: `Table.Cell`
+Description: Table data cell part. In body scope it participates in roving focus and row selection. In footer scope it renders semantic summary cells only.
+
+| Prop       | Type      | Default     | Description                                |
+| ---------- | --------- | ----------- | ------------------------------------------ |
+| `class`    | `string`  | `''`        | Class names for the rendered `td` or `th`. |
+| `children` | `Snippet` | `undefined` | Cell content.                              |
+
+### Context utilities
+
+Name: `Table.Cell` dependencies
+Description: Consumes row context and table context to derive column semantics and keyboard behavior.
+
+| Prop                 | Type                    | Default | Description                                              |
+| -------------------- | ----------------------- | ------- | -------------------------------------------------------- |
+| `useTableRowContext` | `() => TableRowContext` | `-`     | Reads row scope and cell order.                          |
+| `useTableContext`    | `() => TableContext`    | `-`     | Reads table focus, column metadata, and selection state. |