@xplortech/apollo-core 2.6.0 → 2.7.0

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

@@ -0,0 +1,235 @@
+# xpl-spotlight
+
+`xpl-spotlight` renders a guided-tour callout with an anchor dot, optional media, step messaging, and prop-driven footer actions. It can either render inline using the requested `anchorPosition` or attach to a target element with Floating UI when `target` is provided.
+
+## Usage Examples
+
+Use the built-in title/body props and default actions for a simple tour step:
+
+```html
+<xpl-spotlight
+  heading="Review recent activity"
+  body="Check status updates here before moving to the next step."
+  action-layout="default"
+  anchor-position="top-right"
+  current-step="2"
+  total-steps="5"
+  is-dismissible="true"
+  is-open="true"
+  primary-action-label="Next"
+  secondary-action-label="Back"
+  show-actions="true"
+  show-image="true"
+  show-steps="true"
+  target=""
+></xpl-spotlight>
+```
+
+Anchor the spotlight to a specific element and provide custom media content:
+
+```html
+<button id="dashboard-filter-button" type="button">Filters</button>
+
+<xpl-spotlight
+  target="#dashboard-filter-button"
+  heading="Narrow the results"
+  body="Use filters to focus on the accounts or activity that matter most."
+  current-step="1"
+  total-steps="3"
+  primary-action-label="Next"
+  secondary-action-label="Skip"
+>
+  <div slot="image">
+    <img src="/assets/spotlight-filter-preview.png" alt="Preview of filter controls" />
+  </div>
+</xpl-spotlight>
+```
+
+
+Control visibility from the parent with `is-open` and close it by responding to `dismiss`:
+
+```html
+<xpl-spotlight
+  id="guided-tour-step"
+  is-open="true"
+  heading="Review recent activity"
+  body="Check status updates here before moving to the next step."
+></xpl-spotlight>
+
+<script>
+  const spotlight = document.getElementById('guided-tour-step');
+
+  spotlight?.addEventListener('dismiss', () => {
+    spotlight.setAttribute('is-open', 'false');
+  });
+</script>
+```
+
+Mirror the same layout in plain HTML when documenting or prototyping the component structure outside the custom element:
+
+```html
+<div class="xpl-spotlight xpl-spotlight--top-left xpl-spotlight--visible"
+     role="dialog" aria-modal="false" aria-labelledby="spotlight-title" tabindex="-1">
+  <button type="button" class="xpl-spotlight__target" aria-label="Spotlight indicator">
+    <div class="xpl-spotlight__target-outer"></div>
+    <div class="xpl-spotlight__target-inner"></div>
+  </button>
+  <div class="xpl-spotlight__dismiss">
+    <xpl-button variant="secondary" size="sm" icon-only aria-label="Dismiss tour step">
+      <xpl-icon icon="xmark" size="16"></xpl-icon>
+    </xpl-button>
+  </div>
+  <div class="xpl-spotlight__frame">
+    <div class="xpl-spotlight__image-container">
+      <img src="/assets/spotlight-preview.png" alt="Feature preview" />
+    </div>
+    <div class="xpl-spotlight__content">
+      <div class="xpl-spotlight__header">
+        <span class="xpl-spotlight__title" id="spotlight-title">Tour Title</span>
+        <p class="xpl-spotlight__body">Copy about the feature and/or functionality the dot is pointing to.</p>
+      </div>
+      <div class="xpl-spotlight__actions xpl-spotlight__actions--dual xpl-spotlight__actions--with-steps">
+        <div class="xpl-spotlight__action-slot xpl-spotlight__action-slot--secondary">
+          <xpl-button variant="secondary">Back</xpl-button>
+        </div>
+        <span class="xpl-spotlight__step-text">2 of 5</span>
+        <div class="xpl-spotlight__action-slot xpl-spotlight__action-slot--primary">
+          <xpl-button variant="primary">Next</xpl-button>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+## Accessibility
+
+`xpl-spotlight` renders with `role="dialog"` and `aria-modal="false"` so assistive technologies treat it as a **non-modal** tour callout: focus is not trapped inside the card, and users can tab to the rest of the page while the step is open. The accessible name comes from the title region:
+
+- When the default title is used, the generated heading element receives the internal `aria-labelledby` id.
+- When a custom `title` slot is provided, the component assigns that same id to the first slotted title element if it does not already have one. If the slotted element already has an `id`, that value is kept and `aria-labelledby` references it (the host does not point at a missing id).
+- When neither a `heading` prop nor a `title` slot is provided, the dialog falls back to `aria-label="Tour step"` so that assistive technologies always have an accessible name.
+
+### Keyboard navigation
+
+| Key | Behavior |
+|-----|----------|
+| `Tab` / `Shift+Tab` | Moves focus between interactive controls (dismiss button, secondary action, primary action). Focus is **not** trapped — users can tab out of the spotlight to the rest of the page. |
+| `Escape` | Emits `dismiss` when `isDismissible` is true and focus is inside the spotlight. Does nothing when focus is outside the component or the spotlight is closed. |
+| `Enter` / `Space` | Activates the focused button (dismiss, primary, or secondary action) via standard `xpl-button` behavior. |
+
+### Focus management
+
+- **On open:** focus moves automatically to the dismiss button (if `isDismissible` is true) or the first action button. When neither a dismiss button nor action buttons are rendered, the host element itself receives focus via `tabindex="-1"`.
+- **On close:** focus returns to the element that was focused before the spotlight opened, provided that element is still in the DOM.
+- The decorative anchor dot (`.xpl-spotlight__target`) is marked `aria-hidden="true"` so it is not announced or focusable.
+
+
+## Design Tokens
+
+The component relies on Foundation purpose tokens in `spotlight.css` so light/dark mode works without component-level `.dark` overrides.
+
+| Property | Token |
+|----------|-------|
+| Card width | `var(--xpl-spotlight-width)` on the host (defined in `spotlight.css`; design-specific width until shared layout tokens exist — see `TECH_DEBT.md`) |
+| Image region min-height | `var(--xpl-spotlight-image-min-height)` on `.xpl-spotlight__image-container` (same note as card width) |
+| Card background | `var(--xpl-background-surface-default)` |
+| Host stacking | `var(--xpl-z-index-800)` |
+| Placeholder pattern | `var(--xpl-background-surface-subtle)` |
+| Heading text | `var(--xpl-text-default)` |
+| Body text | `var(--xpl-text-default)` |
+| Step text | `var(--xpl-text-subdued)` |
+| Open/closed visibility | `opacity` transition on `.xpl-spotlight--visible` |
+| Anchor outer ring | `var(--xpl-background-surface-information-bold)` |
+| Anchor inner dot | `var(--xpl-background-accent-default)` |
+| Image placeholder icon/text | `var(--xpl-icon-subtle)` |
+| Focus outline | `var(--xpl-border-focus)` |
+| Anchored host (when `target` is set) | `position: fixed` via `.xpl-spotlight--anchored`; `left` / `top` set from Floating UI (`strategy: 'fixed'`) |
+
+## Icon Mapping
+
+`xpl-spotlight` uses Apollo icons for fixed controls and fallback media placeholders:
+
+| UI area | `xpl-icon` name |
+|---------|------------------|
+| Dismiss button | `xmark` |
+| Empty image placeholder, image affordance | `photo` |
+| Empty image placeholder, video affordance | `video` |
+
+## Deprecated props
+
+None.
+
+## Notes
+
+- `showImage="false"` hides the media region even if `slot="image"` content is present.
+- When `showImage` is left enabled and no `slot="image"` content is provided, the component renders the built-in placeholder instead of collapsing the media region.
+- `showActions="false"` removes the default actions row entirely.
+- `is-open="false"` keeps the host element mounted but renders no spotlight UI until it is opened again.
+- `action-layout` defaults to `"default"`. `action-layout="default"` renders the Back/Next pair with **disabled** edge buttons at step boundaries (Back disabled on step 1, Next disabled on the last step). `action-layout="dual"` renders the Back/Next pair with **hidden** edge buttons at step boundaries. `action-layout="single"` renders a single primary action.
+- `primary-action-label` and `secondary-action-label` control the default button text without needing action slots.
+- `target` enables Floating UI positioning with `offset`, `flip`, `shift`, and `autoUpdate` so the spotlight follows the referenced element on resize and scroll. Default offset and shift padding match Foundation spacing (`--xpl-space-12` / `--xpl-space-8`).
+- If `target` is missing or contains an invalid CSS selector, the component safely falls back to the requested `anchor-position` instead of throwing.
+- **Storybook:** open **Components → Spotlight** to adjust props via controls. Set `target` to `#spotlight-story-anchor` to preview Floating UI anchoring against the demo button on the canvas. The **Design** addon links to the Apollo Web Figma file (replace the `node-id` in Storybook with the Spotlight frame when Design publishes a dedicated link).
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property               | Attribute                | Description                                                                                                                                                                                                                                                                                                                                                    | Type                                                           | Default      |
+| ---------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------ |
+| `actionLayout`         | `action-layout`          | Footer action layout. `default` and `dual` both render the standard Back/Next layout, while `single` renders a single acknowledgement CTA (e.g. "Got it!"). Only applies when `showActions` is `true`.                                                                                                                                                         | `"default" \| "dual" \| "single"`                              | `'default'`  |
+| `anchorPosition`       | `anchor-position`        | Which corner of the card the anchor dot uses when not using `target`, or as the preferred side for Floating UI.                                                                                                                                                                                                                                                | `"bottom-left" \| "bottom-right" \| "top-left" \| "top-right"` | `'top-left'` |
+| `body`                 | `body`                   | Body copy when the `body` slot has no slotted content. Whitespace-only values are treated as empty (no fallback paragraph).                                                                                                                                                                                                                                    | `string`                                                       | `undefined`  |
+| `currentStep`          | `current-step`           | Current step index (1-based). Used with `totalSteps` for the step label and for disabling default Back/Next when `showSteps` is true.                                                                                                                                                                                                                          | `number`                                                       | `1`          |
+| `heading`              | `heading`                | Heading when the `title` slot has no slotted content. Whitespace-only values are treated as empty (no fallback title span).                                                                                                                                                                                                                                    | `string`                                                       | `undefined`  |
+| `isDismissible`        | `is-dismissible`         | Whether to show the dismiss (close) control.                                                                                                                                                                                                                                                                                                                   | `boolean`                                                      | `true`       |
+| `isOpen`               | `is-open`                | Controls whether the spotlight is rendered. When false, the host remains in the DOM but the spotlight UI is hidden.                                                                                                                                                                                                                                            | `boolean`                                                      | `true`       |
+| `primaryActionLabel`   | `primary-action-label`   | Label used for the default primary action button. Only applies when `showActions` is `true`.                                                                                                                                                                                                                                                                   | `string`                                                       | `'Next'`     |
+| `secondaryActionLabel` | `secondary-action-label` | Label used for the default secondary action button. Only applies when `showActions` is `true`.                                                                                                                                                                                                                                                                 | `string`                                                       | `'Back'`     |
+| `showActions`          | `show-actions`           | Whether to show the actions row (primary / secondary and optional step counter). When `false`, the spotlight has no action buttons — useful for single-step informational callouts that rely solely on the dismiss control.                                                                                                                                    | `boolean`                                                      | `true`       |
+| `showImage`            | `show-image`             | When true, the media region is shown. Slotted `image` content is rendered when present; otherwise the built-in placeholder UI is shown. When false, the entire media block is hidden.                                                                                                                                                                          | `boolean`                                                      | `true`       |
+| `showSteps`            | `show-steps`             | Whether to show the step counter between actions (`currentStep` of `totalSteps`) and whether default Back/Next use step-based disabled state.                                                                                                                                                                                                                  | `boolean`                                                      | `true`       |
+| `target`               | `target`                 | CSS selector for the element this spotlight anchors to. When set, placement uses Floating UI (`computePosition` with `strategy: 'fixed'`, plus `flip`, `shift`, `offset`) and `autoUpdate` for scroll/resize. The host receives `left` / `top` and the `xpl-spotlight--anchored` class. Invalid selectors are ignored; layout falls back to `anchor-position`. | `string`                                                       | `undefined`  |
+| `totalSteps`           | `total-steps`            | Total number of steps (1-based upper bound). Used with `currentStep` for the step label and for disabling default Back/Next when `showSteps` is true.                                                                                                                                                                                                          | `number`                                                       | `1`          |
+
+
+## Events
+
+| Event             | Description                                                                                    | Type                |
+| ----------------- | ---------------------------------------------------------------------------------------------- | ------------------- |
+| `dismiss`         | Emitted when the dismiss control is activated or Escape is pressed (when dismissible).         | `CustomEvent<void>` |
+| `primaryAction`   | Emitted when the primary action control is activated (default: Next).                          | `CustomEvent<void>` |
+| `secondaryAction` | Emitted when the secondary action control is activated (default: Back).                        | `CustomEvent<void>` |
+| `targetClick`     | Emitted when the target indicator is clicked. Consumers typically toggle `isOpen` in response. | `CustomEvent<void>` |
+
+
+## Slots
+
+| Slot      | Description                                                                                                    |
+| --------- | -------------------------------------------------------------------------------------------------------------- |
+| `"body"`  | Main description; falls back to the `body` prop when the slot is empty and `body` has non-whitespace text      |
+| `"image"` | Optional media slot. When empty and `showImage` is true, the component renders a built-in placeholder instead. |
+| `"title"` | Step title; falls back to the `heading` prop when the slot is empty and `heading` has non-whitespace text      |
+
+
+## Dependencies
+
+### Depends on
+
+- [xpl-button](../xpl-button)
+- [xpl-icon](../xpl-icon)
+
+### Graph
+```mermaid
+graph TD;
+  xpl-spotlight --> xpl-button
+  xpl-spotlight --> xpl-icon
+  xpl-button --> xpl-icon
+  style xpl-spotlight fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

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

@@ -1,24 +1,60 @@
 # xpl-tab
 
+`xpl-tab` is the **label / trigger** for one tab in an `xpl-tabs` group. Place each instance in the **`heading`** slot of `xpl-tabs`. The **`target`** string links this tab to the matching **`xpl-tab-panel`** (same `target` value). The parent sets **`selected`** and syncs **`value`**; you normally do not set `selected` by hand.
 
+Underline tabs render a native **`<button role="tab">`**; segment tabs render **`xpl-button`** with the same tab semantics on the inner control. For variant-specific examples, icon usage, and token tables, see the matching section on the **Tabs** or **Segment control** Storybook page.
+
+**`group-disabled`** is applied by `xpl-tabs` when the group has **`disabled`**; it keeps pills and underline buttons in a disabled state together with the parent.
+
+## Accessibility
+
+- **IDs and ARIA:** With a parent **`xpl-tabs`**, the tab control and matching **`xpl-tab-panel`** share scoped DOM ids derived from **`data-tabs-instance-id`** on the group and each pair’s **`target`** (see **`xpl-tabs`** accessibility notes). Underline tabs set **`id`**, **`role="tab"`**, **`aria-controls`**, and **`aria-selected`** on the native `<button>`. Segment tabs wrap **`xpl-button`**, which forwards **`id`**, **`role`**, and **`aria-*`** attributes to its inner `<button>` so focus and **`aria-labelledby`** stay correct.
+- Underline tabs expose a **single focusable button** per tab.
+- Segment tabs delegate rendering to **`xpl-button`** with the same tab semantics as underline mode; activation follows the same **`tabChange`** event.
+- Disabled tabs are skipped when moving with arrow keys.
 
 <!-- Auto Generated Below -->
 
 
 ## Properties
 
-| Property   | Attribute  | Description                                                | Type      | Default     |
-| ---------- | ---------- | ---------------------------------------------------------- | --------- | ----------- |
-| `selected` | `selected` | Whether the tab is selected                                | `boolean` | `false`     |
-| `target`   | `target`   | The target of the tab, required for the tab to be selected | `string`  | `undefined` |
+| Property        | Attribute             | Description                                                                                                   | Type               | Default     |
+| --------------- | --------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------ | ----------- |
+| `disabled`      | `disabled`            | Disables this tab (pill or underline).                                                                        | `boolean`          | `false`     |
+| `groupDisabled` | `data-group-disabled` | Set when the parent `xpl-tabs` has `disabled` (group-disabled).                                               | `boolean`          | `false`     |
+| `icon`          | `icon`                | Optional icon name for segment-style pills (`type="segment"` on parent `xpl-tabs`). Ignored for default tabs. | `string`           | `undefined` |
+| `iconPosition`  | `icon-position`       | Icon position for segment-style pills.                                                                        | `"end" \| "start"` | `'start'`   |
+| `selected`      | `selected`            | Whether the tab is selected                                                                                   | `boolean`          | `false`     |
+| `target`        | `target`              | The target of the tab, required for the tab to be selected                                                    | `string`           | `undefined` |
 
 
 ## Events
 
-| Event       | Description                                     | Type                  |
-| ----------- | ----------------------------------------------- | --------------------- |
-| `tabChange` | Event that emits the target of the selected tab | `CustomEvent<string>` |
+| Event       | Description                                                                                                                                                                                                       | Type                  |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
+| `tabChange` | Emitted when this tab is activated (if not disabled). The event `detail` is this tab’s `target` string. Parent `xpl-tabs` listens and updates selection; use `tabChange` on `xpl-tabs` for the group-level event. | `CustomEvent<string>` |
+
+
+## Slots
+
+| Slot | Description                                                                        |
+| ---- | ---------------------------------------------------------------------------------- |
+|      | The label for the tab (or pill label when parent `xpl-tabs` has `type="segment"`). |
+
+
+## Dependencies
+
+### Depends on
+
+- [xpl-button](../xpl-button)
 
+### Graph
+```mermaid
+graph TD;
+  xpl-tab --> xpl-button
+  xpl-button --> xpl-icon
+  style xpl-tab fill:#f9f,stroke:#333,stroke-width:4px
+```
 
 ----------------------------------------------
 

package/dist/docs/xpl-tab-panel/readme.md

@@ -1,6 +1,41 @@
 # xpl-tab-panel
 
+`xpl-tab-panel` is the **content region** for one tab. Place each panel in the **`panel`** slot of `xpl-tabs` and set **`target`** to the same string as its paired **`xpl-tab`**. Only the panel whose `target` matches the group’s selection is visible; others stay hidden via CSS until selected.
 
+## When to use
+
+- One panel per tab in the same `xpl-tabs` as the corresponding `xpl-tab`.
+- Put any markup or other components in the **default slot** (panel body).
+
+## Usage
+
+```html
+<xpl-tabs value="overview">
+  <xpl-tab slot="heading" target="overview">Overview</xpl-tab>
+  <xpl-tab slot="heading" target="activity">Activity</xpl-tab>
+  <xpl-tab-panel slot="panel" target="overview">
+    <p class="xpl-text-body">Overview content.</p>
+  </xpl-tab-panel>
+  <xpl-tab-panel slot="panel" target="activity">
+    <p class="xpl-text-body">Activity content.</p>
+  </xpl-tab-panel>
+</xpl-tabs>
+```
+
+The parent **`xpl-tabs`** updates each panel’s **`selected`** state from **`value`** / user interaction; consumers typically only set **`target`** and slot content.
+
+## Accessibility
+
+- The host sets **`role="tabpanel"`**, a stable **`id`** (`…-panel-<target>` scoped by the parent **`xpl-tabs`** instance), and **`aria-labelledby`** referencing the paired tab control’s **`id`**. Use the same **`target`** on **`xpl-tab`** and **`xpl-tab-panel`** so the references stay aligned (see **`xpl-tabs`** accessibility section for the full id pattern).
+- Hidden panels use display toggling (`xpl-tab-panel` / `--selected` in `tabs.css`), not `aria-hidden` on the host; panel content stays in the DOM for simpler state sync.
+
+## Token use
+
+| Part | Token / approach |
+| ---- | ---------------- |
+| Panel visibility | `tabs.css`: hidden unless `xpl-tab-panel--selected` (`display` via Tailwind `@apply`) |
+| Default padding | `py-6` in `tabs.css` on `.xpl-tab-panel` |
+| Inner content | Use typography classes (`xpl-text-body`, etc.) and Foundation tokens as elsewhere in Apollo |
 
 <!-- Auto Generated Below -->
 
@@ -13,6 +48,13 @@
 | `target`   | `target`   | The target of the tab, required for the tab to be selected | `string`  | `undefined` |
 
 
+## Slots
+
+| Slot | Description                           |
+| ---- | ------------------------------------- |
+|      | Content rendered inside of the panel. |
+
+
 ----------------------------------------------
 
 *Built with [StencilJS](https://stenciljs.com/)*

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/)*