@xplortech/apollo-core 2.10.0 → 2.12.0

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
 
@@ -51,6 +51,9 @@ Use the same tags in any HTML page that loads Apollo styles and the component bu
 - On **narrow viewports**, **`slot="right-aside"`** is hidden in the bar. Duplicate those actions into **`xpl-nav-header-menu`** **`slot="right-aside-mobile"`** (narrow-only strip below profile, above the list) so they stay reachable from the account menu.
 - On **`xpl-top-nav-item`**, use **`selected`** for the current page (**`aria-current="page"`**) and optional **`active`** for extra accent styling; see the item readme for modifier details.
 - **`slot="dropdown"`** does not implement arrow-key roving focus; put focusable elements inside the panel or treat full “menu” keyboard behavior as a future enhancement.
+- **Grouping nav items:** put an **`xpl-top-nav-menu`** in a parent **`xpl-top-nav-item`**'s **`slot="dropdown"`** to render a desktop flyout of **`xpl-top-nav-item`** rows (e.g. grouping by product). The same markup also drives the **mobile cascade** below — see **`xpl-top-nav-menu`**'s readme for the full interaction model (back row, focus management, Escape / drawer-close lifecycle).
+- **Mobile cascade:** below **`md`**, tapping a **`left-aside`** parent that has a menu swaps the drawer's Level 1 list for that group's Level 2 rows **in place** (no second panel) — the group's **`xpl-top-nav-menu`** auto-renders a back row (leading `chevron-left` + its `label`) as the first row. Tapping the back row, or pressing **Escape** once, pops back to Level 1; a second **Escape**, or the hamburger toggle, closes the drawer (and resets any still-drilled-in group so the drawer reopens at Level 1). Cascade depth is capped at 2 levels and is mobile-only — the desktop flyout is always a single level of links.
+- **Child-location context on small screens:** for a "Change Account" style row (a plain **`xpl-top-nav-item`** you author in **`slot="user-menu"`**), set **`description`** to the current child-location's name so it reads e.g. "Change Account" / "Acme Corp — Downtown Location" on narrow viewports where that context isn't otherwise visible in the bar. This is a content pattern (see the **`TopNavigation`** story), not a separate framework feature — **`description`** already exists on **`xpl-top-nav-item`**.
 
 ## Theming
 
@@ -100,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

@@ -2,10 +2,14 @@
 
 ## Behavior
 
-- **Plain item:** **`label`** / **`icon`**, default slot, or **`href`** link. Fires **`navItemClick`** (**`detail`**: **`MouseEvent`**) on click and **Enter** / **Space** (keyboard uses a synthetic **`click`** on the trigger).
-- **Dropdown:** Put content in **`slot="dropdown"`** (e.g. `<ul slot="dropdown">`). Shows a chevron and toggles **`.xpl-top-nav-item__dropdown`** in the host light DOM — **not** **`xpl-dropdown`** / **`xpl-popover`**; use those for standalone floating menus (e.g. account in top-nav stories). **`navItemClick`** is not emitted. See **`TECH_DEBT.md`** for tradeoffs.
+- **Plain item:** **`label`** / **`icon`** (or **`slot="leading-icon"`**), default slot, or **`href`** link. Renders a native **`<button type="button">`** (or **`<a href>`** in link mode) and fires **`navItemClick`** (**`detail`**: **`MouseEvent`**) on click and **Enter** / **Space** — the native button handles keyboard activation, and link-mode **Space** maps to a programmatic **`.click()`**.
+- **Dropdown trigger:** Put content in **`slot="dropdown"`** (e.g. `<xpl-top-nav-menu>`). Shows an auto **`chevron-down`** (unless **`slot="trailing-icon"`** is provided) and toggles **`.xpl-top-nav-item__dropdown`** in the host light DOM — **not** **`xpl-dropdown`** / **`xpl-popover`**; use those for standalone floating menus (e.g. account in top-nav stories). **`navItemClick`** is not emitted. See **`TECH_DEBT.md`** for tradeoffs.
+- **Disclosure ARIA:** A dropdown trigger's inner control carries **`aria-expanded`** (open state), **`aria-haspopup="true"`**, and **`aria-controls`** pointing at the **`.xpl-top-nav-item__dropdown`** panel's generated id. Plain items omit all three. **`aria-haspopup`** is the generic **`true`** (disclosure), not **`menu`** — the panel (**`xpl-top-nav-menu`**) is a **`role="list"`** of link rows navigated by **Tab**, not an ARIA menu with arrow-key roving.
+- **Menu row:** The same component reused inside **`xpl-nav-header-menu`** / **`xpl-top-nav-menu`** — add **`description`** for a two-line row, and **`slot="trailing-icon"`** for a functional icon (e.g. `external-link` for "opens in new window").
+- **Open API:** **`open`** (controlled/uncontrolled, reflected) + **`openChange`** event + **`openMenu()`** / **`closeMenu()`** / **`toggleMenu()`** methods — all equivalent ways to drive the dropdown panel.
+- **`openMode`:** **`click`** (default) or **`hover`** — hover only activates on hover-capable, fine-pointer, **`md`**-and-up devices; keyboard (Enter/Space) always toggles regardless.
 - **One open dropdown:** Outside click uses **`ownerDocument`** capture; siblings close via internal **`CustomEvent`** (reliable with JSDOM / **`stopPropagation`**).
