@xplortech/apollo-core 2.5.0 → 2.7.0

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

@@ -1,46 +1,110 @@
-# xpl-table
-
-Tables are used to organize and display information from a data set. 
-
-<!-- Auto Generated Below -->
-
-
-## 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` |
-
-
-## Events
-
-| Event         | Description                                                                                                                                                                                                               | Type                                                                       |
-| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| `sortChanged` | Emits an event whenever the sort changes. The 'sortChanged' event passes an object with colNum (number), colName (string), sortTypeArr(string[]). The default action can be overridden by calling event.preventDefault(). | `CustomEvent<{ colNum: number; colName: string; sortTypeArr: string[]; }>` |
-| `tableSelect` | Callback function that is called when the checkbox for a row of a `multiselect` table is checked                                                                                                                          | `CustomEvent<any>`                                                         |
-
-
-## Dependencies
-
-### Depends on
-
-- [xpl-icon](../xpl-icon)
-
-### Graph
-```mermaid
-graph TD;
-  xpl-table --> xpl-icon
-  style xpl-table fill:#f9f,stroke:#333,stroke-width:4px
-```
-
-----------------------------------------------
-
-*Built with [StencilJS](https://stenciljs.com/)*
+# 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.
+
+**Selection (compositional only):** Set `selectable` on `xpl-table` and **author the selection column in your template** so the framework that renders the table (Ember, React, Angular, etc.) owns every cell node. Required pieces:
+
+- **Header:** one `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.
+
+`xpl-table` keeps `selectedRowIds`, syncs `checked` / `indeterminate` on the header and row checkboxes, sets `selected` on rows, shows the bulk toolbar, and emits `rowSelectionChange` **on the `xpl-table` element** (`bubbles: false`). From a static script, use `customElements.whenDefined('xpl-table')` before `addEventListener`. Row checkboxes get an accessible name 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.
+
+### 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, as described above. `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.
+
+### 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.
+
+<!-- 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`                   | --                             | <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`    | `undefined` |
+| `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                                         |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `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. 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-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-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
+```
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

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

@@ -0,0 +1,10 @@
+# xpl-table-body
+
+
+
+<!-- Auto Generated Below -->
+
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

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

@@ -0,0 +1,33 @@
+# 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.
+
+<!-- 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

@@ -0,0 +1,10 @@
+# xpl-table-footer
+
+
+
+<!-- Auto Generated Below -->
+
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

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

@@ -0,0 +1,30 @@
+# xpl-table-footer-cell
+
+
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property | Attribute | Description                                | Type                            | Default  |
+| -------- | --------- | ------------------------------------------ | ------------------------------- | -------- |
+| `align`  | `align`   | Horizontal text alignment within the cell. | `"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-header → xpl-table/xpl-table-header}/readme.md

@@ -1,13 +1,13 @@
-# xpl-table-header
-
-Component parts used to assemble the Dynamic Table.
-
-> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.
-
-
-<!-- Auto Generated Below -->
-
-
-----------------------------------------------
-
-*Built with [StencilJS](https://stenciljs.com/)*
+# xpl-table-header
+
+Semantic wrapper for the header **row group** in a compositional `xpl-table` (`role="rowgroup"`). Place one `xpl-table-row` (with `xpl-table-header-cell` children) inside.
+
+> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.
+
+
+<!-- Auto Generated Below -->
+
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

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

@@ -0,0 +1,66 @@
+# 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.
+
+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**.
+
+---
+
+<!-- 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.                                                                                                                                                                                              | `"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

@@ -0,0 +1,19 @@
+# xpl-table-row
+
+
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property   | Attribute  | Description                                                                                                                             | Type      | Default     |
+| ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------- |
+| `disabled` | `disabled` | Whether the row and its cells are disabled.                                                                                             | `boolean` | `false`     |
+| `rowId`    | `row-id`   | Stable identifier for this row when used with a selectable compositional `xpl-table`. If omitted, the parent table assigns a unique id. | `string`  | `undefined` |
+| `selected` | `selected` | Whether the row is visually selected.                                                                                                   | `boolean` | `false`     |
+
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

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

@@ -1,23 +1,76 @@
 # xpl-tabs
 
-Tabs organize content across different screens, data sets, and other interactions.
+`xpl-tabs` groups related views into a single surface: users pick a **tab** to show the matching **panel**. It implements the WAI-ARIA tabs pattern with a horizontal tab list, optional full-width layout, and two visual styles—**underline** (`type="tabs"`, default) and **segment** (`type="segment"`, pill controls in a bordered track)—selected with the **`type`** prop. On narrow viewports the heading row is replaced by an `xpl-select` so the same targets and keyboard behavior stay consistent.
+
+The **Tabs** and **Segment control** Storybook entries document this **one component** with different defaults and Figma references. Each page adds variant-specific guidance (when to use, examples, tokens); the sections below describe behavior that is **the same for both** styles.
+
+Pair **`xpl-tab` (slot `heading`)** with **`xpl-tab-panel` (slot `panel`)** and use the same **`target`** string on each pair so selection stays in sync.
+
+## Usage
+
+### Web component (`<xpl-tabs>`)
+
+Minimal group with two tabs: each `xpl-tab` and `xpl-tab-panel` shares a `target` value. Set `value` on `xpl-tabs` to control the selected tab (defaults to the first tab’s `target` if omitted).
+
+```html
+<xpl-tabs value="one">
+  <xpl-tab slot="heading" target="one">First</xpl-tab>
+  <xpl-tab slot="heading" target="two">Second</xpl-tab>
+  <xpl-tab-panel slot="panel" target="one">Content for first tab.</xpl-tab-panel>
+  <xpl-tab-panel slot="panel" target="two">Content for second tab.</xpl-tab-panel>
+</xpl-tabs>
+```
+
+Listen for selection changes with the **`tabChange`** event (detail is the selected `target` string):
+
+```html
+<xpl-tabs id="demo" value="a">
+  <xpl-tab slot="heading" target="a">A</xpl-tab>
+  <xpl-tab slot="heading" target="b">B</xpl-tab>
+  <xpl-tab-panel slot="panel" target="a">…</xpl-tab-panel>
+  <xpl-tab-panel slot="panel" target="b">…</xpl-tab-panel>
+</xpl-tabs>
+<script>
+  document.getElementById('demo').addEventListener('tabChange', (e) => {
+    console.log(e.detail); // "a" | "b"
+  });
+</script>
+```
+
+Disable the entire group (headings, mobile select, and segment pills) with **`disabled`** on `xpl-tabs`. Disable individual tabs with **`disabled`** on `xpl-tab`.
+
+### Plain HTML (BEM classes)
+
+When styling with `tabs.css` without the Stencil component, mirror the structure: `xpl-tabs`, `xpl-tabs__headings` with `role="tablist"` and `aria-orientation="horizontal"`, `xpl-tabs__active-bar` for the underline variant (position/size normally set by JS), **`button.xpl-tab__button`** with **`role="tab"`** (not links), and **`xpl-tab-panel`** for panels. For **segment** (`xpl-tabs--segment`), each heading is **`xpl-tab.xpl-tab--segment`** wrapping **`xpl-button`** (not `.xpl-tab__button`). On small viewports, include **`xpl-tabs__mobile-select`** with **`xpl-select`** for parity with the component.
+
+## Accessibility
+
+- Each **`xpl-tabs`** root gets a unique **`data-tabs-instance-id`** (for example `xpl-tg-1`). **`xpl-tab`** and **`xpl-tab-panel`** derive matching DOM **`id`** values from that id plus the shared **`target`** string: the tab control is **`…-tab-<target>`**, the panel is **`…-panel-<target>`** (with `target` sanitized for HTML `id` rules). The tab exposes **`aria-controls`** pointing at the panel id, **`aria-selected`**, and the panel uses **`aria-labelledby`** pointing at the tab id. **Segment (pill) tabs** render **`xpl-button`**; because **`xpl-button`** does not forward **`id`** / **`role`** / **`aria-*`** to its inner `<button>`, **`xpl-tab`** sets those on the native button after render so focus order and **`aria-labelledby`** stay correct (same pattern as underline tabs, different host element).
+- The tab list container is **`role="tablist"`** with **`aria-orientation="horizontal"`**. Underline tabs use **`role="tab"`** on the inner `<button>`; panels use **`role="tabpanel"`** on **`xpl-tab-panel`**.
+- **Roving tabindex:** only the active tab’s control is in the tab order (`tabindex="0"`); others use `tabindex="-1"` until focused with arrows.
+- **Keyboard:** **Arrow Left/Right** (and **Arrow Up/Down** as next/previous), **Home**, and **End** move between enabled tabs; **Enter** and **Space** activate (via `xpl-button` in segment mode). Direction mirrors in **RTL**.
+- When **`disabled`** is set on `xpl-tabs`, tab keyboard navigation and selection are suppressed for the group.
+
+Variant-specific Foundation mappings for underline vs. segment live in the **Tabs** and **Segment control** Storybook pages. The **`xpl-select`** mobile row reuses **`xpl-select`** / **`xpl-dropdown`** tokens from those components.
 
 <!-- Auto Generated Below -->
 
 
 ## Properties
 
-| Property    | Attribute    | Description                                              | Type      | Default     |
-| ----------- | ------------ | -------------------------------------------------------- | --------- | ----------- |
-| `fullWidth` | `full-width` | Whether to make the tabs full width                      | `boolean` | `false`     |
-| `value`     | `value`      | The selected tab target value, defaults to the first tab | `string`  | `undefined` |
+| Property    | Attribute    | Description                                                                   | Type                  | Default     |
+| ----------- | ------------ | ----------------------------------------------------------------------------- | --------------------- | ----------- |
+| `disabled`  | `disabled`   | Disables the whole tab group (headings, mobile select, and segment pills).    | `boolean`             | `false`     |
+| `fullWidth` | `full-width` | Whether to make the tabs full width                                           | `boolean`             | `false`     |
+| `type`      | `type`       | Visual and layout variant: classic underline tabs or segment (pill) controls. | `"segment" \| "tabs"` | `'tabs'`    |
+| `value`     | `value`      | The selected tab target value, defaults to the first tab                      | `string`              | `undefined` |
 
 
 ## Events
 
-| Event       | Description                                     | Type                  |
-| ----------- | ----------------------------------------------- | --------------------- |
-| `tabChange` | Event that emits the target of the selected tab | `CustomEvent<string>` |
+| Event       | Description                                                                                                                                                                                                                                                                                     | Type                  |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
+| `tabChange` | Emitted when the selected tab changes (click, keyboard, or mobile `xpl-select`). The event `detail` is the selected tab’s `target` string. Always dispatched from this host (including after heading clicks) so `event.target` is consistent for listeners on `xpl-tabs` or bubbling ancestors. | `CustomEvent<string>` |
 
 
 ## Slots
@@ -41,11 +94,13 @@ graph TD;
   xpl-select --> xpl-tag
   xpl-select --> xpl-icon
   xpl-select --> xpl-dropdown
+  xpl-tag --> xpl-icon
   xpl-dropdown --> xpl-dropdown-group
   xpl-dropdown --> xpl-dropdown-option
   xpl-dropdown-group --> xpl-dropdown-group
   xpl-dropdown-group --> xpl-dropdown-option
   xpl-dropdown-group --> xpl-dropdown-heading
+  xpl-dropdown-option --> xpl-icon
   style xpl-tabs fill:#f9f,stroke:#333,stroke-width:4px
 ```