@xplortech/apollo-core 2.5.0 → 2.7.0

package/dist/docs/xpl-side-nav/readme.md

@@ -0,0 +1,71 @@
+# xpl-side-nav
+
+Slot-based sidebar for app navigation: scrollable main area and a fixed footer. Compose with [`xpl-side-nav-item`](./xpl-side-nav-item) for rows in the section and footer.
+
+## Slots
+
+| Slot | Description |
+| ---- | ----------- |
+| `section` | Primary navigation. Place `xpl-side-nav-item` elements (or wrappers) inside this slot; layout uses internal section markup. |
+| `nav-footer` | Footer actions (e.g. Help, Logout). Same item component; typically smaller label styling via CSS. |
+
+## Usage
+
+Use the **`label`** prop for a unique accessible name on the `<nav>` when multiple landmarks exist on the page (see **Multi-Navigation Layouts** below).
+
+```html
+<xpl-side-nav label="Main navigation">
+  <div slot="section">
+    <xpl-side-nav-item label="Dashboard" icon="house-4" selected></xpl-side-nav-item>
+    <xpl-side-nav-item has-children label="Settings" expanded>
+      <xpl-side-nav-item label="Profile"></xpl-side-nav-item>
+    </xpl-side-nav-item>
+  </div>
+  <div slot="nav-footer">
+    <xpl-side-nav-item label="Help" icon="headset"></xpl-side-nav-item>
+  </div>
+</xpl-side-nav>
+```
+
+**Link rows:** use `xpl-side-nav-item` with `link` and an anchor in the default slot — see [xpl-side-nav-item](./xpl-side-nav-item) **Link mode**.
+
+### Multi-Navigation Layouts (Accessibility)
+
+When multiple navigation landmarks exist on a page (e.g., side nav, top nav, breadcrumbs), use the `label` prop to provide a unique accessible name for each `<nav>` element. This helps screen reader users distinguish between them.
+
+```html
+<!-- Main side navigation -->
+<xpl-side-nav label="Main navigation">
+  ...
+</xpl-side-nav>
+
+<!-- Top navigation (different component) -->
+<xpl-top-nav label="User menu">
+  ...
+</xpl-top-nav>
+
+<!-- Breadcrumbs (different component) -->
+<xpl-breadcrumbs label="Breadcrumb">
+  ...
+</xpl-breadcrumbs>
+```
+
+**WCAG Note:** When a page has multiple `<nav>` landmarks, each should have a unique accessible name via `aria-label`.
+
+## Related components
+
+- [xpl-side-nav-item](../xpl-side-nav-item) — Navigation rows (leaf, expandable, or link) for section and footer.
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property | Attribute | Description                                                                                                                                                                                                                                 | Type     | Default     |
+| -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------- |
+| `label`  | `label`   | Accessible label for the navigation landmark. Maps to `aria-label` on the `<nav>` element. Recommended when multiple navigation landmarks exist on a page (e.g., side nav + top nav + breadcrumbs) to help screen readers distinguish them. | `string` | `undefined` |
+
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

package/dist/docs/xpl-side-nav/xpl-side-nav-item/readme.md

