@xplortech/apollo-core 2.8.1 → 2.10.0

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

@@ -162,6 +162,7 @@ The **`state`** prop (`neutral` | `warning` | `success`) is deprecated. Use **`s
  - [xpl-button-row](../xpl-button-row)
  - [xpl-list-item](../xpl-list/xpl-list-item)
  - [xpl-modal](../xpl-modal)
+ - [xpl-side-nav](../xpl-side-nav)
  - [xpl-slideout](../xpl-slideout)
  - [xpl-spotlight](../xpl-spotlight)
  - [xpl-tab](../xpl-tab)
@@ -179,6 +180,7 @@ graph TD;
   xpl-button-row --> xpl-button
   xpl-list-item --> xpl-button
   xpl-modal --> xpl-button
+  xpl-side-nav --> xpl-button
   xpl-slideout --> xpl-button
   xpl-spotlight --> xpl-button
   xpl-tab --> xpl-button

package/dist/docs/xpl-button-row/readme.md

@@ -2,6 +2,19 @@
 
 
 
+### Design Tokens
+
+Tokens used by this component from `@xplortech/apollo-foundation`.
+
+**Color**
+- `--xpl-border-default` — top border color
+
+**Spacing**
+- `--xpl-space-{0,16,24}` — padding / margins
+
+**Border**
+- `--xpl-border-small` — top border width (1px)
+
 <!-- Auto Generated Below -->
 
 

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

@@ -4,6 +4,26 @@ Checkboxes allow users to make selections or choices. Checkboxes can be multi-se
 
 Provide visible label text in the default slot, or set `aria-label` when the checkbox has no adjacent label (for example, icon-only toolbars or table selection cells).
 
+## Design Tokens
+
+The checkbox component uses the following Apollo Foundation tokens:
+
+| Token | Usage |
+|-------|-------|
+| `--xpl-background-surface-default` | Default checkbox background; styled label background (resting/hover/focused) |
+| `--xpl-background-action-primary-default` | Checked/indeterminate state background and border |
+| `--xpl-background-action-disabled` | Disabled state background; disabled label background (styled variant) |
+| `--xpl-background-surface-information` | Checked/indeterminate label background (styled variant) |
+| `--xpl-text-inverse` | Checkmark and indeterminate icon color (checked / indeterminate states; inverse foreground on primary fill) |
+| `--xpl-icon-disabled` | Checkmark and indeterminate icon color (disabled state) |
+| `--xpl-border-strong` | Resting (unchecked) border color |
+| `--xpl-border-hover` | Hover, checked, and indeterminate border color; styled container hover/focus border |
+| `--xpl-border-default` | Styled container border; disabled state border |
+| `--xpl-border-focus` | Focus visible outline |
+| `--xpl-border-radius-small` | Checkbox corner radius and styled container corner radius (4px) |
+| `--xpl-border-small` | Border width (1px) |
+| `--xpl-size-100` | Checkbox dimensions (16px) |
+
 <!-- Auto Generated Below -->
 
 
@@ -20,7 +40,7 @@ Provide visible label text in the default slot, or set `aria-label` when the che
 | `name`          | `name`          | The name attribute for the html input. (submitted in form as name/value pair)                                                                                                                                                                                                        | `string`  | `undefined` |
 | `required`      | `required`      | Whether the input is required                                                                                                                                                                                                                                                        | `boolean` | `undefined` |
 | `styled`        | `styled`        | Whether the input is contained in a box with a border and a background                                                                                                                                                                                                               | `boolean` | `undefined` |
-| `value`         | `value`         | The value attribute for the checkbox input. (submittted in form as name/value pair)                                                                                                                                                                                                  | `string`  | `undefined` |
+| `value`         | `value`         | The value attribute for the checkbox input. (submitted in form as name/value pair)                                                                                                                                                                                                   | `string`  | `undefined` |
 
 
 ## Events
@@ -36,6 +56,7 @@ Provide visible label text in the default slot, or set `aria-label` when the che
 
  - [xpl-choicelist](../xpl-choicelist)
  - [xpl-header-accordion](../xpl-header-accordion)
+ - [xpl-table](../xpl-table)
  - [xpl-table-header-cell](../xpl-table-header-cell)
 
 ### Graph
@@ -43,6 +64,7 @@ Provide visible label text in the default slot, or set `aria-label` when the che
 graph TD;
   xpl-choicelist --> xpl-checkbox
   xpl-header-accordion --> xpl-checkbox
+  xpl-table --> xpl-checkbox
   xpl-table-header-cell --> xpl-checkbox
   style xpl-checkbox fill:#f9f,stroke:#333,stroke-width:4px
 ```

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