-- **Escape:** Document **capture** **`keydown`** — **`preventDefault`** / **`stopPropagation`** so parent shells (**`xpl-top-nav`** mobile drawer, **`xpl-popover`**, modal) do not also react on the same keypress. **`xpl-top-nav`** closes its drawer on **Escape** in **bubble** phase, after this handler runs.
+- **Escape:** Document **capture** **`keydown`** — **`preventDefault`** / **`stopPropagation`** so parent shells (**`xpl-top-nav`** mobile drawer, **`xpl-popover`**, modal) do not also react on the same keypress, then returns focus to the trigger control. **`xpl-top-nav`** closes its drawer on **Escape** in **bubble** phase, after this handler runs.
 
 ## Host modifier classes (BEM)
 
@@ -13,25 +17,28 @@
 | --- | --- |
 | **`xpl-top-nav-item--selected`** | **`selected`** prop |
 | **`xpl-top-nav-item--has-dropdown`** | **`slot="dropdown"`** content present |
-| **`xpl-top-nav-item--dropdown-open`** | Dropdown panel is open |
+| **`xpl-top-nav-item--dropdown-open`** | Dropdown panel is open (**`open`** prop) |
 | **`xpl-top-nav-item--active`** | **`active`** prop (or add the class on the host for edge cases) |
+| **`xpl-top-nav-item--has-active-descendant`** | A descendant row inside **`slot="dropdown"`** is **`active`** / **`selected`** — accents the trigger like **`--active`**. Synced at connect / load / this item's own re-renders, not via a live descendant-class observer (see the JSDoc on **`hasActiveDescendant`** for why). |
 
 ## Slots
 
 | Slot | Description |
 | --- | --- |
 | (default) | Custom trigger when **`label`** is omitted. |
-| `dropdown` | Panel content (e.g. `<ul slot="dropdown">…</ul>`). |
+| `leading-icon` | Illustrative icon before the label. Overrides the **`icon`** prop when present. |
+| `trailing-icon` | Functional icon after the label. Overrides the auto **`chevron-down`** on a dropdown trigger. |
+| `dropdown` | Panel content (e.g. `<xpl-top-nav-menu>…</xpl-top-nav-menu>`). |
 
 <!-- Auto Generated Below -->
 
 
 ## Overview
 
-Single nav row for **`xpl-top-nav`** / **`xpl-nav-header-menu`**. The host uses **`role="listitem"`** when the row
-participates in a list: a **`role="list"`** parent, **`slot="left-aside"`** on **`xpl-top-nav`** (list host is
-**`.xpl-top-nav__left-primary`** while slotted nodes stay light-DOM children of **`xpl-top-nav`**), or default-slot rows
-under **`xpl-nav-header-menu`**. That flag is
+Single nav row for **`xpl-top-nav`** / **`xpl-nav-header-menu`** / **`xpl-top-nav-menu`**. The host uses
+**`role="listitem"`** when the row participates in a list: a **`role="list"`** parent, **`slot="left-aside"`** on
+**`xpl-top-nav`** (list host is **`.xpl-top-nav__left-primary`** while slotted nodes stay light-DOM children of
+**`xpl-top-nav`**), or default-slot rows under **`xpl-nav-header-menu`** / **`xpl-top-nav-menu`**. That flag is
 kept in **`@State`** and refreshed after render plus via **`MutationObserver`** on the host (**`class`**, **`slot`**) and
 on **`parentElement`** (**`role`**) or on **`.xpl-top-nav__left-primary`** (**`role`**) for **`slot="left-aside"`** under **`xpl-top-nav`**) so DOM context changes
 without a full reconnect still re-sync. The internal