@@ -0,0 +1,115 @@
+# xpl-side-nav-item
+
+Row for [`xpl-side-nav`](../xpl-side-nav): place items in `slot="section"` or `slot="nav-footer"`. Supports **leaf** (button), **expandable** (`has-children`), and **link** (slot-only) modes, plus `selected`, `disabled`, and `hidden`.
+
+## Modes
+
+- **Leaf (default)** — Button with optional `label`, `icon`, and `slot="icon"`. Click emits **`navClick`** (not used for expandable rows).
+- **Expandable (`has-children`)** — Put nested `xpl-side-nav-item` elements in the **default slot**. Parent row is **chevron + label only** (no icon column; the `icon` prop is ignored). Click toggles **`expanded`** and emits **`expandedChange`**. “Only one section open” / accordion behavior is **not** built in — your app coordinates `expanded` if needed.
+- **Link (`link`)** — **Default slot only**: pass a real `<a>` or router link with full content. Renders a single `<slot>` (no inner button). **Cannot** be combined with `has-children` (see **Rules**).
+
+## Rules
+
+| Topic | Behavior |
+| ----- | ---------- |
+| **`link` vs `has-children`** | Mutually exclusive. When **`link`** is true, **`hasChildren`** is always false; if both attributes appear in markup, `has-children` is cleared. |
+| **Icons** | `icon` / `slot="icon"` only for **non-link** leaf/footer rows. **Not** rendered for expandable parents. **Nested** items under a parent should use **label only** (icon column hidden in CSS). |
+| **Events** | **`navClick`** — leaf button rows. **`expandedChange`** — expandable rows only (detail = new `expanded` boolean). See **Events** table below. |
+
+## Usage
+
+### Leaf
+```html
+<xpl-side-nav-item label="Dashboard" icon="house-4" selected></xpl-side-nav-item>
+```
+
+### Expandable parent
+```html
+<xpl-side-nav-item has-children label="Settings" expanded>
+  <xpl-side-nav-item label="Profile"></xpl-side-nav-item>
+  <xpl-side-nav-item label="Billing"></xpl-side-nav-item>
+</xpl-side-nav-item>
+```
+
+### Link (slot-only)
+```html
+<xpl-side-nav-item link>
+  <a href="#reports">
+    <xpl-icon icon="chart-line" size="16"></xpl-icon>
+    Reports
+  </a>
+</xpl-side-nav-item>
+```
+
+### Disabled and hidden
+```html
+<xpl-side-nav-item label="Disabled" disabled></xpl-side-nav-item>
+<xpl-side-nav-item label="Hidden" hidden></xpl-side-nav-item>
+```
+
+## Slots
+
+| Slot | Description |
+| ---- | ----------- |
+| `icon` | **Button rows only** (`link` and `has-children` do not expose this slot in the DOM). Optional leading icon: default content from the `icon` prop, or override with slotted content. Omit on nested items under an expandable parent. |
+| *(default)* | **`has-children`:** nested `xpl-side-nav-item` elements. **`link`:** one anchor (or router component) with icon + text as needed. |
+
+## Link mode checklist
+
+- Do **not** use `label` or `icon` props — put text and icons inside your anchor.
+- Set **`aria-current="page"`** on the anchor when the route is active.
+- For **disabled** links: set `disabled` on the host and `aria-disabled="true"` + `tabindex="-1"` on the anchor (see **Accessibility**).
+
+## Accessibility
+
+- **Selected (non-link):** `aria-current="page"` on the `button` (leaf or expandable row).
+- **Selected (link):** set `aria-current="page"` on your slotted anchor.
+- **Expandable:** `aria-expanded` on the parent `button` matches `expanded`.
+- **Disabled:** use the `disabled` prop on non-link rows; for link mode, coordinate host `disabled` with the anchor as above.
+- **Hidden:** `hidden` hides the row; it does not disable interaction by itself — use `disabled` when appropriate.
+
+## Related
+
+- [xpl-side-nav](../xpl-side-nav) — Sidebar container (`slot="section"`, `slot="nav-footer"`).
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property      | Attribute      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Type      | Default     |
+| ------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------- |
+| `disabled`    | `disabled`     | Whether the component is disabled                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `boolean` | `false`     |
+| `expanded`    | `expanded`     | Whether the item is currently expanded (only applies when hasChildren is true)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `boolean` | `false`     |
+| `hasChildren` | `has-children` | Whether the item has child items; when true, shows expand/collapse and a default slot for nested items. Mutually exclusive with <code>link</code>. If <code>link</code> is already true, setting <code>has-children</code> is reverted (<code>@Watch('hasChildren')</code>, <code>@Watch('link')</code>, <code>componentWillLoad</code>, and <code>componentWillRender</code>) so reflected attributes match CSS.                                                                                                                                                                         | `boolean` | `false`     |
+| `hidden`      | `hidden`       | Whether the component is hidden                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `boolean` | `false`     |
+| `icon`        | `icon`         | Optional icon name; default content for <code>slot="icon"</code> (leaf and footer rows only). Expandable parents (<code>has-children</code>) do not show an icon column — only the chevron and label. Omit for nested children under a <code>has-children</code> parent — the icon column is hidden for sub-items.                                                                                                                                                                                                                                                                        | `string`  | `undefined` |
+| `label`       | `label`        | The display label for the navigation item (button / expandable rows; omit in <code>link</code> mode).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `string`  | `undefined` |
+| `link`        | `link`         | When true, the row becomes a slot-only container for consumer-provided links. The consumer provides the full anchor element (or router link) via the default slot. In link mode, <code>label</code> and <code>icon</code> props should not be used. Link mode does not support <code>has-children</code>; use the default button mode for expandable items. When <code>link</code> is true, <code>hasChildren</code> is always false (enforced by <code>@Watch('link')</code>, <code>@Watch('hasChildren')</code>, <code>componentWillLoad</code>, and <code>componentWillRender</code>). | `boolean` | `false`     |
+| `selected`    | `selected`     | Whether the item is currently in a selected state                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `boolean` | `false`     |
+
+
+## Events
+
+| Event            | Description                                                                                         | Type                   |
+| ---------------- | --------------------------------------------------------------------------------------------------- | ---------------------- |
+| `expandedChange` | Emitted when the expanded state changes (hasChildren items only). Detail is the new expanded value. | `CustomEvent<boolean>` |
+| `navClick`       | Emitted when a leaf item is clicked. Expandable parents use expandedChange instead.                 | `CustomEvent<void>`    |
+
+
+## Dependencies
+
+### Depends on
+
+- [xpl-icon](../../xpl-icon)
+
+### Graph
+```mermaid
+graph TD;
+  xpl-side-nav-item --> xpl-icon
+  style xpl-side-nav-item fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

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

@@ -1,6 +1,6 @@
 # xpl-slideout
 
-Content and Footer subcomponents are optional and can be hidden.  Slideout always has a header with an X close button upper right. Slide Out Panel OPTIONALLY uses the [<xpl-backdrop>](https://xplor-apollo.herokuapp.com/?path=/story/components-backdrop--backdrop) component to overlay content and create focus on the Slide Out Panel content.
+Content and Footer subcomponents are optional and can be hidden.  Slideout always has a header with an X close button upper right. Slide Out Panel OPTIONALLY uses the [<xpl-backdrop>](https://apollo.xplordocs.com/?path=/story/components-backdrop--backdrop) component to overlay content and create focus on the Slide Out Panel content.
 
 <!-- Auto Generated Below -->
 
@@ -38,6 +38,7 @@ graph TD;
   xpl-slideout --> xpl-button
   xpl-slideout --> xpl-icon
   xpl-slideout --> xpl-divider
+  xpl-button --> xpl-icon
   style xpl-slideout fill:#f9f,stroke:#333,stroke-width:4px
 ```
 

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