@xplortech/apollo-core 2.11.0 → 2.12.0

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

@@ -18,14 +18,16 @@ Underline tabs render a native **`<button role="tab">`**; segment tabs render **
 
 ## Properties
 
-| 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` |
+| Property        | Attribute             | Description                                                                                                                                                                                            | Type                                                                       | Default     |
+| --------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | ----------- |
+| `badge`         | `badge`               | Optional trailing number badge (e.g. a count). Rendered after the label as a compact `xpl-badge` in both underline (`type="tabs"`) and segment (`type="segment"`) tabs. Leave empty to omit the badge. | `string`                                                                   | `undefined` |
+| `badgeVariant`  | `badge-variant`       | Color palette for the trailing number badge. Only applies when `badge` is set. Defaults to `purple` — the standard number-badge color in the Figma XPL-Tab Group spec.                                 | `"blue" \| "gray" \| "green" \| "orange" \| "purple" \| "red" \| "yellow"` | `'purple'`  |
+| `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 leading icon name (from the Apollo icon set). Rendered in both underline (`type="tabs"`) and segment (`type="segment"`) tabs.                                                                 | `string`                                                                   | `undefined` |
+| `iconPosition`  | `icon-position`       | Icon position relative to the label. Applies to both underline and segment tabs.                                                                                                                       | `"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
@@ -46,12 +48,16 @@ Underline tabs render a native **`<button role="tab">`**; segment tabs render **
 
 ### Depends on
 
+- [xpl-badge](../xpl-badge)
 - [xpl-button](../xpl-button)
+- [xpl-icon](../xpl-icon)
 
 ### Graph
 ```mermaid
 graph TD;
+  xpl-tab --> xpl-badge
   xpl-tab --> xpl-button
+  xpl-tab --> xpl-icon
   xpl-button --> xpl-icon
   style xpl-tab fill:#f9f,stroke:#333,stroke-width:4px
 ```

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

@@ -22,10 +22,10 @@ Tables are used to organize and display information from a data set.
 
 ## 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>`                                                         |
+| Event         | Description                                                                                                                                                                                                                                  | Type                                                                                  |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `sortChanged` | Emits an event whenever the sort changes. The 'sortChanged' event passes an object with colNum (number), colName (string), sortTypeArr(('asc' \| 'desc' \| null)[]). The default action can be overridden by calling event.preventDefault(). | `CustomEvent<{ colNum: number; colName: string; sortTypeArr: ("desc" \| "asc")[]; }>` |
+| `tableSelect` | Callback function that is called when the checkbox for a row of a `multiselect` table is checked                                                                                                                                             | `CustomEvent<any>`                                                                    |
 
 
 ## Dependencies

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