@@ -39,6 +46,10 @@ without a full reconnect still re-sync. The internal
 as do **`slot="right-aside-mobile"`** rows (not a list). **`slot="dropdown"`** uses a local **`.xpl-top-nav-item__dropdown`**
 panel (not **`xpl-dropdown`**); see **`TECH_DEBT.md`**.
 
+**This component does triple duty:** a plain bar item, a dropdown trigger (**`slot="dropdown"`** present), and a
+dropdown/menu **row** (nested inside **`xpl-nav-header-menu`** or **`xpl-top-nav-menu`**). The **`description`** prop
+only applies in the row context — bar items and triggers do not show it in Figma.
+
 **Default slot (no `label`):** do not put **`xpl-top-nav-item__inner`** or other **`xpl-top-nav-item__*`** classes on
 custom trigger content — the component renders the inner wrapper and BEM elements.
 
@@ -47,21 +58,67 @@ values even when the page root is light (consistent with **`xpl-top-nav`**).
 
 ## Properties
 
-| Property        | Attribute         | Description                                                                                                                                                                                                                                                                                                                               | Type      | Default     |
-| --------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------- |
-| `active`        | `active`          | When true, adds **`xpl-top-nav-item--active`** for persistent accent styling (e.g. link color on the bar, or chrome inside **`xpl-nav-header-menu`**). Separate from **`selected`**, which sets **`aria-current="page"`** and **`--selected`**. Use both when the design needs “current page” semantics plus the active visual treatment. | `boolean` | `false`     |
-| `href`          | `href`            | If set without **`slot="dropdown"`**, the inner control renders as a native **`<a href>`** (link mode).                                                                                                                                                                                                                                   | `string`  | `undefined` |
-| `icon`          | `icon`            | Icon name from **`@xplortech/apollo-icons`** (shown before the label when **`label`** is set).                                                                                                                                                                                                                                            | `string`  | `''`        |
-| `itemAriaLabel` | `item-aria-label` | Accessible name for the inner control when there is no **`label`** and no default-slot text (e.g. icon-only). If omitted in that case, **`aria-label`** defaults to **`Navigation item`**. Ignored when **`label`** or default-slot content supplies a visible name.                                                                      | `string`  | `undefined` |
-| `label`         | `label`           | Text label. If omitted, use the default slot for custom trigger content. Long labels use **`text-ellipsis`** on **`.xpl-top-nav-item__label`** (see `top-nav.css`); **`title`** is set to the full string for hover tooltips when the visual line clips.                                                                                  | `string`  | `undefined` |
-| `selected`      | `selected`        | When true, sets **`aria-current="page"`** and selected styling.                                                                                                                                                                                                                                                                           | `boolean` | `false`     |
+| Property        | Attribute         | Description                                                                                                                                                                                                                                                                                                                               | Type                 | Default     |
+| --------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ----------- |
+| `active`        | `active`          | When true, adds **`xpl-top-nav-item--active`** for persistent accent styling (e.g. link color on the bar, or chrome inside **`xpl-nav-header-menu`**). Separate from **`selected`**, which sets **`aria-current="page"`** and **`--selected`**. Use both when the design needs “current page” semantics plus the active visual treatment. | `boolean`            | `false`     |
+| `description`   | `description`     | Optional description line shown below **`label`** (row context only, e.g. inside **`xpl-nav-header-menu`** / **`xpl-top-nav-menu`**). Ignored when **`label`** is not set.                                                                                                                                                                | `string`             | `undefined` |
+| `href`          | `href`            | If set without **`slot="dropdown"`**, the inner control renders as a native **`<a href>`** (link mode).                                                                                                                                                                                                                                   | `string`             | `undefined` |
+| `icon`          | `icon`            | Icon name from **`@xplortech/apollo-icons`** (shown before the label when **`label`** is set). Ignored when **`slot="leading-icon"`** content is present.                                                                                                                                                                                 | `string`             | `''`        |
+| `itemAriaLabel` | `item-aria-label` | Accessible name for the inner control when there is no **`label`** and no default-slot text (e.g. icon-only). If omitted in that case, **`aria-label`** defaults to **`Navigation item`**. Ignored when **`label`** or default-slot content supplies a visible name.                                                                      | `string`             | `undefined` |
+| `label`         | `label`           | Text label. If omitted, use the default slot for custom trigger content. Long labels use **`text-ellipsis`** on **`.xpl-top-nav-item__label`** (see `top-nav.css`); **`title`** is set to the full string for hover tooltips when the visual line clips.                                                                                  | `string`             | `undefined` |
+| `open`          | `open`            | Whether the **`slot="dropdown"`** panel is open. Reflected to the **`open`** attribute so consumers can drive it (controlled) or read it back (uncontrolled, toggled internally on click / hover / keyboard activation). Prefer **`openMenu()`** / **`closeMenu()`** / **`toggleMenu()`** over setting this directly from event handlers. | `boolean`            | `false`     |
+| `openMode`      | `open-mode`       | How the **`slot="dropdown"`** panel opens. **`hover`** is gated on **`TOP_NAV_ITEM_HOVER_OPEN_MQ`** (hover-capable, fine pointer, **`md`** and up) — below that, or on touch / coarse-pointer devices, **`hover`** falls back to click/tap. Keyboard activation (Enter / Space) always toggles regardless of **`openMode`**.              | `"click" \| "hover"` | `'click'`   |
+| `selected`      | `selected`        | When true, sets **`aria-current="page"`** and selected styling.                                                                                                                                                                                                                                                                           | `boolean`            | `false`     |
 
 
 ## Events
 
