@xplortech/apollo-core 2.6.0 → 2.7.1

package/dist/types/components.d.ts

@@ -5,16 +5,26 @@
  * It contains typing information for all components that exist in this project.
  */
 import { HTMLStencilElement, JSXBase } from "./stencil-public-runtime";
+import { AvatarColor, AvatarGroupItem, AvatarStatus, AvatarVariant } from "./components/xpl-avatar/xpl-avatar";
 import { BadgeVariantProp } from "./components/xpl-badge/xpl-badge";
 import { Choice } from "./components/xpl-choicelist/choice";
 import { DropdownItem, DropdownOptionGroup } from "./components/xpl-dropdown/dropdown-option";
-import { ListItem } from "./components/xpl-list/listitem";
+import { Placement } from "@floating-ui/dom";
+import { ListItem, XplListOrderChangeDetail } from "./components/xpl-list/listitem";
+import { BadgeVariantProp as BadgeVariantProp1 } from "./components/xpl-badge/xpl-badge";
 import { PopoverPosition } from "./components/xpl-popover/xpl-popover";
+import { SpotlightActionLayout, SpotlightAnchorPosition } from "./components/xpl-spotlight/xpl-spotlight";
+import { TagDragEndDetail, TagDragStartDetail } from "./components/xpl-tag/xpl-tag";
+export { AvatarColor, AvatarGroupItem, AvatarStatus, AvatarVariant } from "./components/xpl-avatar/xpl-avatar";
 export { BadgeVariantProp } from "./components/xpl-badge/xpl-badge";
 export { Choice } from "./components/xpl-choicelist/choice";
 export { DropdownItem, DropdownOptionGroup } from "./components/xpl-dropdown/dropdown-option";
-export { ListItem } from "./components/xpl-list/listitem";
+export { Placement } from "@floating-ui/dom";
+export { ListItem, XplListOrderChangeDetail } from "./components/xpl-list/listitem";
+export { BadgeVariantProp as BadgeVariantProp1 } from "./components/xpl-badge/xpl-badge";
 export { PopoverPosition } from "./components/xpl-popover/xpl-popover";
