@xplortech/apollo-core 3.1.0 → 3.2.1

package/dist/docs/xpl-table/readme.md

@@ -1,45 +1,203 @@
-# xpl-table
+# xpl-table
+
+Tables are used to organize and display information from a data set.
+
+## Rendering modes
+
+1. **Compositional (recommended)** — Provide `xpl-table-header`, `xpl-table-body`, and optional `xpl-table-footer` with `xpl-table-row` / `xpl-table-header-cell` / `xpl-table-cell` / `xpl-table-footer-cell`. The host uses CSS grid (`role="grid"`). Column widths come from each **`xpl-table-header-cell`** (`width` in px, or `column-width` for any grid track; default `auto` / content-sized). Use `label` for an accessible name. **Sorting:** set `sortable` (and optional `sort-key`) on label header cells; `xpl-table` emits **`sortChanged`** with sort-key slugs → `asc` / `desc` / `null`. The host does **not** reorder row DOM — listen and update your data (or reorder nodes yourself), same as the main Table Storybook demo.
+2. **Legacy data-driven** — Set `columns`, `data`, and optionally `footer` for a built-in `<table>` implementation. That path supports `isSortable` / `sortableColumns`, `multiselect`, and emits `sortChanged` / `tableSelect` (legacy can reorder rows unless you `preventDefault`). Prefer compositional markup for new work.
+
+Composable **selection** (`selectable`), **toolbar**, and copy-paste examples live under **[Usage](#usage)** below (read the breaking-change note first if you are migrating from auto-injected selection cells).
+
+### Row reorder (`row-reorderable`, managed grip column)
+
+When `row-reorderable` is set, Apollo can **inject** a leading reorder column with a native **button** + optional `xpl-icon` on each body row (unless you author that column yourself). Keyboard and pointer reorder share the same grip; **keyboard mode** is indicated by `aria-pressed`, updated labels, the class `xpl-table__row-drag-handle--keyboard-mode`, and optionally a **different icon**.
+
+**Pointer drag (full row):** Body rows use CSS **`subgrid`** so `xpl-table-row` is a real grid box (like `xpl-list-item`’s row surface). When `CSS.supports('grid-template-columns','subgrid')` is true, **`draggable`** is set on **`xpl-table-row`** so the browser’s drag image matches the whole row; drag still **starts only from the grip** (pointer-down there sets the drag token—dragging from other cells is ignored). Engines without subgrid keep **`draggable`** on the grip button only.
+
+| Attribute | When it applies | Purpose |
+| --------- | ---------------- | ------- |
+| `reorder-handle-icon` | Default / drag affordance | Icon name for `xpl-icon` (default `grip-dots-vertical`). Use `reorder-handle-icon=""` to omit the injected icon and use CSS or your own markup in a **custom** reorder cell instead. |
+| `reorder-handle-icon-keyboard` | While that row is in **keyboard reorder mode** (Enter or Space on the grip) | Icon name for the same grip when the user is using **Arrow Up/Down** to move the row (default `caret-expand-y`, matching `xpl-list`). Use `reorder-handle-icon-keyboard=""` to show **no** icon in keyboard mode only. |
+
+**Recommended for product UIs:** Set **both** attributes to your design-system icon names so drag vs keyboard modes are visually distinct. You can still add styles targeting `.xpl-table__row-drag-handle--keyboard-mode` (e.g. outline) for extra clarity.
+
+**Interaction:** Focus the grip → **Enter** or **Space** → **Arrow Up/Down** to reorder → **Escape** to exit. Pointer down on the row exits keyboard mode; starting a drag also exits keyboard mode.
+
+**Custom reorder column:** If you add reorder cells in your own template (not injected), **you** own icons, keyboard behavior, and `rowOrderChange` — these attributes apply only to **managed** injected grips.
+
+## Usage
+
+### Breaking change — compositional `selectable`
+
+**Before:** Setting `selectable` alone caused the table to **inject** selection header/body/footer cells into the light DOM (including nodes marked `data-xpl-selection-managed`).
+
+**After:** You **must** add the selection column in your own markup (see **Selection** below). `xpl-table` no longer creates or removes those cells; it only syncs selection state and emits events. If you previously relied on automatic injection, add the header checkbox column, per-row checkbox cells, and (when using a footer) leading footer cells so column counts match.
+
+### Selection (`selectable`) and `rowSelectionChange`
+
+Set `selectable` on `xpl-table` and **author the selection column in your template** so the framework that renders the table owns every cell node.
+
+**Required pieces:**
+
+- **Header:** one [`xpl-table-header-cell`](xpl-table-header-cell) with `type="checkbox"` (tri-state “select all”).
+- **Body:** in each `xpl-table-row`, a cell aligned with that column containing **`xpl-checkbox`** (value is driven from `row-id` on the row).
+- **Footer:** if you use `xpl-table-footer`, add a leading `xpl-table-footer-cell` per row for the selection column (often empty) so column counts stay aligned.
+
+**Behavior:** After `customElements.whenDefined('xpl-table')`, listen for **`rowSelectionChange`** on the **same** `<xpl-table>` element (`bubbles: false`, `composed: true`). The event payload is `{ selectedRowIds: string[] }`. The host maintains `selectedRowIds`, syncs `checked` / `indeterminate` on the header and row checkboxes, sets `selected` on rows, and shows the bulk toolbar while at least one row is selected. Row checkbox **`aria-label`** is derived from the first **non-selection** data cell in that row (e.g. `Select row, Jordan Lee`); the header uses “Select all rows” unless you set **`checkbox-aria-label`** on the checkbox header cell.
+
+**Example (web component):**
+
+```html
+<xpl-table id="roster" selectable label="Team roster">
+  <xpl-table-header>
+    <xpl-table-row>
+      <xpl-table-header-cell type="checkbox"></xpl-table-header-cell>
+      <xpl-table-header-cell label="Name" sortable sort-key="name"></xpl-table-header-cell>
+    </xpl-table-row>
+  </xpl-table-header>
+  <xpl-table-body>
+    <xpl-table-row row-id="1">
+      <xpl-table-cell><xpl-checkbox></xpl-checkbox></xpl-table-cell>
+      <xpl-table-cell>Ada</xpl-table-cell>
+    </xpl-table-row>
+  </xpl-table-body>
+</xpl-table>
+<script type="module">
+  await customElements.whenDefined('xpl-table');
+  document.getElementById('roster')?.addEventListener('rowSelectionChange', (e) => {
+    console.log(e.detail.selectedRowIds);
+  });
+</script>
+```
+
+#### Framework notes (Vue / React / etc.)
+
+Use **`xpl-checkbox`** in the selection column so `xpl-table` can sync `checked`, `indeterminate`, and `value` from `row-id`. On **`xpl-table-header-cell`**, the selection header uses **`type="checkbox"`**; the prop is **reflected** to the host attribute so Vue bindings like `:type="'checkbox'"` still expose `type="checkbox"` in the DOM for the table’s column detection and CSS.
+
+### Legacy (`columns` / `data`)
+
+Set `columns`, `data`, and optional `footer` as **properties** after `customElements.whenDefined('xpl-table')`, or use attributes where your bundler passes JSON strings.
+
+```html
+<xpl-table id="legacy"></xpl-table>
+<script type="module">
+  await customElements.whenDefined('xpl-table');
+  const t = document.getElementById('legacy');
+  t.columns = ['Name', 'Score'];
+  t.data = [
+    ['Ada', '100'],
+    ['Bob', '95'],
+  ];
+  t.multiselect = true;
+  t.addEventListener('tableSelect', (e) => console.log(e.detail));
+</script>
+```
+
+## Accessibility
+
+| Concern | Behavior |
+| ------- | -------- |
+| Table landmark | Compositional host uses **`role="grid"`**; set **`label`** (maps to `aria-label`). |
+| Columns | Header cells use **`role="columnheader"`** with `aria-colindex`; sortable label headers expose sort state via **`aria-sort`**. |
+| Selection | Checkbox column: header reflects **checked / mixed** via `aria-checked`; row checkboxes get **`aria-label`** from the first non-selection cell’s text (or override with `checkbox-aria-label` on the checkbox header cell). |
+| Sort | Sorting is a **`<button type="button">`** inside the header cell; focus uses **`:focus-visible`** with focus tokens in `table-header-cell.css`. |
+| Row reorder | Managed grip is a **`<button>`** with `aria-label` / `aria-pressed` for keyboard reorder mode; live region announces reorder when enabled. |
+
+Keyboard: **Tab** through sort buttons, checkboxes, reorder grips, and cell actions. **Enter** / **Space** activate sort and the reorder grip per native button semantics.
+
+## Design Tokens
+
+Compositional grid layout tokens live in `table.css`; cell, row, header, and toolbar tokens are split across sibling CSS files.
+
+| Element | Property | Token | Light | Dark |
+| ------- | -------- | ----- | ----- | ---- |
+| Host (compositional) | border | `--xpl-border-small`, `--xpl-border-default` | neutral-200 | neutral-800 |
+| Host (compositional) | border-radius | `--xpl-border-radius-default` | 8px | 8px |
+| Host (compositional) | grid columns | `--column-widths` (runtime from header cells) | — | — |
+| Selection toolbar | sticky z-index | `--xpl-z-index-200` | 200 | 200 |
+| Selection toolbar | min-height | `--xpl-size-350` | 56px | 56px |
+| Freeze shadow | gradient | `--xpl-background-surface-transparent-10` → `-0` | near-black 10% | near-white 10% |
+| Freeze column | sticky z-index | `--xpl-z-index-100` | 100 | 100 |
+| Freeze scroll hint | width | `--xpl-space-24` | 24px | 24px |
+| Striped even rows | cell background | `--xpl-background-surface-subtlest` | neutral-50 | neutral-950 |
+| Striped + selected | cell background | `--xpl-background-surface-information-bold` | blue-100 | blue-900 |
+
+## Icon mapping
+
+When Apollo **injects** the reorder column, icons come from table props (override with `""` to omit):
+
+| Context | Default `xpl-icon` `icon` value |
+| ------- | -------------------------------- |
+| Pointer / idle grip | `grip-dots-vertical` |
+| Keyboard reorder mode | `caret-expand-y` |
+
+Sort direction uses **`xpl-icon`** names from header-cell internals (`graph`, carets, etc.) — see Storybook **Components → Table**.
+
+<!-- Auto Generated Below -->
 
-Tables are used to organize and display information from a data set. 
 
-<!-- Auto Generated Below -->
+## Overview
 
+Compositional tables use CSS grid on the host (`role="grid"`). Legacy mode uses a `<table>`.
 
 ## Properties
 
-| Property          | Attribute     | Description                                                                                                                 | Type         | Default     |
-| ----------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------ | ----------- |
-| `columns`         | --            | The header values for each column.                                                                                          | `string[]`   | `undefined` |
-| `data`            | --            | The data for the body of the table.                                                                                         | `string[][]` | `undefined` |
-| `footer`          | --            | The data for the footer of the table.                                                                                       | `string[][]` | `undefined` |
-| `freeze`          | `freeze`      | When true, the first column of the table is sticky and will cover the leftmost rows in a horizontally scrollable container. | `boolean`    | `undefined` |
-| `isSortable`      | `is-sortable` | Toggles to show the sort button on each table head                                                                          | `boolean`    | `false`     |
-| `multiselect`     | `multiselect` | Toggles a selectable checkbox for each row in the table                                                                     | `boolean`    | `undefined` |
-| `selectedValues`  | --            | The values for the input for each row when multiselect is activated.                                                        | `string[]`   | `[]`        |
-| `sortableColumns` | --            | Manually determined if the column is sortable                                                                               | `boolean[]`  | `[]`        |
-| `striped`         | `striped`     | Toggles an optional styling of the background of each even row of the table body.                                           | `boolean`    | `undefined` |
+| Property                    | Attribute                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Type         | Default     |
+| --------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ----------- |
+| `columns`                   | --                             | <span style="color:red">**[DEPRECATED]**</span> Legacy data-driven table API only (`columns` / `data` / `footer`). May be removed in a future major release.  The header values for each column.<br/><br/>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `string[]`   | `undefined` |
+| `data`                      | --                             | <span style="color:red">**[DEPRECATED]**</span> Legacy data-driven table API only (`columns` / `data` / `footer`). May be removed in a future major release.  The data for the body of the table.<br/><br/>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `string[][]` | `undefined` |
+| `footer`                    | --                             | <span style="color:red">**[DEPRECATED]**</span> Legacy data-driven table API only (`columns` / `data` / `footer`). May be removed in a future major release.  The data for the footer of the table.<br/><br/>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `string[][]` | `undefined` |
+| `freeze`                    | `freeze`                       | When true, the first **data** column (per row) is sticky during horizontal scroll. Leading compositional columns are skipped: `selectable` (checkbox) and/or `row-reorderable` (grip) are not frozen so they scroll with the grid; the next column stays pinned at `left: 0`.                                                                                                                                                                                                                                                                                                                                                                                                                                           | `boolean`    | `undefined` |
+| `isSortable`                | `is-sortable`                  | <span style="color:red">**[DEPRECATED]**</span> Legacy data-driven table API only. May be removed in a future major release.  Toggles to show the sort button on each table head.<br/><br/>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `boolean`    | `false`     |
+| `label`                     | `label`                        | Accessible label for the table. Maps to `aria-label` in compositional mode.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `string`     | `undefined` |
+| `multiselect`               | `multiselect`                  | <span style="color:red">**[DEPRECATED]**</span> Legacy data-driven table API only. May be removed in a future major release.  Toggles a selectable checkbox for each row in the table.<br/><br/>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `boolean`    | `undefined` |
+| `reorderHandleIcon`         | `reorder-handle-icon`          | Icon name for the optional `xpl-icon` inside each **managed** reorder grip when the row is **not** in keyboard reorder mode (pointer / idle). Set to `""` to omit the icon so you can style the button or author a fully custom reorder column in markup. When omitted, defaults to `grip-dots-vertical`.                                                                                                                                                                                                                                                                                                                                                                                                               | `string`     | `undefined` |
+| `reorderHandleIconKeyboard` | `reorder-handle-icon-keyboard` | Icon name for the managed reorder grip **while that row is in keyboard reorder mode** (after the user activates the grip with Enter or Space). Use a different icon than `reorder-handle-icon` so users can see they should use arrow keys. When omitted, defaults to `caret-expand-y` (same as `xpl-list` keyboard reorder). Set to `""` to show no icon in keyboard mode only (combine with CSS on `.xpl-table__row-drag-handle--keyboard-mode` if needed).                                                                                                                                                                                                                                                           | `string`     | `undefined` |
+| `rowReorderable`            | `row-reorderable`              | When true (compositional mode only), **prepends** a managed reorder column as the **first** grid column (empty header + grip button per body row) and enables HTML5 drag-and-drop row reordering (same interaction model as `xpl-list`). With `selectable`, DOM order is **reorder \| selection \| data** unless you author a custom reorder column. The table updates the DOM and emits `rowOrderChange`; consumers should persist order if needed. Ignored in legacy `columns`/`data` mode.                                                                                                                                                                                                                           | `boolean`    | `false`     |
+| `selectable`                | `selectable`                   | When true (compositional mode only), enables row selection state, the selection toolbar (“N Selected”), and `rowSelectionChange`. **You must add the selection column in your markup:** a header cell with `type="checkbox"`, a body cell containing `xpl-checkbox` per row (aligned with that column), and matching `xpl-table-footer-cell` cells when you use a footer. Each body row should use `row-id` on `xpl-table-row` (or accept auto-generated ids) so `rowSelectionChange` can report `selectedRowIds`.  The toolbar uses the same layout as `xpl-toolbar` and is visible only while at least one row is selected. Use `toolbar-actions-left` / `toolbar-actions-right` slots on this host for bulk actions. | `boolean`    | `undefined` |
+| `selectedValues`            | --                             | <span style="color:red">**[DEPRECATED]**</span> Legacy data-driven table API only. May be removed in a future major release.  The values for the input for each row when multiselect is activated.<br/><br/>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `string[]`   | `[]`        |
+| `sortableColumns`           | --                             | <span style="color:red">**[DEPRECATED]**</span> Use the compositional slot-based API instead. Will be removed in a future major release.  Manually determined if the column is sortable.<br/><br/>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `boolean[]`  | `[]`        |
+| `striped`                   | `striped`                      | Toggles an optional styling of the background of each even row of the table body.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `boolean`    | `undefined` |
 
 
 ## Events
 
-| Event         | Description                                                                                                                                                                                                                                  | Type                                                                                  |
-| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| `sortChanged` | Emits an event whenever the sort changes. The 'sortChanged' event passes an object with colNum (number), colName (string), sortTypeArr(('asc' \| 'desc' \| null)[]). The default action can be overridden by calling event.preventDefault(). | `CustomEvent<{ colNum: number; colName: string; sortTypeArr: ("desc" \| "asc")[]; }>` |
-| `tableSelect` | Callback function that is called when the checkbox for a row of a `multiselect` table is checked                                                                                                                                             | `CustomEvent<any>`                                                                    |
+| Event                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Type                                         |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `rowOrderChange`     | Emitted after body rows are reordered via drag-and-drop (compositional `row-reorderable` mode).                                                                                                                                                                                                                                                                                                                                                                                  | `CustomEvent<XplTableRowOrderChangeDetail>`  |
+| `rowSelectionChange` | Emitted when row selection changes in compositional `selectable` mode (`bubbles: false`, `composed: true`). Listen on this `xpl-table` instance only; the event does not bubble to parents—use `table.addEventListener('rowSelectionChange', …)` on the same element. When wiring from a script in static HTML, wait for `customElements.whenDefined('xpl-table')` so the host is ready. (Named `rowSelectionChange` to avoid clashing with the native `selectionchange` event.) | `CustomEvent<{ selectedRowIds: string[]; }>` |
+| `sortChanged`        | Emitted when sort changes in **legacy** or **compositional** mode. `event.detail` is a plain object: **sort-key slug → `'asc' \| 'desc' \| null`** (null = that column not sorted). Keys match legacy column titles (slugified) or compositional `sort-key` / label slugs. Call `event.preventDefault()` in legacy mode to skip built-in row sorting; compositional tables do not reorder rows automatically.                                                                    | `CustomEvent<XplTableSortChangedDetail>`     |
+| `tableSelect`        | Callback function that is called when the checkbox for a row of a `multiselect` table is checked.                                                                                                                                                                                                                                                                                                                                                                                | `CustomEvent<any>`                           |
+
+
+## Slots
+
+| Slot                      | Description                                                                                                                                      |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+|                           | `xpl-table-header`, `xpl-table-body`, and optional `xpl-table-footer`.                                                                           |
+| `"toolbar-actions-left"`  | Bulk actions in the selection toolbar (left group). Only when `selectable` is set; the toolbar is shown only while at least one row is selected. |
+| `"toolbar-actions-right"` | Bulk actions in the selection toolbar (right group). Same visibility as `toolbar-actions-left`.                                                  |
 
 
 ## Dependencies
 
 ### Depends on
 
-- [xpl-checkbox](../xpl-checkbox)
+- [xpl-table-header-cell](xpl-table-header-cell)
+- [xpl-table-cell](xpl-table-cell)
 - [xpl-icon](../xpl-icon)
+- [xpl-table-footer-cell](xpl-table-footer-cell)
 
 ### Graph
 ```mermaid
 graph TD;
-  xpl-table --> xpl-checkbox
+  xpl-table --> xpl-table-header-cell
+  xpl-table --> xpl-table-cell
   xpl-table --> xpl-icon
+  xpl-table --> xpl-table-footer-cell
+  xpl-table-header-cell --> xpl-icon
+  xpl-table-header-cell --> xpl-checkbox
   style xpl-table fill:#f9f,stroke:#333,stroke-width:4px
 ```
 

package/dist/docs/xpl-table/xpl-table-body/readme.md

@@ -2,11 +2,11 @@
 
 Row group for compositional table body content. Uses `display: contents` so slotted rows participate in the parent grid layout.
 
-### Design Tokens
+## Design Tokens
 
-| Element | Property | Token | Value |
-| -- | -- | -- | -- |
-| Host | display | — | `contents` |
+| Element | Property | Token | Light | Dark |
+| ------- | -------- | ----- | ----- | ---- |
+| Host | display | — | `contents` | `contents` |
 
 <!-- Auto Generated Below -->
 

package/dist/docs/xpl-table/xpl-table-cell/readme.md

@@ -0,0 +1,53 @@
+# xpl-table-cell
+
+Body cell for compositional [`xpl-table`](../readme.md). Place content in the default slot; use `align`, `bold`, and `underline` for typography. Interactive controls inside the cell inherit `disabled` when the parent [`xpl-table-row`](../xpl-table-row) is disabled.
+
+## Design Tokens
+
+Extends `.xpl-table-cell-base` (`table-cell-base.css`); row states (selected, disabled, striped) are applied from `table-row.css`.
+
+| Element | Property | Token | Light | Dark |
+| ------- | -------- | ----- | ----- | ---- |
+| Cell | background | `--xpl-background-surface-default` | neutral-0 | neutral-1000 |
+| Cell | text | `--xpl-text-default` | neutral-900 | neutral-50 |
+| Cell | border (right/bottom) | `--xpl-border-small`, `--xpl-border-default` | 1px, neutral-200 | 1px, neutral-800 |
+| Cell | padding | `--xpl-space-10`, `--xpl-space-16` | 10px / 16px | 10px / 16px |
+| Cell | min-height | `--xpl-size-350` | 56px | 56px |
+| Cell | typography | `@extend .xpl-text-title-5` | title-5 / medium | title-5 / medium |
+| Bold text | font-weight | `--xpl-font-weight-semibold` | 600 | 600 |
+| Disabled | text | `--xpl-text-disabled` | neutral-400 | neutral-600 |
+| Caption slot | text | `--xpl-text-subdued` | neutral-600 | neutral-400 |
+| Icon | color | `--xpl-icon-default` | neutral-900 | neutral-50 |
+| Reorder grip | color | `--xpl-icon-subtle` | neutral-600 | neutral-400 |
+| Reorder grip focus | outline | `--xpl-border-focus` | purple-500 | purple-400 |
+| Checkbox-only column | padding | `--xpl-space-16` + `--xpl-space-4` | 20px / 16px | 20px / 16px |
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property    | Attribute   | Description                                                                                     | Type                            | Default  |
+| ----------- | ----------- | ----------------------------------------------------------------------------------------------- | ------------------------------- | -------- |
+| `align`     | `align`     | Horizontal text alignment within the cell.                                                      | `"center" \| "left" \| "right"` | `'left'` |
+| `bold`      | `bold`      | Renders cell text in bold (--xpl-font-weight-semibold).                                         | `boolean`                       | `false`  |
+| `disabled`  | `disabled`  | Whether the cell and its interactive children are disabled. Set automatically by xpl-table-row. | `boolean`                       | `false`  |
+| `underline` | `underline` | Adds an underline to cell text.                                                                 | `boolean`                       | `false`  |
+
+
+## Dependencies
+
+### Used by
+
+ - [xpl-table](..)
+
+### Graph
+```mermaid
+graph TD;
+  xpl-table --> xpl-table-cell
+  style xpl-table-cell fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

package/dist/docs/xpl-table/xpl-table-footer/readme.md

@@ -2,11 +2,11 @@
 
 Row group for compositional table footer content. Uses `display: contents` so slotted footer rows participate in the parent grid layout.
 
-### Design Tokens
+## Design Tokens
 
-| Element | Property | Token | Value |
-| -- | -- | -- | -- |
-| Host | display | — | `contents` |
+| Element | Property | Token | Light | Dark |
+| ------- | -------- | ----- | ----- | ---- |
+| Host | display | — | `contents` | `contents` |
 
 <!-- Auto Generated Below -->
 

package/dist/docs/xpl-table/xpl-table-footer-cell/readme.md

@@ -1,20 +1,16 @@
 # xpl-table-footer-cell
 
-Footer cell for compositional tables. Extends the shared `.xpl-table-cell-base` styles with a strong top border.
-
-### Design Tokens
-
-| Element | Property | Token | Value |
-| -- | -- | -- | -- |
-| Cell | extends | `.xpl-table-cell-base` | (shared compositional cell base) |
-| Cell | background | `--xpl-background-surface-default` | neutral-0 (lm) / neutral-900 (dm) |
-| Cell | text | `--xpl-text-default` | neutral-900 (lm) / neutral-50 (dm) |
-| Cell | border (right/bottom) | `--xpl-border-small`, `--xpl-border-default` | 1px, neutral-200 |
-| Footer row border | border-top | `--xpl-border-large`, `--xpl-border-strong` | 2px, neutral-300 |
-| Cell | height | `--xpl-size-350` | 56px |
-| Cell | min-width | `--xpl-size-300` | 48px |
-| Cell | padding | `--xpl-space-16` | 16px |
-| Cell | typography | `@extend .xpl-text-title-5` | title-5 / medium |
+Footer cell for compositional tables. Extends the shared `.xpl-table-cell-base` styles with footer-row border rules from `table.css`.
+
+## Design Tokens
+
+| Element | Property | Token | Light | Dark |
+| ------- | -------- | ----- | ----- | ---- |
+| Cell | extends | `.xpl-table-cell-base` | (shared compositional cell base) | (shared compositional cell base) |
+| Cell | background | `--xpl-background-surface-default` | neutral-0 | neutral-1000 |
+| Cell | text | `--xpl-text-default` | neutral-900 | neutral-50 |
+| Cell | border (right/bottom) | `--xpl-border-small`, `--xpl-border-default` | 1px, neutral-200 | 1px, neutral-800 |
+| Last footer row | border-bottom | none (host draws frame) | — | — |
 
 <!-- Auto Generated Below -->
 
@@ -26,6 +22,19 @@ Footer cell for compositional tables. Extends the shared `.xpl-table-cell-base`
 | `align`  | `align`   | Horizontal alignment of footer cell content. | `"center" \| "left" \| "right"` | `'left'` |
 
 
+## Dependencies
+
+### Used by
+
+ - [xpl-table](..)
+
+### Graph
+```mermaid
+graph TD;
+  xpl-table --> xpl-table-footer-cell
+  style xpl-table-footer-cell fill:#f9f,stroke:#333,stroke-width:4px
+```
+
 ----------------------------------------------
 
 *Built with [StencilJS](https://stenciljs.com/)*

package/dist/docs/xpl-table/xpl-table-header-cell/readme.md

@@ -0,0 +1,84 @@
+# xpl-table-header-cell
+
+> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.
+
+The `icon` property accepts icon names as strings. See [xpl-icon available icons](../xpl-icon/ICONS.md) for the complete list.
+
+When this cell is used inside a compositional [`xpl-table`](../xpl-table) with `selectable`, **you** add a `type="checkbox"` header cell for select-all; `xpl-table` keeps `checked` and `indeterminate` in sync with row selection.
+
+**Frameworks (Vue / etc.):** `type` is **reflected** to the DOM. You may bind with `:type="'checkbox'"` or `type="checkbox"`; the host will still expose `type="checkbox"` as an attribute so the table’s selection column logic and styles stay correct.
+
+For **sortable** columns (`type="label"`), set **`sortable`** and optionally **`sort-key`**; the parent table emits **`sortChanged`** (see [`xpl-table` events](../xpl-table#events)).
+
+**Column width (compositional grid):** Each header cell defines one grid column on the parent `xpl-table`. By default the track is **`auto`** (sizes from content). Set **`width`** for a fixed pixel width (minimum 48px), or **`column-width`** for any CSS grid track string (`1fr`, `minmax(120px, 1fr)`, etc.). When both are set, **`column-width` wins**.
+
+## Design Tokens
+
+| Element | Property | Token | Light | Dark |
+| ------- | -------- | ----- | ----- | ---- |
+| Cell | background | `--xpl-background-surface-subtlest` | neutral-50 | neutral-950 |
+| Cell | text | `--xpl-text-subdued` | neutral-600 | neutral-400 |
+| Cell | border (right/bottom) | `--xpl-border-small`, `--xpl-border-default` | 1px, neutral-200 | 1px, neutral-800 |
+| Cell | min-width | `--xpl-size-300` | 48px | 48px |
+| Cell | min-height | `--xpl-size-350` | 56px | 56px |
+| Cell | typography | `@extend .xpl-text-title-5` | title-5 / medium | title-5 / medium |
+| Sort button | padding | `--xpl-space-12`, `--xpl-space-16` | 12px / 16px | 12px / 16px |
+| Sort button focus | outline | `--xpl-border-focus` | purple-500 | purple-400 |
+| Sort icon (default) | color | `--xpl-text-subdued` | neutral-600 | neutral-400 |
+| Sort icon (active) | color | `--xpl-icon-information` | blue-500 | blue-400 |
+| Checkbox column | padding | `--xpl-space-16` + `--xpl-space-4` | 20px / 16px | 20px / 16px |
+
+---
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property            | Attribute             | Description                                                                                                                                                                                                                                    | Type                                         | Default     |
+| ------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ----------- |
+| `align`             | `align`               | Horizontal text alignment within the header cell.                                                                                                                                                                                              | `"center" \| "left" \| "right"`              | `'left'`    |
+| `checkboxAriaLabel` | `checkbox-aria-label` | Accessible name for the header checkbox (native `aria-label`). Defaults to “Select all rows” when `type` is `checkbox`.                                                                                                                        | `string`                                     | `undefined` |
+| `checked`           | `checked`             | Whether the header checkbox is checked                                                                                                                                                                                                         | `boolean`                                    | `false`     |
+| `columnWidth`       | `column-width`        | CSS grid track size for this column (e.g. `1fr`, `minmax(120px, 1fr)`, `auto`). When set, overrides `width`. Use this when you need flexible columns; default layout uses `auto` per column unless you set a track here.                       | `string`                                     | `undefined` |
+| `icon`              | `icon`                | Icon to display in the cell.  See [xpl-icon available icons](../xpl-icon/ICONS.md) for valid icon names.                                                                                                                                       | `string`                                     | `undefined` |
+| `indeterminate`     | `indeterminate`       | Whether the checkbox is in indeterminate (partially selected) state                                                                                                                                                                            | `boolean`                                    | `false`     |
+| `label`             | `label`               | Text to display in the cell.                                                                                                                                                                                                                   | `string`                                     | `''`        |
+| `sortDirection`     | `sort-direction`      | Active sort direction for this column when `sortable`. Set by `xpl-table` when used inside a compositional table; may be set by the app for controlled updates.                                                                                | `"asc" \| "desc"`                            | `undefined` |
+| `sortKey`           | `sort-key`            | When `sortable` is true, optional stable id used as the key in `sortChanged`’s detail object. Falls back to a slug of `label` when omitted.                                                                                                    | `string`                                     | `undefined` |
+| `sortable`          | `sortable`            | When true (and `type` is `label`), renders a sort control (button + affordance icon).                                                                                                                                                          | `boolean`                                    | `false`     |
+| `type`              | `type`                | The type of cell to render. **Reflected** to the host `type` attribute so `xpl-table` (and CSS `[type="checkbox"]`) can find the selection column after frameworks set the prop without syncing the attribute (e.g. Vue `:type="'checkbox'"`). | `"checkbox" \| "empty" \| "icon" \| "label"` | `'label'`   |
+| `width`             | `width`               | Fixed width for this column in pixels (minimum 48px). Sets the grid track to `Npx`. Ignored when `columnWidth` is set. When omitted, the column track defaults to `auto` (content-sized).                                                      | `number`                                     | `undefined` |
+
+
+## Events
+
+| Event                  | Description                                                                                                        | Type                                  |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------- |
+| `headerCheckboxChange` | Emitted when header checkbox changes                                                                               | `CustomEvent<boolean>`                |
+| `headerSortChange`     | Emitted when a sortable label header is activated. Parent `xpl-table` coordinates columns and emits `sortChanged`. | `CustomEvent<HeaderSortChangeDetail>` |
+
+
+## Dependencies
+
+### Used by
+
+ - [xpl-table](..)
+
+### Depends on
+
+- [xpl-icon](../../xpl-icon)
+- [xpl-checkbox](../../xpl-checkbox)
+
+### Graph
+```mermaid
+graph TD;
+  xpl-table-header-cell --> xpl-icon
+  xpl-table-header-cell --> xpl-checkbox
+  xpl-table --> xpl-table-header-cell
+  style xpl-table-header-cell fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

package/dist/docs/xpl-table/xpl-table-row/readme.md

@@ -2,20 +2,24 @@
 
 Data row for compositional tables. Uses `display: contents` by default so cells align to the parent grid; when the body supports subgrid, the row becomes a full-width subgrid for drag interactions.
 
-### Design Tokens
-
-| Element | Property | Token | Value |
-| -- | -- | -- | -- |
-| Host (default) | display | — | `contents` |
-| Host (subgrid body) | display | — | `grid` with `subgrid` |
-| Disabled row | background | `--xpl-background-surface-subtlest` | neutral-50 (lm) / neutral-950 (dm) |
-| Disabled row | text | `--xpl-text-disabled` | neutral-400 (lm) / neutral-600 (dm) |
-| Dragging row | background | `--xpl-background-surface-subtle` | neutral-100 (lm) / neutral-900 (dm) |
-| Dragging row | opacity | `--xpl-opacity-75` | 0.75 (custom, mirrors xpl-list) |
-| Selected row | background | `--xpl-background-surface-information` | blue-50 (lm) / blue-950 (dm) |
-| Drag-over outline | color | `--xpl-border-focus` | purple-500 |
-| Striped even | background | `--xpl-background-surface-subtlest` | neutral-50 (lm) / neutral-950 (dm) |
-| Striped selected | background | `--xpl-background-surface-information-bold` | blue-100 (lm) / blue-900 (dm) |
+## Design Tokens
+
+Row state styles target descendant `.xpl-table-cell` nodes (see `table-row.css`).
+
+| Element | Property | Token | Light | Dark |
+| ------- | -------- | ----- | ----- | ---- |
+| Host (default) | display | — | `contents` | `contents` |
+| Host (subgrid body) | display | — | `grid` with `subgrid` | `grid` with `subgrid` |
+| Disabled row | background | `--xpl-background-surface-subtlest` | neutral-50 | neutral-950 |
+| Disabled row | text | `--xpl-text-disabled` | neutral-400 | neutral-600 |
+| Dragging row | background | `--xpl-background-surface-subtle` | neutral-100 | neutral-900 |
+| Dragging row | opacity | `--xpl-opacity-75` | 0.75 | 0.75 |
+| Selected row | background | `--xpl-background-surface-information` | blue-50 | blue-950 |
+| Selected grip (reorder) | icon color | `--xpl-icon-information` | blue-500 | blue-400 |
+| Drag-over outline | inset ring | `--xpl-border-focus`, `--xpl-border-small` | purple-500 | purple-400 |
+| Striped even | background | `--xpl-background-surface-subtlest` | neutral-50 | neutral-950 |
+| Striped selected | background | `--xpl-background-surface-information-bold` | blue-100 | blue-900 |
+| Keyboard reorder grip | outline | `--xpl-border-focus` | purple-500 | purple-400 |
 
 <!-- Auto Generated Below -->
 

package/dist/docs/xpl-toast/readme.md

@@ -126,7 +126,7 @@ The mobile breakpoint (≤ 768px) resets the toast to bottom-center. If your app
 | `&__icon--warning` | color | `--xpl-icon-negative` |
 | `&__icon--success` | color | `--xpl-icon-positive` |
 | `&` | body radius | `--xpl-border-radius-small` |
-| `&` | shadow color | `--xpl-color-transparent-neutral-10` / `--xpl-color-transparent-neutral-5` |
+| `&` | shadow | `--xpl-elevation-3` (theme-aware) |
 | `&__title` | typography (size / weight / line-height) | `@extend .xpl-text-title-5` → `title-5` / `medium` / `1.4286` |
 | `&__caption` | typography (size / weight / line-height) | `@extend .xpl-text-callout` → `callout` / `normal` / `1.3333` |
 | `&__close` | margin | `@apply ml-4` |
@@ -142,7 +142,7 @@ Like `xpl-banner`, the messaging backgrounds resolve to transparent in dark mode
 - Toast content is projected through the `title` and `action` slots. Provide the title as text (e.g. `<p slot="title">`) so screen readers announce the message.
 - Dismissing runs a fade-out animation and then removes the host element from the DOM, so a dismissed toast leaves nothing behind in the accessibility tree.
 
-> **Elevation shadow (interim):** Figma specs the toast shadow as the single "Shadow 4" elevation style (`y=20`, `blur=25`, color `background-surface-transparent-10`). Foundation has no elevation/shadow tokens yet, so the shadow geometry is hand-authored and its color uses the primitive `--xpl-color-transparent-neutral-10 / -5`. This migrates to the purpose-specific `--xpl-background-surface-transparent-10` (theme-aware) once elevation tokens land — tracked in `TECH_DEBT.md`.
+> **Elevation shadow:** the toast uses `--xpl-elevation-3` (theme-aware), re-specified by design during the elevation 1–4 formalization — an earlier note citing the single "Shadow 4" style was superseded. See `TECH_DEBT.md`.
 
 <!-- Auto Generated Below -->
 

package/dist/docs/xpl-toggle/readme.md

@@ -24,7 +24,7 @@ in light and dark mode (no `.dark` overrides).
 | Track (disabled, on/off) | `background-color` | `--xpl-background-action-disabled` |
 | Track border | `border-color` | `--xpl-border-default` |
 | Knob (all states) | `background-color` | `--xpl-background-surface-inverse-on-dark` (always-light — resolves to neutral-0 in both modes) |
-| Knob shadow | `box-shadow` color | `--xpl-color-transparent-neutral-10` |
+| Knob shadow | `box-shadow` | `--xpl-elevation-1` (theme-aware) |
 | Focus ring | `outline-color` | `--xpl-border-focus` (2px outline, 2px offset) |
 | Heading | `color` | `--xpl-text-strong` |
 | Heading | typography | `@extend .xpl-text-title-5` — 14px / medium / 1.4286 (via shared `label.css`) |

package/dist/docs/xpl-toolbar/readme.md

@@ -12,15 +12,17 @@ in both light and dark themes. Styling comes from Apollo Foundation tokens
 | --- | --- | --- | --- |
 | `.toolbar` surface | `background-color` | `--xpl-background-surface-inverse-on-light` | neutral-1000 / neutral-1000 |
 | `.toolbar` top/bottom border | `border-color` | `--xpl-border-default` | neutral-600 (always-dark host) |
-| `.toolbar` elevation | `box-shadow` | `--xpl-color-transparent-neutral-10`, `--xpl-color-transparent-neutral-5` | fixed neutral transparent |
+| `.toolbar` elevation | `box-shadow` | `--xpl-elevation-1` | theme-aware (near-black light / near-white dark) |
 | `.toolbar` height | `height` | `--xpl-size-350` | 56px |
 | `.selected-item-count` text | `color` | `--xpl-text-inverse-on-dark` | white / white |
 | `.selected-item-count` divider | `border-color` | `--xpl-border-default` | neutral-600 (always-dark host) |
 | `.selected-item-count` label | `font-size` / `font-weight` / `line-height` | `@extend .xpl-text-title-5` (14px, medium, 1.4286) | — |
 
 > **Design note:** the always-dark surface decision is confirmed (there is no
-> toolbar node in `figma-manifest.json`). Foundation defines no shadow tokens, so the
-> elevation uses the neutral transparent primitives. See `TECH_DEBT.md`.
+> toolbar node in `figma-manifest.json`). The elevation uses the theme-aware
+> `--xpl-elevation-1` token: in dark mode the shadow color flips to near-white, so
+> the always-dark bar gets a light halo beneath it — flagged for design verification
+> (see `TECH_DEBT.md`).
 
 <!-- Auto Generated Below -->
 

package/dist/docs/xpl-tooltip/readme.md

@@ -12,8 +12,7 @@ Tokens used by this component from `@xplortech/apollo-foundation`.
 
 **Color**
 - `--xpl-background-surface-default` — tooltip background and arrow fill
-- `--xpl-background-surface-transparent-10` — shadow primary layer
-- `--xpl-background-surface-transparent-5` — shadow secondary layer
+- `--xpl-elevation-3` — tooltip shadow (theme-aware)
 - `--xpl-text-default` — tooltip text color
 - `--xpl-border-default` — tooltip border and arrow stroke (keeps the arrow edge theme-aware in dark mode)