-| Event          | Description                                                                                                                                                                                                                                                                                                                                                                                            | Type                      |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |
-| `navItemClick` | Emitted for plain items (button or link) on pointer **click**, or when keyboard activation produces a **`click`** (native for **Enter** on **`<a href>`**, or programmatic **`.click()`** for **Space** on links). **`detail`** is the **`MouseEvent`** from that activation (synthetic only for **`<div role="button">`** via **Enter** / **Space**). Not emitted when **`slot="dropdown"`** is used. | `CustomEvent<MouseEvent>` |
+| Event          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Type                      |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
+| `navItemClick` | Emitted for plain items (button or link) on pointer **click**, or when keyboard activation produces a **`click`**: the native **`<button>`** fires a real **`click`** on **Enter** / **Space**, a native **`<a href>`** on **Enter**, and **Space** on a link maps to a programmatic **`.click()`**. **`detail`** is always the real **`MouseEvent`** from that activation (keyboard-driven clicks have **`detail === 0`**). Not emitted when **`slot="dropdown"`** is used. | `CustomEvent<MouseEvent>` |
+| `openChange`   | Emitted whenever **`open`** changes (click, hover, keyboard, Escape, outside click, or programmatic).                                                                                                                                                                                                                                                                                                                                                                        | `CustomEvent<boolean>`    |
+
+
+## Methods
+
+### `closeMenu() => Promise<void>`
+
+No-op when there is no **`slot="dropdown"`** panel to open.
+
+#### Returns
+
+Type: `Promise<void>`
+
+
+
+### `openMenu() => Promise<void>`
+
+No-op when there is no **`slot="dropdown"`** panel to open.
+
+#### Returns
+
+Type: `Promise<void>`
+
+
+
+### `toggleMenu() => Promise<void>`
+
+No-op when there is no **`slot="dropdown"`** panel to open.
+
+#### Returns
+
+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 renders here: **`chevron-down`** on the desktop flyout, **`chevron-right`** on the mobile cascade (drill-in). |
 
 
 ## Dependencies
@@ -69,6 +126,7 @@ values even when the page root is light (consistent with **`xpl-top-nav`**).
 ### Used by
 
  - [xpl-top-nav](..)
+ - [xpl-top-nav-menu](../xpl-top-nav-menu)
 
 ### Depends on
 
@@ -79,6 +137,7 @@ values even when the page root is light (consistent with **`xpl-top-nav`**).
 graph TD;
   xpl-top-nav-item --> xpl-icon
   xpl-top-nav --> xpl-top-nav-item