@@ -1,7 +1,25 @@
-# xpl-divider
-
-Allows for easy separation and titling of sections within forms or other content.
-
+# xpl-divider
+
+Allows for easy separation and titling of sections within forms or other content.
+
+### Design Tokens
+
+Tokens used by this component from `@xplortech/apollo-foundation`.
+
+**Color**
+- `--xpl-border-default` — divider line color
+- `--xpl-text-default` — label text color
+
+**Spacing**
+- `--xpl-space-{0,4,16}` — padding / margin
+
+**Typography**
+- `--xpl-font-size-body` — base label font size
+- Tier typography extends the shared type scale from `typography.css`: tier 3 → `.xpl-text-title-3`, tier 2 → `.xpl-text-title-4`, tier 1 → `.xpl-text-title-5`
+
+**Border**
+- `--xpl-border-small` — line width (1px)
+
 <!-- Auto Generated Below -->
 
 

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

@@ -4,6 +4,57 @@ A flexible form input that supports multiple `type` values: `text`, `number`, `p
 
 For `type="phone"`, the value is always emitted in **E.164** format (e.g. `+14155551234`). See [`xpl-input-phone`](xpl-input-phone) for full phone-input documentation.
 
+## Design Tokens
+
+The `xpl-input` component uses Apollo Foundation tokens for consistent theming across light and dark modes:
+
+| Element | Property | Token |
+|---------|----------|-------|
+| Input wrapper border (default) | `border-color` | `var(--xpl-border-default)` |
+| Input wrapper border (focus) | `border-color` | `var(--xpl-border-focus)` |
+| Input wrapper border (error) | `border-color` | `var(--xpl-border-negative)` |
+| Input wrapper background (default) | `background-color` | `var(--xpl-background-surface-default)` |
+| Input/textarea background | `background-color` | `var(--xpl-background-surface-transparent-0)` |
+| Disabled/readonly wrapper background | `background-color` | `var(--xpl-background-action-disabled)` |
+| Post element background | `background-color` | `var(--xpl-background-surface-subtle)` |
+| Input text | `color` | `var(--xpl-text-default)` |
+| Disabled/readonly text | `color` | `var(--xpl-text-disabled)` |
+| Label text | `color` | `var(--xpl-text-strong)` |
+| Description text | `color` | `var(--xpl-text-subdued)` |
+| Error text | `color` | `var(--xpl-text-negative)` |
+| Character counter background (default) | `background-color` | `var(--xpl-background-surface-default)` |
+| Character counter background (disabled/readonly) | `background-color` | `var(--xpl-background-action-disabled)` |
+| Character counter text | `color` | `var(--xpl-text-subdued)` |
+| Calendar/password icon | `color` | `var(--xpl-icon-default)` |
+
+### Spacing Tokens
+
+| Element | Property | Token |
+|---------|----------|-------|
+| Input | `padding-right` | `var(--xpl-space-8)` |
+| Textarea | `padding-top` | `var(--xpl-space-12)` |
+| Textarea | `padding-bottom` | `var(--xpl-space-8)` |
+| Wrapper | `padding-left` | `var(--xpl-space-12)` |
+| Pre element (leading icon/text) | `padding-right` | `var(--xpl-space-8)` |
+| Post element (trailing unit / AM-PM) | `padding-left`, `padding-right` | `var(--xpl-space-12)` |
+| Label | `padding-bottom` | `var(--xpl-space-4)` |
+| Character counter | `padding` | `var(--xpl-space-8) var(--xpl-space-12)` |
+| Error message | `padding`, `gap` | `var(--xpl-space-4)` |
+| Calendar icon | `right` | `var(--xpl-space-12)` |
+| Password button | `padding-left`, `padding-right` | `var(--xpl-space-12)` |
+
+### Dimension Tokens
+
+| Element | Property | Token |
+|---------|----------|-------|
+| Input | `height` | `var(--xpl-size-250)` (40px; matches Figma `form/height`) |
+| Textarea | `min-height` | `var(--xpl-size-250)` (40px) |
+| Textarea | `height` | `var(--xpl-size-700)` (112px; rounded up from 98px) |
+| Wrapper | `border-width` | `var(--xpl-border-small)` |
+| Wrapper | `border-radius` | `var(--xpl-border-radius-small)` (4px; matches Figma `border/radius/small`) |
+| Post element | `height` | `var(--xpl-size-250)` (40px; vertically centered via flex) |
+| Post element | `border-left-width` | `var(--xpl-border-small)` |
+
 ### Delegated types (`search`, `phone`, `date`, `time`, …)
 
 `valueChange`, `inputEvent`, `focusEvent`, and `blurEvent` are emitted by the inner component and **bubble** to `<xpl-input>`. For **`type="search"`**, **`focusEvent`** and **`blurEvent`** are **re-emitted from `<xpl-input>`** (parent uses **`onFocusEvent`** / **`onBlurEvent`** on **`<xpl-input-search>`** with **`stopPropagation`**) so **`event.target`** matches **`type="text"`**. For **`valueChange`** and **`inputEvent`** on search, events still **bubble** from **`xpl-input-search`** without parent re-emission; **`event.target`** may be the inner host—prefer **`event.detail`** (the string) or **`event.currentTarget`** when you attach the listener on **`<xpl-input>`**. Other delegated types follow the same **`event.detail`** / **`event.currentTarget`** guidance.

package/dist/docs/xpl-input/xpl-input-date/readme.md

@@ -2,6 +2,13 @@
 
 
 
+### Design Tokens
+
+Tokens used by this component from `@xplortech/apollo-foundation`.
+
+**Color**
+- `--xpl-border-negative` — error state border color
+
 <!-- Auto Generated Below -->
 
 

package/dist/docs/xpl-input/xpl-input-phone/readme.md

@@ -99,6 +99,26 @@ Countries with custom formatters: US/CA, GB, AU, DE/AT/CH, FR, BR, MX, JP, CN, I
 
 28 countries are currently supported. See `phone-country-data.ts` for the full list. Countries with custom number formatting are noted above. To add a new country, add an entry to the `PHONE_COUNTRIES` array and optionally add a formatter in `phone-format.ts`.
 
+### Design Tokens
+
+Tokens used by this component from `@xplortech/apollo-foundation`.
+
+**Color**
+- `--xpl-background-surface-subtlest` — trigger background
+- `--xpl-background-surface-information` — trigger hover / open background
+- `--xpl-border-negative` — error state border
+- `--xpl-border-focus` — wrapper and trigger focus outline
+- `--xpl-border-default` — trigger divider, search border
+- `--xpl-text-default` — trigger text, dial code
+- `--xpl-text-subdued` — clear button color
+- `--xpl-icon-default` — search icon
+
+**Border**
+- `--xpl-border-small` — trigger divider width (1px)
+
+**Focus**
+- `--xpl-border-focus` — `:focus-visible` outline (inset, 2px)
+
 <!-- Auto Generated Below -->
 
 
@@ -108,6 +128,7 @@ Countries with custom formatters: US/CA, GB, AU, DE/AT/CH, FR, BR, MX, JP, CN, I
 | -------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ----------- |
 | `defaultCountry`     | `default-country`  | Default country code (ISO 3166-1 alpha-2) when value is empty, e.g. "US".                                                                                                                                                      | `string`   | `'US'`      |
 | `disabled`           | `disabled`         | Whether the field is disabled                                                                                                                                                                                                  | `boolean`  | `undefined` |
+| `error`              | `error`            | Whether the field is in an error state. When true, the input renders with the error border styling. The error message itself is owned by the parent `xpl-input` wrapper.                                                       | `boolean`  | `undefined` |
 | `inputId`            | `input-id`         | The `inputId` is used to associate the input with a label.                                                                                                                                                                     | `string`   | `undefined` |
 | `isInternational`    | `is-international` | Enables international mode with a country selector and dial code prefix. When false, the input is locked to `defaultCountry` with no country picker and no dial code shown in the display value. Emitted value is still E.164. | `boolean`  | `true`      |
 | `name`               | `name`             | Most inputs are used in forms, and should have a `name` associated with the input for handling form data.                                                                                                                      | `string`   | `undefined` |

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

@@ -2,6 +2,30 @@
 
 A popover is an overlay that pops up over all other layers and is triggered by a click or tap, and dismissed by clicking outside the popover or a dismiss icon. Popovers can contain additional actions and allow those actions to be triggered.
 
+
+### Design Tokens
+
+Tokens used by this component from `@xplortech/apollo-foundation`.
+
+**Color**
+- `--xpl-background-surface-default` — content panel background and arrow fill
+- `--xpl-background-surface-transparent-10` — shadow primary layer
+- `--xpl-background-surface-transparent-5` — shadow secondary layer
+- `--xpl-text-default` — content text color
+- `--xpl-border-default` — content panel border and arrow stroke
+
+**Spacing**
+- `--xpl-space-8` — popover margin (offset from trigger), via `--xpl-popover-margin`
+- `--xpl-space-16` — content panel padding (Figma `padding/tight`; corrected from the legacy 24px during the Foundation migration — see `TECH_DEBT.md`)
+
+**Border**
+- `--xpl-border-small` — border width (1px)
+- `--xpl-border-radius-default` — content panel corner radius (8px)
+
+**Z-index**
+- `--xpl-z-index-100` — content panel stacking order
+- `--xpl-z-index-900` — arrow stacking order
+
 <!-- Auto Generated Below -->
 
 

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

@@ -1,7 +1,24 @@
-# xpl-radio
-
-Radio buttons allow users to make selections or choices. Radios are always single select, and can also act as controls.
-
+# xpl-radio
+
+Radio buttons allow users to make selections or choices. Radios are always single select, and can also act as controls.
+
+## Design Tokens
+
+The radio component uses the following Apollo Foundation tokens:
+
+| Token | Usage |
+|-------|-------|
+| `--xpl-background-surface-default` | Disabled checked state background; styled label background (resting/hover/focused) |
+| `--xpl-background-action-disabled` | Disabled state background; disabled label background (styled variant) |
+| `--xpl-background-surface-information` | Checked label background (styled variant) |
+| `--xpl-border-strong` | Resting (unchecked) border color |
+| `--xpl-border-hover` | Checked/hover/active border color; styled container hover/focus border |
+| `--xpl-border-default` | Disabled state border color |
+| `--xpl-border-focus` | Focus visible outline |
+| `--xpl-border-radius-small` | Styled container corner radius (4px) |
+| `--xpl-border-small` | Default border width (1px) |
+| `--xpl-size-100` | Radio dimensions (16px) |
+
 <!-- Auto Generated Below -->
 
 

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

@@ -27,7 +27,75 @@ Use the **`label`** prop for a unique accessible name on the `<nav>` when multip
 </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**.
+**Link rows:** use `xpl-side-nav-item` with `link` when the row needs to be a real `<a>` element (framework router components, right-click / open-in-new-tab, semantic link role). For typical in-app navigation, the default button mode is simpler. See [xpl-side-nav-item](./xpl-side-nav-item) **Link mode** for usage and styling guidance.
+
+## Mobile behavior
+
+Below the Tailwind `md` breakpoint (768px) the sidebar collapses to a ~56px top bar with a built-in toggle button (`sidebar-left-show` / `sidebar-left-hide`). Activating the toggle opens a drawer containing the `section` + `nav-footer` content over an [`xpl-backdrop`](../xpl-backdrop) scrim. Above `md` the toggle and backdrop are hidden and the sidebar renders inline — no markup changes are needed for either layout.
+
+**Keyboard / focus:**
+- **Escape** closes the drawer and returns focus to the toggle.
+- A **backdrop click** closes the drawer.
+- **Focus is trapped** inside the open drawer — Tab cycles only through the toggle and drawer rows.
+- The toggle exposes `aria-expanded` and a dynamic `aria-label` ("Open/Close navigation menu").
+
+**Row-level responsive scaling (applied automatically inside the drawer):**
+
+| Property | Desktop (≥ 768px) | Mobile (< 768px) |
+|---|---|---|
+| Tap target (`xpl-side-nav-item` wrapper) | — (inner button sized by content) | `min-height: 48px; padding: 6px 8px` |
+| Leading / trailing icon size | 16px | 24px |
+| Top-level label typography | `title-4` (16px, medium) | `title-3` (20px, medium) |
+| Child item label typography | `title-5` | `title-4` (16px, medium) |
+| Footer item label typography | `title-5` | `title-4` (16px, medium) |
+| Footer row min-height | `28px` | `--xpl-size-200` (32px) |
+| Footer leading / trailing icon | 16px | 20px |
+
+No markup or props are needed for these changes — they are driven entirely by CSS.
+
+### Open state API
+
+The `open` prop, `openChange` event, and `toggle()` / `setOpen()` methods control and observe the drawer. The component works **uncontrolled** (the built-in toggle flips `open`) or **controlled** (the consumer owns `open`).
+
+**Uncontrolled** — the built-in toggle manages everything; listen to `openChange` if you need to react:
+
+```html
+<xpl-side-nav label="Main navigation" id="nav">
+    <div slot="section">…</div>
+    <div slot="nav-footer">…</div>
+</xpl-side-nav>
+<script>
+    document.getElementById('nav').addEventListener('openChange', (e) => {
+        console.log('drawer open:', e.detail);
+    });
+</script>
+```
+
+**Controlled** — own `open` and update it from `openChange` (and/or the imperative methods):
+
+```html
+<xpl-side-nav label="Main navigation" id="nav" open>…</xpl-side-nav>
+<script>
+    const nav = document.getElementById('nav');
+    // Keep your state in sync with user-driven changes (toggle, Escape, backdrop):
+    nav.addEventListener('openChange', (e) => {
+        nav.open = e.detail;
+    });
+    // Programmatic control:
+    await nav.toggle();
+    await nav.setOpen(false);
+</script>
+```
+
+> **v2 breaking change (beta):** the mobile toggle + drawer are now built in. Consumers who previously wrapped their own toggle around `xpl-side-nav` should remove it.
+
+### Implementation details (mobile drawer)
+
+- **Host class hooks** — when the drawer is open the host carries `xpl-side-nav--open` alongside `xpl-side-nav`. Useful for app-level CSS that needs to react (e.g. lock body scroll).
+- **Drawer transition** — `transform` + `opacity` + `visibility` over **300 ms** with `ease-out`. Closed state is `translateX(-100%)` + `opacity: 0` + `visibility: hidden`; the `visibility` flip is delayed 300 ms on close so the slide is visible.
+- **Backdrop transition** — `opacity` + `visibility` over **500 ms** with `ease-in-out`. Open state uses `opacity-50` (matches the native `xpl-backdrop` value, not full opaque). Visibility delayed 500 ms on close. `pointer-events: none` applies immediately on close so page content is tappable while the scrim fades out.
+- **Drawer geometry** — width `80vw` with a `min-width: 300px` floor (Figma spec; no Foundation token yet — see `TECH_DEBT.md`). The remaining `20vw` shows the backdrop scrim.
+- **Toggle styling overrides** — the built-in `xpl-button` toggle uses `padding-inline: var(--xpl-space-12)` on its inner `<button>` and renders its icon at `var(--xpl-size-200)` (32 px) so the icon's left edge aligns with the drawer's nav-item icon column.
 
 ### Multi-Navigation Layouts (Accessibility)
 
@@ -54,17 +122,97 @@ When multiple navigation landmarks exist on a page (e.g., side nav, top nav, bre
 
 ## Related components
 
-- [xpl-side-nav-item](../xpl-side-nav-item) — Navigation rows (leaf, expandable, or link) for section and footer.
+- [xpl-side-nav-item](./xpl-side-nav-item) — Navigation rows for section and footer: leaf button, expandable parent, or link (real `<a>`) mode.
 
 <!-- Auto Generated Below -->
 
 
+## Overview
+
+Slot-based sidebar for app navigation: a scrollable main `section` and a fixed
+`nav-footer`. Compose with `xpl-side-nav-item` for rows.
+
+**Mobile (v2):** below the Tailwind `md` breakpoint, the sidebar collapses to a
+~56px top bar with a toggle button (`sidebar-left-show` / `sidebar-left-hide`).
+Activating the toggle opens a drawer containing the `section` + `nav-footer`
+content behind an `xpl-backdrop` scrim. The drawer traps focus while open;
+Escape or a backdrop click closes it and returns focus to the toggle. Above
+`md` the toggle and backdrop are hidden via CSS and the sidebar renders inline.
+
+The toggle is always rendered (no gating prop) and hidden above the breakpoint
+in CSS. Open state is exposed via the `open` prop (controlled or uncontrolled),
+the `openChange` event, and the `toggle()` / `setOpen()` methods.
+
+**v2 breaking change (beta):** consumers who wrapped their own mobile toggle
+around `xpl-side-nav` should remove it — the toggle and drawer are now built in.
+
 ## 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` |