+export { SpotlightActionLayout, SpotlightAnchorPosition } from "./components/xpl-spotlight/xpl-spotlight";
+export { TagDragEndDetail, TagDragStartDetail } from "./components/xpl-tag/xpl-tag";
 export namespace Components {
     interface XplAccordion {
         /**
@@ -76,22 +86,26 @@ export namespace Components {
         /**
           * Background color when there is no image src
          */
-        "color"?: 'green' | 'yellow' | 'pink' | 'primary' | 'secondary';
+        "color"?: AvatarColor;
         /**
           * Sets a disabled state on the avatar when set to true
           * @default false
          */
         "disabled"?: boolean;
+        /**
+          * When `variant` is `group`, data for each face (max 4 visible + overflow count). Each item: { src?, name?, color? }.
+         */
+        "groupData"?: AvatarGroupItem[] | string;
         /**
           * The URL if the avatar should be hyperlinked
          */
         "href"?: string;
         /**
-          * Alt text for the image if there is an image src
+          * Alt text for the image; also used for initials when no image and no slot.
          */
         "name"?: string;
         /**
-          * Size of the avatar
+          * Size of the avatar (and of each avatar in a group).
          */
         "size"?: 'md' | 'sm';
         /**
@@ -99,13 +113,22 @@ export namespace Components {
          */
         "src"?: string;
         /**
-          * Color styles for the dot indicator to indicate varied states
+          * Shown for the default avatar, `profile`, and `with-text`; not shown when `variant` is `group`. **Legacy
+          * @deprecated :** `active`, `warning`, and `inactive` still map to `green`, `red`, and `gray` for existing consumers. Prefer palette names; legacy values are scheduled for removal in the next **major** release.
+         */
+        "status"?: AvatarStatus;
+        /**
+          * Secondary text shown when `variant` is `with-text` (e.g. email).
          */
-        "status"?: 'active' | 'warning' | 'inactive';
+        "subText"?: string;
         /**
           * Where to open the URL chosen for the `href` prop: `_self` (default), `_blank`, `_parent`, or `_top`
          */
         "target"?: string;
+        /**
+          * Optional layout: `profile` (large profile sizes), `group` (stacked faces + `groupData`; `status` not shown), `with-text` (avatar with `name` / `subText` beside it). Omit for the default single avatar.
+         */
+        "variant"?: AvatarVariant;
     }
     interface XplBackdrop {
         /**
@@ -193,6 +216,16 @@ export namespace Components {
     interface XplBreadcrumbs {
     }
     interface XplButton {
+        /**
+          * Attributes to apply to the inner native `<button>` (e.g., tab a11y wiring). Use this instead of setting `id` / `role` / `aria-*` on the host when the inner control is the element that needs them (e.g., WAI-ARIA composite widgets).
+         */
+        "controlAttrs"?: {
+        id?: string;
+        role?: string;
+        'aria-controls'?: string;
+        'aria-selected'?: 'true' | 'false';
+        'aria-current'?: string;
+    };
         /**
           * Whether button should be disabled
           * @default false
@@ -311,6 +344,11 @@ export namespace Components {
         "setDate": (date: string | string[]) => Promise<void>;
     }
     interface XplCheckbox {
+        /**
+          * Accessible name for the native checkbox input (sets `aria-label` on the `input`). Use when there is no visible label text in the default slot. Defaults to `''`; empty or whitespace-only values omit `aria-label` on the input so a visible `<label>` remains the sole name source.
+          * @default ''
+         */
+        "ariaLabel": string;
         /**
           * Whether the input is checked
          */
@@ -458,6 +496,10 @@ export namespace Components {
           * @default true
          */
         "closeOnSelect": boolean;
+        /**
+          * When `anchorToTrigger` is true, additional placements to try when the default `placement` does not fit (passed to Floating UI `flip`).
+         */
+        "flipFallbackPlacements"?: Placement[];
         /**
           * called on dropdown option click and keydown events to update isSelected states
          */
@@ -476,6 +518,11 @@ export namespace Components {
           * options that are listed
          */
         "options"?: DropdownItem[];
+        /**
+          * Floating UI placement when `anchorToTrigger` is true (e.g. `bottom-start`, `top-start`).
+          * @default 'bottom-start'
+         */
+        "placement": Placement;
         /**
           * whether selection should be made when focusing on interactive element
           * @default false
@@ -638,7 +685,12 @@ export namespace Components {
          */
         "allowCustomOption"?: boolean;
         /**
-          * Hint for form autofill feature  Applies to text, password, number.
+          * Accessible name for search inputs when there is no visible `label` (after trim). Ignored for naming when a visible label is shown. Defaults to `''`; whitespace-only values are treated as missing and fall back to `'Search'` so the field is never unnamed when there is no visible label.  Applies to search inputs (`type="search"`).
+          * @default ''
+         */
+        "ariaLabel": string;
+        /**
+          * Hint for form autofill feature  Applies to text, password, number, and search inputs.
          */
         "autocomplete"?: string;
         /**
@@ -723,7 +775,7 @@ export namespace Components {
          */
         "name"?: string;
         /**
-          * Placeholder text that appears when the field has no value  Applies to text, password, number, and date inputs.
+          * Placeholder text that appears when the field has no value  Applies to text, password, number, date, and search inputs.
          */
         "placeholder"?: string;
         /**
@@ -739,13 +791,21 @@ export namespace Components {
          */
         "preferredCountries"?: string[];
         /**
-          * Whether the input is editable  Applies to text, password, number, and date inputs.
+          * Whether the input is editable  Applies to text, password, number, date, and search inputs.
          */
         "readonly"?: boolean;
         /**
           * Whether the input is required  Applies to all input types.
          */
         "required"?: boolean;
+        /**
+          * Moves keyboard focus to the native control (text field, textarea, or search inner input).
+         */
+        "setFocus": () => Promise<void>;
+        /**
+          * Shell corner radius for search inputs: `rounded` (pill) or `box` (rounded rectangle).  Applies to search inputs (`type="search"`).
+         */
+        "shape"?: 'rounded' | 'box';
         /**
           * The granularity that the value in a `number` input must adhere to when incrementing or decrementing. The default stepping value for number inputs is 1  Applies to number and time inputs.
          */
@@ -759,9 +819,17 @@ export namespace Components {
           * The type of form control
           * @default 'text'
          */
-        "type"?: 'date' | 'time' | 'text' | 'number' | 'password' | 'file' | 'color' | 'phone';
+        "type"?: | 'date'
+        | 'time'
+        | 'text'
+        | 'number'
+        | 'password'
+        | 'file'
+        | 'color'
+        | 'phone'
+        | 'search';
         /**
-          * Including a `value` will pre-populate the input with the given string.  Applies to text, password, number, and date inputs.
+          * Including a `value` will pre-populate the input with the given string.  Applies to text, password, number, date, and search inputs.
          */
         "value"?: string;
     }
@@ -935,6 +1003,74 @@ export namespace Components {
          */
         "value"?: string;
     }
+    interface XplInputSearch {
+        /**
+          * Accessible name when there is no visible label from the parent; maps to `aria-label` on the input. When the parent provides a visible label, the input is named by `<label for="…">` — this prop is ignored for naming. Empty or whitespace-only values are treated as missing and fall back to `'Search'` so the field is never unnamed.
+          * @default 'Search'
+         */
+        "ariaLabel": string;
+        /**
+          * Passed to the native input (`autocomplete` attribute). Default `off` matches common inline-search UX; browsers may still apply heuristics.
+          * @default 'off'
+         */
+        "autocomplete": string;
+        /**
+          * Disables the field and clear control.
+          * @default false
+         */
+        "disabled": boolean;
+        /**
+          * Element id for `aria-describedby` when `hasError` (error message lives on `xpl-input`).
+         */
+        "errorMessageId"?: string;
+        /**
+          * Set by `xpl-input` when `error` is shown — drives `aria-invalid` / `aria-describedby`.
+          * @default false
+         */
+        "hasError": boolean;
+        /**
+          * When true, parent `xpl-input` renders a visible label — omit `aria-label` on the input.
+          * @default false
+         */
+        "hasVisibleLabel": boolean;
+        /**
+          * Associates the control with the parent `xpl-input` label (`for` / `id`).
+         */
+        "inputId": string;
+        /**
+          * Form field `name` on the native input.
+         */
+        "name"?: string;
+        /**
+          * Placeholder shown when the value is empty.
+          * @default 'Search'
+         */
+        "placeholder": string;
+        /**
+          * Whether the input is editable.
+          * @default false
+         */
+        "readonly": boolean;
+        /**
+          * Whether the input is required.
+          * @default false
+         */
+        "required": boolean;
+        /**
+          * Moves keyboard focus to the search field.
+         */
+        "setFocus": () => Promise<void>;
+        /**
+          * Shell corner radius: `rounded` (pill) or `box` (rounded rectangle).
+          * @default 'rounded'
+         */
+        "shape": 'rounded' | 'box';
+        /**
+          * Current value (controlled-friendly).
+          * @default ''
+         */
+        "value": string;
+    }
     interface XplInputTime {
         /**
           * For time inputs, whether to allow custom option in the input even if not available in the dropdown. Example: A step of 30 minutes will allow 15:03, 15:37, etc.  Applies to time inputs.
@@ -1011,10 +1147,94 @@ export namespace Components {
     }
     interface XplList {
         /**
-          * `items` should be an array of objects with the following signature: {   avatar?: string;        // The URL of the avatar, or the placeholder initials (ex. "SPD").   avatars?: string[];     // The URLs of multiple avatars to be displayed in a group on the right.   badges?: string[] | {   // An array of strings or badge-like objects to be displayed as badges     dot?: boolean;        // in a group on the right. See <xpl-badge> for more details.     text: string;     variant?: string;   }[];   href?: string;          // A URL, if this list item is meant to link somewhere.   title: string;          // The text to be displayed for the list item.   metadata?: string[] | { // An array of strings or strings with icons (reference the allowed     icon: string;         // Apollo icons) to be displayed as metadata below the title.     text: string;   }[];   subtext?: string;       // Subtext to be displayed on the right. }  - Note that you should *only use one of* `avatars`, `badges`, or `subtext`, to avoid cluttering   the right-hand side of the list item.
+          * Clears all radio selections in the list. Also runs when `selectable` is true, the user presses Escape, and focus is on the selected row. Emits `itemSelect` once per row that was selected (checked radio or `selected` prop), typically one.
+         */
+        "clearSelection": () => Promise<void>;
+        /**
+          * Array of list items to render. Each item should follow the ListItem interface. **Deprecated.** Use slot-based xpl-list-item children instead.
           * @default []
          */
-        "items"?: ListItem[];
+        "items": ListItem[];
+        /**
+          * Accessible name for the list, exposed as `aria-label` on the host when set. Use when the list has no visible heading. Ignored when `labelledBy` is set (see `labelledBy` for precedence).
+         */
+        "label"?: string;
+        /**
+          * Element id(s) that label this list (space-separated), exposed as `aria-labelledby` when set. When set, `label` is not applied as `aria-label` so the list has a single naming source.
+         */
+        "labelledBy"?: string;
+        /**
+          * When true, enables reorder UI and behavior for **slot-based** child rows (drag handle + keyboard). Legacy rows rendered from the deprecated `items` prop do **not** show a drag handle; migrate to slots if reorder is required.
+          * @default false
+         */
+        "reorderable": boolean;
+        /**
+          * Determines if this list is selectable (shows `xpl-radio` per row in a shared group). Press Escape while focus is on the **selected** row to clear selection (same as `clearSelection()`).
+          * @default false
+         */
+        "selectable": boolean;
+    }
+    interface XplListItem {
+        /**
+          * Whether the item is disabled.
+          * @default false
+         */
+        "disabled"?: boolean;
+        /**
+          * Whether to show the item in an error state.
+          * @default false
+         */
+        "error"?: boolean;
+        /**
+          * When true, the row is not shown and does not participate in visible-only list behavior (e.g. `orderChange` / `orderedItemIds`, reorder targets). Use for filtering, conditional display, or keeping stable `item-id` while the row is off-screen. See `xpl-list` readme “Hidden rows”.  **Accessibility:** Renders an empty host with the native `hidden` attribute only (no `role="listitem"`), consistent with the row not participating as a list item while hidden.
+          * @default false
+         */
+        "hidden": boolean;
+        /**
+          * URL for link behavior. When provided, the entire row becomes clickable. Clicks on `actions` or `avatar` slots are prevented from triggering navigation.
+         */
+        "href"?: string;
+        /**
+          * Optional item data for prop-based rendering. When provided, this takes precedence over slotted content and renders using the legacy ListItem interface. **Deprecated.** Prefer slot-based composition (named slots on `xpl-list-item`).
+         */
+        "item"?: ListItem;
+        /**
+          * Unique identifier for this item. Used for selection and drag/drop. Mutable so the host can sync from `item-id` / `id` in `componentWillLoad` without breaking one-way data flow.
+         */
+        "itemId"?: string;
+        /**
+          * When set by the parent, indicates this item is the active keyboard reorder item.
+          * @default false
+         */
+        "keyboardActive"?: boolean;
+        /**
+          * Name attribute for radio inputs (shared across selectable items in a list).
+         */
+        "radioName"?: string;
+        /**
+          * Whether this item is reorderable (shows a drag handle in **slot-based** layout). When the deprecated `item` prop is used, legacy markup has **no** reorder handle even if this is true.
+          * @default false
+         */
+        "reorderable"?: boolean;
+        /**
+          * Whether this item is selectable (shows `xpl-radio` in a shared group).
+          * @default false
+         */
+        "selectable"?: boolean;
+        /**
+          * Whether this item is selected (radio checked state).
+          * @default false
+         */
+        "selected"?: boolean;
+        /**
+          * Whether to show a divider below the item.
+          * @default false
+         */
+        "showDivider"?: boolean;
+        /**
+          * Optional badge to display next to the title (dot badge). Only used when `item` prop is not provided (slot mode). Matches `xpl-badge` variant values (e.g. purple, green, red).
+         */
+        "titleBadgeVariant"?: BadgeVariantProp1;
     }
     interface XplMainNav {
         /**
@@ -1040,6 +1260,34 @@ export namespace Components {
          */
         "variant": 'default' | 'warning';
     }
+    /**
+     * Profile / account block (username, email, default slot for **`xpl-top-nav-item`** / **`xpl-divider`**).
+     * Tag **`xpl-nav-header-menu`**; implementation folder **`xpl-nav-header-menu`**. **`.xpl-nav-header-menu__slot`** is
+     * **`role="list"`** for slotted **`xpl-top-nav-item`** (**`role="listitem"`**).
+     * **Slotted content:** do not add **`xpl-nav-header-menu__*`** BEM classes on nodes you pass into the default slot —
+     * profile, list shell, and **`xpl-top-nav-item`** **`role="listitem"`** are handled by the component. Use
+     * **`xpl-top-nav-item`** (or plain elements that are not Apollo **`xpl-*`** BEM hooks) in the slot only.
+     * **`slot="right-aside-mobile"`** — optional block **between** the profile header and the default-slot list (e.g. narrow-only
+     * duplicate of **every** **`slot="right-aside"`** control per Figma when **`xpl-top-nav`** hides **`right-aside`** on narrow viewports (always)).
+     * Not **`role="list"`**; use **`xpl-button`** / **`xpl-top-nav-item`** as needed. Shown only on **narrow viewports** (one pixel below Tailwind **`md`** — **`top-nav.css`**) so bar actions stay in **`slot="right-aside"`** on wider viewports.
+     * Light-DOM **`slotchange`** is unreliable; a host **`MutationObserver`** (child / subtree / **`slot`** attribute) keeps
+     * **`xpl-nav-header-menu--has-right-aside-mobile`** in sync when nodes are added or retargeted after mount (same pattern as **`xpl-top-nav`**).
+     * Stencil **`newSpecPage`** / mock-doc does not define **`MutationObserver`**; slot presence still updates on the next
+     * deferred flush (**`setTimeout(0)`** coalesced with **`componentDidRender`**). In real browsers the observer handles child /
+     * **`slot`** mutations without stacking uncancellable microtasks.
+     * **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 (same contract as **`xpl-top-nav`** / **`xpl-top-nav-item`**).
+     */
+    interface XplNavHeaderMenu {
+        /**
+          * Email address shown below the username.
+         */
+        "email"?: string;
+        /**
+          * Display name shown in the profile block.
+         */
+        "username"?: string;
+    }
     interface XplNavItem {
         /**
           * @property {boolean} - Whether or not the item should control the main nav state on click
@@ -1085,7 +1333,7 @@ export namespace Components {
          */
         "accent": 'none' | 'primary' | 'secondary' | 'positive' | 'negative' | 'highlight';
         /**
-          * Padding density applied to the content area. Responsive: scales down at tablet and mobile breakpoints.  - `default` – 24 px desktop / 16 px tablet+mobile - `tight`   – 16 px desktop / 8 px tablet+mobile - `loose`   – 40 px desktop / 32 px tablet / 24 px mobile
+          * Padding density applied to the content area. (default and tight keep desktop padding through tablet; mobile ≤480px).  - `default` – 24 px desktop & tablet / 16 px mobile - `tight`   – 16 px desktop & tablet / 8 px mobile - `loose`   – 40 px desktop / 32 px tablet / 24 px mobile
           * @default 'default'
          */
         "padding": 'default' | 'tight' | 'loose';
@@ -1112,17 +1360,6 @@ export namespace Components {
          */
         "position": PopoverPosition;
     }
-    interface XplProgress {
-        /**
-          * Current step, is the index of the current active step
-          * @default 0
-         */
-        "currentStep": number;
-        /**
-          * The steps is an array of the steps name.
-         */
-        "steps"?: string[];
-    }
     interface XplProgressBar {
         /**
           * The helper text displayed below the progress bar (recommended for error state)
@@ -1153,6 +1390,32 @@ export namespace Components {
          */
         "variant": 'default' | 'success' | 'error' | 'indeterminate';
     }
+    interface XplProgressIndicator {
+        /**
+          * Current step index. Steps with index < currentStep are "finished", the step at currentStep is "active", and steps beyond are "waiting". Set to steps.length to mark all steps as finished. Automatically clamped to [0, steps.length].
+          * @default 0
+         */
+        "currentStep": number;
+        /**
+          * Layout direction - 'horizontal' or 'vertical'
+          * @default 'horizontal'
+         */
+        "layout": 'horizontal' | 'vertical';
+        /**
+          * Whether to show step labels
+          * @default true
+         */
+        "showLabels": boolean;
+        /**
+          * Whether to show step numbers inside circles
+          * @default true
+         */
+        "showNumbers": boolean;
+        /**
+          * The steps is an array of the steps name.
+         */
+        "steps"?: string[];
+    }
     interface XplRadio {
         /**
           * Whether the input is "on"
@@ -1207,6 +1470,15 @@ export namespace Components {
           * Whether the field is disabled
          */
         "disabled"?: boolean;
+        /**
+          * Additional placements to try for the options panel when the default `dropdownPlacement` does not fit. Passed to `xpl-dropdown` / Floating UI `flip`.
+         */
+        "dropdownFlipFallbackPlacements"?: Placement[];
+        /**
+          * Initial Floating UI placement for the options panel (e.g. `top-start`, `bottom-start`). Forwarded to the inner `xpl-dropdown` when the menu is open.
+          * @default 'bottom-start'
+         */
+        "dropdownPlacement": Placement;
         /**
           * If an empty string (attribute present with no value), will display visually as an error. If a string is included, will display visually as an error and include the value as an error message.
          */
@@ -1354,16 +1626,126 @@ export namespace Components {
          */
         "variant": 'default' | 'warning';
     }
+    interface XplSpotlight {
+        /**
+          * Footer action layout. `default` and `dual` both render the standard Back/Next layout, while `single` renders a single acknowledgement CTA (e.g. "Got it!"). Only applies when `showActions` is `true`.
+          * @default 'default'
+         */
+        "actionLayout": SpotlightActionLayout;
+        /**
+          * Which corner of the card the anchor dot uses when not using `target`, or as the preferred side for Floating UI.
+          * @default 'top-left'
+         */
+        "anchorPosition": SpotlightAnchorPosition;
+        /**
+          * Body copy when the `body` slot has no slotted content. Whitespace-only values are treated as empty (no fallback paragraph).
+         */
+        "body"?: string;
+        /**
+          * Current step index (1-based). Used with `totalSteps` for the step label and for disabling default Back/Next when `showSteps` is true.
+          * @default 1
+         */
+        "currentStep": number;
+        /**
+          * Heading when the `title` slot has no slotted content. Whitespace-only values are treated as empty (no fallback title span).
+         */
+        "heading"?: string;
+        /**
+          * Whether to show the dismiss (close) control.
+          * @default true
+         */
+        "isDismissible": boolean;
+        /**
+          * Controls whether the spotlight is rendered. When false, the host remains in the DOM but the spotlight UI is hidden.
+          * @default true
+         */
+        "isOpen": boolean;
+        /**
+          * Label used for the default primary action button. Only applies when `showActions` is `true`.
+          * @default 'Next'
+         */
+        "primaryActionLabel": string;
+        /**
+          * Label used for the default secondary action button. Only applies when `showActions` is `true`.
+          * @default 'Back'
+         */
+        "secondaryActionLabel": string;
+        /**
+          * Whether to show the actions row (primary / secondary and optional step counter). When `false`, the spotlight has no action buttons — useful for single-step informational callouts that rely solely on the dismiss control.
+          * @default true
+         */
+        "showActions": boolean;
+        /**
+          * When true, the media region is shown. Slotted `image` content is rendered when present; otherwise the built-in placeholder UI is shown. When false, the entire media block is hidden.
+          * @default true
+         */
+        "showImage": boolean;
+        /**
+          * Whether to show the step counter between actions (`currentStep` of `totalSteps`) and whether default Back/Next use step-based disabled state.
+          * @default true
+         */
+        "showSteps": boolean;
+        /**
+          * CSS selector for the element this spotlight anchors to. When set, placement uses Floating UI (`computePosition` with `strategy: 'fixed'`, plus `flip`, `shift`, `offset`) and `autoUpdate` for scroll/resize. The host receives `left` / `top` and the `xpl-spotlight--anchored` class. Invalid selectors are ignored; layout falls back to `anchor-position`.
+         */
+        "target"?: string;
+        /**
+          * Total number of steps (1-based upper bound). Used with `currentStep` for the step label and for disabling default Back/Next when `showSteps` is true.
+          * @default 1
+         */
+        "totalSteps": number;
+    }
     interface XplTab {
+        /**
+          * Disables this tab (pill or underline).
+          * @default false
+         */
+        "disabled": boolean;
+        /**
+          * Focuses the tab's trigger button.
+         */
+        "focusTrigger": () => Promise<void>;
+        /**
+          * Whether the tab should take full width (set by parent `xpl-tabs` when fullWidth is true).
+          * @default false
+         */
+        "fullWidth": boolean;
+        /**
+          * Returns the focusable button element for this tab (underline `<button>` or segment `xpl-button` inner button).
+         */
+        "getFocusableElement": () => Promise<HTMLButtonElement | null>;
+        /**
+          * Set when the parent `xpl-tabs` has `disabled` (group-disabled).
+          * @default false
+         */
+        "groupDisabled": boolean;
+        /**
+          * Optional icon name for segment-style pills (`type="segment"` on parent `xpl-tabs`). Ignored for default tabs.
+         */
+        "icon"?: string;
+        /**
+          * Icon position for segment-style pills.
+          * @default 'start'
+         */
+        "iconPosition": 'start' | 'end';
         /**
           * Whether the tab is selected
           * @default false
          */
         "selected": boolean;
+        /**
+          * Sets the tabindex on the focusable button element.
+         */
+        "setTabIndex": (value: number) => Promise<void>;
         /**
           * The target of the tab, required for the tab to be selected
          */
         "target": string;
+        /**
+          * Visual variant: 'tabs' for underline tabs, 'segment' for pill controls. Set by the parent `xpl-tabs` component based on its `type` prop.
+          * @default 'tabs'
+         */
+        "variant": 'tabs' | 'segment';
     }
     interface XplTabPanel {
         /**
@@ -1445,17 +1827,51 @@ export namespace Components {
         "width"?: number;
     }
     interface XplTabs {
+        /**
+          * Disables the whole tab group (headings, mobile select, and segment pills).
+          * @default false
+         */
+        "disabled": boolean;
         /**
           * Whether to make the tabs full width
           * @default false
          */
         "fullWidth": boolean;
+        /**
+          * Visual and layout variant: classic underline tabs or segment (pill) controls.
+          * @default 'tabs'
+         */
+        "type": 'tabs' | 'segment';
         /**
           * The selected tab target value, defaults to the first tab
          */
         "value": string;
     }
     interface XplTag {
+        /**
+          * Whether the tag is disabled
+          * @default false
+         */
+        "disabled": boolean;
+        /**
+          * Whether the tag shows a dismiss button
+          * @default true
+         */
+        "dismissible": boolean;
+        /**
+          * When true, the tag label uses native HTML5 drag (the inner label is the drag source). Named `isDraggable` so the Stencil prop does not collide with the native `HTMLElement.draggable` API. `reflect: false` avoids syncing a `draggable` attribute onto the host; the inner label remains the drag source. Host `onDragStart` still suppresses stray native drags from host chrome.
+          * @default false
+         */
+        "isDraggable": boolean;
+        /**
+          * The size of the tag
+          * @default 'default'
+         */
+        "size": 'default' | 'sm';
+        /**
+          * Optional stable id for the tag. When set, it is included in `tagDragStart` / `tagDragEnd` detail and written to `dataTransfer` as `application/x-tag-id`.
+         */
+        "tagId"?: string;
     }
     interface XplToast {
         /**
@@ -1544,17 +1960,110 @@ export namespace Components {
          */
         "text": string;
     }
-    interface XplUtilityBar {
+    /**
+     * Horizontal top navigation with **`left-aside`** and a **right rail**: **`right-aside`** then **user menu**
+     * (see **`.xpl-top-nav__right-rail`** in `render()`). The account menu uses an internal **`xpl-popover`** (**`bottom-end`**, **`display="menu"`**): built-in trigger uses **`child-account-label`** (prop / attribute) as the label beside a trailing **`chevron-down`** on **`xpl-button`** (**`icon`** / **`iconPosition="end"`**), or **`slot="user-menu-trigger"`** for a custom trigger; panel from **`slot="user-menu"`** (e.g. **`xpl-nav-header-menu`**).
+     * 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).
+     * **`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.
+     * **Theming:** The host always includes Foundation’s **`dark`** class so **`--xpl-*`** purpose tokens under this subtree
+     * resolve to dark-mode values even when the page root is light. Floating overlays (e.g. **`xpl-popover`** / **`xpl-dropdown`**
+     * content teleported outside the host) do not inherit this scope — add **`dark`** on those panels if they should match.
+     * **Layout:** **`right-aside`** and the user-menu region are wrapped internally (**`.xpl-top-nav__right-lead`**, etc.).
+     * Consumers should not add those BEM classes — slot content only.
+     * **Brand logo:** use **`brand-logo`** (URL) for a built-in **`<img>`**, or **`slot="brand-logo"`** for custom markup (e.g. **`xpl-icon`**, SVG). When the URL prop is set, it takes precedence and the slot is not used for the image. On **narrow viewports** (one pixel below Tailwind **`md`** — see **`top-nav.css`**), **`brand-name`** text is hidden in the bar (logo / slot mark only); keep a meaningful **`alt`** on **`brand-logo`** or accessible slotted mark for context.
+     * **Narrow / mobile** (same breakpoint as above): **`slot="left-aside"`** is **hidden** in the bar until **`nav-control`**
+     * is set **and** the drawer is open (floating panel per Figma). **Without **`nav-control`**, there is no mobile drawer** —
+     * primary links remain hidden below **`md`** until the viewport is wide enough for the horizontal bar. The built-in **brand**
+     * stays in the top bar (**hamburger → brand** when **`nav-control`** is set). **`right-aside`** is hidden in the bar on narrow
+     * viewports (**`top-nav.css`**, one pixel below Tailwind **`md`**); duplicate those actions into **`xpl-nav-header-menu`**
+     * **`slot="right-aside-mobile"`** (below profile, above the list; narrow-only CSS in **`top-nav.css`**) per Figma.
+     * **Account menu vs drawer:** Opening the built-in account **`xpl-popover`** while the mobile drawer is open **closes the drawer**
+     * and emits **`navOpen(false)`** so the two layers do not stack.
+     */
+    interface XplTopNav {
         /**
-          * @property {boolean} - Optional property that defines whether or not the main nav is open at startup.
+          * Destination URL for the brand control when using native navigation (**`<a href>`**). When unset, the brand is a **`role="button"`** control and **`brandClick`** fires on activation instead.
          */
-        "isNavOpenAtStartup"?: boolean;
+        "brandHref"?: string;
         /**
-          * @property {boolean} - whether or not to show the bars to control the state of the navigation bar (open/close)
+          * Optional image URL for the brand mark (leading the brand row, before **`brand-name`** text). When set, renders **`<img class="xpl-top-nav__brand-logo">`** and ignores **`slot="brand-logo"`** for the mark. When unset, use **`slot="brand-logo"`** for custom logo content.
          */
-        "navControl"?: boolean;
-    }
-}
+        "brandLogo"?: string;
+        /**
+          * Visible product / app name next to **`brand-logo`**. Omit for logo-only; provide **`brand-logo`** and/or this string to show the built-in brand row (**`left-aside`** is then primary nav links only).
+         */
+        "brandName"?: string;
+        /**
+          * Label text for the built-in account menu trigger (shown **before** the **`chevron-down`** icon) when **`slot="user-menu"`** is present and **`slot="user-menu-trigger"`** is not used. When empty or whitespace-only, the trigger shows only the chevron and uses **`aria-label="Open account menu"`** on the button.
+         */
+        "childAccountLabel"?: string;
+        /**
+          * Accessible name for the `<nav>` landmark (maps to `aria-label`). Use a unique label when the page has multiple navigation regions (e.g. side nav + top nav). When unset, defaults to `top-navigation-bar`.
+         */
+        "label"?: string;
+        /**
+          * When true, renders the navigation control (hamburger) for toggling the left slot on small viewports. The control is **hidden from the Tailwind `md` breakpoint up**; collapse/show for **`left-aside`** uses **`max-width: calc(theme('screens.md') - 1px)`** in **`top-nav.css`** (Figma’s 767px at a 16px root and default **`screens.md`**). Reflected to the **`nav-control`** attribute so host updates (framework props) re-run **`@Watch`**: drawer state and document **Escape** handling stay in sync, the host **`xpl-top-nav--nav-control`** class toggles for **`top-nav.css`**, and **`navOpen(false)`** is emitted if **`nav-control`** is cleared while the drawer was open.
+         */
+        "navControl"?: boolean;
+    }
+    /**
+     * 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
+     * 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
+     * **`xpl-top-nav__brand`** row omits **`listitem`** (it sits in **`.xpl-top-nav__brand-bar`**, not **`.xpl-top-nav__left-primary`**),
+     * 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`**.
+     * **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.
+     * **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 **`xpl-top-nav`**).
+     */
+    interface XplTopNavItem {
+        /**
+          * 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.
+          * @default false
+         */
+        "active": boolean;
+        /**
+          * If set without **`slot="dropdown"`**, the inner control renders as a native **`<a href>`** (link mode).
+         */
+        "href"?: string;
+        /**
+          * Icon name from **`@xplortech/apollo-icons`** (shown before the label when **`label`** is set).
+          * @default ''
+         */
+        "icon": string;
+        /**
+          * 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.
+         */
+        "itemAriaLabel"?: string;
+        /**
+          * 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.
+         */
+        "label"?: string;
+        /**
+          * When true, sets **`aria-current="page"`** and selected styling.
+          * @default false
+         */
+        "selected": boolean;
+    }
+    interface XplUtilityBar {
+        /**
+          * @property {boolean} - Optional property that defines whether or not the main nav is open at startup.
+         */
+        "isNavOpenAtStartup"?: boolean;
+        /**
+          * @property {boolean} - whether or not to show the bars to control the state of the navigation bar (open/close)
+         */
+        "navControl"?: boolean;
+    }
+}
 export interface XplBannerCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLXplBannerElement;
@@ -1603,10 +2112,22 @@ export interface XplInputPhoneCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLXplInputPhoneElement;
 }
+export interface XplInputSearchCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLXplInputSearchElement;
+}
 export interface XplInputTimeCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLXplInputTimeElement;
 }
+export interface XplListCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLXplListElement;
+}
+export interface XplListItemCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLXplListItemElement;
+}
 export interface XplMainNavCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLXplMainNavElement;