+  xpl-top-nav-menu --> xpl-top-nav-item
   style xpl-top-nav-item fill:#f9f,stroke:#333,stroke-width:4px
 ```
 

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

@@ -0,0 +1,96 @@
+# xpl-top-nav-menu
+
+## Behavior
+
+- **Thin grouping container only.** No item logic lives here — put **`xpl-top-nav-item`** rows in the default slot. This component owns list semantics (**`role="list"`**) and shared panel chrome (width, surface, shadow, radius, padding), nothing else.
+- **One authoring markup, two renderings:** the same **`<xpl-top-nav-menu>`** renders as the **desktop flyout** (nested in a parent **`xpl-top-nav-item`**'s **`slot="dropdown"`** — the panel opens absolutely-positioned under the trigger) and, below the **`md`** breakpoint, drives the **mobile cascade**: the parent's dropdown content swaps in **in place** of the top-level nav list (no second panel), with an auto **back row** as the first row.
+- **`label`** is the accessible name for the list (**`aria-label`**) and, on mobile, the text shown in the auto-rendered back row (leading **`chevron-left`**) when drilling back out of this group. Tapping the back row calls **`closeMenu()`** on the parent trigger (pop to Level 1) and restores focus to it.
+- The back row only renders below **`md`** (synced from a **`matchMedia`** listener) — desktop never sees it, since the flyout there is a single level of links.
+- **Cascade lifecycle** (owned by **`xpl-top-nav`**, the shell): pressing **Escape** while drilled in pops the cascade before it closes the mobile drawer (two separate presses); closing the drawer via the hamburger toggle while still drilled in resets the group closed so the drawer reopens at Level 1 next time.
+
+## Usage
+
+```html
+<xpl-top-nav-item slot="left-aside" label="Xplor Ops" open-mode="hover">
+  <xpl-top-nav-menu slot="dropdown" label="Xplor Ops">
+    <xpl-top-nav-item label="Payroll" href="/payroll"></xpl-top-nav-item>
+    <xpl-top-nav-item label="Capital" href="/capital">
+      <xpl-icon slot="trailing-icon" icon="open-rect-arrow-out"></xpl-icon>
+    </xpl-top-nav-item>
+  </xpl-top-nav-menu>
+</xpl-top-nav-item>
+```
+
+## Host modifier classes (BEM)
+
+None on the host itself. Row-level state (`active`, `selected`, description, icons) lives entirely on the slotted `xpl-top-nav-item` rows.
+
+| Class | Source |
+| --- | --- |
+| `.xpl-top-nav-menu__back` | Auto-rendered on the back-row `xpl-top-nav-item` (mobile only, `label` set). Not a hook to restyle — it uses the same row treatment as any other `xpl-top-nav-item` in this list. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | `xpl-top-nav-item` rows. |
+
+<!-- Auto Generated Below -->
+
+
+## Overview
+
+Thin grouping container for **`xpl-top-nav-item`** rows — the panel content for a desktop flyout
+(**`slot="dropdown"`** on the parent **`xpl-top-nav-item`**) and, on small screens, the **mobile
+cascade**: the same markup drills in to a **Level 2** view in place, with an auto-rendered **back
+row** (leading **`chevron-left`** + this component's **`label`**) as the first row. Tapping the back
+row closes the parent trigger's dropdown (**`closeMenu()`**), returning to **Level 1** and restoring
+focus to the parent trigger. No item logic otherwise lives here — row behavior (icons, description,
+links, nested dropdowns) is entirely **`xpl-top-nav-item`**.
+
+**One authoring markup, two renderings:** consumers write this once; **`isMobileCascade`** (synced
+from **`TOP_NAV_MOBILE_MQ`**) decides whether the back row renders. Desktop never sees it — the
+flyout is a single level of links (see `xpl-top-nav-item`'s cascade-depth notes).
+
+**Panel chrome** is shared with **`xpl-nav-header-menu`** (the account menu): width
+(**`--xpl-top-nav-panel-width`**), surface, shadow, radius, and vertical padding all come from the
+same selector in `top-nav.css` so the desktop flyout, mobile cascade, and account menu read as one
+visual family.
+
+**Theming:** The host always includes Foundation’s **`dark`** class so **`--xpl-*`** purpose tokens
+resolve to dark-mode values even when the page root is light (consistent with the rest of the
+**`xpl-top-nav`** family).
+
+## Properties
+
+| Property | Attribute | Description                                                                                                                                          | Type     | Default     |
+| -------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------- |
+| `label`  | `label`   | Accessible name for the list (**`aria-label`** on the host) and the label shown in the mobile cascade back row when drilling back out of this group. | `string` | `undefined` |
+
+
+## Slots
+
+| Slot          | Description                  |
+| ------------- | ---------------------------- |
+| `"(default)"` | **`xpl-top-nav-item`** rows. |
+
+
+## Dependencies
+
+### Depends on
+
+- [xpl-top-nav-item](../xpl-top-nav-item)
+- [xpl-icon](../../xpl-icon)
+
+### Graph
+```mermaid
+graph TD;
+  xpl-top-nav-menu --> xpl-top-nav-item
+  xpl-top-nav-menu --> xpl-icon
+  xpl-top-nav-item --> xpl-icon
+  style xpl-top-nav-menu fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

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 -->