+| 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` |
+| `open`   | `open`    | Whether the mobile drawer is open. Reflected to the `open` attribute so CSS and host state stay in sync. Controlled (consumer owns `open`) or uncontrolled (built-in toggle flips it). Has no visible effect above the `md` breakpoint, where the sidebar always renders inline. | `boolean` | `false`     |
+
+
+## Events
 
+| Event        | Description                                                                                                                                                        | Type                   |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- |
+| `openChange` | Emitted when the mobile drawer open state changes: toggle activation, Escape, or a backdrop click. Detail is the new open state (`true` = open, `false` = closed). | `CustomEvent<boolean>` |
+
+
+## Methods
+
+### `setOpen(open: boolean) => Promise<void>`
+
+Programmatically set the mobile drawer open state. Emits `openChange` when it changes.
+
+#### Parameters
+
+| Name   | Type      | Description |
+| ------ | --------- | ----------- |
+| `open` | `boolean` |             |
+
+#### Returns
+
+Type: `Promise<void>`
+
+
+
+### `toggle() => Promise<void>`
+
+Programmatically toggle the mobile drawer open/closed. Emits `openChange`.
+
+#### Returns
+
+Type: `Promise<void>`
+
+
+
+
+## Slots
+
+| Slot           | Description                                                  |
+| -------------- | ------------------------------------------------------------ |
+| `"nav-footer"` | Footer items (e.g. Help, Logout), separated by a top border. |
+| `"section"`    | Primary navigation items (`xpl-side-nav-item`).              |
+
+
+## Dependencies
+
+### Depends on
+
+- [xpl-button](../xpl-button)
+- [xpl-backdrop](../xpl-backdrop)
+
+### Graph
+```mermaid
+graph TD;
+  xpl-side-nav --> xpl-button
+  xpl-side-nav --> xpl-backdrop
+  xpl-button --> xpl-icon
+  style xpl-side-nav fill:#f9f,stroke:#333,stroke-width:4px
+```
 
 ----------------------------------------------