@@ -1643,6 +2164,10 @@ export interface XplSlideoutCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLXplSlideoutElement;
 }
+export interface XplSpotlightCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLXplSpotlightElement;
+}
 export interface XplTabCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLXplTabElement;
@@ -1663,6 +2188,14 @@ export interface XplTagCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLXplTagElement;
 }
+export interface XplTopNavCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLXplTopNavElement;
+}
+export interface XplTopNavItemCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLXplTopNavItemElement;
+}
 export interface XplUtilityBarCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLXplUtilityBarElement;
@@ -1923,6 +2456,7 @@ declare global {
         "blurEvent": FocusEvent;
         "valueChange": string;
         "inputEvent": string;
+        "search": string;
     }
     interface HTMLXplInputElement extends Components.XplInput, HTMLStencilElement {
         addEventListener<K extends keyof HTMLXplInputElementEventMap>(type: K, listener: (this: HTMLXplInputElement, ev: XplInputCustomEvent<HTMLXplInputElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
@@ -2016,6 +2550,27 @@ declare global {
         prototype: HTMLXplInputPhoneElement;
         new (): HTMLXplInputPhoneElement;
     };
+    interface HTMLXplInputSearchElementEventMap {
+        "blurEvent": FocusEvent;
+        "focusEvent": FocusEvent;
+        "inputEvent": string;
+        "search": string;
+        "valueChange": string;
+    }
+    interface HTMLXplInputSearchElement extends Components.XplInputSearch, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLXplInputSearchElementEventMap>(type: K, listener: (this: HTMLXplInputSearchElement, ev: XplInputSearchCustomEvent<HTMLXplInputSearchElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLXplInputSearchElementEventMap>(type: K, listener: (this: HTMLXplInputSearchElement, ev: XplInputSearchCustomEvent<HTMLXplInputSearchElementEventMap[K]>) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    }
+    var HTMLXplInputSearchElement: {
+        prototype: HTMLXplInputSearchElement;
+        new (): HTMLXplInputSearchElement;
+    };
     interface HTMLXplInputTimeElementEventMap {
         "valueChange": string;
         "hasErrorStateChanged": string | null;
@@ -2040,12 +2595,44 @@ declare global {
         prototype: HTMLXplLargeCardElement;
         new (): HTMLXplLargeCardElement;
     };
+    interface HTMLXplListElementEventMap {
+        "itemSelect": { itemId?: string };
+        "orderChange": XplListOrderChangeDetail;
+    }
     interface HTMLXplListElement extends Components.XplList, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLXplListElementEventMap>(type: K, listener: (this: HTMLXplListElement, ev: XplListCustomEvent<HTMLXplListElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLXplListElementEventMap>(type: K, listener: (this: HTMLXplListElement, ev: XplListCustomEvent<HTMLXplListElementEventMap[K]>) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
     }
     var HTMLXplListElement: {
         prototype: HTMLXplListElement;
         new (): HTMLXplListElement;
     };
+    interface HTMLXplListItemElementEventMap {
+        "itemDragEnd": { itemId?: string; item: HTMLElement };
+        "itemDragStart": { itemId?: string; item: HTMLElement };
+        "itemDrop": { itemId?: string; item: HTMLElement };
+        "itemSelect": { itemId?: string };
+    }
+    interface HTMLXplListItemElement extends Components.XplListItem, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLXplListItemElementEventMap>(type: K, listener: (this: HTMLXplListItemElement, ev: XplListItemCustomEvent<HTMLXplListItemElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLXplListItemElementEventMap>(type: K, listener: (this: HTMLXplListItemElement, ev: XplListItemCustomEvent<HTMLXplListItemElementEventMap[K]>) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    }
+    var HTMLXplListItemElement: {
+        prototype: HTMLXplListItemElement;
+        new (): HTMLXplListItemElement;
+    };
     interface HTMLXplMainNavElementEventMap {
         "navWidth": string;
     }
@@ -2080,6 +2667,30 @@ declare global {
         prototype: HTMLXplModalElement;
         new (): HTMLXplModalElement;
     };
+    /**
+     * Profile / account block (username, email, default slot for **`xpl-top-nav-item`** / **`xpl-divider`**).
+     * Tag **`xpl-nav-header-menu`**; implementation folder **`xpl-nav-header-menu`**. **`.xpl-nav-header-menu__slot`** is
+     * **`role="list"`** for slotted **`xpl-top-nav-item`** (**`role="listitem"`**).
+     * **Slotted content:** do not add **`xpl-nav-header-menu__*`** BEM classes on nodes you pass into the default slot —
+     * profile, list shell, and **`xpl-top-nav-item`** **`role="listitem"`** are handled by the component. Use
+     * **`xpl-top-nav-item`** (or plain elements that are not Apollo **`xpl-*`** BEM hooks) in the slot only.
+     * **`slot="right-aside-mobile"`** — optional block **between** the profile header and the default-slot list (e.g. narrow-only
+     * duplicate of **every** **`slot="right-aside"`** control per Figma when **`xpl-top-nav`** hides **`right-aside`** on narrow viewports (always)).
+     * Not **`role="list"`**; use **`xpl-button`** / **`xpl-top-nav-item`** as needed. Shown only on **narrow viewports** (one pixel below Tailwind **`md`** — **`top-nav.css`**) so bar actions stay in **`slot="right-aside"`** on wider viewports.
+     * Light-DOM **`slotchange`** is unreliable; a host **`MutationObserver`** (child / subtree / **`slot`** attribute) keeps
+     * **`xpl-nav-header-menu--has-right-aside-mobile`** in sync when nodes are added or retargeted after mount (same pattern as **`xpl-top-nav`**).
+     * Stencil **`newSpecPage`** / mock-doc does not define **`MutationObserver`**; slot presence still updates on the next
+     * deferred flush (**`setTimeout(0)`** coalesced with **`componentDidRender`**). In real browsers the observer handles child /
+     * **`slot`** mutations without stacking uncancellable microtasks.
+     * **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 (same contract as **`xpl-top-nav`** / **`xpl-top-nav-item`**).
+     */
+    interface HTMLXplNavHeaderMenuElement extends Components.XplNavHeaderMenu, HTMLStencilElement {
+    }
+    var HTMLXplNavHeaderMenuElement: {
+        prototype: HTMLXplNavHeaderMenuElement;
+        new (): HTMLXplNavHeaderMenuElement;
+    };
     interface HTMLXplNavItemElementEventMap {
         "navOpen": boolean;
     }
@@ -2142,18 +2753,18 @@ declare global {
         prototype: HTMLXplPopoverElement;
         new (): HTMLXplPopoverElement;
     };
-    interface HTMLXplProgressElement extends Components.XplProgress, HTMLStencilElement {
-    }
-    var HTMLXplProgressElement: {
-        prototype: HTMLXplProgressElement;
-        new (): HTMLXplProgressElement;
-    };
     interface HTMLXplProgressBarElement extends Components.XplProgressBar, HTMLStencilElement {
     }
     var HTMLXplProgressBarElement: {
         prototype: HTMLXplProgressBarElement;
         new (): HTMLXplProgressBarElement;
     };
+    interface HTMLXplProgressIndicatorElement extends Components.XplProgressIndicator, HTMLStencilElement {
+    }
+    var HTMLXplProgressIndicatorElement: {
+        prototype: HTMLXplProgressIndicatorElement;
+        new (): HTMLXplProgressIndicatorElement;
+    };
     interface HTMLXplRadioElementEventMap {
         "radioChange": string | boolean;
     }
@@ -2247,6 +2858,26 @@ declare global {
         prototype: HTMLXplSlideoutElement;
         new (): HTMLXplSlideoutElement;
     };
+    interface HTMLXplSpotlightElementEventMap {
+        "dismiss": void;
+        "primaryAction": void;
+        "secondaryAction": void;
+        "targetClick": void;
+    }
+    interface HTMLXplSpotlightElement extends Components.XplSpotlight, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLXplSpotlightElementEventMap>(type: K, listener: (this: HTMLXplSpotlightElement, ev: XplSpotlightCustomEvent<HTMLXplSpotlightElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLXplSpotlightElementEventMap>(type: K, listener: (this: HTMLXplSpotlightElement, ev: XplSpotlightCustomEvent<HTMLXplSpotlightElementEventMap[K]>) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    }
+    var HTMLXplSpotlightElement: {
+        prototype: HTMLXplSpotlightElement;
+        new (): HTMLXplSpotlightElement;
+    };
     interface HTMLXplTabElementEventMap {
         "tabChange": string;
     }
@@ -2333,7 +2964,10 @@ declare global {
         new (): HTMLXplTabsElement;
     };
     interface HTMLXplTagElementEventMap {
-        "close": any;
+        "close": void;
+        "tagDragEnd": TagDragEndDetail;
+        "tagDragStart": TagDragStartDetail;
+        "tagRemove": void;
     }
     interface HTMLXplTagElement extends Components.XplTag, HTMLStencilElement {
         addEventListener<K extends keyof HTMLXplTagElementEventMap>(type: K, listener: (this: HTMLXplTagElement, ev: XplTagCustomEvent<HTMLXplTagElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
@@ -2373,6 +3007,79 @@ declare global {
         prototype: HTMLXplTooltipElement;
         new (): HTMLXplTooltipElement;
     };
+    interface HTMLXplTopNavElementEventMap {
+        "brandClick": MouseEvent;
+        "navOpen": boolean;
+    }
+    /**
+     * Horizontal top navigation with **`left-aside`** and a **right rail**: **`right-aside`** then **user menu**
+     * (see **`.xpl-top-nav__right-rail`** in `render()`). The account menu uses an internal **`xpl-popover`** (**`bottom-end`**, **`display="menu"`**): built-in trigger uses **`child-account-label`** (prop / attribute) as the label beside a trailing **`chevron-down`** on **`xpl-button`** (**`icon`** / **`iconPosition="end"`**), or **`slot="user-menu-trigger"`** for a custom trigger; panel from **`slot="user-menu"`** (e.g. **`xpl-nav-header-menu`**).
+     * 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).
+     * **`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.
+     * **Theming:** The host always includes Foundation’s **`dark`** class so **`--xpl-*`** purpose tokens under this subtree
+     * resolve to dark-mode values even when the page root is light. Floating overlays (e.g. **`xpl-popover`** / **`xpl-dropdown`**
+     * content teleported outside the host) do not inherit this scope — add **`dark`** on those panels if they should match.
+     * **Layout:** **`right-aside`** and the user-menu region are wrapped internally (**`.xpl-top-nav__right-lead`**, etc.).
+     * Consumers should not add those BEM classes — slot content only.
+     * **Brand logo:** use **`brand-logo`** (URL) for a built-in **`<img>`**, or **`slot="brand-logo"`** for custom markup (e.g. **`xpl-icon`**, SVG). When the URL prop is set, it takes precedence and the slot is not used for the image. On **narrow viewports** (one pixel below Tailwind **`md`** — see **`top-nav.css`**), **`brand-name`** text is hidden in the bar (logo / slot mark only); keep a meaningful **`alt`** on **`brand-logo`** or accessible slotted mark for context.
+     * **Narrow / mobile** (same breakpoint as above): **`slot="left-aside"`** is **hidden** in the bar until **`nav-control`**
+     * is set **and** the drawer is open (floating panel per Figma). **Without **`nav-control`**, there is no mobile drawer** —
+     * primary links remain hidden below **`md`** until the viewport is wide enough for the horizontal bar. The built-in **brand**
+     * stays in the top bar (**hamburger → brand** when **`nav-control`** is set). **`right-aside`** is hidden in the bar on narrow
+     * viewports (**`top-nav.css`**, one pixel below Tailwind **`md`**); duplicate those actions into **`xpl-nav-header-menu`**
+     * **`slot="right-aside-mobile"`** (below profile, above the list; narrow-only CSS in **`top-nav.css`**) per Figma.
+     * **Account menu vs drawer:** Opening the built-in account **`xpl-popover`** while the mobile drawer is open **closes the drawer**
+     * and emits **`navOpen(false)`** so the two layers do not stack.
+     */
+    interface HTMLXplTopNavElement extends Components.XplTopNav, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLXplTopNavElementEventMap>(type: K, listener: (this: HTMLXplTopNavElement, ev: XplTopNavCustomEvent<HTMLXplTopNavElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLXplTopNavElementEventMap>(type: K, listener: (this: HTMLXplTopNavElement, ev: XplTopNavCustomEvent<HTMLXplTopNavElementEventMap[K]>) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    }
+    var HTMLXplTopNavElement: {
+        prototype: HTMLXplTopNavElement;
+        new (): HTMLXplTopNavElement;
+    };
+    interface HTMLXplTopNavItemElementEventMap {
+        "navItemClick": MouseEvent;
+    }
+    /**
+     * 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
+     * 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
+     * **`xpl-top-nav__brand`** row omits **`listitem`** (it sits in **`.xpl-top-nav__brand-bar`**, not **`.xpl-top-nav__left-primary`**),
+     * 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`**.
+     * **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.
+     * **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 **`xpl-top-nav`**).
+     */
+    interface HTMLXplTopNavItemElement extends Components.XplTopNavItem, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLXplTopNavItemElementEventMap>(type: K, listener: (this: HTMLXplTopNavItemElement, ev: XplTopNavItemCustomEvent<HTMLXplTopNavItemElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLXplTopNavItemElementEventMap>(type: K, listener: (this: HTMLXplTopNavItemElement, ev: XplTopNavItemCustomEvent<HTMLXplTopNavItemElementEventMap[K]>) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    }
+    var HTMLXplTopNavItemElement: {
+        prototype: HTMLXplTopNavItemElement;
+        new (): HTMLXplTopNavItemElement;
+    };
     interface HTMLXplUtilityBarElementEventMap {
         "navOpen": boolean;
     }
@@ -2424,17 +3131,20 @@ declare global {
         "xpl-input-date": HTMLXplInputDateElement;
         "xpl-input-file": HTMLXplInputFileElement;
         "xpl-input-phone": HTMLXplInputPhoneElement;
+        "xpl-input-search": HTMLXplInputSearchElement;
         "xpl-input-time": HTMLXplInputTimeElement;
         "xpl-large-card": HTMLXplLargeCardElement;
         "xpl-list": HTMLXplListElement;
+        "xpl-list-item": HTMLXplListItemElement;
         "xpl-main-nav": HTMLXplMainNavElement;
         "xpl-modal": HTMLXplModalElement;
+        "xpl-nav-header-menu": HTMLXplNavHeaderMenuElement;
         "xpl-nav-item": HTMLXplNavItemElement;
         "xpl-pagination": HTMLXplPaginationElement;
         "xpl-panel": HTMLXplPanelElement;
         "xpl-popover": HTMLXplPopoverElement;
-        "xpl-progress": HTMLXplProgressElement;
         "xpl-progress-bar": HTMLXplProgressBarElement;
+        "xpl-progress-indicator": HTMLXplProgressIndicatorElement;
         "xpl-radio": HTMLXplRadioElement;
         "xpl-secondary-nav": HTMLXplSecondaryNavElement;
         "xpl-select": HTMLXplSelectElement;
@@ -2442,6 +3152,7 @@ declare global {
         "xpl-side-nav-item": HTMLXplSideNavItemElement;
         "xpl-skeleton": HTMLXplSkeletonElement;
         "xpl-slideout": HTMLXplSlideoutElement;
+        "xpl-spotlight": HTMLXplSpotlightElement;
         "xpl-tab": HTMLXplTabElement;
         "xpl-tab-panel": HTMLXplTabPanelElement;
         "xpl-table": HTMLXplTableElement;
@@ -2453,6 +3164,8 @@ declare global {
         "xpl-toggle": HTMLXplToggleElement;
         "xpl-toolbar": HTMLXplToolbarElement;
         "xpl-tooltip": HTMLXplTooltipElement;
+        "xpl-top-nav": HTMLXplTopNavElement;
+        "xpl-top-nav-item": HTMLXplTopNavItemElement;
         "xpl-utility-bar": HTMLXplUtilityBarElement;
     }
 }
@@ -2514,22 +3227,26 @@ declare namespace LocalJSX {
         /**
           * Background color when there is no image src
          */
-        "color"?: 'green' | 'yellow' | 'pink' | 'primary' | 'secondary';
+        "color"?: AvatarColor;
         /**
           * Sets a disabled state on the avatar when set to true
           * @default false
          */
         "disabled"?: boolean;
+        /**
+          * When `variant` is `group`, data for each face (max 4 visible + overflow count). Each item: { src?, name?, color? }.
+         */
+        "groupData"?: AvatarGroupItem[] | string;
         /**
           * The URL if the avatar should be hyperlinked
          */
         "href"?: string;
         /**
-          * Alt text for the image if there is an image src
+          * Alt text for the image; also used for initials when no image and no slot.
          */
         "name"?: string;
         /**
-          * Size of the avatar
+          * Size of the avatar (and of each avatar in a group).
          */
         "size"?: 'md' | 'sm';
         /**
@@ -2537,13 +3254,22 @@ declare namespace LocalJSX {
          */
         "src"?: string;
         /**
-          * Color styles for the dot indicator to indicate varied states
+          * Shown for the default avatar, `profile`, and `with-text`; not shown when `variant` is `group`. **Legacy
+          * @deprecated :** `active`, `warning`, and `inactive` still map to `green`, `red`, and `gray` for existing consumers. Prefer palette names; legacy values are scheduled for removal in the next **major** release.
+         */
+        "status"?: AvatarStatus;
+        /**
+          * Secondary text shown when `variant` is `with-text` (e.g. email).
          */
-        "status"?: 'active' | 'warning' | 'inactive';
+        "subText"?: string;
         /**
           * Where to open the URL chosen for the `href` prop: `_self` (default), `_blank`, `_parent`, or `_top`
          */
         "target"?: string;
+        /**
+          * Optional layout: `profile` (large profile sizes), `group` (stacked faces + `groupData`; `status` not shown), `with-text` (avatar with `name` / `subText` beside it). Omit for the default single avatar.
+         */
+        "variant"?: AvatarVariant;
     }
     interface XplBackdrop {
         /**
@@ -2643,6 +3369,16 @@ declare namespace LocalJSX {
     interface XplBreadcrumbs {
     }
     interface XplButton {
+        /**
+          * Attributes to apply to the inner native `<button>` (e.g., tab a11y wiring). Use this instead of setting `id` / `role` / `aria-*` on the host when the inner control is the element that needs them (e.g., WAI-ARIA composite widgets).
+         */
+        "controlAttrs"?: {
+        id?: string;
+        role?: string;
+        'aria-controls'?: string;
+        'aria-selected'?: 'true' | 'false';
+        'aria-current'?: string;
+    };
         /**
           * Whether button should be disabled
           * @default false
@@ -2773,6 +3509,11 @@ declare namespace LocalJSX {
         "onDateSelected"?: (event: XplCalendarCustomEvent<string | string[]>) => void;
     }
     interface XplCheckbox {
+        /**
+          * Accessible name for the native checkbox input (sets `aria-label` on the `input`). Use when there is no visible label text in the default slot. Defaults to `''`; empty or whitespace-only values omit `aria-label` on the input so a visible `<label>` remains the sole name source.
+          * @default ''
+         */
+        "ariaLabel"?: string;
         /**
           * Whether the input is checked
          */
@@ -2932,6 +3673,10 @@ declare namespace LocalJSX {
           * @default true
          */
         "closeOnSelect"?: boolean;
+        /**
+          * When `anchorToTrigger` is true, additional placements to try when the default `placement` does not fit (passed to Floating UI `flip`).
+         */
+        "flipFallbackPlacements"?: Placement[];
         /**
           * text to display as heading
           * @default false
@@ -2950,6 +3695,11 @@ declare namespace LocalJSX {
           * options that are listed
          */
         "options"?: DropdownItem[];
+        /**
+          * Floating UI placement when `anchorToTrigger` is true (e.g. `bottom-start`, `top-start`).
+          * @default 'bottom-start'
+         */
+        "placement"?: Placement;
         /**
           * whether selection should be made when focusing on interactive element
           * @default false
@@ -3116,7 +3866,12 @@ declare namespace LocalJSX {
          */
         "allowCustomOption"?: boolean;
         /**
-          * Hint for form autofill feature  Applies to text, password, number.
+          * Accessible name for search inputs when there is no visible `label` (after trim). Ignored for naming when a visible label is shown. Defaults to `''`; whitespace-only values are treated as missing and fall back to `'Search'` so the field is never unnamed when there is no visible label.  Applies to search inputs (`type="search"`).
+          * @default ''
+         */
+        "ariaLabel"?: string;
+        /**
+          * Hint for form autofill feature  Applies to text, password, number, and search inputs.
          */
         "autocomplete"?: string;
         /**
@@ -3209,15 +3964,19 @@ declare namespace LocalJSX {
          */
         "onFocusEvent"?: (event: XplInputCustomEvent<FocusEvent>) => void;
         /**
-          * Event that emits the current value of the input  Applies to text like inputs only.
+          * Event that emits the current value of the input  Applies to text-like inputs and search inputs.
          */
         "onInputEvent"?: (event: XplInputCustomEvent<string>) => void;
         /**
-          * Event that emits the current value of the input
+          * Emitted when the user commits a search (Enter with no enclosing form owner, or submit of the internal search form). `event.detail` is the trimmed query string.  Applies to search inputs (`type="search"`).
+         */
+        "onSearch"?: (event: XplInputCustomEvent<string>) => void;
+        /**
+          * Event that emits the current value of the input (including search fields).
          */
         "onValueChange"?: (event: XplInputCustomEvent<string>) => void;
         /**
-          * Placeholder text that appears when the field has no value  Applies to text, password, number, and date inputs.
+          * Placeholder text that appears when the field has no value  Applies to text, password, number, date, and search inputs.
          */
         "placeholder"?: string;
         /**
@@ -3233,13 +3992,17 @@ declare namespace LocalJSX {
          */
         "preferredCountries"?: string[];
         /**
-          * Whether the input is editable  Applies to text, password, number, and date inputs.
+          * Whether the input is editable  Applies to text, password, number, date, and search inputs.
          */
         "readonly"?: boolean;
         /**
           * Whether the input is required  Applies to all input types.
          */
         "required"?: boolean;
+        /**
+          * Shell corner radius for search inputs: `rounded` (pill) or `box` (rounded rectangle).  Applies to search inputs (`type="search"`).
+         */
+        "shape"?: 'rounded' | 'box';
         /**
           * The granularity that the value in a `number` input must adhere to when incrementing or decrementing. The default stepping value for number inputs is 1  Applies to number and time inputs.
          */
@@ -3253,9 +4016,17 @@ declare namespace LocalJSX {
           * The type of form control
           * @default 'text'
          */
-        "type"?: 'date' | 'time' | 'text' | 'number' | 'password' | 'file' | 'color' | 'phone';
+        "type"?: | 'date'
+        | 'time'
+        | 'text'
+        | 'number'
+        | 'password'
+        | 'file'
+        | 'color'
+        | 'phone'
+        | 'search';
         /**
-          * Including a `value` will pre-populate the input with the given string.  Applies to text, password, number, and date inputs.
+          * Including a `value` will pre-populate the input with the given string.  Applies to text, password, number, date, and search inputs.
          */
         "value"?: string;
     }
@@ -3459,6 +4230,90 @@ declare namespace LocalJSX {
          */
         "value"?: string;
     }
+    interface XplInputSearch {
+        /**
+          * Accessible name when there is no visible label from the parent; maps to `aria-label` on the input. When the parent provides a visible label, the input is named by `<label for="…">` — this prop is ignored for naming. Empty or whitespace-only values are treated as missing and fall back to `'Search'` so the field is never unnamed.
+          * @default 'Search'
+         */
+        "ariaLabel"?: string;
+        /**
+          * Passed to the native input (`autocomplete` attribute). Default `off` matches common inline-search UX; browsers may still apply heuristics.
+          * @default 'off'
+         */
+        "autocomplete"?: string;
+        /**
+          * Disables the field and clear control.
+          * @default false
+         */
+        "disabled"?: boolean;
+        /**
+          * Element id for `aria-describedby` when `hasError` (error message lives on `xpl-input`).
+         */
+        "errorMessageId"?: string;
+        /**
+          * Set by `xpl-input` when `error` is shown — drives `aria-invalid` / `aria-describedby`.
+          * @default false
+         */
+        "hasError"?: boolean;
+        /**
+          * When true, parent `xpl-input` renders a visible label — omit `aria-label` on the input.
+          * @default false
+         */
+        "hasVisibleLabel"?: boolean;
+        /**
+          * Associates the control with the parent `xpl-input` label (`for` / `id`).
+         */
+        "inputId": string;
+        /**
+          * Form field `name` on the native input.
+         */
+        "name"?: string;
+        /**
+          * Emitted when the inner control loses focus. When nested under `xpl-input type="search"`, this event bubbles to the `xpl-input` host (same event name as other input types).
+         */
+        "onBlurEvent"?: (event: XplInputSearchCustomEvent<FocusEvent>) => void;
+        /**
+          * Emitted when the inner control receives focus. When nested under `xpl-input type="search"`, this event bubbles to the `xpl-input` host (same event name as other input types).
+         */
+        "onFocusEvent"?: (event: XplInputSearchCustomEvent<FocusEvent>) => void;
+        /**
+          * Fired on every input change (typing, paste) and when the value is cleared — mirrors `xpl-input` text fields. When nested under `xpl-input type="search"`, bubbles to the `xpl-input` host.
+         */
+        "onInputEvent"?: (event: XplInputSearchCustomEvent<string>) => void;
+        /**
+          * Emitted when the user commits a search (Enter with no enclosing form owner, or submit of the inner search form). `event.detail` is the trimmed query string. When nested under `xpl-input type="search"`, the parent listens with `onSearch` and re-emits so the canonical `search` `@Event` stays on `xpl-input`.
+         */
+        "onSearch"?: (event: XplInputSearchCustomEvent<string>) => void;
+        /**
+          * Fired on every input change (typing, paste) and when the value is cleared. `event.detail` is the raw `value` string (not trimmed). When nested under `xpl-input type="search"`, bubbles to the `xpl-input` host.
+         */
+        "onValueChange"?: (event: XplInputSearchCustomEvent<string>) => void;
+        /**
+          * Placeholder shown when the value is empty.
+          * @default 'Search'
+         */
+        "placeholder"?: string;
+        /**
+          * Whether the input is editable.
+          * @default false
+         */
+        "readonly"?: boolean;
+        /**
+          * Whether the input is required.
+          * @default false
+         */
+        "required"?: boolean;
+        /**
+          * Shell corner radius: `rounded` (pill) or `box` (rounded rectangle).
+          * @default 'rounded'
+         */
+        "shape"?: 'rounded' | 'box';
+        /**
+          * Current value (controlled-friendly).
+          * @default ''
+         */
+        "value"?: string;
+    }
     interface XplInputTime {
         /**
           * For time inputs, whether to allow custom option in the input even if not available in the dropdown. Example: A step of 30 minutes will allow 15:03, 15:37, etc.  Applies to time inputs.
@@ -3543,10 +4398,114 @@ declare namespace LocalJSX {
     }
     interface XplList {
         /**
-          * `items` should be an array of objects with the following signature: {   avatar?: string;        // The URL of the avatar, or the placeholder initials (ex. "SPD").   avatars?: string[];     // The URLs of multiple avatars to be displayed in a group on the right.   badges?: string[] | {   // An array of strings or badge-like objects to be displayed as badges     dot?: boolean;        // in a group on the right. See <xpl-badge> for more details.     text: string;     variant?: string;   }[];   href?: string;          // A URL, if this list item is meant to link somewhere.   title: string;          // The text to be displayed for the list item.   metadata?: string[] | { // An array of strings or strings with icons (reference the allowed     icon: string;         // Apollo icons) to be displayed as metadata below the title.     text: string;   }[];   subtext?: string;       // Subtext to be displayed on the right. }  - Note that you should *only use one of* `avatars`, `badges`, or `subtext`, to avoid cluttering   the right-hand side of the list item.
+          * Array of list items to render. Each item should follow the ListItem interface. **Deprecated.** Use slot-based xpl-list-item children instead.
           * @default []
          */
         "items"?: ListItem[];
+        /**
+          * Accessible name for the list, exposed as `aria-label` on the host when set. Use when the list has no visible heading. Ignored when `labelledBy` is set (see `labelledBy` for precedence).
+         */
+        "label"?: string;
+        /**
+          * Element id(s) that label this list (space-separated), exposed as `aria-labelledby` when set. When set, `label` is not applied as `aria-label` so the list has a single naming source.
+         */
+        "labelledBy"?: string;
+        /**
+          * Emitted when an item is selected.
+         */
+        "onItemSelect"?: (event: XplListCustomEvent<{ itemId?: string }>) => void;
+        /**
+          * Emitted when the order of items changes (after the DOM has been updated). `orderedItemIds` lists **visible** row ids only (hidden rows excluded).
+         */
+        "onOrderChange"?: (event: XplListCustomEvent<XplListOrderChangeDetail>) => void;
+        /**
+          * When true, enables reorder UI and behavior for **slot-based** child rows (drag handle + keyboard). Legacy rows rendered from the deprecated `items` prop do **not** show a drag handle; migrate to slots if reorder is required.
+          * @default false
+         */
+        "reorderable"?: boolean;
+        /**
+          * Determines if this list is selectable (shows `xpl-radio` per row in a shared group). Press Escape while focus is on the **selected** row to clear selection (same as `clearSelection()`).
+          * @default false
+         */
+        "selectable"?: boolean;
+    }
+    interface XplListItem {
+        /**
+          * Whether the item is disabled.
+          * @default false
+         */
+        "disabled"?: boolean;
+        /**
+          * Whether to show the item in an error state.
+          * @default false
+         */
+        "error"?: boolean;
+        /**
+          * When true, the row is not shown and does not participate in visible-only list behavior (e.g. `orderChange` / `orderedItemIds`, reorder targets). Use for filtering, conditional display, or keeping stable `item-id` while the row is off-screen. See `xpl-list` readme “Hidden rows”.  **Accessibility:** Renders an empty host with the native `hidden` attribute only (no `role="listitem"`), consistent with the row not participating as a list item while hidden.
+          * @default false
+         */
+        "hidden"?: boolean;
+        /**
+          * URL for link behavior. When provided, the entire row becomes clickable. Clicks on `actions` or `avatar` slots are prevented from triggering navigation.
+         */
+        "href"?: string;
+        /**
+          * Optional item data for prop-based rendering. When provided, this takes precedence over slotted content and renders using the legacy ListItem interface. **Deprecated.** Prefer slot-based composition (named slots on `xpl-list-item`).
+         */
+        "item"?: ListItem;
+        /**
+          * Unique identifier for this item. Used for selection and drag/drop. Mutable so the host can sync from `item-id` / `id` in `componentWillLoad` without breaking one-way data flow.
+         */
+        "itemId"?: string;
+        /**
+          * When set by the parent, indicates this item is the active keyboard reorder item.
+          * @default false
+         */
+        "keyboardActive"?: boolean;
+        /**
+          * Emitted when a drag operation ends on this item (after drop or cancel).
+         */
+        "onItemDragEnd"?: (event: XplListItemCustomEvent<{ itemId?: string; item: HTMLElement }>) => void;
+        /**
+          * Emitted when drag starts on this item.
+         */
+        "onItemDragStart"?: (event: XplListItemCustomEvent<{ itemId?: string; item: HTMLElement }>) => void;
+        /**
+          * Emitted when an item is dropped on this item.
+         */
+        "onItemDrop"?: (event: XplListItemCustomEvent<{ itemId?: string; item: HTMLElement }>) => void;
+        /**
+          * Emitted when the item is selected (radio change).
+         */
+        "onItemSelect"?: (event: XplListItemCustomEvent<{ itemId?: string }>) => void;
+        /**
+          * Name attribute for radio inputs (shared across selectable items in a list).
+         */
+        "radioName"?: string;
+        /**
+          * Whether this item is reorderable (shows a drag handle in **slot-based** layout). When the deprecated `item` prop is used, legacy markup has **no** reorder handle even if this is true.
+          * @default false
+         */
+        "reorderable"?: boolean;
+        /**
+          * Whether this item is selectable (shows `xpl-radio` in a shared group).
+          * @default false
+         */
+        "selectable"?: boolean;
+        /**
+          * Whether this item is selected (radio checked state).
+          * @default false
+         */
+        "selected"?: boolean;
+        /**
+          * Whether to show a divider below the item.
+          * @default false
+         */
+        "showDivider"?: boolean;
+        /**
+          * Optional badge to display next to the title (dot badge). Only used when `item` prop is not provided (slot mode). Matches `xpl-badge` variant values (e.g. purple, green, red).
+         */
+        "titleBadgeVariant"?: BadgeVariantProp1;
     }
     interface XplMainNav {
         /**
@@ -3580,6 +4539,34 @@ declare namespace LocalJSX {
          */
         "variant"?: 'default' | 'warning';
     }
+    /**
+     * Profile / account block (username, email, default slot for **`xpl-top-nav-item`** / **`xpl-divider`**).
+     * Tag **`xpl-nav-header-menu`**; implementation folder **`xpl-nav-header-menu`**. **`.xpl-nav-header-menu__slot`** is
+     * **`role="list"`** for slotted **`xpl-top-nav-item`** (**`role="listitem"`**).
+     * **Slotted content:** do not add **`xpl-nav-header-menu__*`** BEM classes on nodes you pass into the default slot —
+     * profile, list shell, and **`xpl-top-nav-item`** **`role="listitem"`** are handled by the component. Use
+     * **`xpl-top-nav-item`** (or plain elements that are not Apollo **`xpl-*`** BEM hooks) in the slot only.
+     * **`slot="right-aside-mobile"`** — optional block **between** the profile header and the default-slot list (e.g. narrow-only
+     * duplicate of **every** **`slot="right-aside"`** control per Figma when **`xpl-top-nav`** hides **`right-aside`** on narrow viewports (always)).
+     * Not **`role="list"`**; use **`xpl-button`** / **`xpl-top-nav-item`** as needed. Shown only on **narrow viewports** (one pixel below Tailwind **`md`** — **`top-nav.css`**) so bar actions stay in **`slot="right-aside"`** on wider viewports.
+     * Light-DOM **`slotchange`** is unreliable; a host **`MutationObserver`** (child / subtree / **`slot`** attribute) keeps
+     * **`xpl-nav-header-menu--has-right-aside-mobile`** in sync when nodes are added or retargeted after mount (same pattern as **`xpl-top-nav`**).
+     * Stencil **`newSpecPage`** / mock-doc does not define **`MutationObserver`**; slot presence still updates on the next
+     * deferred flush (**`setTimeout(0)`** coalesced with **`componentDidRender`**). In real browsers the observer handles child /
+     * **`slot`** mutations without stacking uncancellable microtasks.
+     * **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 (same contract as **`xpl-top-nav`** / **`xpl-top-nav-item`**).
+     */
+    interface XplNavHeaderMenu {
+        /**
+          * Email address shown below the username.
+         */
+        "email"?: string;
+        /**
+          * Display name shown in the profile block.
+         */
+        "username"?: string;
+    }
     interface XplNavItem {
         /**
           * @property {boolean} - Whether or not the item should control the main nav state on click
@@ -3637,7 +4624,7 @@ declare namespace LocalJSX {
          */
         "accent"?: 'none' | 'primary' | 'secondary' | 'positive' | 'negative' | 'highlight';
         /**
-          * Padding density applied to the content area. Responsive: scales down at tablet and mobile breakpoints.  - `default` – 24 px desktop / 16 px tablet+mobile - `tight`   – 16 px desktop / 8 px tablet+mobile - `loose`   – 40 px desktop / 32 px tablet / 24 px mobile
+          * Padding density applied to the content area. (default and tight keep desktop padding through tablet; mobile ≤480px).  - `default` – 24 px desktop & tablet / 16 px mobile - `tight`   – 16 px desktop & tablet / 8 px mobile - `loose`   – 40 px desktop / 32 px tablet / 24 px mobile
           * @default 'default'
          */
         "padding"?: 'default' | 'tight' | 'loose';
@@ -3668,17 +4655,6 @@ declare namespace LocalJSX {
          */
         "position"?: PopoverPosition;
     }
-    interface XplProgress {
-        /**
-          * Current step, is the index of the current active step
-          * @default 0
-         */
-        "currentStep"?: number;
-        /**
-          * The steps is an array of the steps name.
-         */
-        "steps"?: string[];
-    }
     interface XplProgressBar {
         /**
           * The helper text displayed below the progress bar (recommended for error state)
@@ -3709,6 +4685,32 @@ declare namespace LocalJSX {
          */
         "variant"?: 'default' | 'success' | 'error' | 'indeterminate';
     }
+    interface XplProgressIndicator {
+        /**
+          * Current step index. Steps with index < currentStep are "finished", the step at currentStep is "active", and steps beyond are "waiting". Set to steps.length to mark all steps as finished. Automatically clamped to [0, steps.length].
+          * @default 0
+         */
+        "currentStep"?: number;
+        /**
+          * Layout direction - 'horizontal' or 'vertical'
+          * @default 'horizontal'
+         */
+        "layout"?: 'horizontal' | 'vertical';
+        /**
+          * Whether to show step labels
+          * @default true
+         */
+        "showLabels"?: boolean;
+        /**
+          * Whether to show step numbers inside circles
+          * @default true
+         */
+        "showNumbers"?: boolean;
+        /**
+          * The steps is an array of the steps name.
+         */
+        "steps"?: string[];
+    }
     interface XplRadio {
         /**
           * Whether the input is "on"
@@ -3767,6 +4769,15 @@ declare namespace LocalJSX {
           * Whether the field is disabled
          */
         "disabled"?: boolean;
+        /**
+          * Additional placements to try for the options panel when the default `dropdownPlacement` does not fit. Passed to `xpl-dropdown` / Floating UI `flip`.
+         */
+        "dropdownFlipFallbackPlacements"?: Placement[];
+        /**
+          * Initial Floating UI placement for the options panel (e.g. `top-start`, `bottom-start`). Forwarded to the inner `xpl-dropdown` when the menu is open.
+          * @default 'bottom-start'
+         */
+        "dropdownPlacement"?: Placement;
         /**
           * If an empty string (attribute present with no value), will display visually as an error. If a string is included, will display visually as an error and include the value as an error message.
          */
@@ -3941,9 +4952,113 @@ declare namespace LocalJSX {
          */
         "variant"?: 'default' | 'warning';
     }
+    interface XplSpotlight {
+        /**
+          * Footer action layout. `default` and `dual` both render the standard Back/Next layout, while `single` renders a single acknowledgement CTA (e.g. "Got it!"). Only applies when `showActions` is `true`.
+          * @default 'default'
+         */
+        "actionLayout"?: SpotlightActionLayout;
+        /**
+          * Which corner of the card the anchor dot uses when not using `target`, or as the preferred side for Floating UI.
+          * @default 'top-left'
+         */
+        "anchorPosition"?: SpotlightAnchorPosition;
+        /**
+          * Body copy when the `body` slot has no slotted content. Whitespace-only values are treated as empty (no fallback paragraph).
+         */
+        "body"?: string;
+        /**
+          * Current step index (1-based). Used with `totalSteps` for the step label and for disabling default Back/Next when `showSteps` is true.
+          * @default 1
+         */
+        "currentStep"?: number;
+        /**
+          * Heading when the `title` slot has no slotted content. Whitespace-only values are treated as empty (no fallback title span).
+         */
+        "heading"?: string;
+        /**
+          * Whether to show the dismiss (close) control.
+          * @default true
+         */
+        "isDismissible"?: boolean;
+        /**
+          * Controls whether the spotlight is rendered. When false, the host remains in the DOM but the spotlight UI is hidden.
+          * @default true
+         */
+        "isOpen"?: boolean;
+        /**
+          * Emitted when the dismiss control is activated or Escape is pressed (when dismissible).
+         */
+        "onDismiss"?: (event: XplSpotlightCustomEvent<void>) => void;
+        /**
+          * Emitted when the primary action control is activated (default: Next).
+         */
+        "onPrimaryAction"?: (event: XplSpotlightCustomEvent<void>) => void;
+        /**
+          * Emitted when the secondary action control is activated (default: Back).
+         */
+        "onSecondaryAction"?: (event: XplSpotlightCustomEvent<void>) => void;
+        /**
+          * Emitted when the target indicator is clicked. Consumers typically toggle `isOpen` in response.
+         */
+        "onTargetClick"?: (event: XplSpotlightCustomEvent<void>) => void;
+        /**
+          * Label used for the default primary action button. Only applies when `showActions` is `true`.
+          * @default 'Next'
+         */
+        "primaryActionLabel"?: string;
+        /**
+          * Label used for the default secondary action button. Only applies when `showActions` is `true`.
+          * @default 'Back'
+         */
+        "secondaryActionLabel"?: string;
+        /**
+          * Whether to show the actions row (primary / secondary and optional step counter). When `false`, the spotlight has no action buttons — useful for single-step informational callouts that rely solely on the dismiss control.
+          * @default true
+         */
+        "showActions"?: boolean;
+        /**
+          * When true, the media region is shown. Slotted `image` content is rendered when present; otherwise the built-in placeholder UI is shown. When false, the entire media block is hidden.
+          * @default true
+         */
+        "showImage"?: boolean;
+        /**
+          * Whether to show the step counter between actions (`currentStep` of `totalSteps`) and whether default Back/Next use step-based disabled state.
+          * @default true
+         */
+        "showSteps"?: boolean;
+        /**
+          * CSS selector for the element this spotlight anchors to. When set, placement uses Floating UI (`computePosition` with `strategy: 'fixed'`, plus `flip`, `shift`, `offset`) and `autoUpdate` for scroll/resize. The host receives `left` / `top` and the `xpl-spotlight--anchored` class. Invalid selectors are ignored; layout falls back to `anchor-position`.
+         */
+        "target"?: string;
+        /**
+          * Total number of steps (1-based upper bound). Used with `currentStep` for the step label and for disabling default Back/Next when `showSteps` is true.
+          * @default 1
+         */
+        "totalSteps"?: number;
+    }
     interface XplTab {
         /**
-          * Event that emits the target of the selected tab
+          * Disables this tab (pill or underline).
+          * @default false
+         */
+        "disabled"?: boolean;
+        /**
+          * Set when the parent `xpl-tabs` has `disabled` (group-disabled).
+          * @default false
+         */
+        "groupDisabled"?: boolean;
+        /**
+          * Optional icon name for segment-style pills (`type="segment"` on parent `xpl-tabs`). Ignored for default tabs.
+         */
+        "icon"?: string;
+        /**
+          * Icon position for segment-style pills.
+          * @default 'start'
+         */
+        "iconPosition"?: 'start' | 'end';
+        /**
+          * Emitted when this tab is activated (if not disabled). The event `detail` is this tab’s `target` string. Parent `xpl-tabs` listens and updates selection; use `tabChange` on `xpl-tabs` for the group-level event.
          */
         "onTabChange"?: (event: XplTabCustomEvent<string>) => void;
         /**
@@ -4052,15 +5167,25 @@ declare namespace LocalJSX {
         "width"?: number;
     }
     interface XplTabs {
+        /**
+          * Disables the whole tab group (headings, mobile select, and segment pills).
+          * @default false
+         */
+        "disabled"?: boolean;
         /**
           * Whether to make the tabs full width
           * @default false
          */
         "fullWidth"?: boolean;
         /**
-          * Event that emits the target of the selected tab
+          * Emitted when the selected tab changes (click, keyboard, or mobile `xpl-select`). The event `detail` is the selected tab’s `target` string. Always dispatched from this host (including after heading clicks) so `event.target` is consistent for listeners on `xpl-tabs` or bubbling ancestors.
          */
         "onTabChange"?: (event: XplTabsCustomEvent<string>) => void;
+        /**
+          * Visual and layout variant: classic underline tabs or segment (pill) controls.
+          * @default 'tabs'
+         */
+        "type"?: 'tabs' | 'segment';
         /**
           * The selected tab target value, defaults to the first tab
          */
@@ -4068,9 +5193,46 @@ declare namespace LocalJSX {
     }
     interface XplTag {
         /**
-          * Callback function that is called when tag text or `x` icon is clicked
+          * Whether the tag is disabled
+          * @default false
+         */
+        "disabled"?: boolean;
+        /**
+          * Whether the tag shows a dismiss button
+          * @default true
+         */
+        "dismissible"?: boolean;
+        /**
+          * When true, the tag label uses native HTML5 drag (the inner label is the drag source). Named `isDraggable` so the Stencil prop does not collide with the native `HTMLElement.draggable` API. `reflect: false` avoids syncing a `draggable` attribute onto the host; the inner label remains the drag source. Host `onDragStart` still suppresses stray native drags from host chrome.
+          * @default false
+         */
+        "isDraggable"?: boolean;
+        /**
+          * Emitted when the tag is dismissed (content click when `isDraggable` is false, or dismiss button click).
+          * @deprecated Use `tagRemove` for dismiss button clicks only. The `close` event will be removed in a future major version.
+         */
+        "onClose"?: (event: XplTagCustomEvent<void>) => void;
+        /**
+          * Emitted when a drag operation ends. `event.detail`: `{ tagId?, dropped, originalEvent }`. `dropped` is `true` when `dataTransfer.dropEffect === 'move'`. `originalEvent` is the native `DragEvent`; browsers may clear `dataTransfer` after the synchronous handler runs — do not read `originalEvent.dataTransfer.getData(...)` asynchronously.
          */
-        "onClose"?: (event: XplTagCustomEvent<any>) => void;
+        "onTagDragEnd"?: (event: XplTagCustomEvent<TagDragEndDetail>) => void;
+        /**
+          * Emitted when a drag operation starts (native `dragstart` on the inner label). `event.detail`: `{ tagId?, content, originalEvent }`. `originalEvent` is the native `DragEvent`; browsers may clear `dataTransfer` after the synchronous handler runs — do not read `originalEvent.dataTransfer.getData(...)` asynchronously.
+         */
+        "onTagDragStart"?: (event: XplTagCustomEvent<TagDragStartDetail>) => void;
+        /**
+          * Emitted when the tag dismiss (×) button is clicked
+         */
+        "onTagRemove"?: (event: XplTagCustomEvent<void>) => void;
+        /**
+          * The size of the tag
+          * @default 'default'
+         */
+        "size"?: 'default' | 'sm';
+        /**
+          * Optional stable id for the tag. When set, it is included in `tagDragStart` / `tagDragEnd` detail and written to `dataTransfer` as `application/x-tag-id`.
+         */
+        "tagId"?: string;
     }
     interface XplToast {
         /**
@@ -4159,6 +5321,111 @@ declare namespace LocalJSX {
          */
         "text"?: string;
     }
+    /**
+     * Horizontal top navigation with **`left-aside`** and a **right rail**: **`right-aside`** then **user menu**
+     * (see **`.xpl-top-nav__right-rail`** in `render()`). The account menu uses an internal **`xpl-popover`** (**`bottom-end`**, **`display="menu"`**): built-in trigger uses **`child-account-label`** (prop / attribute) as the label beside a trailing **`chevron-down`** on **`xpl-button`** (**`icon`** / **`iconPosition="end"`**), or **`slot="user-menu-trigger"`** for a custom trigger; panel from **`slot="user-menu"`** (e.g. **`xpl-nav-header-menu`**).
+     * 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).
+     * **`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.
+     * **Theming:** The host always includes Foundation’s **`dark`** class so **`--xpl-*`** purpose tokens under this subtree
+     * resolve to dark-mode values even when the page root is light. Floating overlays (e.g. **`xpl-popover`** / **`xpl-dropdown`**
+     * content teleported outside the host) do not inherit this scope — add **`dark`** on those panels if they should match.
+     * **Layout:** **`right-aside`** and the user-menu region are wrapped internally (**`.xpl-top-nav__right-lead`**, etc.).
+     * Consumers should not add those BEM classes — slot content only.
+     * **Brand logo:** use **`brand-logo`** (URL) for a built-in **`<img>`**, or **`slot="brand-logo"`** for custom markup (e.g. **`xpl-icon`**, SVG). When the URL prop is set, it takes precedence and the slot is not used for the image. On **narrow viewports** (one pixel below Tailwind **`md`** — see **`top-nav.css`**), **`brand-name`** text is hidden in the bar (logo / slot mark only); keep a meaningful **`alt`** on **`brand-logo`** or accessible slotted mark for context.
+     * **Narrow / mobile** (same breakpoint as above): **`slot="left-aside"`** is **hidden** in the bar until **`nav-control`**
+     * is set **and** the drawer is open (floating panel per Figma). **Without **`nav-control`**, there is no mobile drawer** —
+     * primary links remain hidden below **`md`** until the viewport is wide enough for the horizontal bar. The built-in **brand**
+     * stays in the top bar (**hamburger → brand** when **`nav-control`** is set). **`right-aside`** is hidden in the bar on narrow
+     * viewports (**`top-nav.css`**, one pixel below Tailwind **`md`**); duplicate those actions into **`xpl-nav-header-menu`**
+     * **`slot="right-aside-mobile"`** (below profile, above the list; narrow-only CSS in **`top-nav.css`**) per Figma.
+     * **Account menu vs drawer:** Opening the built-in account **`xpl-popover`** while the mobile drawer is open **closes the drawer**
+     * and emits **`navOpen(false)`** so the two layers do not stack.
+     */
+    interface XplTopNav {
+        /**
+          * Destination URL for the brand control when using native navigation (**`<a href>`**). When unset, the brand is a **`role="button"`** control and **`brandClick`** fires on activation instead.
+         */
+        "brandHref"?: string;
+        /**
+          * Optional image URL for the brand mark (leading the brand row, before **`brand-name`** text). When set, renders **`<img class="xpl-top-nav__brand-logo">`** and ignores **`slot="brand-logo"`** for the mark. When unset, use **`slot="brand-logo"`** for custom logo content.
+         */
+        "brandLogo"?: string;
+        /**
+          * Visible product / app name next to **`brand-logo`**. Omit for logo-only; provide **`brand-logo`** and/or this string to show the built-in brand row (**`left-aside`** is then primary nav links only).
+         */
+        "brandName"?: string;
+        /**
+          * Label text for the built-in account menu trigger (shown **before** the **`chevron-down`** icon) when **`slot="user-menu"`** is present and **`slot="user-menu-trigger"`** is not used. When empty or whitespace-only, the trigger shows only the chevron and uses **`aria-label="Open account menu"`** on the button.
+         */
+        "childAccountLabel"?: string;
+        /**
+          * Accessible name for the `<nav>` landmark (maps to `aria-label`). Use a unique label when the page has multiple navigation regions (e.g. side nav + top nav). When unset, defaults to `top-navigation-bar`.
+         */
+        "label"?: string;
+        /**
+          * When true, renders the navigation control (hamburger) for toggling the left slot on small viewports. The control is **hidden from the Tailwind `md` breakpoint up**; collapse/show for **`left-aside`** uses **`max-width: calc(theme('screens.md') - 1px)`** in **`top-nav.css`** (Figma’s 767px at a 16px root and default **`screens.md`**). Reflected to the **`nav-control`** attribute so host updates (framework props) re-run **`@Watch`**: drawer state and document **Escape** handling stay in sync, the host **`xpl-top-nav--nav-control`** class toggles for **`top-nav.css`**, and **`navOpen(false)`** is emitted if **`nav-control`** is cleared while the drawer was open.
+         */
+        "navControl"?: boolean;
+        /**
+          * Emitted when the brand control is activated and **`brandHref`** is **not** set (SPA / in-app navigation). **`detail`** is the **`MouseEvent`** from **`xpl-top-nav-item`** **`navItemClick`**. Not emitted when **`brandHref`** is set (use native link navigation).
+         */
+        "onBrandClick"?: (event: XplTopNavCustomEvent<MouseEvent>) => void;
+        /**
+          * Emitted when the mobile nav open state changes: hamburger toggle, or **Escape** closing the drawer (when **`nav-control`** is set and the bar was open). Detail is the new open state (**`true`** = open, **`false`** = closed).
+         */
+        "onNavOpen"?: (event: XplTopNavCustomEvent<boolean>) => void;
+    }
+    /**
+     * 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
+     * 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
+     * **`xpl-top-nav__brand`** row omits **`listitem`** (it sits in **`.xpl-top-nav__brand-bar`**, not **`.xpl-top-nav__left-primary`**),
+     * 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`**.
+     * **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.
+     * **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 **`xpl-top-nav`**).
+     */
+    interface XplTopNavItem {
+        /**
+          * 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.
+          * @default false
+         */
+        "active"?: boolean;
+        /**
+          * If set without **`slot="dropdown"`**, the inner control renders as a native **`<a href>`** (link mode).
+         */
+        "href"?: string;
+        /**
+          * Icon name from **`@xplortech/apollo-icons`** (shown before the label when **`label`** is set).
+          * @default ''
+         */
+        "icon"?: string;
+        /**
+          * 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.
+         */
+        "itemAriaLabel"?: string;
+        /**
+          * 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.
+         */
+        "label"?: string;
+        /**
+          * 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.
+         */
+        "onNavItemClick"?: (event: XplTopNavItemCustomEvent<MouseEvent>) => void;
+        /**
+          * When true, sets **`aria-current="page"`** and selected styling.
+          * @default false
+         */
+        "selected"?: boolean;
+    }
     interface XplUtilityBar {
         /**
           * @property {boolean} - Optional property that defines whether or not the main nav is open at startup.
@@ -4189,14 +5456,17 @@ declare namespace LocalJSX {
         "isNavOpenAtStartup": boolean;
     }
     interface XplAvatarAttributes {
-        "color": 'green' | 'yellow' | 'pink' | 'primary' | 'secondary';
+        "color": AvatarColor;
         "disabled": boolean;
+        "groupData": AvatarGroupItem[] | string;
         "href": string;
         "name": string;
         "size": 'md' | 'sm';
         "src": string;
-        "status": 'active' | 'warning' | 'inactive';
+        "status": AvatarStatus;
+        "subText": string;
         "target": string;
+        "variant": AvatarVariant;
     }
     interface XplBackdropAttributes {
         "relative": boolean;
@@ -4251,6 +5521,7 @@ declare namespace LocalJSX {
         "defaultDate": string;
     }
     interface XplCheckboxAttributes {
+        "ariaLabel": string;
         "checked": boolean;
         "description": string;
         "disabled": boolean;
@@ -4294,6 +5565,7 @@ declare namespace LocalJSX {
         "closeOnSelect": boolean;
         "mode": 'single' | 'multi';
         "anchorToTrigger": boolean;
+        "placement": Placement;
         "selectedValues": string | string[];
         "selectOnFocus": boolean;
         "triggerId": string;
@@ -4368,7 +5640,17 @@ declare namespace LocalJSX {
         "hideEyeDropper": boolean;
         "defaultCountry": string;
         "isInternational": boolean;
-        "type": 'date' | 'time' | 'text' | 'number' | 'password' | 'file' | 'color' | 'phone';
+        "ariaLabel": string;
+        "shape": 'rounded' | 'box';
+        "type": | 'date'
+        | 'time'
+        | 'text'
+        | 'number'
+        | 'password'
+        | 'file'
+        | 'color'
+        | 'phone'
+        | 'search';
     }
     interface XplInputColorAttributes {
         "value": string;
@@ -4413,6 +5695,21 @@ declare namespace LocalJSX {
         "required": boolean;
         "value": string;
     }
+    interface XplInputSearchAttributes {
+        "ariaLabel": string;
+        "autocomplete": string;
+        "disabled": boolean;
+        "errorMessageId": string;
+        "hasError": boolean;
+        "hasVisibleLabel": boolean;
+        "inputId": string;
+        "name": string;
+        "placeholder": string;
+        "readonly": boolean;
+        "required": boolean;
+        "shape": 'rounded' | 'box';
+        "value": string;
+    }
     interface XplInputTimeAttributes {
         "inputId": string;
         "disabled": boolean;
@@ -4433,6 +5730,26 @@ declare namespace LocalJSX {
         "name": string;
         "description": string;
     }
+    interface XplListAttributes {
+        "label": string;
+        "labelledBy": string;
+        "reorderable": boolean;
+        "selectable": boolean;
+    }
+    interface XplListItemAttributes {
+        "disabled": boolean;
+        "error": boolean;
+        "hidden": boolean;
+        "href": string;
+        "itemId": string;
+        "keyboardActive": boolean;
+        "radioName": string;
+        "reorderable": boolean;
+        "selectable": boolean;
+        "selected": boolean;
+        "showDivider": boolean;
+        "titleBadgeVariant": BadgeVariantProp;
+    }
     interface XplMainNavAttributes {
         "width": 'default' | 'md' | 'sm';
     }
@@ -4441,6 +5758,10 @@ declare namespace LocalJSX {
         "size": 'large' | 'medium' | 'small';
         "variant": 'default' | 'warning';
     }
+    interface XplNavHeaderMenuAttributes {
+        "email": string;
+        "username": string;
+    }
     interface XplNavItemAttributes {
         "navControl": boolean;
     }
@@ -4461,9 +5782,6 @@ declare namespace LocalJSX {
         "position": PopoverPosition;
         "display": 'arrow' | 'menu';
     }
-    interface XplProgressAttributes {
-        "currentStep": number;
-    }
     interface XplProgressBarAttributes {
         "helperText": string;
         "label": string;
@@ -4472,6 +5790,12 @@ declare namespace LocalJSX {
         "value": number;
         "variant": 'default' | 'success' | 'error' | 'indeterminate';
     }
+    interface XplProgressIndicatorAttributes {
+        "currentStep": number;
+        "layout": 'horizontal' | 'vertical';
+        "showLabels": boolean;
+        "showNumbers": boolean;
+    }
     interface XplRadioAttributes {
         "checked": boolean;
         "description": string;
@@ -4485,6 +5809,7 @@ declare namespace LocalJSX {
         "selectIcon": string;
         "description": string;
         "disabled": boolean;
+        "dropdownPlacement": Placement;
         "error": string;
         "label": string;
         "mode": 'single' | 'multi';
@@ -4530,13 +5855,33 @@ declare namespace LocalJSX {
         "variant": 'default' | 'warning';
         "showFooter": boolean;
     }
-    interface XplTabAttributes {
+    interface XplSpotlightAttributes {
+        "actionLayout": SpotlightActionLayout;
+        "anchorPosition": SpotlightAnchorPosition;
+        "body": string;
+        "currentStep": number;
+        "heading": string;
+        "isDismissible": boolean;
+        "isOpen": boolean;
+        "primaryActionLabel": string;
+        "secondaryActionLabel": string;
+        "showActions": boolean;
+        "showImage": boolean;
+        "showSteps": boolean;
         "target": string;
+        "totalSteps": number;
+    }
+    interface XplTabAttributes {
+        "disabled": boolean;
+        "groupDisabled": boolean;
+        "icon": string;
+        "iconPosition": 'start' | 'end';
         "selected": boolean;
+        "target": string;
     }
     interface XplTabPanelAttributes {
-        "target": string;
         "selected": boolean;
+        "target": string;
     }
     interface XplTableAttributes {
         "freeze": boolean;
@@ -4552,8 +5897,17 @@ declare namespace LocalJSX {
         "width": number;
     }
     interface XplTabsAttributes {
-        "value": string;
+        "disabled": boolean;
         "fullWidth": boolean;
+        "type": 'tabs' | 'segment';
+        "value": string;
+    }
+    interface XplTagAttributes {
+        "disabled": boolean;
+        "dismissible": boolean;
+        "isDraggable": boolean;
+        "size": 'default' | 'sm';
+        "tagId": string;
     }
     interface XplToastAttributes {
         "variant": 'neutral' | 'warning' | 'success';
@@ -4586,6 +5940,22 @@ declare namespace LocalJSX {
         | 'bottom-right';
         "hideArrow": boolean;
     }
+    interface XplTopNavAttributes {
+        "brandHref": string;
+        "brandLogo": string;
+        "brandName": string;
+        "childAccountLabel": string;
+        "label": string;
+        "navControl": boolean;
+    }
+    interface XplTopNavItemAttributes {
+        "active": boolean;
+        "href": string;
+        "icon": string;
+        "itemAriaLabel": string;
+        "label": string;
+        "selected": boolean;
+    }
     interface XplUtilityBarAttributes {
         "navControl": boolean;
         "isNavOpenAtStartup": boolean;
@@ -4625,17 +5995,20 @@ declare namespace LocalJSX {
         "xpl-input-date": Omit<XplInputDate, keyof XplInputDateAttributes> & { [K in keyof XplInputDate & keyof XplInputDateAttributes]?: XplInputDate[K] } & { [K in keyof XplInputDate & keyof XplInputDateAttributes as `attr:${K}`]?: XplInputDateAttributes[K] } & { [K in keyof XplInputDate & keyof XplInputDateAttributes as `prop:${K}`]?: XplInputDate[K] };
         "xpl-input-file": Omit<XplInputFile, keyof XplInputFileAttributes> & { [K in keyof XplInputFile & keyof XplInputFileAttributes]?: XplInputFile[K] } & { [K in keyof XplInputFile & keyof XplInputFileAttributes as `attr:${K}`]?: XplInputFileAttributes[K] } & { [K in keyof XplInputFile & keyof XplInputFileAttributes as `prop:${K}`]?: XplInputFile[K] };
         "xpl-input-phone": Omit<XplInputPhone, keyof XplInputPhoneAttributes> & { [K in keyof XplInputPhone & keyof XplInputPhoneAttributes]?: XplInputPhone[K] } & { [K in keyof XplInputPhone & keyof XplInputPhoneAttributes as `attr:${K}`]?: XplInputPhoneAttributes[K] } & { [K in keyof XplInputPhone & keyof XplInputPhoneAttributes as `prop:${K}`]?: XplInputPhone[K] };
+        "xpl-input-search": Omit<XplInputSearch, keyof XplInputSearchAttributes> & { [K in keyof XplInputSearch & keyof XplInputSearchAttributes]?: XplInputSearch[K] } & { [K in keyof XplInputSearch & keyof XplInputSearchAttributes as `attr:${K}`]?: XplInputSearchAttributes[K] } & { [K in keyof XplInputSearch & keyof XplInputSearchAttributes as `prop:${K}`]?: XplInputSearch[K] } & OneOf<"inputId", XplInputSearch["inputId"], XplInputSearchAttributes["inputId"]>;
         "xpl-input-time": Omit<XplInputTime, keyof XplInputTimeAttributes> & { [K in keyof XplInputTime & keyof XplInputTimeAttributes]?: XplInputTime[K] } & { [K in keyof XplInputTime & keyof XplInputTimeAttributes as `attr:${K}`]?: XplInputTimeAttributes[K] } & { [K in keyof XplInputTime & keyof XplInputTimeAttributes as `prop:${K}`]?: XplInputTime[K] };
         "xpl-large-card": Omit<XplLargeCard, keyof XplLargeCardAttributes> & { [K in keyof XplLargeCard & keyof XplLargeCardAttributes]?: XplLargeCard[K] } & { [K in keyof XplLargeCard & keyof XplLargeCardAttributes as `attr:${K}`]?: XplLargeCardAttributes[K] } & { [K in keyof XplLargeCard & keyof XplLargeCardAttributes as `prop:${K}`]?: XplLargeCard[K] };
-        "xpl-list": XplList;
+        "xpl-list": Omit<XplList, keyof XplListAttributes> & { [K in keyof XplList & keyof XplListAttributes]?: XplList[K] } & { [K in keyof XplList & keyof XplListAttributes as `attr:${K}`]?: XplListAttributes[K] } & { [K in keyof XplList & keyof XplListAttributes as `prop:${K}`]?: XplList[K] };
+        "xpl-list-item": Omit<XplListItem, keyof XplListItemAttributes> & { [K in keyof XplListItem & keyof XplListItemAttributes]?: XplListItem[K] } & { [K in keyof XplListItem & keyof XplListItemAttributes as `attr:${K}`]?: XplListItemAttributes[K] } & { [K in keyof XplListItem & keyof XplListItemAttributes as `prop:${K}`]?: XplListItem[K] };
         "xpl-main-nav": Omit<XplMainNav, keyof XplMainNavAttributes> & { [K in keyof XplMainNav & keyof XplMainNavAttributes]?: XplMainNav[K] } & { [K in keyof XplMainNav & keyof XplMainNavAttributes as `attr:${K}`]?: XplMainNavAttributes[K] } & { [K in keyof XplMainNav & keyof XplMainNavAttributes as `prop:${K}`]?: XplMainNav[K] };
         "xpl-modal": Omit<XplModal, keyof XplModalAttributes> & { [K in keyof XplModal & keyof XplModalAttributes]?: XplModal[K] } & { [K in keyof XplModal & keyof XplModalAttributes as `attr:${K}`]?: XplModalAttributes[K] } & { [K in keyof XplModal & keyof XplModalAttributes as `prop:${K}`]?: XplModal[K] };
+        "xpl-nav-header-menu": Omit<XplNavHeaderMenu, keyof XplNavHeaderMenuAttributes> & { [K in keyof XplNavHeaderMenu & keyof XplNavHeaderMenuAttributes]?: XplNavHeaderMenu[K] } & { [K in keyof XplNavHeaderMenu & keyof XplNavHeaderMenuAttributes as `attr:${K}`]?: XplNavHeaderMenuAttributes[K] } & { [K in keyof XplNavHeaderMenu & keyof XplNavHeaderMenuAttributes as `prop:${K}`]?: XplNavHeaderMenu[K] };
         "xpl-nav-item": Omit<XplNavItem, keyof XplNavItemAttributes> & { [K in keyof XplNavItem & keyof XplNavItemAttributes]?: XplNavItem[K] } & { [K in keyof XplNavItem & keyof XplNavItemAttributes as `attr:${K}`]?: XplNavItemAttributes[K] } & { [K in keyof XplNavItem & keyof XplNavItemAttributes as `prop:${K}`]?: XplNavItem[K] };
         "xpl-pagination": Omit<XplPagination, keyof XplPaginationAttributes> & { [K in keyof XplPagination & keyof XplPaginationAttributes]?: XplPagination[K] } & { [K in keyof XplPagination & keyof XplPaginationAttributes as `attr:${K}`]?: XplPaginationAttributes[K] } & { [K in keyof XplPagination & keyof XplPaginationAttributes as `prop:${K}`]?: XplPagination[K] };
         "xpl-panel": Omit<XplPanel, keyof XplPanelAttributes> & { [K in keyof XplPanel & keyof XplPanelAttributes]?: XplPanel[K] } & { [K in keyof XplPanel & keyof XplPanelAttributes as `attr:${K}`]?: XplPanelAttributes[K] } & { [K in keyof XplPanel & keyof XplPanelAttributes as `prop:${K}`]?: XplPanel[K] };
         "xpl-popover": Omit<XplPopover, keyof XplPopoverAttributes> & { [K in keyof XplPopover & keyof XplPopoverAttributes]?: XplPopover[K] } & { [K in keyof XplPopover & keyof XplPopoverAttributes as `attr:${K}`]?: XplPopoverAttributes[K] } & { [K in keyof XplPopover & keyof XplPopoverAttributes as `prop:${K}`]?: XplPopover[K] };
-        "xpl-progress": Omit<XplProgress, keyof XplProgressAttributes> & { [K in keyof XplProgress & keyof XplProgressAttributes]?: XplProgress[K] } & { [K in keyof XplProgress & keyof XplProgressAttributes as `attr:${K}`]?: XplProgressAttributes[K] } & { [K in keyof XplProgress & keyof XplProgressAttributes as `prop:${K}`]?: XplProgress[K] };
         "xpl-progress-bar": Omit<XplProgressBar, keyof XplProgressBarAttributes> & { [K in keyof XplProgressBar & keyof XplProgressBarAttributes]?: XplProgressBar[K] } & { [K in keyof XplProgressBar & keyof XplProgressBarAttributes as `attr:${K}`]?: XplProgressBarAttributes[K] } & { [K in keyof XplProgressBar & keyof XplProgressBarAttributes as `prop:${K}`]?: XplProgressBar[K] };
+        "xpl-progress-indicator": Omit<XplProgressIndicator, keyof XplProgressIndicatorAttributes> & { [K in keyof XplProgressIndicator & keyof XplProgressIndicatorAttributes]?: XplProgressIndicator[K] } & { [K in keyof XplProgressIndicator & keyof XplProgressIndicatorAttributes as `attr:${K}`]?: XplProgressIndicatorAttributes[K] } & { [K in keyof XplProgressIndicator & keyof XplProgressIndicatorAttributes as `prop:${K}`]?: XplProgressIndicator[K] };
         "xpl-radio": Omit<XplRadio, keyof XplRadioAttributes> & { [K in keyof XplRadio & keyof XplRadioAttributes]?: XplRadio[K] } & { [K in keyof XplRadio & keyof XplRadioAttributes as `attr:${K}`]?: XplRadioAttributes[K] } & { [K in keyof XplRadio & keyof XplRadioAttributes as `prop:${K}`]?: XplRadio[K] };
         "xpl-secondary-nav": XplSecondaryNav;
         "xpl-select": Omit<XplSelect, keyof XplSelectAttributes> & { [K in keyof XplSelect & keyof XplSelectAttributes]?: XplSelect[K] } & { [K in keyof XplSelect & keyof XplSelectAttributes as `attr:${K}`]?: XplSelectAttributes[K] } & { [K in keyof XplSelect & keyof XplSelectAttributes as `prop:${K}`]?: XplSelect[K] };
@@ -4643,17 +6016,20 @@ declare namespace LocalJSX {
         "xpl-side-nav-item": Omit<XplSideNavItem, keyof XplSideNavItemAttributes> & { [K in keyof XplSideNavItem & keyof XplSideNavItemAttributes]?: XplSideNavItem[K] } & { [K in keyof XplSideNavItem & keyof XplSideNavItemAttributes as `attr:${K}`]?: XplSideNavItemAttributes[K] } & { [K in keyof XplSideNavItem & keyof XplSideNavItemAttributes as `prop:${K}`]?: XplSideNavItem[K] };
         "xpl-skeleton": Omit<XplSkeleton, keyof XplSkeletonAttributes> & { [K in keyof XplSkeleton & keyof XplSkeletonAttributes]?: XplSkeleton[K] } & { [K in keyof XplSkeleton & keyof XplSkeletonAttributes as `attr:${K}`]?: XplSkeletonAttributes[K] } & { [K in keyof XplSkeleton & keyof XplSkeletonAttributes as `prop:${K}`]?: XplSkeleton[K] };
         "xpl-slideout": Omit<XplSlideout, keyof XplSlideoutAttributes> & { [K in keyof XplSlideout & keyof XplSlideoutAttributes]?: XplSlideout[K] } & { [K in keyof XplSlideout & keyof XplSlideoutAttributes as `attr:${K}`]?: XplSlideoutAttributes[K] } & { [K in keyof XplSlideout & keyof XplSlideoutAttributes as `prop:${K}`]?: XplSlideout[K] };
+        "xpl-spotlight": Omit<XplSpotlight, keyof XplSpotlightAttributes> & { [K in keyof XplSpotlight & keyof XplSpotlightAttributes]?: XplSpotlight[K] } & { [K in keyof XplSpotlight & keyof XplSpotlightAttributes as `attr:${K}`]?: XplSpotlightAttributes[K] } & { [K in keyof XplSpotlight & keyof XplSpotlightAttributes as `prop:${K}`]?: XplSpotlight[K] };
         "xpl-tab": Omit<XplTab, keyof XplTabAttributes> & { [K in keyof XplTab & keyof XplTabAttributes]?: XplTab[K] } & { [K in keyof XplTab & keyof XplTabAttributes as `attr:${K}`]?: XplTabAttributes[K] } & { [K in keyof XplTab & keyof XplTabAttributes as `prop:${K}`]?: XplTab[K] };
         "xpl-tab-panel": Omit<XplTabPanel, keyof XplTabPanelAttributes> & { [K in keyof XplTabPanel & keyof XplTabPanelAttributes]?: XplTabPanel[K] } & { [K in keyof XplTabPanel & keyof XplTabPanelAttributes as `attr:${K}`]?: XplTabPanelAttributes[K] } & { [K in keyof XplTabPanel & keyof XplTabPanelAttributes as `prop:${K}`]?: XplTabPanel[K] };
         "xpl-table": Omit<XplTable, keyof XplTableAttributes> & { [K in keyof XplTable & keyof XplTableAttributes]?: XplTable[K] } & { [K in keyof XplTable & keyof XplTableAttributes as `attr:${K}`]?: XplTableAttributes[K] } & { [K in keyof XplTable & keyof XplTableAttributes as `prop:${K}`]?: XplTable[K] };
         "xpl-table-header": XplTableHeader;
         "xpl-table-header-cell": Omit<XplTableHeaderCell, keyof XplTableHeaderCellAttributes> & { [K in keyof XplTableHeaderCell & keyof XplTableHeaderCellAttributes]?: XplTableHeaderCell[K] } & { [K in keyof XplTableHeaderCell & keyof XplTableHeaderCellAttributes as `attr:${K}`]?: XplTableHeaderCellAttributes[K] } & { [K in keyof XplTableHeaderCell & keyof XplTableHeaderCellAttributes as `prop:${K}`]?: XplTableHeaderCell[K] };
         "xpl-tabs": Omit<XplTabs, keyof XplTabsAttributes> & { [K in keyof XplTabs & keyof XplTabsAttributes]?: XplTabs[K] } & { [K in keyof XplTabs & keyof XplTabsAttributes as `attr:${K}`]?: XplTabsAttributes[K] } & { [K in keyof XplTabs & keyof XplTabsAttributes as `prop:${K}`]?: XplTabs[K] };
-        "xpl-tag": XplTag;
+        "xpl-tag": Omit<XplTag, keyof XplTagAttributes> & { [K in keyof XplTag & keyof XplTagAttributes]?: XplTag[K] } & { [K in keyof XplTag & keyof XplTagAttributes as `attr:${K}`]?: XplTagAttributes[K] } & { [K in keyof XplTag & keyof XplTagAttributes as `prop:${K}`]?: XplTag[K] };
         "xpl-toast": Omit<XplToast, keyof XplToastAttributes> & { [K in keyof XplToast & keyof XplToastAttributes]?: XplToast[K] } & { [K in keyof XplToast & keyof XplToastAttributes as `attr:${K}`]?: XplToastAttributes[K] } & { [K in keyof XplToast & keyof XplToastAttributes as `prop:${K}`]?: XplToast[K] };
         "xpl-toggle": Omit<XplToggle, keyof XplToggleAttributes> & { [K in keyof XplToggle & keyof XplToggleAttributes]?: XplToggle[K] } & { [K in keyof XplToggle & keyof XplToggleAttributes as `attr:${K}`]?: XplToggleAttributes[K] } & { [K in keyof XplToggle & keyof XplToggleAttributes as `prop:${K}`]?: XplToggle[K] };
         "xpl-toolbar": Omit<XplToolbar, keyof XplToolbarAttributes> & { [K in keyof XplToolbar & keyof XplToolbarAttributes]?: XplToolbar[K] } & { [K in keyof XplToolbar & keyof XplToolbarAttributes as `attr:${K}`]?: XplToolbarAttributes[K] } & { [K in keyof XplToolbar & keyof XplToolbarAttributes as `prop:${K}`]?: XplToolbar[K] };
         "xpl-tooltip": Omit<XplTooltip, keyof XplTooltipAttributes> & { [K in keyof XplTooltip & keyof XplTooltipAttributes]?: XplTooltip[K] } & { [K in keyof XplTooltip & keyof XplTooltipAttributes as `attr:${K}`]?: XplTooltipAttributes[K] } & { [K in keyof XplTooltip & keyof XplTooltipAttributes as `prop:${K}`]?: XplTooltip[K] };
+        "xpl-top-nav": Omit<XplTopNav, keyof XplTopNavAttributes> & { [K in keyof XplTopNav & keyof XplTopNavAttributes]?: XplTopNav[K] } & { [K in keyof XplTopNav & keyof XplTopNavAttributes as `attr:${K}`]?: XplTopNavAttributes[K] } & { [K in keyof XplTopNav & keyof XplTopNavAttributes as `prop:${K}`]?: XplTopNav[K] };
+        "xpl-top-nav-item": Omit<XplTopNavItem, keyof XplTopNavItemAttributes> & { [K in keyof XplTopNavItem & keyof XplTopNavItemAttributes]?: XplTopNavItem[K] } & { [K in keyof XplTopNavItem & keyof XplTopNavItemAttributes as `attr:${K}`]?: XplTopNavItemAttributes[K] } & { [K in keyof XplTopNavItem & keyof XplTopNavItemAttributes as `prop:${K}`]?: XplTopNavItem[K] };
         "xpl-utility-bar": Omit<XplUtilityBar, keyof XplUtilityBarAttributes> & { [K in keyof XplUtilityBar & keyof XplUtilityBarAttributes]?: XplUtilityBar[K] } & { [K in keyof XplUtilityBar & keyof XplUtilityBarAttributes as `attr:${K}`]?: XplUtilityBarAttributes[K] } & { [K in keyof XplUtilityBar & keyof XplUtilityBarAttributes as `prop:${K}`]?: XplUtilityBar[K] };
     }
 }
@@ -4697,11 +6073,32 @@ declare module "@stencil/core" {
              */
             "xpl-input-file": LocalJSX.IntrinsicElements["xpl-input-file"] & JSXBase.HTMLAttributes<HTMLXplInputFileElement>;
             "xpl-input-phone": LocalJSX.IntrinsicElements["xpl-input-phone"] & JSXBase.HTMLAttributes<HTMLXplInputPhoneElement>;
+            "xpl-input-search": LocalJSX.IntrinsicElements["xpl-input-search"] & JSXBase.HTMLAttributes<HTMLXplInputSearchElement>;
             "xpl-input-time": LocalJSX.IntrinsicElements["xpl-input-time"] & JSXBase.HTMLAttributes<HTMLXplInputTimeElement>;
             "xpl-large-card": LocalJSX.IntrinsicElements["xpl-large-card"] & JSXBase.HTMLAttributes<HTMLXplLargeCardElement>;
             "xpl-list": LocalJSX.IntrinsicElements["xpl-list"] & JSXBase.HTMLAttributes<HTMLXplListElement>;
+            "xpl-list-item": LocalJSX.IntrinsicElements["xpl-list-item"] & JSXBase.HTMLAttributes<HTMLXplListItemElement>;
             "xpl-main-nav": LocalJSX.IntrinsicElements["xpl-main-nav"] & JSXBase.HTMLAttributes<HTMLXplMainNavElement>;
             "xpl-modal": LocalJSX.IntrinsicElements["xpl-modal"] & JSXBase.HTMLAttributes<HTMLXplModalElement>;
+            /**
+             * Profile / account block (username, email, default slot for **`xpl-top-nav-item`** / **`xpl-divider`**).
+             * Tag **`xpl-nav-header-menu`**; implementation folder **`xpl-nav-header-menu`**. **`.xpl-nav-header-menu__slot`** is
+             * **`role="list"`** for slotted **`xpl-top-nav-item`** (**`role="listitem"`**).
+             * **Slotted content:** do not add **`xpl-nav-header-menu__*`** BEM classes on nodes you pass into the default slot —
+             * profile, list shell, and **`xpl-top-nav-item`** **`role="listitem"`** are handled by the component. Use
+             * **`xpl-top-nav-item`** (or plain elements that are not Apollo **`xpl-*`** BEM hooks) in the slot only.
+             * **`slot="right-aside-mobile"`** — optional block **between** the profile header and the default-slot list (e.g. narrow-only
+             * duplicate of **every** **`slot="right-aside"`** control per Figma when **`xpl-top-nav`** hides **`right-aside`** on narrow viewports (always)).
+             * Not **`role="list"`**; use **`xpl-button`** / **`xpl-top-nav-item`** as needed. Shown only on **narrow viewports** (one pixel below Tailwind **`md`** — **`top-nav.css`**) so bar actions stay in **`slot="right-aside"`** on wider viewports.
+             * Light-DOM **`slotchange`** is unreliable; a host **`MutationObserver`** (child / subtree / **`slot`** attribute) keeps
+             * **`xpl-nav-header-menu--has-right-aside-mobile`** in sync when nodes are added or retargeted after mount (same pattern as **`xpl-top-nav`**).
+             * Stencil **`newSpecPage`** / mock-doc does not define **`MutationObserver`**; slot presence still updates on the next
+             * deferred flush (**`setTimeout(0)`** coalesced with **`componentDidRender`**). In real browsers the observer handles child /
+             * **`slot`** mutations without stacking uncancellable microtasks.
+             * **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 (same contract as **`xpl-top-nav`** / **`xpl-top-nav-item`**).
+             */
+            "xpl-nav-header-menu": LocalJSX.IntrinsicElements["xpl-nav-header-menu"] & JSXBase.HTMLAttributes<HTMLXplNavHeaderMenuElement>;
             "xpl-nav-item": LocalJSX.IntrinsicElements["xpl-nav-item"] & JSXBase.HTMLAttributes<HTMLXplNavItemElement>;
             "xpl-pagination": LocalJSX.IntrinsicElements["xpl-pagination"] & JSXBase.HTMLAttributes<HTMLXplPaginationElement>;
             /**
@@ -4710,8 +6107,8 @@ declare module "@stencil/core" {
              */
             "xpl-panel": LocalJSX.IntrinsicElements["xpl-panel"] & JSXBase.HTMLAttributes<HTMLXplPanelElement>;
             "xpl-popover": LocalJSX.IntrinsicElements["xpl-popover"] & JSXBase.HTMLAttributes<HTMLXplPopoverElement>;
-            "xpl-progress": LocalJSX.IntrinsicElements["xpl-progress"] & JSXBase.HTMLAttributes<HTMLXplProgressElement>;
             "xpl-progress-bar": LocalJSX.IntrinsicElements["xpl-progress-bar"] & JSXBase.HTMLAttributes<HTMLXplProgressBarElement>;
+            "xpl-progress-indicator": LocalJSX.IntrinsicElements["xpl-progress-indicator"] & JSXBase.HTMLAttributes<HTMLXplProgressIndicatorElement>;
             "xpl-radio": LocalJSX.IntrinsicElements["xpl-radio"] & JSXBase.HTMLAttributes<HTMLXplRadioElement>;
             "xpl-secondary-nav": LocalJSX.IntrinsicElements["xpl-secondary-nav"] & JSXBase.HTMLAttributes<HTMLXplSecondaryNavElement>;
             "xpl-select": LocalJSX.IntrinsicElements["xpl-select"] & JSXBase.HTMLAttributes<HTMLXplSelectElement>;
@@ -4719,6 +6116,7 @@ declare module "@stencil/core" {
             "xpl-side-nav-item": LocalJSX.IntrinsicElements["xpl-side-nav-item"] & JSXBase.HTMLAttributes<HTMLXplSideNavItemElement>;
             "xpl-skeleton": LocalJSX.IntrinsicElements["xpl-skeleton"] & JSXBase.HTMLAttributes<HTMLXplSkeletonElement>;
             "xpl-slideout": LocalJSX.IntrinsicElements["xpl-slideout"] & JSXBase.HTMLAttributes<HTMLXplSlideoutElement>;
+            "xpl-spotlight": LocalJSX.IntrinsicElements["xpl-spotlight"] & JSXBase.HTMLAttributes<HTMLXplSpotlightElement>;
             "xpl-tab": LocalJSX.IntrinsicElements["xpl-tab"] & JSXBase.HTMLAttributes<HTMLXplTabElement>;
             "xpl-tab-panel": LocalJSX.IntrinsicElements["xpl-tab-panel"] & JSXBase.HTMLAttributes<HTMLXplTabPanelElement>;
             "xpl-table": LocalJSX.IntrinsicElements["xpl-table"] & JSXBase.HTMLAttributes<HTMLXplTableElement>;
@@ -4730,6 +6128,46 @@ declare module "@stencil/core" {
             "xpl-toggle": LocalJSX.IntrinsicElements["xpl-toggle"] & JSXBase.HTMLAttributes<HTMLXplToggleElement>;
             "xpl-toolbar": LocalJSX.IntrinsicElements["xpl-toolbar"] & JSXBase.HTMLAttributes<HTMLXplToolbarElement>;
             "xpl-tooltip": LocalJSX.IntrinsicElements["xpl-tooltip"] & JSXBase.HTMLAttributes<HTMLXplTooltipElement>;
+            /**
+             * Horizontal top navigation with **`left-aside`** and a **right rail**: **`right-aside`** then **user menu**
+             * (see **`.xpl-top-nav__right-rail`** in `render()`). The account menu uses an internal **`xpl-popover`** (**`bottom-end`**, **`display="menu"`**): built-in trigger uses **`child-account-label`** (prop / attribute) as the label beside a trailing **`chevron-down`** on **`xpl-button`** (**`icon`** / **`iconPosition="end"`**), or **`slot="user-menu-trigger"`** for a custom trigger; panel from **`slot="user-menu"`** (e.g. **`xpl-nav-header-menu`**).
+             * 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).
+             * **`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.
+             * **Theming:** The host always includes Foundation’s **`dark`** class so **`--xpl-*`** purpose tokens under this subtree
+             * resolve to dark-mode values even when the page root is light. Floating overlays (e.g. **`xpl-popover`** / **`xpl-dropdown`**
+             * content teleported outside the host) do not inherit this scope — add **`dark`** on those panels if they should match.
+             * **Layout:** **`right-aside`** and the user-menu region are wrapped internally (**`.xpl-top-nav__right-lead`**, etc.).
+             * Consumers should not add those BEM classes — slot content only.
+             * **Brand logo:** use **`brand-logo`** (URL) for a built-in **`<img>`**, or **`slot="brand-logo"`** for custom markup (e.g. **`xpl-icon`**, SVG). When the URL prop is set, it takes precedence and the slot is not used for the image. On **narrow viewports** (one pixel below Tailwind **`md`** — see **`top-nav.css`**), **`brand-name`** text is hidden in the bar (logo / slot mark only); keep a meaningful **`alt`** on **`brand-logo`** or accessible slotted mark for context.
+             * **Narrow / mobile** (same breakpoint as above): **`slot="left-aside"`** is **hidden** in the bar until **`nav-control`**
+             * is set **and** the drawer is open (floating panel per Figma). **Without **`nav-control`**, there is no mobile drawer** —
+             * primary links remain hidden below **`md`** until the viewport is wide enough for the horizontal bar. The built-in **brand**
+             * stays in the top bar (**hamburger → brand** when **`nav-control`** is set). **`right-aside`** is hidden in the bar on narrow
+             * viewports (**`top-nav.css`**, one pixel below Tailwind **`md`**); duplicate those actions into **`xpl-nav-header-menu`**
+             * **`slot="right-aside-mobile"`** (below profile, above the list; narrow-only CSS in **`top-nav.css`**) per Figma.
+             * **Account menu vs drawer:** Opening the built-in account **`xpl-popover`** while the mobile drawer is open **closes the drawer**
+             * and emits **`navOpen(false)`** so the two layers do not stack.
+             */
+            "xpl-top-nav": LocalJSX.IntrinsicElements["xpl-top-nav"] & JSXBase.HTMLAttributes<HTMLXplTopNavElement>;
+            /**
+             * 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
+             * 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
+             * **`xpl-top-nav__brand`** row omits **`listitem`** (it sits in **`.xpl-top-nav__brand-bar`**, not **`.xpl-top-nav__left-primary`**),
+             * 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`**.
+             * **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.
+             * **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 **`xpl-top-nav`**).
+             */
+            "xpl-top-nav-item": LocalJSX.IntrinsicElements["xpl-top-nav-item"] & JSXBase.HTMLAttributes<HTMLXplTopNavItemElement>;
             "xpl-utility-bar": LocalJSX.IntrinsicElements["xpl-utility-bar"] & JSXBase.HTMLAttributes<HTMLXplUtilityBarElement>;
         }
     }