@@ -10,6 +10,51 @@ Match your messaging with the sentiment of the toast. Most messages will have a
 
 Toasts only support a single action and up to 85 characters. If multiple actions can be taken, or the message is longer than a few words, use a [Modal component](https://apollo.xplordocs.com/?path=/story/components-modal--modal) instead.
 
+## Usage
+
+```html
+<!-- Neutral toast with a caption, auto-dismissing after the default 8s -->
+<xpl-toast caption="Your changes have been saved.">
+    <p slot="title">Saved</p>
+</xpl-toast>
+
+<!-- With an action. Auto-dismiss is suppressed while the action slot has content -->
+<xpl-toast variant="warning" caption="We couldn't reach the server.">
+    <p slot="title">Sync failed</p>
+    <xpl-button slot="action" size="sm">Retry</xpl-button>
+</xpl-toast>
+
+<!-- No close button; disable auto-dismiss with timeout="0" -->
+<xpl-toast dismissible="false" timeout="0">
+    <p slot="title">Uploading…</p>
+</xpl-toast>
+```
+
+## Deprecations
+
+### `dismissable` → `dismissible`
+
+The **`dismissable`** prop is misspelled and is **deprecated**. Use **`dismissible`** instead.
+
+```html
+<!-- Before -->
+<xpl-toast dismissable="false">…</xpl-toast>
+
+<!-- After -->
+<xpl-toast dismissible="false">…</xpl-toast>
+```
+
+Both props are supported during the deprecation window, so no consumer change is required immediately:
+
+| `dismissable` | `dismissible` | Close button shown | Notes |
+| ------------- | ------------- | ------------------ | ----- |
+| unset | unset | ✅ | Default (`dismissible` defaults to `true`) |
+| unset | `false` | ❌ | Recommended usage |
+| `false` | unset | ❌ | Existing markup keeps working |
+| `false` | `true` | ❌ | `dismissable` wins while it exists |
+
+`dismissable` has **no default** (`undefined` when unset) so the component can tell "not set" from "set to `false`". When it is used, the component logs a one-time deprecation warning to the console. `dismissable` will be removed in the next major version, at which point `dismissible` becomes the only option.
+
 ## Positioning
 
 The default position is arbitrarily set to `40px` from top and `40px` from right of the browser viewport on desktop and bottom-center on mobile. This position should be adjusted to ensure it's not covering your App's header. Apollo, by design, does not prescribe a position for toasts because this will be dependent on the app that it is being used in.
@@ -65,18 +110,53 @@ The mobile breakpoint (≤ 768px) resets the toast to bottom-center. If your app
 
 > **Tip:** Place these overrides in a global stylesheet so every toast in your app appears in the same location.
 
+## Token Use
+
+`xpl-toast` follows the same messaging-component token pattern as [`xpl-banner`](../xpl-banner) (background `--xpl-background-messaging-*` + accent/sentiment border). Light and dark mode are handled by the Foundation token definitions, so the component has no `.dark` overrides.
+
+| Variant / element | Property | Token |
+| ----------------- | -------- | ----- |
+| `neutral` (default) | background | `--xpl-background-messaging-information` |
+| `neutral` (default) | border | `--xpl-border-accent-information` |
+| `&--warning` | background | `--xpl-background-messaging-negative` |
+| `&--warning` | border | `--xpl-border-negative` |
+| `&--success` | background | `--xpl-background-messaging-positive` |
+| `&--success` | border | `--xpl-border-positive` |
+| `&__icon--neutral` | color | `--xpl-icon-default` |
+| `&__icon--warning` | color | `--xpl-icon-negative` |
+| `&__icon--success` | color | `--xpl-icon-positive` |
+| `&` | body radius | `--xpl-border-radius-small` |
+| `&` | shadow color | `--xpl-color-transparent-neutral-10` / `--xpl-color-transparent-neutral-5` |
+| `&__title` | typography (size / weight / line-height) | `@extend .xpl-text-title-5` → `title-5` / `medium` / `1.4286` |
+| `&__caption` | typography (size / weight / line-height) | `@extend .xpl-text-callout` → `callout` / `normal` / `1.3333` |
+| `&__close` | margin | `@apply ml-4` |
+
+The close control is an [`xpl-button`](../xpl-button) (`variant="tertiary"`, `size="sm"`, `iconOnly`), so its radius, colors, and hover / focus / active states come from `button.css` rather than `toast.css`.
+
+Like `xpl-banner`, the messaging backgrounds resolve to transparent in dark mode; the sentiment border and page surface carry the visual treatment in that theme.
+
+## Accessibility
+
+- The close control is an [`xpl-button`](../xpl-button), so it is focusable and keyboard-activable (Tab, then Enter or Space) and gets the shared `:focus-visible` outline.
+- It carries `aria-label="Dismiss notification"` and `type="button"` — the explicit type keeps a toast rendered inside a `<form>` from submitting it when the toast is closed.
+- Toast content is projected through the `title` and `action` slots. Provide the title as text (e.g. `<p slot="title">`) so screen readers announce the message.
+- Dismissing runs a fade-out animation and then removes the host element from the DOM, so a dismissed toast leaves nothing behind in the accessibility tree.
+
+> **Elevation shadow (interim):** Figma specs the toast shadow as the single "Shadow 4" elevation style (`y=20`, `blur=25`, color `background-surface-transparent-10`). Foundation has no elevation/shadow tokens yet, so the shadow geometry is hand-authored and its color uses the primitive `--xpl-color-transparent-neutral-10 / -5`. This migrates to the purpose-specific `--xpl-background-surface-transparent-10` (theme-aware) once elevation tokens land — tracked in `TECH_DEBT.md`.
+
 <!-- Auto Generated Below -->
 
 
 ## Properties
 
-| Property      | Attribute     | Description | Type                                  | Default     |
-| ------------- | ------------- | ----------- | ------------------------------------- | ----------- |
-| `caption`     | `caption`     |             | `string`                              | `undefined` |
-| `dismissable` | `dismissable` |             | `boolean`                             | `true`      |
-| `showIcon`    | `show-icon`   |             | `boolean`                             | `true`      |
-| `timeout`     | `timeout`     |             | `number`                              | `8000`      |
-| `variant`     | `variant`     |             | `"neutral" \| "success" \| "warning"` | `'neutral'` |
+| Property      | Attribute     | Description                                                                                                                                                                                                                                                                   | Type                                  | Default     |
+| ------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ----------- |
+| `caption`     | `caption`     | The caption of the toast, limited to 85 characters.                                                                                                                                                                                                                           | `string`                              | `''`        |
+| `dismissable` | `dismissable` | <span style="color:red">**[DEPRECATED]**</span> Misspelled. Use `dismissible` instead. When both are set, `dismissable` wins so existing markup keeps working; `dismissable` is removed in the next major version.<br/><br/>Whether the toast shows a dismiss (close) button. | `boolean`                             | `undefined` |
+| `dismissible` | `dismissible` | Whether the toast shows a dismiss (close) button.                                                                                                                                                                                                                             | `boolean`                             | `true`      |
+| `showIcon`    | `show-icon`   | Whether to show the leading sentiment icon.                                                                                                                                                                                                                                   | `boolean`                             | `true`      |
+| `timeout`     | `timeout`     | How long the toast waits before auto-dismissing, in ms. Set to `0` to disable auto-dismiss. Ignored when the `action` slot has content.                                                                                                                                       | `number`                              | `8000`      |
+| `variant`     | `variant`     | The sentiment of the toast.                                                                                                                                                                                                                                                   | `"neutral" \| "success" \| "warning"` | `'neutral'` |
 
 
 ## Dependencies
@@ -84,11 +164,14 @@ The mobile breakpoint (≤ 768px) resets the toast to bottom-center. If your app
 ### Depends on
 
 - [xpl-icon](../xpl-icon)
+- [xpl-button](../xpl-button)
 
 ### Graph
 ```mermaid
 graph TD;
   xpl-toast --> xpl-icon
+  xpl-toast --> xpl-button
+  xpl-button --> xpl-icon
   style xpl-toast fill:#f9f,stroke:#333,stroke-width:4px
 ```
 

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

@@ -2,6 +2,52 @@
 
 A Toggle is a type of form control that is used to switch between enabled and disabled states of an element.
 
+## Usage
+
+```html
+<xpl-toggle heading="Notifications" label="Email me" checked></xpl-toggle>
+<xpl-toggle label="Compact" variant="small"></xpl-toggle>
+<xpl-toggle label="Unavailable" disabled></xpl-toggle>
+```
+
+## Design Tokens
+
+The toggle uses Apollo Foundation purpose-specific tokens so it themes automatically
+in light and dark mode (no `.dark` overrides).
+
+| Element / state | Property | Token |
+| --- | --- | --- |
+| Track (off) | `background-color` | `--xpl-background-accent-neutral` |
+| Track (off, hover) | `background-color` | `--xpl-background-accent-neutral-bold` |
+| Track (on) | `background-color` | `--xpl-background-action-primary-default` |
+| Track (on, hover) | `background-color` | `--xpl-background-action-primary-hover` |
+| Track (disabled, on/off) | `background-color` | `--xpl-background-action-disabled` |
+| Track border | `border-color` | `--xpl-border-default` |
+| Knob (all states) | `background-color` | `--xpl-background-surface-inverse-on-dark` (always-light — resolves to neutral-0 in both modes) |
+| Knob shadow | `box-shadow` color | `--xpl-color-transparent-neutral-10` |
+| Focus ring | `outline-color` | `--xpl-border-focus` (2px outline, 2px offset) |
+| Heading | `color` | `--xpl-text-strong` |
+| Heading | typography | `@extend .xpl-text-title-5` — 14px / medium / 1.4286 (via shared `label.css`) |
+| Trailing label | `color` | `--xpl-text-strong` |
+| Trailing label | typography | `@extend .xpl-text-body` — 14px / normal / 1.4286 |
+| Label (disabled) | `color` | `--xpl-text-disabled` |
+| Description (`small`) | `color` | `--xpl-text-subdued` |
+| Description (`small`) | typography | `@extend .xpl-text-callout` — 12px / normal / 1.3333 (via shared `label.css`) |
+
+**Sizing:** knob (`--xpl-size-125` / small `--xpl-size-075`), default track height
+(`--xpl-size-150`), small track height/radius (`--xpl-size-100` / `--xpl-border-radius-default`),
+default track + knob radius (`--xpl-border-radius-full`), inset (`--xpl-space-2`), knob travel
+(`translateX(--xpl-size-125)` / small `--xpl-size-075`). The `44px`/`28px` track widths have no
+matching Foundation token and remain literals (see TECH_DEBT.md).
+
+The knob glyphs (X / check marks) remain hardcoded data-URI SVGs; a `mask-image` +
+`var(--xpl-icon-*)` refactor is tracked in TECH_DEBT.md.
+
+## Accessibility
+
+The toggle renders a native `<input type="checkbox">`, so it is keyboard-focusable and
+operable with Tab and Space. The `:focus-visible` outline is applied to the control itself.
+
 <!-- Auto Generated Below -->
 
 

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

@@ -2,6 +2,25 @@
 
 > **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.
 
+## Design Tokens
+
+The toolbar is an **always-dark** selection bar (nav-rail pattern) — its surface stays dark
+in both light and dark themes. Styling comes from Apollo Foundation tokens
+(`packages/apollo-core/src/css/toolbar.css`):
+
+| Element | Property | Token | Resolves (light / dark) |
+| --- | --- | --- | --- |
+| `.toolbar` surface | `background-color` | `--xpl-background-surface-inverse-on-light` | neutral-1000 / neutral-1000 |
+| `.toolbar` top/bottom border | `border-color` | `--xpl-border-default` | neutral-600 (always-dark host) |
+| `.toolbar` elevation | `box-shadow` | `--xpl-color-transparent-neutral-10`, `--xpl-color-transparent-neutral-5` | fixed neutral transparent |
+| `.toolbar` height | `height` | `--xpl-size-350` | 56px |
+| `.selected-item-count` text | `color` | `--xpl-text-inverse-on-dark` | white / white |
+| `.selected-item-count` divider | `border-color` | `--xpl-border-default` | neutral-600 (always-dark host) |
+| `.selected-item-count` label | `font-size` / `font-weight` / `line-height` | `@extend .xpl-text-title-5` (14px, medium, 1.4286) | — |
+
+> **Design note:** the always-dark surface decision is confirmed (there is no
+> toolbar node in `figma-manifest.json`). Foundation defines no shadow tokens, so the
+> elevation uses the neutral transparent primitives. See `TECH_DEBT.md`.
 
 <!-- Auto Generated Below -->
 

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

@@ -1,6 +1,6 @@
 # xpl-top-nav
 
-Top navigation shell for brand, primary navigation, right-side actions, and an optional account menu.
+Top navigation shell for navigating between Xplor applications and account controls — brand, cross-app navigation, right-side actions, and an optional account menu. In Xplor's primary use case it switches between Xplor products within one account, while the side navigation handles primary navigation within a single app.
 
 ## Usage
 
@@ -103,6 +103,7 @@ Horizontal top navigation with **`left-aside`** and a **right rail**: **`right-a
 Optional **`nav-control`** and **`navOpen`**. **`left-aside`** uses **`role="list"`** for primary **`xpl-top-nav-item`** rows (**`role="listitem"`** on each item host). The built-in **`xpl-top-nav__brand`** item omits **`listitem`** (it is not a child of that list). **`label`** maps to **`nav`** **`aria-label`**. Opening state is internal (not a prop) — use **`navOpen`** and host **`xpl-top-nav--open`** for styling.
 
 **Escape:** With **`nav-control`**, **Escape** closes the mobile drawer and emits **`navOpen`** **`false`** (skips while **any** descendant **`xpl-popover`** is open — detected from each popover’s inner **`.xpl-popover--is-open`** marker — or when a **`xpl-top-nav-item`** dropdown is open — capture/bubble order). Focus returns to the nav toggle after the drawer closes (**Escape** or second toggle click).
+**Outside click:** With **`nav-control`**, a click outside the drawer panel (**`.xpl-top-nav__left-primary`**) also closes it and emits **`navOpen`** **`false`** (document **capture**, mirroring **`xpl-top-nav-item`**); it skips clicks on the hamburger toggle and while a descendant **`xpl-popover`** is open, and does not move focus.
 **`xpl-top-nav-item`** **`slot="dropdown"`** uses document **capture** for **Escape** first; the shell uses **bubble**
 on **`ownerDocument`** so nested dropdowns close before the drawer.
 

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

@@ -114,11 +114,11 @@ Type: `Promise<void>`
 
 ## Slots
 
-| Slot              | Description                                                                                                                                                                                                         |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `"dropdown"`      | Panel content (e.g. `<xpl-top-nav-menu>`). Presence of this slot makes the row a disclosure trigger.                                                                                                                |
-| `"leading-icon"`  | Illustrative icon before the label. Overrides the **`icon`** prop when present.                                                                                                                                     |
-| `"trailing-icon"` | Functional icon after the label (e.g. **`external-link`** for "opens in new window"). When **`slot="dropdown"`** is present and no **`trailing-icon`** content is slotted, an auto **`chevron-down`** renders here. |
+| Slot              | Description                                                                                                                                                                                                                                                                                              |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `"dropdown"`      | Panel content (e.g. `<xpl-top-nav-menu>`). Presence of this slot makes the row a disclosure trigger.                                                                                                                                                                                                     |
+| `"leading-icon"`  | Illustrative icon before the label. Overrides the **`icon`** prop when present.                                                                                                                                                                                                                          |
+| `"trailing-icon"` | Functional icon after the label (e.g. **`external-link`** for "opens in new window"). When **`slot="dropdown"`** is present and no **`trailing-icon`** content is slotted, an auto chevron renders here: **`chevron-down`** on the desktop flyout, **`chevron-right`** on the mobile cascade (drill-in). |
 
 
 ## Dependencies

package/dist/docs/xpl-utility-bar/readme.md

@@ -19,6 +19,18 @@ To add content to the slots, just create a `<ul>` tag and target the desired slo
 
 `<ul slot="aside">...</ul>`
 
+## Design Tokens
+
+The utility bar uses Apollo Foundation purpose-specific tokens, which theme automatically in light and dark mode (no `.dark` overrides).
+
+| Element | Property | Token |
+| --- | --- | --- |
+| `.xpl-utility-bar` | `background-color` | `--xpl-background-surface-default` |
+| `.xpl-utility-bar` | `color` (muted text) | `--xpl-text-subdued` |
+| `.xpl-utility-nav__bars` | `color` (nav-control icon) | `--xpl-icon-default` |
+| `.xpl-utility-nav__bars` | `height` | `--xpl-size-100` |
+| `.xpl-utility-bar__nav-control` `:focus-visible` | `outline-color` | `--xpl-border-focus` |
+
 <!-- Auto Generated Below -->