@xplortech/apollo-core 2.10.0 → 2.12.0

package/dist/types/components.d.ts

@@ -9,23 +9,30 @@ import { AvatarColor, AvatarGroupItem, AvatarStatus, AvatarVariant } from "./com
 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 { Placement } from "@floating-ui/dom";
+import { Placement } from "./utils/floating";
+import { Event } from "./stencil-public-runtime";
 import { ListItem, XplListOrderChangeDetail } from "./components/xpl-list/listitem";
-import { BadgeVariantProp as BadgeVariantProp1 } from "./components/xpl-badge/xpl-badge";
+import { BadgePalette, BadgeVariantProp as BadgeVariantProp1 } from "./components/xpl-badge/xpl-badge";
 import { PopoverPosition } from "./components/xpl-popover/xpl-popover";
+import { Placement as Placement1 } from "@floating-ui/dom";
 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 { Placement } from "@floating-ui/dom";
+export { Placement } from "./utils/floating";
+export { Event } from "./stencil-public-runtime";
 export { ListItem, XplListOrderChangeDetail } from "./components/xpl-list/listitem";
-export { BadgeVariantProp as BadgeVariantProp1 } from "./components/xpl-badge/xpl-badge";
+export { BadgePalette, BadgeVariantProp as BadgeVariantProp1 } from "./components/xpl-badge/xpl-badge";
 export { PopoverPosition } from "./components/xpl-popover/xpl-popover";
+export { Placement as Placement1 } from "@floating-ui/dom";
 export { SpotlightActionLayout, SpotlightAnchorPosition } from "./components/xpl-spotlight/xpl-spotlight";
 export { TagDragEndDetail, TagDragStartDetail } from "./components/xpl-tag/xpl-tag";
 export namespace Components {
+    /**
+     * @since 2.0.0
+     */
     interface XplAccordion {
         /**
           * set the border of the accordion  none: there’s no border wrapping the header  bottom:there’s a border below the header  bordered: the header is wrapped by a white panel with a rounded border around it on every side
@@ -60,6 +67,9 @@ export namespace Components {
          */
         "size": '1' | '2' | '3';
     }
+    /**
+     * @since 0.5.0
+     */
     interface XplApplicationShell {
         /**
           * @property {boolean} - *
@@ -82,6 +92,9 @@ export namespace Components {
          */
         "withUtility": boolean;
     }
+    /**
+     * @since 0.1.1
+     */
     interface XplAvatar {
         /**
           * Background color when there is no image src
@@ -130,6 +143,9 @@ export namespace Components {
          */
         "variant"?: AvatarVariant;
     }
+    /**
+     * @since 0.1.2
+     */
     interface XplBackdrop {
         /**
           * @property {boolean} - When true, backdrop will have relative position. This is useful when the backdrop doesn't cover the whole view area. If false, the position will be fixed and cover the whole view area.
@@ -137,6 +153,9 @@ export namespace Components {
          */
         "relative": boolean;
     }
+    /**
+     * @since 0.1.1
+     */
     interface XplBadge {
         /**
           * Whether badge shows a bordered ring
@@ -168,6 +187,9 @@ export namespace Components {
          */
         "variant": BadgeVariantProp;
     }
+    /**
+     * @since 2.6.0
+     */
     interface XplBanner {
         /**
           * Primary action label. When provided, an action button is rendered.
@@ -215,6 +237,9 @@ export namespace Components {
     }
     interface XplBreadcrumbs {
     }
+    /**
+     * @since 0.1.1
+     */
     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).
@@ -296,6 +321,9 @@ export namespace Components {
          */
         "variant": 'primary' | 'secondary' | 'tertiary' | 'subtle';
     }
+    /**
+     * @since 0.4.0
+     */
     interface XplButtonRow {
         /**
           * The text for the primary button.
@@ -310,6 +338,9 @@ export namespace Components {
          */
         "tertiary": 'string';
     }
+    /**
+     * @since 2.0.0
+     */
     interface XplCalendar {
         /**
           * Format of the date displayed in the calendar. Default is 'Y-m-d'.
@@ -343,6 +374,9 @@ export namespace Components {
          */
         "setDate": (date: string | string[]) => Promise<void>;
     }
+    /**
+     * @since 0.1.1
+     */
     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.
@@ -386,6 +420,9 @@ export namespace Components {
          */
         "value"?: string;
     }
+    /**
+     * @since 0.1.1
+     */
     interface XplChoicelist {
         /**
           * An array of choices to be displayed in the list. Each choice should be an object with keys: - `checked` [boolean] - whether to pre-check or not - `children` [Choice[]] - an array of child choices (recursive) - `description` [string] - `label` [string]
@@ -413,6 +450,9 @@ export namespace Components {
          */
         "styled"?: boolean;
     }
+    /**
+     * @since 0.1.2
+     */
     interface XplContentArea {
         /**
           * @property {string}  size  - The content-area size.
@@ -420,8 +460,14 @@ export namespace Components {
          */
         "size": 'wide' | 'narrow' | 'full';
     }
+    /**
+     * @since 1.0.0
+     */
     interface XplDashboard {
     }
+    /**
+     * @since 1.0.0
+     */
     interface XplDataCard {
         /**
           * An optional field that typically describes or modifies the small stat
@@ -479,12 +525,18 @@ export namespace Components {
          */
         "variant"?: 'primary' | 'secondary';
     }
+    /**
+     * @since 0.3.0
+     */
     interface XplDivider {
         /**
           * The tier should be an integer between 0 and 3. Tier 0 dividers do not display text, and 1-3 increase in size with each increasing tier.
          */
         "tier"?: number;
     }
+    /**
+     * @since 0.4.0
+     */
     interface XplDropdown {
         /**
           * whether to anchor the dropdown to the trigger element, requires triggerId to be set
@@ -503,7 +555,7 @@ export namespace Components {
         /**
           * called on dropdown option click and keydown events to update isSelected states
          */
-        "handleSelect": (e: any, { component }: { component: XplDropdownOption; }) => Promise<void>;
+        "handleSelect": (e: Event | null, { component }: DropdownSelectContext) => Promise<void>;
         /**
           * text to display as heading
           * @default false
@@ -539,7 +591,7 @@ export namespace Components {
         /**
           * call back function invoked when a selection is made
          */
-        "update"?: (e, { component }: { component: Dropdown }) => void;
+        "update"?: (e: Event | null, context: { component: Dropdown }) => void;
     }
     interface XplDropdownGroup {
         /**
@@ -583,8 +635,14 @@ export namespace Components {
          */
         "value"?: string;
     }
+    /**
+     * @since 1.4.0
+     */
     interface XplDynamicTable {
     }
+    /**
+     * @since 1.3.0
+     */
     interface XplDynamicTableCell {
         /**
           * Whether the cell and its contents are disabled.
@@ -592,6 +650,9 @@ export namespace Components {
          */
         "disabled": boolean;
     }
+    /**
+     * @since 1.3.0
+     */
     interface XplDynamicTableRow {
         /**
           * Whether the row and its cells are disabled.
@@ -604,8 +665,14 @@ export namespace Components {
          */
         "selected": boolean;
     }
+    /**
+     * @since 0.4.0
+     */
     interface XplGrid {
     }
+    /**
+     * @since 0.4.0
+     */
     interface XplGridItem {
         /**
           * The number of columns the element should span  out of a 6 column grid on a  lg size screen
@@ -628,6 +695,9 @@ export namespace Components {
          */
         "xs": number;
     }
+    /**
+     * @since 1.2.0
+     */
     interface XplHeaderAccordion {
         /**
           * The id of the content region controlled by the accordion.
@@ -654,6 +724,9 @@ export namespace Components {
          */
         "selectedCount": number;
     }
+    /**
+     * @since 1.0.0
+     */
     interface XplIcon {
         /**
           * Icon's background color.
@@ -669,6 +742,9 @@ export namespace Components {
          */
         "size": number;
     }
+    /**
+     * @since 0.3.0
+     */
     interface XplInput {
         /**
           * Because `id` is a reserved HTMLElement attribute, we prefix it with an underscore here so that it doesn't get automatically applied to the outer container.  Applies to all input types.
@@ -1135,6 +1211,9 @@ export namespace Components {
          */
         "value"?: string;
     }
+    /**
+     * @since 1.9.1
+     */
     interface XplLargeCard {
         /**
           * Description of the Card
@@ -1149,6 +1228,9 @@ export namespace Components {
          */
         "name": string;
     }
+    /**
+     * @since 0.4.0
+     */
     interface XplList {
         /**
           * 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.
@@ -1240,6 +1322,9 @@ export namespace Components {
          */
         "titleBadgeVariant"?: BadgeVariantProp1;
     }
+    /**
+     * @since 0.1.2
+     */
     interface XplMainNav {
         /**
           * @property {string}  width  - The width of the Main Nav.
@@ -1247,6 +1332,9 @@ export namespace Components {
          */
         "width": 'default' | 'md' | 'sm';
     }
+    /**
+     * @since 1.1.0
+     */
     interface XplModal {
         /**
           * Whether the modal is open.
@@ -1292,6 +1380,9 @@ export namespace Components {
          */
         "username"?: string;
     }
+    /**
+     * @since 0.1.2
+     */
     interface XplNavItem {
         /**
           * @property {boolean} - Whether or not the item should control the main nav state on click
@@ -1299,6 +1390,9 @@ export namespace Components {
          */
         "navControl"?: boolean;
     }
+    /**
+     * @since 0.1.1
+     */
     interface XplPagination {
         /**
           * The current active page (1-based). Marked as mutable so we can update from inside this component.
@@ -1329,6 +1423,7 @@ export namespace Components {
     /**
      * A stateless container that defines a section on a page and can house any
      * type of content. Panels are not dismissible and may contain a top accent.
+     * @since 2.6.0
      */
     interface XplPanel {
         /**
@@ -1342,6 +1437,9 @@ export namespace Components {
          */
         "padding": 'default' | 'tight' | 'loose';
     }
+    /**
+     * @since 2.0.0
+     */
     interface XplPopover {
         /**
           * Whether the popover is disabled or not.
@@ -1364,6 +1462,9 @@ export namespace Components {
          */
         "position": PopoverPosition;
     }
+    /**
+     * @since 2.6.0
+     */
     interface XplProgressBar {
         /**
           * The helper text displayed below the progress bar (recommended for error state)
@@ -1394,6 +1495,9 @@ export namespace Components {
          */
         "variant": 'default' | 'success' | 'error' | 'indeterminate';
     }
+    /**
+     * @since 2.7.0
+     */
     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].
@@ -1420,6 +1524,9 @@ export namespace Components {
          */
         "steps"?: string[];
     }
+    /**
+     * @since 0.1.1
+     */
     interface XplRadio {
         /**
           * Whether the input is "on"
@@ -1454,8 +1561,14 @@ export namespace Components {
          */
         "value"?: string;
     }
+    /**
+     * @since 0.3.0
+     */
     interface XplSecondaryNav {
     }
+    /**
+     * @since 0.4.0
+     */
     interface XplSelect {
         /**
           * An array of choices for the user to choose from. Each choice should be of the form: {   label: string;   href?: string;   value?: string;   isGroupHeading?: boolean;   isSelected?: boolean;   isDisabled?: boolean;   options?: DropdownItem[];   groupName?: string; }
@@ -1481,12 +1594,12 @@ export namespace Components {
         /**
           * Additional placements to try for the options panel when the default `dropdownPlacement` does not fit. Passed to `xpl-dropdown` / Floating UI `flip`.
          */
-        "dropdownFlipFallbackPlacements"?: Placement[];
+        "dropdownFlipFallbackPlacements"?: Placement1[];
         /**
           * 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;
+        "dropdownPlacement": Placement1;
         /**
           * 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.
          */
@@ -1528,8 +1641,8 @@ export namespace Components {
         "truncate"?: boolean;
     }
     /**
-     * Slot-based sidebar for app navigation: a scrollable main `section` and a fixed
-     * `nav-footer`. Compose with `xpl-side-nav-item` for rows.
+     * Slot-based sidebar for app navigation: a scrollable `nav-header` + `section`
+     * area and a fixed `nav-footer`. Compose with `xpl-side-nav-item` for rows.
      * **Mobile (v2):** below the Tailwind `md` breakpoint, the sidebar collapses to a
      * ~56px top bar with a toggle button (`sidebar-left-show` / `sidebar-left-hide`).
      * Activating the toggle opens a drawer containing the `section` + `nav-footer`
@@ -1541,6 +1654,7 @@ export namespace Components {
      * the `openChange` event, and the `toggle()` / `setOpen()` methods.
      * **v2 breaking change (beta):** consumers who wrapped their own mobile toggle
      * around `xpl-side-nav` should remove it — the toggle and drawer are now built in.
+     * @since 2.6.0
      */
     interface XplSideNav {
         /**
@@ -1561,6 +1675,49 @@ export namespace Components {
          */
         "toggle": () => Promise<void>;
     }
+    /**
+     * Header row for `xpl-side-nav`'s `nav-header` slot (Figma `<navHeaderItem>`,
+     * node `51299-9007`). Two types:
+     * - **`product-label` (default)** — a non-interactive `<div>` row that shows the
+     *   current product/area name in a subdued color. No click behavior.
+     * - **`sub-account`** — an interactive `<button>` row (e.g. a location / account
+     *   switcher). Emits `navigate` on activation (pointer click or keyboard); the
+     *   consumer wires this to open a modal or other entity-switching experience.
+     *   When no `slot="trailing"` content is provided, an auto chevron
+     *   (`chevron-expand-y`, a static dual-arrow glyph — no rotation) renders by default.
+     * Both types support `slot="leading"` / `slot="trailing"` (the `icon` prop is a
+     * convenience shorthand for `slot="leading"`, same as `xpl-side-nav-item`) so they
+     * can scale to future uses. Unlike `xpl-side-nav-item`, the leading/trailing
+     * columns are NOT unconditionally reserved — they only render when there is
+     * content, matching the Figma variants where the leading icon is an optional toggle.
+     * **Note on the `sub-account` hover / selected visual:** the interactive row
+     * mirrors `xpl-side-nav-item` — the hover and selected backgrounds fill a single
+     * `__content` pill that wraps the leading icon + label + trailing chevron, with
+     * an 8px (`--xpl-border-radius-default`) radius. The pill insets 8px from the nav
+     * edge (an 8px gutter on the button) so it lines up with the item rows below it,
+     * and hover/selected therefore highlight the whole row content rather than a
+     * partial fragment.
+     */
+    interface XplSideNavHeaderItem {
+        /**
+          * Optional icon name; renders as the default content for `slot="leading"`. When `slot="leading"` content is present, this prop is ignored.
+         */
+        "icon"?: string;
+        /**
+          * The display label for the header item (e.g. the product name or sub-account name).
+         */
+        "label"?: string;
+        /**
+          * Whether the item is currently in a selected state. Only meaningful when `type` is `sub-account` — applies the information-surface pill around the label + trailing chevron.
+          * @default false
+         */
+        "selected": boolean;
+        /**
+          * The header item variant. `product-label` is a static, non-interactive label. `sub-account` is an interactive button that emits `navigate`.
+          * @default 'product-label'
+         */
+        "type": 'product-label' | 'sub-account';
+    }
     /**
      * Navigation row for `xpl-side-nav`. Renders a button (default) or a slot-only
      * anchor container (`link` mode). Three slot positions are available:
@@ -1625,6 +1782,41 @@ export namespace Components {
          */
         "selected": boolean;
     }
+    /**
+     * Grouping / accordion header for `xpl-side-nav`. Wraps nested `xpl-side-nav-item`
+     * (and optional divider separators) elements in the default slot and collapses
+     * them as a unit.
+     * Two variants:
+     * - **Collapsible (default, `collapsible=true`)** — a `<button>` header with a
+     *   chevron (`chevron-right` collapsed / `chevron-down` expanded, no rotation —
+     *   the glyph itself swaps). Click toggles `expanded` and emits `expandedChange`.
+     * - **Static (`collapsible=false`)** — a non-interactive title row with no chevron;
+     *   children are always shown. Used for a static section label (e.g. a future
+     *   product-name / location-changer header).
+     * Unlike `xpl-side-nav-item[has-children]`, section children are **not indented**
+     * — they align with top-level items at the same leading-icon column.
+     * `slot="badge"` renders an optional badge (e.g. `xpl-badge`) in the header title
+     * row. The wrapper is suppressed when the slot is empty.
+     */
+    interface XplSideNavSection {
+        /**
+          * Whether the section can be collapsed/expanded. When `false`, renders a static title (no chevron, not a button) and children are always shown.
+          * @default true
+         */
+        "collapsible": boolean;
+        /**
+          * Whether the section is currently expanded. Only meaningful when `collapsible` is true.
+          * @default false
+         */
+        "expanded": boolean;
+        /**
+          * The section title text. Optional, but when `collapsible` is true and both `heading` and `slot="badge"` lack an accessible name, the toggle `<button>` falls back to `aria-label="Toggle section"` so it always has an accessible name.
+         */
+        "heading"?: string;
+    }
+    /**
+     * @since 2.3.6
+     */
     interface XplSkeleton {
         /**
           * A CSS class name to apply to the component.
@@ -1664,6 +1856,9 @@ export namespace Components {
          */
         "width"?: CSSStyleDeclaration['width'];
     }
+    /**
+     * @since 1.1.0
+     */
     interface XplSlideout {
         /**
           * Whether to show a backdrop behind the slideout.
@@ -1686,6 +1881,9 @@ export namespace Components {
          */
         "variant": 'default' | 'warning';
     }
+    /**
+     * @since 2.7.0
+     */
     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`.
@@ -1755,7 +1953,19 @@ export namespace Components {
          */
         "totalSteps": number;
     }
+    /**
+     * @since 2.3.8
+     */
     interface XplTab {
+        /**
+          * Optional trailing number badge (e.g. a count). Rendered after the label as a compact `xpl-badge` in both underline (`type="tabs"`) and segment (`type="segment"`) tabs. Leave empty to omit the badge.
+         */
+        "badge"?: string;
+        /**
+          * Color palette for the trailing number badge. Only applies when `badge` is set. Defaults to `purple` — the standard number-badge color in the Figma XPL-Tab Group spec.
+          * @default 'purple'
+         */
+        "badgeVariant": BadgePalette;
         /**
           * Disables this tab (pill or underline).
           * @default false
@@ -1780,11 +1990,11 @@ export namespace Components {
          */
         "groupDisabled": boolean;
         /**
-          * Optional icon name for segment-style pills (`type="segment"` on parent `xpl-tabs`). Ignored for default tabs.
+          * Optional leading icon name (from the Apollo icon set). Rendered in both underline (`type="tabs"`) and segment (`type="segment"`) tabs.
          */
         "icon"?: string;
         /**
-          * Icon position for segment-style pills.
+          * Icon position relative to the label. Applies to both underline and segment tabs.
           * @default 'start'
          */
         "iconPosition": 'start' | 'end';
@@ -1807,6 +2017,9 @@ export namespace Components {
          */
         "variant": 'tabs' | 'segment';
     }
+    /**
+     * @since 2.3.8
+     */
     interface XplTabPanel {
         /**
           * Whether the panel is selected
@@ -1818,6 +2031,9 @@ export namespace Components {
          */
         "target": string;
     }
+    /**
+     * @since 0.1.1
+     */
     interface XplTable {
         /**
           * The header values for each column.
@@ -1839,7 +2055,7 @@ export namespace Components {
           * Toggles to show the sort button on each table head
           * @default false
          */
-        "isSortable"?: boolean;
+        "isSortable": boolean;
         /**
           * Toggles a selectable checkbox for each row in the table
          */
@@ -1848,19 +2064,25 @@ export namespace Components {
           * The values for the input for each row when multiselect is activated.
           * @default []
          */
-        "selectedValues"?: string[];
+        "selectedValues": string[];
         /**
           * Manually determined if the column is sortable
           * @default []
          */
-        "sortableColumns"?: boolean[];
+        "sortableColumns": boolean[];
         /**
           * Toggles an optional styling of the background of each even row of the table body.
          */
         "striped"?: boolean;
     }
+    /**
+     * @since 1.0.0
+     */
     interface XplTableHeader {
     }
+    /**
+     * @since 1.3.0
+     */
     interface XplTableHeaderCell {
         /**
           * Icon to display in the cell.  See [xpl-icon available icons](../xpl-icon/ICONS.md) for valid icon names.
@@ -1886,6 +2108,9 @@ export namespace Components {
          */
         "width"?: number;
     }
+    /**
+     * @since 2.3.8
+     */
     interface XplTabs {
         /**
           * Disables the whole tab group (headings, mobile select, and segment pills).
@@ -1907,6 +2132,9 @@ export namespace Components {
          */
         "value": string;
     }
+    /**
+     * @since 0.4.0
+     */
     interface XplTag {
         /**
           * Whether the tag is disabled
@@ -1933,32 +2161,44 @@ export namespace Components {
          */
         "tagId"?: string;
     }
+    /**
+     * @since 1.2.0
+     */
     interface XplToast {
         /**
-          * @property {string} - The caption of the toast, limited to 85 characters
+          * The caption of the toast, limited to 85 characters.
+          * @default ''
          */
         "caption": string;
         /**
-          * @property {boolean} - Whether or not the toast is dismissible
+          * Whether the toast shows a dismiss (close) button.
+          * @deprecated Misspelled. Use `dismissible` instead. When both are set, `dismissable` wins so existing markup keeps working; `dismissable` is removed in the next major version.
+         */
+        "dismissable"?: boolean;
+        /**
+          * Whether the toast shows a dismiss (close) button.
           * @default true
          */
-        "dismissable": boolean;
+        "dismissible": boolean;
         /**
-          * @property {boolean} - Whether or not to show the icon
+          * Whether to show the leading sentiment icon.
           * @default true
          */
         "showIcon"?: boolean;
         /**
-          * @property {number} - The timeout for the toast to dismiss in ms, default 8 seconds
+          * How long the toast waits before auto-dismissing, in ms. Set to `0` to disable auto-dismiss. Ignored when the `action` slot has content.
           * @default 8000
          */
         "timeout": number;
         /**
-          * @property {string} - The variant of the toast
+          * The sentiment of the toast.
           * @default 'neutral'
          */
         "variant": 'neutral' | 'warning' | 'success';
     }
+    /**
+     * @since 0.3.0
+     */
     interface XplToggle {
         /**
           * Whether the toggle is `on`
@@ -1990,6 +2230,9 @@ export namespace Components {
          */
         "variant"?: 'default' | 'small';
     }
+    /**
+     * @since 1.2.0
+     */
     interface XplToolbar {
         /**
           * The number of selected items to display in the toolbar.
@@ -1997,6 +2240,9 @@ export namespace Components {
          */
         "selectedItemCount": number;
     }
+    /**
+     * @since 1.7.0
+     */
     interface XplTooltip {
         /**
           * Hide the arrow
@@ -2025,6 +2271,7 @@ export namespace Components {
      * (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).
+     * **Outside click:** With **`nav-control`**, a click outside the drawer panel (**`.xpl-top-nav__left-primary`**) also closes it and emits **`navOpen`** **`false`** (document **capture**, mirroring **`xpl-top-nav-item`**); it skips clicks on the hamburger toggle and while a descendant **`xpl-popover`** is open, and does not move focus.
      * **`xpl-top-nav-item`** **`slot="dropdown"`** uses document **capture** for **Escape** first; the shell uses **bubble**
      * on **`ownerDocument`** so nested dropdowns close before the drawer.
      * **Theming:** The host always includes Foundation’s **`dark`** class so **`--xpl-*`** purpose tokens under this subtree
@@ -2041,6 +2288,7 @@ export namespace Components {
      * **`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.
+     * @since 2.7.0
      */
     interface XplTopNav {
         /**
@@ -2069,16 +2317,19 @@ export namespace Components {
         "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
+     * Single nav row for **`xpl-top-nav`** / **`xpl-nav-header-menu`** / **`xpl-top-nav-menu`**. The host uses
+     * **`role="listitem"`** when the row participates in a list: a **`role="list"`** parent, **`slot="left-aside"`** on
+     * **`xpl-top-nav`** (list host is **`.xpl-top-nav__left-primary`** while slotted nodes stay light-DOM children of
+     * **`xpl-top-nav`**), or default-slot rows under **`xpl-nav-header-menu`** / **`xpl-top-nav-menu`**. That flag is
      * kept in **`@State`** and refreshed after render plus via **`MutationObserver`** on the host (**`class`**, **`slot`**) and
      * on **`parentElement`** (**`role`**) or on **`.xpl-top-nav__left-primary`** (**`role`**) for **`slot="left-aside"`** under **`xpl-top-nav`**) so DOM context changes
      * without a full reconnect still re-sync. The internal
      * **`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`**.
+     * **This component does triple duty:** a plain bar item, a dropdown trigger (**`slot="dropdown"`** present), and a
+     * dropdown/menu **row** (nested inside **`xpl-nav-header-menu`** or **`xpl-top-nav-menu`**). The **`description`** prop
+     * only applies in the row context — bar items and triggers do not show it in Figma.
      * **Default slot (no `label`):** do not put **`xpl-top-nav-item__inner`** or other **`xpl-top-nav-item__*`** classes on
      * custom trigger content — the component renders the inner wrapper and BEM elements.
      * **Theming:** The host always includes Foundation’s **`dark`** class so **`--xpl-*`** purpose tokens resolve to dark-mode
@@ -2090,12 +2341,20 @@ export namespace Components {
           * @default false
          */
         "active": boolean;
+        /**
+          * No-op when there is no **`slot="dropdown"`** panel to open.
+         */
+        "closeMenu": () => Promise<void>;
+        /**
+          * Optional description line shown below **`label`** (row context only, e.g. inside **`xpl-nav-header-menu`** / **`xpl-top-nav-menu`**). Ignored when **`label`** is not set.
+         */
+        "description"?: string;
         /**
           * 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).
+          * Icon name from **`@xplortech/apollo-icons`** (shown before the label when **`label`** is set). Ignored when **`slot="leading-icon"`** content is present.
           * @default ''
          */
         "icon": string;
@@ -2107,12 +2366,58 @@ export namespace Components {
           * 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;
+        /**
+          * Whether the **`slot="dropdown"`** panel is open. Reflected to the **`open`** attribute so consumers can drive it (controlled) or read it back (uncontrolled, toggled internally on click / hover / keyboard activation). Prefer **`openMenu()`** / **`closeMenu()`** / **`toggleMenu()`** over setting this directly from event handlers.
+          * @default false
+         */
+        "open": boolean;
+        /**
+          * No-op when there is no **`slot="dropdown"`** panel to open.
+         */
+        "openMenu": () => Promise<void>;
+        /**
+          * How the **`slot="dropdown"`** panel opens. **`hover`** is gated on **`TOP_NAV_ITEM_HOVER_OPEN_MQ`** (hover-capable, fine pointer, **`md`** and up) — below that, or on touch / coarse-pointer devices, **`hover`** falls back to click/tap. Keyboard activation (Enter / Space) always toggles regardless of **`openMode`**.
+          * @default 'click'
+         */
+        "openMode": 'click' | 'hover';
         /**
           * When true, sets **`aria-current="page"`** and selected styling.
           * @default false
          */
         "selected": boolean;
+        /**
+          * No-op when there is no **`slot="dropdown"`** panel to open.
+         */
+        "toggleMenu": () => Promise<void>;
+    }
+    /**
+     * Thin grouping container for **`xpl-top-nav-item`** rows — the panel content for a desktop flyout
+     * (**`slot="dropdown"`** on the parent **`xpl-top-nav-item`**) and, on small screens, the **mobile
+     * cascade**: the same markup drills in to a **Level 2** view in place, with an auto-rendered **back
+     * row** (leading **`chevron-left`** + this component's **`label`**) as the first row. Tapping the back
+     * row closes the parent trigger's dropdown (**`closeMenu()`**), returning to **Level 1** and restoring
+     * focus to the parent trigger. No item logic otherwise lives here — row behavior (icons, description,
+     * links, nested dropdowns) is entirely **`xpl-top-nav-item`**.
+     * **One authoring markup, two renderings:** consumers write this once; **`isMobileCascade`** (synced
+     * from **`TOP_NAV_MOBILE_MQ`**) decides whether the back row renders. Desktop never sees it — the
+     * flyout is a single level of links (see `xpl-top-nav-item`'s cascade-depth notes).
+     * **Panel chrome** is shared with **`xpl-nav-header-menu`** (the account menu): width
+     * (**`--xpl-top-nav-panel-width`**), surface, shadow, radius, and vertical padding all come from the
+     * same selector in `top-nav.css` so the desktop flyout, mobile cascade, and account menu read as one
+     * visual family.
+     * **Theming:** The host always includes Foundation’s **`dark`** class so **`--xpl-*`** purpose tokens
+     * resolve to dark-mode values even when the page root is light (consistent with the rest of the
+     * **`xpl-top-nav`** family).
+     */
+    interface XplTopNavMenu {
+        /**
+          * Accessible name for the list (**`aria-label`** on the host) and the label shown in the mobile cascade back row when drilling back out of this group.
+         */
+        "label"?: string;
     }
+    /**
+     * @since 0.1.1
+     */
     interface XplUtilityBar {
         /**
           * @property {boolean} - Optional property that defines whether or not the main nav is open at startup.
@@ -2220,10 +2525,18 @@ export interface XplSideNavCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLXplSideNavElement;
 }
+export interface XplSideNavHeaderItemCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLXplSideNavHeaderItemElement;
+}
 export interface XplSideNavItemCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLXplSideNavItemElement;
 }
+export interface XplSideNavSectionCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLXplSideNavSectionElement;
+}
 export interface XplSlideoutCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLXplSlideoutElement;
@@ -2269,30 +2582,45 @@ export interface XplUtilityBarCustomEvent<T> extends CustomEvent<T> {
     target: HTMLXplUtilityBarElement;
 }
 declare global {
+    /**
+     * @since 2.0.0
+     */
     interface HTMLXplAccordionElement extends Components.XplAccordion, HTMLStencilElement {
     }
     var HTMLXplAccordionElement: {
         prototype: HTMLXplAccordionElement;
         new (): HTMLXplAccordionElement;
     };
+    /**
+     * @since 0.5.0
+     */
     interface HTMLXplApplicationShellElement extends Components.XplApplicationShell, HTMLStencilElement {
     }
     var HTMLXplApplicationShellElement: {
         prototype: HTMLXplApplicationShellElement;
         new (): HTMLXplApplicationShellElement;
     };
+    /**
+     * @since 0.1.1
+     */
     interface HTMLXplAvatarElement extends Components.XplAvatar, HTMLStencilElement {
     }
     var HTMLXplAvatarElement: {
         prototype: HTMLXplAvatarElement;
         new (): HTMLXplAvatarElement;
     };
+    /**
+     * @since 0.1.2
+     */
     interface HTMLXplBackdropElement extends Components.XplBackdrop, HTMLStencilElement {
     }
     var HTMLXplBackdropElement: {
         prototype: HTMLXplBackdropElement;
         new (): HTMLXplBackdropElement;
     };
+    /**
+     * @since 0.1.1
+     */
     interface HTMLXplBadgeElement extends Components.XplBadge, HTMLStencilElement {
     }
     var HTMLXplBadgeElement: {
@@ -2304,6 +2632,9 @@ declare global {
         "dismiss": void;
         "secondaryAction": void;
     }
+    /**
+     * @since 2.6.0
+     */
     interface HTMLXplBannerElement extends Components.XplBanner, HTMLStencilElement {
         addEventListener<K extends keyof HTMLXplBannerElementEventMap>(type: K, listener: (this: HTMLXplBannerElement, ev: XplBannerCustomEvent<HTMLXplBannerElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -2330,6 +2661,9 @@ declare global {
         prototype: HTMLXplBreadcrumbsElement;
         new (): HTMLXplBreadcrumbsElement;
     };
+    /**
+     * @since 0.1.1
+     */
     interface HTMLXplButtonElement extends Components.XplButton, HTMLStencilElement {
     }
     var HTMLXplButtonElement: {
@@ -2341,6 +2675,9 @@ declare global {
         "clickSecondary": any;
         "clickTertiary": any;
     }
+    /**
+     * @since 0.4.0
+     */
     interface HTMLXplButtonRowElement extends Components.XplButtonRow, HTMLStencilElement {
         addEventListener<K extends keyof HTMLXplButtonRowElementEventMap>(type: K, listener: (this: HTMLXplButtonRowElement, ev: XplButtonRowCustomEvent<HTMLXplButtonRowElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -2358,6 +2695,9 @@ declare global {
     interface HTMLXplCalendarElementEventMap {
         "dateSelected": string | string[];
     }
+    /**
+     * @since 2.0.0
+     */
     interface HTMLXplCalendarElement extends Components.XplCalendar, HTMLStencilElement {
         addEventListener<K extends keyof HTMLXplCalendarElementEventMap>(type: K, listener: (this: HTMLXplCalendarElement, ev: XplCalendarCustomEvent<HTMLXplCalendarElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -2375,6 +2715,9 @@ declare global {
     interface HTMLXplCheckboxElementEventMap {
         "checkboxChange": boolean;
     }
+    /**
+     * @since 0.1.1
+     */
     interface HTMLXplCheckboxElement extends Components.XplCheckbox, HTMLStencilElement {
         addEventListener<K extends keyof HTMLXplCheckboxElementEventMap>(type: K, listener: (this: HTMLXplCheckboxElement, ev: XplCheckboxCustomEvent<HTMLXplCheckboxElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -2393,6 +2736,9 @@ declare global {
         "choicelistChange": boolean[];
         "choicelistValueChange": string | boolean | (string | boolean)[];
     }
+    /**
+     * @since 0.1.1
+     */
     interface HTMLXplChoicelistElement extends Components.XplChoicelist, HTMLStencilElement {
         addEventListener<K extends keyof HTMLXplChoicelistElementEventMap>(type: K, listener: (this: HTMLXplChoicelistElement, ev: XplChoicelistCustomEvent<HTMLXplChoicelistElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -2407,24 +2753,36 @@ declare global {
         prototype: HTMLXplChoicelistElement;
         new (): HTMLXplChoicelistElement;
     };
+    /**
+     * @since 0.1.2
+     */
     interface HTMLXplContentAreaElement extends Components.XplContentArea, HTMLStencilElement {
     }
     var HTMLXplContentAreaElement: {
         prototype: HTMLXplContentAreaElement;
         new (): HTMLXplContentAreaElement;
     };
+    /**
+     * @since 1.0.0
+     */
     interface HTMLXplDashboardElement extends Components.XplDashboard, HTMLStencilElement {
     }
     var HTMLXplDashboardElement: {
         prototype: HTMLXplDashboardElement;
         new (): HTMLXplDashboardElement;
     };
+    /**
+     * @since 1.0.0
+     */
     interface HTMLXplDataCardElement extends Components.XplDataCard, HTMLStencilElement {
     }
     var HTMLXplDataCardElement: {
         prototype: HTMLXplDataCardElement;
         new (): HTMLXplDataCardElement;
     };
+    /**
+     * @since 0.3.0
+     */
     interface HTMLXplDividerElement extends Components.XplDivider, HTMLStencilElement {
     }
     var HTMLXplDividerElement: {
@@ -2434,6 +2792,9 @@ declare global {
     interface HTMLXplDropdownElementEventMap {
         "isOpenChange": boolean;
     }
+    /**
+     * @since 0.4.0
+     */
     interface HTMLXplDropdownElement extends Components.XplDropdown, HTMLStencilElement {
         addEventListener<K extends keyof HTMLXplDropdownElementEventMap>(type: K, listener: (this: HTMLXplDropdownElement, ev: XplDropdownCustomEvent<HTMLXplDropdownElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -2469,6 +2830,9 @@ declare global {
     interface HTMLXplDynamicTableElementEventMap {
         "selectedItemCountChange": string[];
     }
+    /**
+     * @since 1.4.0
+     */
     interface HTMLXplDynamicTableElement extends Components.XplDynamicTable, HTMLStencilElement {
         addEventListener<K extends keyof HTMLXplDynamicTableElementEventMap>(type: K, listener: (this: HTMLXplDynamicTableElement, ev: XplDynamicTableCustomEvent<HTMLXplDynamicTableElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -2483,36 +2847,54 @@ declare global {
         prototype: HTMLXplDynamicTableElement;
         new (): HTMLXplDynamicTableElement;
     };
+    /**
+     * @since 1.3.0
+     */
     interface HTMLXplDynamicTableCellElement extends Components.XplDynamicTableCell, HTMLStencilElement {
     }
     var HTMLXplDynamicTableCellElement: {
         prototype: HTMLXplDynamicTableCellElement;
         new (): HTMLXplDynamicTableCellElement;
     };
+    /**
+     * @since 1.3.0
+     */
     interface HTMLXplDynamicTableRowElement extends Components.XplDynamicTableRow, HTMLStencilElement {
     }
     var HTMLXplDynamicTableRowElement: {
         prototype: HTMLXplDynamicTableRowElement;
         new (): HTMLXplDynamicTableRowElement;
     };
+    /**
+     * @since 0.4.0
+     */
     interface HTMLXplGridElement extends Components.XplGrid, HTMLStencilElement {
     }
     var HTMLXplGridElement: {
         prototype: HTMLXplGridElement;
         new (): HTMLXplGridElement;
     };
+    /**
+     * @since 0.4.0
+     */
     interface HTMLXplGridItemElement extends Components.XplGridItem, HTMLStencilElement {
     }
     var HTMLXplGridItemElement: {
         prototype: HTMLXplGridItemElement;
         new (): HTMLXplGridItemElement;
     };
+    /**
+     * @since 1.2.0
+     */
     interface HTMLXplHeaderAccordionElement extends Components.XplHeaderAccordion, HTMLStencilElement {
     }
     var HTMLXplHeaderAccordionElement: {
         prototype: HTMLXplHeaderAccordionElement;
         new (): HTMLXplHeaderAccordionElement;
     };
+    /**
+     * @since 1.0.0
+     */
     interface HTMLXplIconElement extends Components.XplIcon, HTMLStencilElement {
     }
     var HTMLXplIconElement: {
@@ -2526,6 +2908,9 @@ declare global {
         "search": string;
         "valueChange": string;
     }
+    /**
+     * @since 0.3.0
+     */
     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;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -2657,6 +3042,9 @@ declare global {
         prototype: HTMLXplInputTimeElement;
         new (): HTMLXplInputTimeElement;
     };
+    /**
+     * @since 1.9.1
+     */
     interface HTMLXplLargeCardElement extends Components.XplLargeCard, HTMLStencilElement {
     }
     var HTMLXplLargeCardElement: {
@@ -2667,6 +3055,9 @@ declare global {
         "itemSelect": { itemId?: string };
         "orderChange": XplListOrderChangeDetail;
     }
+    /**
+     * @since 0.4.0
+     */
     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;
@@ -2704,6 +3095,9 @@ declare global {
     interface HTMLXplMainNavElementEventMap {
         "navWidth": string;
     }
+    /**
+     * @since 0.1.2
+     */
     interface HTMLXplMainNavElement extends Components.XplMainNav, HTMLStencilElement {
         addEventListener<K extends keyof HTMLXplMainNavElementEventMap>(type: K, listener: (this: HTMLXplMainNavElement, ev: XplMainNavCustomEvent<HTMLXplMainNavElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -2721,6 +3115,9 @@ declare global {
     interface HTMLXplModalElementEventMap {
         "modalClosed": void;
     }
+    /**
+     * @since 1.1.0
+     */
     interface HTMLXplModalElement extends Components.XplModal, HTMLStencilElement {
         addEventListener<K extends keyof HTMLXplModalElementEventMap>(type: K, listener: (this: HTMLXplModalElement, ev: XplModalCustomEvent<HTMLXplModalElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -2762,6 +3159,9 @@ declare global {
     interface HTMLXplNavItemElementEventMap {
         "navOpen": boolean;
     }
+    /**
+     * @since 0.1.2
+     */
     interface HTMLXplNavItemElement extends Components.XplNavItem, HTMLStencilElement {
         addEventListener<K extends keyof HTMLXplNavItemElementEventMap>(type: K, listener: (this: HTMLXplNavItemElement, ev: XplNavItemCustomEvent<HTMLXplNavItemElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -2780,6 +3180,9 @@ declare global {
         "pageChange": number;
         "rowsPerPageChange": number;
     }
+    /**
+     * @since 0.1.1
+     */
     interface HTMLXplPaginationElement extends Components.XplPagination, HTMLStencilElement {
         addEventListener<K extends keyof HTMLXplPaginationElementEventMap>(type: K, listener: (this: HTMLXplPaginationElement, ev: XplPaginationCustomEvent<HTMLXplPaginationElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -2797,6 +3200,7 @@ declare global {
     /**
      * A stateless container that defines a section on a page and can house any
      * type of content. Panels are not dismissible and may contain a top accent.
+     * @since 2.6.0
      */
     interface HTMLXplPanelElement extends Components.XplPanel, HTMLStencilElement {
     }
@@ -2807,6 +3211,9 @@ declare global {
     interface HTMLXplPopoverElementEventMap {
         "isOpenChange": boolean;
     }
+    /**
+     * @since 2.0.0
+     */
     interface HTMLXplPopoverElement extends Components.XplPopover, HTMLStencilElement {
         addEventListener<K extends keyof HTMLXplPopoverElementEventMap>(type: K, listener: (this: HTMLXplPopoverElement, ev: XplPopoverCustomEvent<HTMLXplPopoverElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -2821,12 +3228,18 @@ declare global {
         prototype: HTMLXplPopoverElement;
         new (): HTMLXplPopoverElement;
     };
+    /**
+     * @since 2.6.0
+     */
     interface HTMLXplProgressBarElement extends Components.XplProgressBar, HTMLStencilElement {
     }
     var HTMLXplProgressBarElement: {
         prototype: HTMLXplProgressBarElement;
         new (): HTMLXplProgressBarElement;
     };
+    /**
+     * @since 2.7.0
+     */
     interface HTMLXplProgressIndicatorElement extends Components.XplProgressIndicator, HTMLStencilElement {
     }
     var HTMLXplProgressIndicatorElement: {
@@ -2836,6 +3249,9 @@ declare global {
     interface HTMLXplRadioElementEventMap {
         "radioChange": string | boolean;
     }
+    /**
+     * @since 0.1.1
+     */
     interface HTMLXplRadioElement extends Components.XplRadio, HTMLStencilElement {
         addEventListener<K extends keyof HTMLXplRadioElementEventMap>(type: K, listener: (this: HTMLXplRadioElement, ev: XplRadioCustomEvent<HTMLXplRadioElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -2850,6 +3266,9 @@ declare global {
         prototype: HTMLXplRadioElement;
         new (): HTMLXplRadioElement;
     };
+    /**
+     * @since 0.3.0
+     */
     interface HTMLXplSecondaryNavElement extends Components.XplSecondaryNav, HTMLStencilElement {
     }
     var HTMLXplSecondaryNavElement: {
@@ -2865,6 +3284,9 @@ declare global {
         nextState: boolean;
     };
     }
+    /**
+     * @since 0.4.0
+     */
     interface HTMLXplSelectElement extends Components.XplSelect, HTMLStencilElement {
         addEventListener<K extends keyof HTMLXplSelectElementEventMap>(type: K, listener: (this: HTMLXplSelectElement, ev: XplSelectCustomEvent<HTMLXplSelectElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -2883,8 +3305,8 @@ declare global {
         "openChange": boolean;
     }
     /**
-     * Slot-based sidebar for app navigation: a scrollable main `section` and a fixed
-     * `nav-footer`. Compose with `xpl-side-nav-item` for rows.
+     * Slot-based sidebar for app navigation: a scrollable `nav-header` + `section`
+     * area and a fixed `nav-footer`. Compose with `xpl-side-nav-item` for rows.
      * **Mobile (v2):** below the Tailwind `md` breakpoint, the sidebar collapses to a
      * ~56px top bar with a toggle button (`sidebar-left-show` / `sidebar-left-hide`).
      * Activating the toggle opens a drawer containing the `section` + `nav-footer`
@@ -2896,6 +3318,7 @@ declare global {
      * the `openChange` event, and the `toggle()` / `setOpen()` methods.
      * **v2 breaking change (beta):** consumers who wrapped their own mobile toggle
      * around `xpl-side-nav` should remove it — the toggle and drawer are now built in.
+     * @since 2.6.0
      */
     interface HTMLXplSideNavElement extends Components.XplSideNav, HTMLStencilElement {
         addEventListener<K extends keyof HTMLXplSideNavElementEventMap>(type: K, listener: (this: HTMLXplSideNavElement, ev: XplSideNavCustomEvent<HTMLXplSideNavElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
@@ -2911,9 +3334,49 @@ declare global {
         prototype: HTMLXplSideNavElement;
         new (): HTMLXplSideNavElement;
     };
+    interface HTMLXplSideNavHeaderItemElementEventMap {
+        "navigate": void;
+    }
+    /**
+     * Header row for `xpl-side-nav`'s `nav-header` slot (Figma `<navHeaderItem>`,
+     * node `51299-9007`). Two types:
+     * - **`product-label` (default)** — a non-interactive `<div>` row that shows the
+     *   current product/area name in a subdued color. No click behavior.
+     * - **`sub-account`** — an interactive `<button>` row (e.g. a location / account
+     *   switcher). Emits `navigate` on activation (pointer click or keyboard); the
+     *   consumer wires this to open a modal or other entity-switching experience.
+     *   When no `slot="trailing"` content is provided, an auto chevron
+     *   (`chevron-expand-y`, a static dual-arrow glyph — no rotation) renders by default.
+     * Both types support `slot="leading"` / `slot="trailing"` (the `icon` prop is a
+     * convenience shorthand for `slot="leading"`, same as `xpl-side-nav-item`) so they
+     * can scale to future uses. Unlike `xpl-side-nav-item`, the leading/trailing
+     * columns are NOT unconditionally reserved — they only render when there is
+     * content, matching the Figma variants where the leading icon is an optional toggle.
+     * **Note on the `sub-account` hover / selected visual:** the interactive row
+     * mirrors `xpl-side-nav-item` — the hover and selected backgrounds fill a single
+     * `__content` pill that wraps the leading icon + label + trailing chevron, with
+     * an 8px (`--xpl-border-radius-default`) radius. The pill insets 8px from the nav
+     * edge (an 8px gutter on the button) so it lines up with the item rows below it,
+     * and hover/selected therefore highlight the whole row content rather than a
+     * partial fragment.
+     */
+    interface HTMLXplSideNavHeaderItemElement extends Components.XplSideNavHeaderItem, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLXplSideNavHeaderItemElementEventMap>(type: K, listener: (this: HTMLXplSideNavHeaderItemElement, ev: XplSideNavHeaderItemCustomEvent<HTMLXplSideNavHeaderItemElementEventMap[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 HTMLXplSideNavHeaderItemElementEventMap>(type: K, listener: (this: HTMLXplSideNavHeaderItemElement, ev: XplSideNavHeaderItemCustomEvent<HTMLXplSideNavHeaderItemElementEventMap[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 HTMLXplSideNavHeaderItemElement: {
+        prototype: HTMLXplSideNavHeaderItemElement;
+        new (): HTMLXplSideNavHeaderItemElement;
+    };
     interface HTMLXplSideNavItemElementEventMap {
         "expandedChange": boolean;
-        "navClick": void;
+        "navigate": void;
     }
     /**
      * Navigation row for `xpl-side-nav`. Renders a button (default) or a slot-only
@@ -2953,7 +3416,43 @@ declare global {
         prototype: HTMLXplSideNavItemElement;
         new (): HTMLXplSideNavItemElement;
     };
-    interface HTMLXplSkeletonElement extends Components.XplSkeleton, HTMLStencilElement {
+    interface HTMLXplSideNavSectionElementEventMap {
+        "expandedChange": boolean;
+    }
+    /**
+     * Grouping / accordion header for `xpl-side-nav`. Wraps nested `xpl-side-nav-item`
+     * (and optional divider separators) elements in the default slot and collapses
+     * them as a unit.
+     * Two variants:
+     * - **Collapsible (default, `collapsible=true`)** — a `<button>` header with a
+     *   chevron (`chevron-right` collapsed / `chevron-down` expanded, no rotation —
+     *   the glyph itself swaps). Click toggles `expanded` and emits `expandedChange`.
+     * - **Static (`collapsible=false`)** — a non-interactive title row with no chevron;
+     *   children are always shown. Used for a static section label (e.g. a future
+     *   product-name / location-changer header).
+     * Unlike `xpl-side-nav-item[has-children]`, section children are **not indented**
+     * — they align with top-level items at the same leading-icon column.
+     * `slot="badge"` renders an optional badge (e.g. `xpl-badge`) in the header title
+     * row. The wrapper is suppressed when the slot is empty.
+     */
+    interface HTMLXplSideNavSectionElement extends Components.XplSideNavSection, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLXplSideNavSectionElementEventMap>(type: K, listener: (this: HTMLXplSideNavSectionElement, ev: XplSideNavSectionCustomEvent<HTMLXplSideNavSectionElementEventMap[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 HTMLXplSideNavSectionElementEventMap>(type: K, listener: (this: HTMLXplSideNavSectionElement, ev: XplSideNavSectionCustomEvent<HTMLXplSideNavSectionElementEventMap[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 HTMLXplSideNavSectionElement: {
+        prototype: HTMLXplSideNavSectionElement;
+        new (): HTMLXplSideNavSectionElement;
+    };
+    /**
+     * @since 2.3.6
+     */
+    interface HTMLXplSkeletonElement extends Components.XplSkeleton, HTMLStencilElement {
     }
     var HTMLXplSkeletonElement: {
         prototype: HTMLXplSkeletonElement;
@@ -2962,6 +3461,9 @@ declare global {
     interface HTMLXplSlideoutElementEventMap {
         "isOpenChange": boolean;
     }
+    /**
+     * @since 1.1.0
+     */
     interface HTMLXplSlideoutElement extends Components.XplSlideout, HTMLStencilElement {
         addEventListener<K extends keyof HTMLXplSlideoutElementEventMap>(type: K, listener: (this: HTMLXplSlideoutElement, ev: XplSlideoutCustomEvent<HTMLXplSlideoutElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -2982,6 +3484,9 @@ declare global {
         "secondaryAction": void;
         "targetClick": void;
     }
+    /**
+     * @since 2.7.0
+     */
     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;
@@ -2999,6 +3504,9 @@ declare global {
     interface HTMLXplTabElementEventMap {
         "tabChange": string;
     }
+    /**
+     * @since 2.3.8
+     */
     interface HTMLXplTabElement extends Components.XplTab, HTMLStencilElement {
         addEventListener<K extends keyof HTMLXplTabElementEventMap>(type: K, listener: (this: HTMLXplTabElement, ev: XplTabCustomEvent<HTMLXplTabElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -3013,6 +3521,9 @@ declare global {
         prototype: HTMLXplTabElement;
         new (): HTMLXplTabElement;
     };
+    /**
+     * @since 2.3.8
+     */
     interface HTMLXplTabPanelElement extends Components.XplTabPanel, HTMLStencilElement {
     }
     var HTMLXplTabPanelElement: {
@@ -3024,9 +3535,12 @@ declare global {
         "sortChanged": {
         colNum: number;
         colName: string;
-        sortTypeArr: string[];
+        sortTypeArr: ('asc' | 'desc' | null)[];
     };
     }
+    /**
+     * @since 0.1.1
+     */
     interface HTMLXplTableElement extends Components.XplTable, HTMLStencilElement {
         addEventListener<K extends keyof HTMLXplTableElementEventMap>(type: K, listener: (this: HTMLXplTableElement, ev: XplTableCustomEvent<HTMLXplTableElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -3041,6 +3555,9 @@ declare global {
         prototype: HTMLXplTableElement;
         new (): HTMLXplTableElement;
     };
+    /**
+     * @since 1.0.0
+     */
     interface HTMLXplTableHeaderElement extends Components.XplTableHeader, HTMLStencilElement {
     }
     var HTMLXplTableHeaderElement: {
@@ -3050,6 +3567,9 @@ declare global {
     interface HTMLXplTableHeaderCellElementEventMap {
         "sortChanged": 'asc' | 'desc' | 'none';
     }
+    /**
+     * @since 1.3.0
+     */
     interface HTMLXplTableHeaderCellElement extends Components.XplTableHeaderCell, HTMLStencilElement {
         addEventListener<K extends keyof HTMLXplTableHeaderCellElementEventMap>(type: K, listener: (this: HTMLXplTableHeaderCellElement, ev: XplTableHeaderCellCustomEvent<HTMLXplTableHeaderCellElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -3067,6 +3587,9 @@ declare global {
     interface HTMLXplTabsElementEventMap {
         "tabChange": string;
     }
+    /**
+     * @since 2.3.8
+     */
     interface HTMLXplTabsElement extends Components.XplTabs, HTMLStencilElement {
         addEventListener<K extends keyof HTMLXplTabsElementEventMap>(type: K, listener: (this: HTMLXplTabsElement, ev: XplTabsCustomEvent<HTMLXplTabsElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -3087,6 +3610,9 @@ declare global {
         "tagDragStart": TagDragStartDetail;
         "tagRemove": void;
     }
+    /**
+     * @since 0.4.0
+     */
     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;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -3101,6 +3627,9 @@ declare global {
         prototype: HTMLXplTagElement;
         new (): HTMLXplTagElement;
     };
+    /**
+     * @since 1.2.0
+     */
     interface HTMLXplToastElement extends Components.XplToast, HTMLStencilElement {
     }
     var HTMLXplToastElement: {
@@ -3110,6 +3639,9 @@ declare global {
     interface HTMLXplToggleElementEventMap {
         "toggleChange": boolean;
     }
+    /**
+     * @since 0.3.0
+     */
     interface HTMLXplToggleElement extends Components.XplToggle, HTMLStencilElement {
         addEventListener<K extends keyof HTMLXplToggleElementEventMap>(type: K, listener: (this: HTMLXplToggleElement, ev: XplToggleCustomEvent<HTMLXplToggleElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -3124,12 +3656,18 @@ declare global {
         prototype: HTMLXplToggleElement;
         new (): HTMLXplToggleElement;
     };
+    /**
+     * @since 1.2.0
+     */
     interface HTMLXplToolbarElement extends Components.XplToolbar, HTMLStencilElement {
     }
     var HTMLXplToolbarElement: {
         prototype: HTMLXplToolbarElement;
         new (): HTMLXplToolbarElement;
     };
+    /**
+     * @since 1.7.0
+     */
     interface HTMLXplTooltipElement extends Components.XplTooltip, HTMLStencilElement {
     }
     var HTMLXplTooltipElement: {
@@ -3145,6 +3683,7 @@ declare global {
      * (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).
+     * **Outside click:** With **`nav-control`**, a click outside the drawer panel (**`.xpl-top-nav__left-primary`**) also closes it and emits **`navOpen`** **`false`** (document **capture**, mirroring **`xpl-top-nav-item`**); it skips clicks on the hamburger toggle and while a descendant **`xpl-popover`** is open, and does not move focus.
      * **`xpl-top-nav-item`** **`slot="dropdown"`** uses document **capture** for **Escape** first; the shell uses **bubble**
      * on **`ownerDocument`** so nested dropdowns close before the drawer.
      * **Theming:** The host always includes Foundation’s **`dark`** class so **`--xpl-*`** purpose tokens under this subtree
@@ -3161,6 +3700,7 @@ declare global {
      * **`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.
+     * @since 2.7.0
      */
     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;
@@ -3178,18 +3718,22 @@ declare global {
     };
     interface HTMLXplTopNavItemElementEventMap {
         "navItemClick": MouseEvent;
+        "openChange": 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
+     * Single nav row for **`xpl-top-nav`** / **`xpl-nav-header-menu`** / **`xpl-top-nav-menu`**. The host uses
+     * **`role="listitem"`** when the row participates in a list: a **`role="list"`** parent, **`slot="left-aside"`** on
+     * **`xpl-top-nav`** (list host is **`.xpl-top-nav__left-primary`** while slotted nodes stay light-DOM children of
+     * **`xpl-top-nav`**), or default-slot rows under **`xpl-nav-header-menu`** / **`xpl-top-nav-menu`**. That flag is
      * kept in **`@State`** and refreshed after render plus via **`MutationObserver`** on the host (**`class`**, **`slot`**) and
      * on **`parentElement`** (**`role`**) or on **`.xpl-top-nav__left-primary`** (**`role`**) for **`slot="left-aside"`** under **`xpl-top-nav`**) so DOM context changes
      * without a full reconnect still re-sync. The internal
      * **`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`**.
+     * **This component does triple duty:** a plain bar item, a dropdown trigger (**`slot="dropdown"`** present), and a
+     * dropdown/menu **row** (nested inside **`xpl-nav-header-menu`** or **`xpl-top-nav-menu`**). The **`description`** prop
+     * only applies in the row context — bar items and triggers do not show it in Figma.
      * **Default slot (no `label`):** do not put **`xpl-top-nav-item__inner`** or other **`xpl-top-nav-item__*`** classes on
      * custom trigger content — the component renders the inner wrapper and BEM elements.
      * **Theming:** The host always includes Foundation’s **`dark`** class so **`--xpl-*`** purpose tokens resolve to dark-mode
@@ -3209,9 +3753,37 @@ declare global {
         prototype: HTMLXplTopNavItemElement;
         new (): HTMLXplTopNavItemElement;
     };
+    /**
+     * Thin grouping container for **`xpl-top-nav-item`** rows — the panel content for a desktop flyout
+     * (**`slot="dropdown"`** on the parent **`xpl-top-nav-item`**) and, on small screens, the **mobile
+     * cascade**: the same markup drills in to a **Level 2** view in place, with an auto-rendered **back
+     * row** (leading **`chevron-left`** + this component's **`label`**) as the first row. Tapping the back
+     * row closes the parent trigger's dropdown (**`closeMenu()`**), returning to **Level 1** and restoring
+     * focus to the parent trigger. No item logic otherwise lives here — row behavior (icons, description,
+     * links, nested dropdowns) is entirely **`xpl-top-nav-item`**.
+     * **One authoring markup, two renderings:** consumers write this once; **`isMobileCascade`** (synced
+     * from **`TOP_NAV_MOBILE_MQ`**) decides whether the back row renders. Desktop never sees it — the
+     * flyout is a single level of links (see `xpl-top-nav-item`'s cascade-depth notes).
+     * **Panel chrome** is shared with **`xpl-nav-header-menu`** (the account menu): width
+     * (**`--xpl-top-nav-panel-width`**), surface, shadow, radius, and vertical padding all come from the
+     * same selector in `top-nav.css` so the desktop flyout, mobile cascade, and account menu read as one
+     * visual family.
+     * **Theming:** The host always includes Foundation’s **`dark`** class so **`--xpl-*`** purpose tokens
+     * resolve to dark-mode values even when the page root is light (consistent with the rest of the
+     * **`xpl-top-nav`** family).
+     */
+    interface HTMLXplTopNavMenuElement extends Components.XplTopNavMenu, HTMLStencilElement {
+    }
+    var HTMLXplTopNavMenuElement: {
+        prototype: HTMLXplTopNavMenuElement;
+        new (): HTMLXplTopNavMenuElement;
+    };
     interface HTMLXplUtilityBarElementEventMap {
         "navOpen": boolean;
     }
+    /**
+     * @since 0.1.1
+     */
     interface HTMLXplUtilityBarElement extends Components.XplUtilityBar, HTMLStencilElement {
         addEventListener<K extends keyof HTMLXplUtilityBarElementEventMap>(type: K, listener: (this: HTMLXplUtilityBarElement, ev: XplUtilityBarCustomEvent<HTMLXplUtilityBarElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -3278,7 +3850,9 @@ declare global {
         "xpl-secondary-nav": HTMLXplSecondaryNavElement;
         "xpl-select": HTMLXplSelectElement;
         "xpl-side-nav": HTMLXplSideNavElement;
+        "xpl-side-nav-header-item": HTMLXplSideNavHeaderItemElement;
         "xpl-side-nav-item": HTMLXplSideNavItemElement;
+        "xpl-side-nav-section": HTMLXplSideNavSectionElement;
         "xpl-skeleton": HTMLXplSkeletonElement;
         "xpl-slideout": HTMLXplSlideoutElement;
         "xpl-spotlight": HTMLXplSpotlightElement;
@@ -3295,12 +3869,16 @@ declare global {
         "xpl-tooltip": HTMLXplTooltipElement;
         "xpl-top-nav": HTMLXplTopNavElement;
         "xpl-top-nav-item": HTMLXplTopNavItemElement;
+        "xpl-top-nav-menu": HTMLXplTopNavMenuElement;
         "xpl-utility-bar": HTMLXplUtilityBarElement;
     }
 }
 declare namespace LocalJSX {
     type OneOf<K extends string, PropT, AttrT = PropT> = { [P in K]: PropT } & { [P in `attr:${K}` | `prop:${K}`]?: never } | { [P in `attr:${K}`]: AttrT } & { [P in K | `prop:${K}`]?: never } | { [P in `prop:${K}`]: PropT } & { [P in K | `attr:${K}`]?: never };
 
+    /**
+     * @since 2.0.0
+     */
     interface XplAccordion {
         /**
           * set the border of the accordion  none: there’s no border wrapping the header  bottom:there’s a border below the header  bordered: the header is wrapped by a white panel with a rounded border around it on every side
@@ -3330,6 +3908,9 @@ declare namespace LocalJSX {
          */
         "size"?: '1' | '2' | '3';
     }
+    /**
+     * @since 0.5.0
+     */
     interface XplApplicationShell {
         /**
           * @property {boolean} - *
@@ -3352,6 +3933,9 @@ declare namespace LocalJSX {
          */
         "withUtility"?: boolean;
     }
+    /**
+     * @since 0.1.1
+     */
     interface XplAvatar {
         /**
           * Background color when there is no image src
@@ -3400,6 +3984,9 @@ declare namespace LocalJSX {
          */
         "variant"?: AvatarVariant;
     }
+    /**
+     * @since 0.1.2
+     */
     interface XplBackdrop {
         /**
           * @property {boolean} - When true, backdrop will have relative position. This is useful when the backdrop doesn't cover the whole view area. If false, the position will be fixed and cover the whole view area.
@@ -3407,6 +3994,9 @@ declare namespace LocalJSX {
          */
         "relative"?: boolean;
     }
+    /**
+     * @since 0.1.1
+     */
     interface XplBadge {
         /**
           * Whether badge shows a bordered ring
@@ -3438,6 +4028,9 @@ declare namespace LocalJSX {
          */
         "variant"?: BadgeVariantProp;
     }
+    /**
+     * @since 2.6.0
+     */
     interface XplBanner {
         /**
           * Primary action label. When provided, an action button is rendered.
@@ -3497,6 +4090,9 @@ declare namespace LocalJSX {
     }
     interface XplBreadcrumbs {
     }
+    /**
+     * @since 0.1.1
+     */
     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).
@@ -3578,6 +4174,9 @@ declare namespace LocalJSX {
          */
         "variant"?: 'primary' | 'secondary' | 'tertiary' | 'subtle';
     }
+    /**
+     * @since 0.4.0
+     */
     interface XplButtonRow {
         /**
           * Fires on the primary button. If not set, the button can act as a standard submit button for a form.
@@ -3604,6 +4203,9 @@ declare namespace LocalJSX {
          */
         "tertiary"?: 'string';
     }
+    /**
+     * @since 2.0.0
+     */
     interface XplCalendar {
         /**
           * Format of the date displayed in the calendar. Default is 'Y-m-d'.
@@ -3637,6 +4239,9 @@ declare namespace LocalJSX {
          */
         "onDateSelected"?: (event: XplCalendarCustomEvent<string | string[]>) => void;
     }
+    /**
+     * @since 0.1.1
+     */
     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.
@@ -3684,6 +4289,9 @@ declare namespace LocalJSX {
          */
         "value"?: string;
     }
+    /**
+     * @since 0.1.1
+     */
     interface XplChoicelist {
         /**
           * An array of choices to be displayed in the list. Each choice should be an object with keys: - `checked` [boolean] - whether to pre-check or not - `children` [Choice[]] - an array of child choices (recursive) - `description` [string] - `label` [string]
@@ -3719,6 +4327,9 @@ declare namespace LocalJSX {
          */
         "styled"?: boolean;
     }
+    /**
+     * @since 0.1.2
+     */
     interface XplContentArea {
         /**
           * @property {string}  size  - The content-area size.
@@ -3726,8 +4337,14 @@ declare namespace LocalJSX {
          */
         "size"?: 'wide' | 'narrow' | 'full';
     }
+    /**
+     * @since 1.0.0
+     */
     interface XplDashboard {
     }
+    /**
+     * @since 1.0.0
+     */
     interface XplDataCard {
         /**
           * An optional field that typically describes or modifies the small stat
@@ -3785,12 +4402,18 @@ declare namespace LocalJSX {
          */
         "variant"?: 'primary' | 'secondary';
     }
+    /**
+     * @since 0.3.0
+     */
     interface XplDivider {
         /**
           * The tier should be an integer between 0 and 3. Tier 0 dividers do not display text, and 1-3 increase in size with each increasing tier.
          */
         "tier"?: number;
     }
+    /**
+     * @since 0.4.0
+     */
     interface XplDropdown {
         /**
           * whether to anchor the dropdown to the trigger element, requires triggerId to be set
@@ -3845,7 +4468,7 @@ declare namespace LocalJSX {
         /**
           * call back function invoked when a selection is made
          */
-        "update"?: (e, { component }: { component: Dropdown }) => void;
+        "update"?: (e: Event | null, context: { component: Dropdown }) => void;
     }
     interface XplDropdownGroup {
         /**
@@ -3889,12 +4512,18 @@ declare namespace LocalJSX {
          */
         "value"?: string;
     }
+    /**
+     * @since 1.4.0
+     */
     interface XplDynamicTable {
         /**
           * Emitted when the number of selected items changes.
          */
         "onSelectedItemCountChange"?: (event: XplDynamicTableCustomEvent<string[]>) => void;
     }
+    /**
+     * @since 1.3.0
+     */
     interface XplDynamicTableCell {
         /**
           * Whether the cell and its contents are disabled.
@@ -3902,6 +4531,9 @@ declare namespace LocalJSX {
          */
         "disabled"?: boolean;
     }
+    /**
+     * @since 1.3.0
+     */
     interface XplDynamicTableRow {
         /**
           * Whether the row and its cells are disabled.
@@ -3914,8 +4546,14 @@ declare namespace LocalJSX {
          */
         "selected"?: boolean;
     }
+    /**
+     * @since 0.4.0
+     */
     interface XplGrid {
     }
+    /**
+     * @since 0.4.0
+     */
     interface XplGridItem {
         /**
           * The number of columns the element should span  out of a 6 column grid on a  lg size screen
@@ -3938,6 +4576,9 @@ declare namespace LocalJSX {
          */
         "xs"?: number;
     }
+    /**
+     * @since 1.2.0
+     */
     interface XplHeaderAccordion {
         /**
           * The id of the content region controlled by the accordion.
@@ -3964,6 +4605,9 @@ declare namespace LocalJSX {
          */
         "selectedCount"?: number;
     }
+    /**
+     * @since 1.0.0
+     */
     interface XplIcon {
         /**
           * Icon's background color.
@@ -3979,6 +4623,9 @@ declare namespace LocalJSX {
          */
         "size"?: number;
     }
+    /**
+     * @since 0.3.0
+     */
     interface XplInput {
         /**
           * Because `id` is a reserved HTMLElement attribute, we prefix it with an underscore here so that it doesn't get automatically applied to the outer container.  Applies to all input types.
@@ -4515,6 +5162,9 @@ declare namespace LocalJSX {
          */
         "value"?: string;
     }
+    /**
+     * @since 1.9.1
+     */
     interface XplLargeCard {
         /**
           * Description of the Card
@@ -4529,6 +5179,9 @@ declare namespace LocalJSX {
          */
         "name"?: string;
     }
+    /**
+     * @since 0.4.0
+     */
     interface XplList {
         /**
           * Array of list items to render. Each item should follow the ListItem interface. **Deprecated.** Use slot-based xpl-list-item children instead.
@@ -4640,6 +5293,9 @@ declare namespace LocalJSX {
          */
         "titleBadgeVariant"?: BadgeVariantProp1;
     }
+    /**
+     * @since 0.1.2
+     */
     interface XplMainNav {
         /**
           * @event {string} navWidth - Emits the `nav-width` prop set by the user when the component is attached to the DOM and when the component is updated.
@@ -4651,6 +5307,9 @@ declare namespace LocalJSX {
          */
         "width"?: 'default' | 'md' | 'sm';
     }
+    /**
+     * @since 1.1.0
+     */
     interface XplModal {
         /**
           * Whether the modal is open.
@@ -4700,6 +5359,9 @@ declare namespace LocalJSX {
          */
         "username"?: string;
     }
+    /**
+     * @since 0.1.2
+     */
     interface XplNavItem {
         /**
           * @property {boolean} - Whether or not the item should control the main nav state on click
@@ -4711,6 +5373,9 @@ declare namespace LocalJSX {
          */
         "onNavOpen"?: (event: XplNavItemCustomEvent<boolean>) => void;
     }
+    /**
+     * @since 0.1.1
+     */
     interface XplPagination {
         /**
           * The current active page (1-based). Marked as mutable so we can update from inside this component.
@@ -4749,6 +5414,7 @@ declare namespace LocalJSX {
     /**
      * A stateless container that defines a section on a page and can house any
      * type of content. Panels are not dismissible and may contain a top accent.
+     * @since 2.6.0
      */
     interface XplPanel {
         /**
@@ -4762,6 +5428,9 @@ declare namespace LocalJSX {
          */
         "padding"?: 'default' | 'tight' | 'loose';
     }
+    /**
+     * @since 2.0.0
+     */
     interface XplPopover {
         /**
           * Whether the popover is disabled or not.
@@ -4788,6 +5457,9 @@ declare namespace LocalJSX {
          */
         "position"?: PopoverPosition;
     }
+    /**
+     * @since 2.6.0
+     */
     interface XplProgressBar {
         /**
           * The helper text displayed below the progress bar (recommended for error state)
@@ -4818,6 +5490,9 @@ declare namespace LocalJSX {
          */
         "variant"?: 'default' | 'success' | 'error' | 'indeterminate';
     }
+    /**
+     * @since 2.7.0
+     */
     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].
@@ -4844,6 +5519,9 @@ declare namespace LocalJSX {
          */
         "steps"?: string[];
     }
+    /**
+     * @since 0.1.1
+     */
     interface XplRadio {
         /**
           * Whether the input is "on"
@@ -4882,8 +5560,14 @@ declare namespace LocalJSX {
          */
         "value"?: string;
     }
+    /**
+     * @since 0.3.0
+     */
     interface XplSecondaryNav {
     }
+    /**
+     * @since 0.4.0
+     */
     interface XplSelect {
         /**
           * An array of choices for the user to choose from. Each choice should be of the form: {   label: string;   href?: string;   value?: string;   isGroupHeading?: boolean;   isSelected?: boolean;   isDisabled?: boolean;   options?: DropdownItem[];   groupName?: string; }
@@ -4909,12 +5593,12 @@ declare namespace LocalJSX {
         /**
           * Additional placements to try for the options panel when the default `dropdownPlacement` does not fit. Passed to `xpl-dropdown` / Floating UI `flip`.
          */
-        "dropdownFlipFallbackPlacements"?: Placement[];
+        "dropdownFlipFallbackPlacements"?: Placement1[];
         /**
           * 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;
+        "dropdownPlacement"?: Placement1;
         /**
           * 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.
          */
@@ -4971,8 +5655,8 @@ declare namespace LocalJSX {
         "truncate"?: boolean;
     }
     /**
-     * Slot-based sidebar for app navigation: a scrollable main `section` and a fixed
-     * `nav-footer`. Compose with `xpl-side-nav-item` for rows.
+     * Slot-based sidebar for app navigation: a scrollable `nav-header` + `section`
+     * area and a fixed `nav-footer`. Compose with `xpl-side-nav-item` for rows.
      * **Mobile (v2):** below the Tailwind `md` breakpoint, the sidebar collapses to a
      * ~56px top bar with a toggle button (`sidebar-left-show` / `sidebar-left-hide`).
      * Activating the toggle opens a drawer containing the `section` + `nav-footer`
@@ -4984,6 +5668,7 @@ declare namespace LocalJSX {
      * the `openChange` event, and the `toggle()` / `setOpen()` methods.
      * **v2 breaking change (beta):** consumers who wrapped their own mobile toggle
      * around `xpl-side-nav` should remove it — the toggle and drawer are now built in.
+     * @since 2.6.0
      */
     interface XplSideNav {
         /**
@@ -5000,6 +5685,53 @@ declare namespace LocalJSX {
          */
         "open"?: boolean;
     }
+    /**
+     * Header row for `xpl-side-nav`'s `nav-header` slot (Figma `<navHeaderItem>`,
+     * node `51299-9007`). Two types:
+     * - **`product-label` (default)** — a non-interactive `<div>` row that shows the
+     *   current product/area name in a subdued color. No click behavior.
+     * - **`sub-account`** — an interactive `<button>` row (e.g. a location / account
+     *   switcher). Emits `navigate` on activation (pointer click or keyboard); the
+     *   consumer wires this to open a modal or other entity-switching experience.
+     *   When no `slot="trailing"` content is provided, an auto chevron
+     *   (`chevron-expand-y`, a static dual-arrow glyph — no rotation) renders by default.
+     * Both types support `slot="leading"` / `slot="trailing"` (the `icon` prop is a
+     * convenience shorthand for `slot="leading"`, same as `xpl-side-nav-item`) so they
+     * can scale to future uses. Unlike `xpl-side-nav-item`, the leading/trailing
+     * columns are NOT unconditionally reserved — they only render when there is
+     * content, matching the Figma variants where the leading icon is an optional toggle.
+     * **Note on the `sub-account` hover / selected visual:** the interactive row
+     * mirrors `xpl-side-nav-item` — the hover and selected backgrounds fill a single
+     * `__content` pill that wraps the leading icon + label + trailing chevron, with
+     * an 8px (`--xpl-border-radius-default`) radius. The pill insets 8px from the nav
+     * edge (an 8px gutter on the button) so it lines up with the item rows below it,
+     * and hover/selected therefore highlight the whole row content rather than a
+     * partial fragment.
+     */
+    interface XplSideNavHeaderItem {
+        /**
+          * Optional icon name; renders as the default content for `slot="leading"`. When `slot="leading"` content is present, this prop is ignored.
+         */
+        "icon"?: string;
+        /**
+          * The display label for the header item (e.g. the product name or sub-account name).
+         */
+        "label"?: string;
+        /**
+          * Emitted when a `sub-account` item is activated (pointer click or keyboard activation of the native `<button>`). Not emitted for `product-label` (static, no interaction).
+         */
+        "onNavigate"?: (event: XplSideNavHeaderItemCustomEvent<void>) => void;
+        /**
+          * Whether the item is currently in a selected state. Only meaningful when `type` is `sub-account` — applies the information-surface pill around the label + trailing chevron.
+          * @default false
+         */
+        "selected"?: boolean;
+        /**
+          * The header item variant. `product-label` is a static, non-interactive label. `sub-account` is an interactive button that emits `navigate`.
+          * @default 'product-label'
+         */
+        "type"?: 'product-label' | 'sub-account';
+    }
     /**
      * Navigation row for `xpl-side-nav`. Renders a button (default) or a slot-only
      * anchor container (`link` mode). Three slot positions are available:
@@ -5063,15 +5795,54 @@ declare namespace LocalJSX {
          */
         "onExpandedChange"?: (event: XplSideNavItemCustomEvent<boolean>) => void;
         /**
-          * Emitted when a leaf item is clicked. Expandable parents use `expandedChange` instead.
+          * Emitted when a leaf item is activated (pointer click or keyboard activation of the native `<button>`). Expandable parents use `expandedChange` instead.
          */
-        "onNavClick"?: (event: XplSideNavItemCustomEvent<void>) => void;
+        "onNavigate"?: (event: XplSideNavItemCustomEvent<void>) => void;
         /**
           * Whether the item is currently in a selected state.
           * @default false
          */
         "selected"?: boolean;
     }
+    /**
+     * Grouping / accordion header for `xpl-side-nav`. Wraps nested `xpl-side-nav-item`
+     * (and optional divider separators) elements in the default slot and collapses
+     * them as a unit.
+     * Two variants:
+     * - **Collapsible (default, `collapsible=true`)** — a `<button>` header with a
+     *   chevron (`chevron-right` collapsed / `chevron-down` expanded, no rotation —
+     *   the glyph itself swaps). Click toggles `expanded` and emits `expandedChange`.
+     * - **Static (`collapsible=false`)** — a non-interactive title row with no chevron;
+     *   children are always shown. Used for a static section label (e.g. a future
+     *   product-name / location-changer header).
+     * Unlike `xpl-side-nav-item[has-children]`, section children are **not indented**
+     * — they align with top-level items at the same leading-icon column.
+     * `slot="badge"` renders an optional badge (e.g. `xpl-badge`) in the header title
+     * row. The wrapper is suppressed when the slot is empty.
+     */
+    interface XplSideNavSection {
+        /**
+          * Whether the section can be collapsed/expanded. When `false`, renders a static title (no chevron, not a button) and children are always shown.
+          * @default true
+         */
+        "collapsible"?: boolean;
+        /**
+          * Whether the section is currently expanded. Only meaningful when `collapsible` is true.
+          * @default false
+         */
+        "expanded"?: boolean;
+        /**
+          * The section title text. Optional, but when `collapsible` is true and both `heading` and `slot="badge"` lack an accessible name, the toggle `<button>` falls back to `aria-label="Toggle section"` so it always has an accessible name.
+         */
+        "heading"?: string;
+        /**
+          * Emitted when the expanded state changes (collapsible sections only). Detail is the new expanded value.
+         */
+        "onExpandedChange"?: (event: XplSideNavSectionCustomEvent<boolean>) => void;
+    }
+    /**
+     * @since 2.3.6
+     */
     interface XplSkeleton {
         /**
           * A CSS class name to apply to the component.
@@ -5111,6 +5882,9 @@ declare namespace LocalJSX {
          */
         "width"?: CSSStyleDeclaration['width'];
     }
+    /**
+     * @since 1.1.0
+     */
     interface XplSlideout {
         /**
           * Whether to show a backdrop behind the slideout.
@@ -5137,6 +5911,9 @@ declare namespace LocalJSX {
          */
         "variant"?: 'default' | 'warning';
     }
+    /**
+     * @since 2.7.0
+     */
     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`.
@@ -5222,7 +5999,19 @@ declare namespace LocalJSX {
          */
         "totalSteps"?: number;
     }
+    /**
+     * @since 2.3.8
+     */
     interface XplTab {
+        /**
+          * Optional trailing number badge (e.g. a count). Rendered after the label as a compact `xpl-badge` in both underline (`type="tabs"`) and segment (`type="segment"`) tabs. Leave empty to omit the badge.
+         */
+        "badge"?: string;
+        /**
+          * Color palette for the trailing number badge. Only applies when `badge` is set. Defaults to `purple` — the standard number-badge color in the Figma XPL-Tab Group spec.
+          * @default 'purple'
+         */
+        "badgeVariant"?: BadgePalette;
         /**
           * Disables this tab (pill or underline).
           * @default false
@@ -5234,11 +6023,11 @@ declare namespace LocalJSX {
          */
         "groupDisabled"?: boolean;
         /**
-          * Optional icon name for segment-style pills (`type="segment"` on parent `xpl-tabs`). Ignored for default tabs.
+          * Optional leading icon name (from the Apollo icon set). Rendered in both underline (`type="tabs"`) and segment (`type="segment"`) tabs.
          */
         "icon"?: string;
         /**
-          * Icon position for segment-style pills.
+          * Icon position relative to the label. Applies to both underline and segment tabs.
           * @default 'start'
          */
         "iconPosition"?: 'start' | 'end';
@@ -5256,6 +6045,9 @@ declare namespace LocalJSX {
          */
         "target"?: string;
     }
+    /**
+     * @since 2.3.8
+     */
     interface XplTabPanel {
         /**
           * Whether the panel is selected
@@ -5267,6 +6059,9 @@ declare namespace LocalJSX {
          */
         "target"?: string;
     }
+    /**
+     * @since 0.1.1
+     */
     interface XplTable {
         /**
           * The header values for each column.
@@ -5294,12 +6089,12 @@ declare namespace LocalJSX {
          */
         "multiselect"?: boolean;
         /**
-          * Emits an event whenever the sort changes. The 'sortChanged' event passes an object with colNum (number), colName (string), sortTypeArr(string[]). The default action can be overridden by calling event.preventDefault().
+          * Emits an event whenever the sort changes. The 'sortChanged' event passes an object with colNum (number), colName (string), sortTypeArr(('asc' | 'desc' | null)[]). The default action can be overridden by calling event.preventDefault().
          */
         "onSortChanged"?: (event: XplTableCustomEvent<{
         colNum: number;
         colName: string;
-        sortTypeArr: string[];
+        sortTypeArr: ('asc' | 'desc' | null)[];
     }>) => void;
         /**
           * Callback function that is called when the checkbox for a row of a `multiselect` table is checked
@@ -5320,8 +6115,14 @@ declare namespace LocalJSX {
          */
         "striped"?: boolean;
     }
+    /**
+     * @since 1.0.0
+     */
     interface XplTableHeader {
     }
+    /**
+     * @since 1.3.0
+     */
     interface XplTableHeaderCell {
         /**
           * Icon to display in the cell.  See [xpl-icon available icons](../xpl-icon/ICONS.md) for valid icon names.
@@ -5351,6 +6152,9 @@ declare namespace LocalJSX {
          */
         "width"?: number;
     }
+    /**
+     * @since 2.3.8
+     */
     interface XplTabs {
         /**
           * Disables the whole tab group (headings, mobile select, and segment pills).
@@ -5376,6 +6180,9 @@ declare namespace LocalJSX {
          */
         "value"?: string;
     }
+    /**
+     * @since 0.4.0
+     */
     interface XplTag {
         /**
           * Whether the tag is disabled
@@ -5419,32 +6226,44 @@ declare namespace LocalJSX {
          */
         "tagId"?: string;
     }
+    /**
+     * @since 1.2.0
+     */
     interface XplToast {
         /**
-          * @property {string} - The caption of the toast, limited to 85 characters
+          * The caption of the toast, limited to 85 characters.
+          * @default ''
          */
         "caption"?: string;
         /**
-          * @property {boolean} - Whether or not the toast is dismissible
-          * @default true
+          * Whether the toast shows a dismiss (close) button.
+          * @deprecated Misspelled. Use `dismissible` instead. When both are set, `dismissable` wins so existing markup keeps working; `dismissable` is removed in the next major version.
          */
         "dismissable"?: boolean;
         /**
-          * @property {boolean} - Whether or not to show the icon
+          * Whether the toast shows a dismiss (close) button.
+          * @default true
+         */
+        "dismissible"?: boolean;
+        /**
+          * Whether to show the leading sentiment icon.
           * @default true
          */
         "showIcon"?: boolean;
         /**
-          * @property {number} - The timeout for the toast to dismiss in ms, default 8 seconds
+          * How long the toast waits before auto-dismissing, in ms. Set to `0` to disable auto-dismiss. Ignored when the `action` slot has content.
           * @default 8000
          */
         "timeout"?: number;
         /**
-          * @property {string} - The variant of the toast
+          * The sentiment of the toast.
           * @default 'neutral'
          */
         "variant"?: 'neutral' | 'warning' | 'success';
     }
+    /**
+     * @since 0.3.0
+     */
     interface XplToggle {
         /**
           * Whether the toggle is `on`
@@ -5480,6 +6299,9 @@ declare namespace LocalJSX {
          */
         "variant"?: 'default' | 'small';
     }
+    /**
+     * @since 1.2.0
+     */
     interface XplToolbar {
         /**
           * The number of selected items to display in the toolbar.
@@ -5487,6 +6309,9 @@ declare namespace LocalJSX {
          */
         "selectedItemCount"?: number;
     }
+    /**
+     * @since 1.7.0
+     */
     interface XplTooltip {
         /**
           * Hide the arrow
@@ -5515,6 +6340,7 @@ declare namespace LocalJSX {
      * (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).
+     * **Outside click:** With **`nav-control`**, a click outside the drawer panel (**`.xpl-top-nav__left-primary`**) also closes it and emits **`navOpen`** **`false`** (document **capture**, mirroring **`xpl-top-nav-item`**); it skips clicks on the hamburger toggle and while a descendant **`xpl-popover`** is open, and does not move focus.
      * **`xpl-top-nav-item`** **`slot="dropdown"`** uses document **capture** for **Escape** first; the shell uses **bubble**
      * on **`ownerDocument`** so nested dropdowns close before the drawer.
      * **Theming:** The host always includes Foundation’s **`dark`** class so **`--xpl-*`** purpose tokens under this subtree
@@ -5531,6 +6357,7 @@ declare namespace LocalJSX {
      * **`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.
+     * @since 2.7.0
      */
     interface XplTopNav {
         /**
@@ -5567,16 +6394,19 @@ declare namespace LocalJSX {
         "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
+     * Single nav row for **`xpl-top-nav`** / **`xpl-nav-header-menu`** / **`xpl-top-nav-menu`**. The host uses
+     * **`role="listitem"`** when the row participates in a list: a **`role="list"`** parent, **`slot="left-aside"`** on
+     * **`xpl-top-nav`** (list host is **`.xpl-top-nav__left-primary`** while slotted nodes stay light-DOM children of
+     * **`xpl-top-nav`**), or default-slot rows under **`xpl-nav-header-menu`** / **`xpl-top-nav-menu`**. That flag is
      * kept in **`@State`** and refreshed after render plus via **`MutationObserver`** on the host (**`class`**, **`slot`**) and
      * on **`parentElement`** (**`role`**) or on **`.xpl-top-nav__left-primary`** (**`role`**) for **`slot="left-aside"`** under **`xpl-top-nav`**) so DOM context changes
      * without a full reconnect still re-sync. The internal
      * **`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`**.
+     * **This component does triple duty:** a plain bar item, a dropdown trigger (**`slot="dropdown"`** present), and a
+     * dropdown/menu **row** (nested inside **`xpl-nav-header-menu`** or **`xpl-top-nav-menu`**). The **`description`** prop
+     * only applies in the row context — bar items and triggers do not show it in Figma.
      * **Default slot (no `label`):** do not put **`xpl-top-nav-item__inner`** or other **`xpl-top-nav-item__*`** classes on
      * custom trigger content — the component renders the inner wrapper and BEM elements.
      * **Theming:** The host always includes Foundation’s **`dark`** class so **`--xpl-*`** purpose tokens resolve to dark-mode
@@ -5588,12 +6418,16 @@ declare namespace LocalJSX {
           * @default false
          */
         "active"?: boolean;
+        /**
+          * Optional description line shown below **`label`** (row context only, e.g. inside **`xpl-nav-header-menu`** / **`xpl-top-nav-menu`**). Ignored when **`label`** is not set.
+         */
+        "description"?: string;
         /**
           * 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).
+          * Icon name from **`@xplortech/apollo-icons`** (shown before the label when **`label`** is set). Ignored when **`slot="leading-icon"`** content is present.
           * @default ''
          */
         "icon"?: string;
@@ -5606,15 +6440,57 @@ declare namespace LocalJSX {
          */
         "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.
+          * Emitted for plain items (button or link) on pointer **click**, or when keyboard activation produces a **`click`**: the native **`<button>`** fires a real **`click`** on **Enter** / **Space**, a native **`<a href>`** on **Enter**, and **Space** on a link maps to a programmatic **`.click()`**. **`detail`** is always the real **`MouseEvent`** from that activation (keyboard-driven clicks have **`detail === 0`**). Not emitted when **`slot="dropdown"`** is used.
          */
         "onNavItemClick"?: (event: XplTopNavItemCustomEvent<MouseEvent>) => void;
+        /**
+          * Emitted whenever **`open`** changes (click, hover, keyboard, Escape, outside click, or programmatic).
+         */
+        "onOpenChange"?: (event: XplTopNavItemCustomEvent<boolean>) => void;
+        /**
+          * Whether the **`slot="dropdown"`** panel is open. Reflected to the **`open`** attribute so consumers can drive it (controlled) or read it back (uncontrolled, toggled internally on click / hover / keyboard activation). Prefer **`openMenu()`** / **`closeMenu()`** / **`toggleMenu()`** over setting this directly from event handlers.
+          * @default false
+         */
+        "open"?: boolean;
+        /**
+          * How the **`slot="dropdown"`** panel opens. **`hover`** is gated on **`TOP_NAV_ITEM_HOVER_OPEN_MQ`** (hover-capable, fine pointer, **`md`** and up) — below that, or on touch / coarse-pointer devices, **`hover`** falls back to click/tap. Keyboard activation (Enter / Space) always toggles regardless of **`openMode`**.
+          * @default 'click'
+         */
+        "openMode"?: 'click' | 'hover';
         /**
           * When true, sets **`aria-current="page"`** and selected styling.
           * @default false
          */
         "selected"?: boolean;
     }
+    /**
+     * Thin grouping container for **`xpl-top-nav-item`** rows — the panel content for a desktop flyout
+     * (**`slot="dropdown"`** on the parent **`xpl-top-nav-item`**) and, on small screens, the **mobile
+     * cascade**: the same markup drills in to a **Level 2** view in place, with an auto-rendered **back
+     * row** (leading **`chevron-left`** + this component's **`label`**) as the first row. Tapping the back
+     * row closes the parent trigger's dropdown (**`closeMenu()`**), returning to **Level 1** and restoring
+     * focus to the parent trigger. No item logic otherwise lives here — row behavior (icons, description,
+     * links, nested dropdowns) is entirely **`xpl-top-nav-item`**.
+     * **One authoring markup, two renderings:** consumers write this once; **`isMobileCascade`** (synced
+     * from **`TOP_NAV_MOBILE_MQ`**) decides whether the back row renders. Desktop never sees it — the
+     * flyout is a single level of links (see `xpl-top-nav-item`'s cascade-depth notes).
+     * **Panel chrome** is shared with **`xpl-nav-header-menu`** (the account menu): width
+     * (**`--xpl-top-nav-panel-width`**), surface, shadow, radius, and vertical padding all come from the
+     * same selector in `top-nav.css` so the desktop flyout, mobile cascade, and account menu read as one
+     * visual family.
+     * **Theming:** The host always includes Foundation’s **`dark`** class so **`--xpl-*`** purpose tokens
+     * resolve to dark-mode values even when the page root is light (consistent with the rest of the
+     * **`xpl-top-nav`** family).
+     */
+    interface XplTopNavMenu {
+        /**
+          * Accessible name for the list (**`aria-label`** on the host) and the label shown in the mobile cascade back row when drilling back out of this group.
+         */
+        "label"?: string;
+    }
+    /**
+     * @since 0.1.1
+     */
     interface XplUtilityBar {
         /**
           * @property {boolean} - Optional property that defines whether or not the main nav is open at startup.
@@ -6015,6 +6891,12 @@ declare namespace LocalJSX {
         "label": string;
         "open": boolean;
     }
+    interface XplSideNavHeaderItemAttributes {
+        "icon": string;
+        "label": string;
+        "selected": boolean;
+        "type": 'product-label' | 'sub-account';
+    }
     interface XplSideNavItemAttributes {
         "disabled": boolean;
         "expanded": boolean;
@@ -6025,6 +6907,11 @@ declare namespace LocalJSX {
         "link": boolean;
         "selected": boolean;
     }
+    interface XplSideNavSectionAttributes {
+        "collapsible": boolean;
+        "expanded": boolean;
+        "heading": string;
+    }
     interface XplSkeletonAttributes {
         "classNames": string;
         "fullWidth": boolean;
@@ -6064,6 +6951,8 @@ declare namespace LocalJSX {
         "totalSteps": number;
     }
     interface XplTabAttributes {
+        "badge": string;
+        "badgeVariant": BadgePalette;
         "disabled": boolean;
         "groupDisabled": boolean;
         "icon": string;
@@ -6102,11 +6991,12 @@ declare namespace LocalJSX {
         "tagId": string;
     }
     interface XplToastAttributes {
-        "variant": 'neutral' | 'warning' | 'success';
-        "showIcon": boolean;
         "caption": string;
         "dismissable": boolean;
+        "dismissible": boolean;
+        "showIcon": boolean;
         "timeout": number;
+        "variant": 'neutral' | 'warning' | 'success';
     }
     interface XplToggleAttributes {
         "checked": boolean;
@@ -6142,12 +7032,18 @@ declare namespace LocalJSX {
     }
     interface XplTopNavItemAttributes {
         "active": boolean;
+        "description": string;
         "href": string;
         "icon": string;
         "itemAriaLabel": string;
         "label": string;
+        "open": boolean;
+        "openMode": 'click' | 'hover';
         "selected": boolean;
     }
+    interface XplTopNavMenuAttributes {
+        "label": string;
+    }
     interface XplUtilityBarAttributes {
         "navControl": boolean;
         "isNavOpenAtStartup": boolean;
@@ -6205,7 +7101,9 @@ declare namespace LocalJSX {
         "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] };
         "xpl-side-nav": Omit<XplSideNav, keyof XplSideNavAttributes> & { [K in keyof XplSideNav & keyof XplSideNavAttributes]?: XplSideNav[K] } & { [K in keyof XplSideNav & keyof XplSideNavAttributes as `attr:${K}`]?: XplSideNavAttributes[K] } & { [K in keyof XplSideNav & keyof XplSideNavAttributes as `prop:${K}`]?: XplSideNav[K] };
+        "xpl-side-nav-header-item": Omit<XplSideNavHeaderItem, keyof XplSideNavHeaderItemAttributes> & { [K in keyof XplSideNavHeaderItem & keyof XplSideNavHeaderItemAttributes]?: XplSideNavHeaderItem[K] } & { [K in keyof XplSideNavHeaderItem & keyof XplSideNavHeaderItemAttributes as `attr:${K}`]?: XplSideNavHeaderItemAttributes[K] } & { [K in keyof XplSideNavHeaderItem & keyof XplSideNavHeaderItemAttributes as `prop:${K}`]?: XplSideNavHeaderItem[K] };
         "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-side-nav-section": Omit<XplSideNavSection, keyof XplSideNavSectionAttributes> & { [K in keyof XplSideNavSection & keyof XplSideNavSectionAttributes]?: XplSideNavSection[K] } & { [K in keyof XplSideNavSection & keyof XplSideNavSectionAttributes as `attr:${K}`]?: XplSideNavSectionAttributes[K] } & { [K in keyof XplSideNavSection & keyof XplSideNavSectionAttributes as `prop:${K}`]?: XplSideNavSection[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] };
@@ -6222,6 +7120,7 @@ declare namespace LocalJSX {
         "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-top-nav-menu": Omit<XplTopNavMenu, keyof XplTopNavMenuAttributes> & { [K in keyof XplTopNavMenu & keyof XplTopNavMenuAttributes]?: XplTopNavMenu[K] } & { [K in keyof XplTopNavMenu & keyof XplTopNavMenuAttributes as `attr:${K}`]?: XplTopNavMenuAttributes[K] } & { [K in keyof XplTopNavMenu & keyof XplTopNavMenuAttributes as `prop:${K}`]?: XplTopNavMenu[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] };
     }
 }
@@ -6229,34 +7128,106 @@ export { LocalJSX as JSX };
 declare module "@stencil/core" {
     export namespace JSX {
         interface IntrinsicElements {
+            /**
+             * @since 2.0.0
+             */
             "xpl-accordion": LocalJSX.IntrinsicElements["xpl-accordion"] & JSXBase.HTMLAttributes<HTMLXplAccordionElement>;
+            /**
+             * @since 0.5.0
+             */
             "xpl-application-shell": LocalJSX.IntrinsicElements["xpl-application-shell"] & JSXBase.HTMLAttributes<HTMLXplApplicationShellElement>;
+            /**
+             * @since 0.1.1
+             */
             "xpl-avatar": LocalJSX.IntrinsicElements["xpl-avatar"] & JSXBase.HTMLAttributes<HTMLXplAvatarElement>;
+            /**
+             * @since 0.1.2
+             */
             "xpl-backdrop": LocalJSX.IntrinsicElements["xpl-backdrop"] & JSXBase.HTMLAttributes<HTMLXplBackdropElement>;
+            /**
+             * @since 0.1.1
+             */
             "xpl-badge": LocalJSX.IntrinsicElements["xpl-badge"] & JSXBase.HTMLAttributes<HTMLXplBadgeElement>;
+            /**
+             * @since 2.6.0
+             */
             "xpl-banner": LocalJSX.IntrinsicElements["xpl-banner"] & JSXBase.HTMLAttributes<HTMLXplBannerElement>;
             "xpl-breadcrumb-item": LocalJSX.IntrinsicElements["xpl-breadcrumb-item"] & JSXBase.HTMLAttributes<HTMLXplBreadcrumbItemElement>;
             "xpl-breadcrumbs": LocalJSX.IntrinsicElements["xpl-breadcrumbs"] & JSXBase.HTMLAttributes<HTMLXplBreadcrumbsElement>;
+            /**
+             * @since 0.1.1
+             */
             "xpl-button": LocalJSX.IntrinsicElements["xpl-button"] & JSXBase.HTMLAttributes<HTMLXplButtonElement>;
+            /**
+             * @since 0.4.0
+             */
             "xpl-button-row": LocalJSX.IntrinsicElements["xpl-button-row"] & JSXBase.HTMLAttributes<HTMLXplButtonRowElement>;
+            /**
+             * @since 2.0.0
+             */
             "xpl-calendar": LocalJSX.IntrinsicElements["xpl-calendar"] & JSXBase.HTMLAttributes<HTMLXplCalendarElement>;
+            /**
+             * @since 0.1.1
+             */
             "xpl-checkbox": LocalJSX.IntrinsicElements["xpl-checkbox"] & JSXBase.HTMLAttributes<HTMLXplCheckboxElement>;
+            /**
+             * @since 0.1.1
+             */
             "xpl-choicelist": LocalJSX.IntrinsicElements["xpl-choicelist"] & JSXBase.HTMLAttributes<HTMLXplChoicelistElement>;
+            /**
+             * @since 0.1.2
+             */
             "xpl-content-area": LocalJSX.IntrinsicElements["xpl-content-area"] & JSXBase.HTMLAttributes<HTMLXplContentAreaElement>;
+            /**
+             * @since 1.0.0
+             */
             "xpl-dashboard": LocalJSX.IntrinsicElements["xpl-dashboard"] & JSXBase.HTMLAttributes<HTMLXplDashboardElement>;
+            /**
+             * @since 1.0.0
+             */
             "xpl-data-card": LocalJSX.IntrinsicElements["xpl-data-card"] & JSXBase.HTMLAttributes<HTMLXplDataCardElement>;
+            /**
+             * @since 0.3.0
+             */
             "xpl-divider": LocalJSX.IntrinsicElements["xpl-divider"] & JSXBase.HTMLAttributes<HTMLXplDividerElement>;
+            /**
+             * @since 0.4.0
+             */
             "xpl-dropdown": LocalJSX.IntrinsicElements["xpl-dropdown"] & JSXBase.HTMLAttributes<HTMLXplDropdownElement>;
             "xpl-dropdown-group": LocalJSX.IntrinsicElements["xpl-dropdown-group"] & JSXBase.HTMLAttributes<HTMLXplDropdownGroupElement>;
             "xpl-dropdown-heading": LocalJSX.IntrinsicElements["xpl-dropdown-heading"] & JSXBase.HTMLAttributes<HTMLXplDropdownHeadingElement>;
             "xpl-dropdown-option": LocalJSX.IntrinsicElements["xpl-dropdown-option"] & JSXBase.HTMLAttributes<HTMLXplDropdownOptionElement>;
+            /**
+             * @since 1.4.0
+             */
             "xpl-dynamic-table": LocalJSX.IntrinsicElements["xpl-dynamic-table"] & JSXBase.HTMLAttributes<HTMLXplDynamicTableElement>;
+            /**
+             * @since 1.3.0
+             */
             "xpl-dynamic-table-cell": LocalJSX.IntrinsicElements["xpl-dynamic-table-cell"] & JSXBase.HTMLAttributes<HTMLXplDynamicTableCellElement>;
+            /**
+             * @since 1.3.0
+             */
             "xpl-dynamic-table-row": LocalJSX.IntrinsicElements["xpl-dynamic-table-row"] & JSXBase.HTMLAttributes<HTMLXplDynamicTableRowElement>;
+            /**
+             * @since 0.4.0
+             */
             "xpl-grid": LocalJSX.IntrinsicElements["xpl-grid"] & JSXBase.HTMLAttributes<HTMLXplGridElement>;
+            /**
+             * @since 0.4.0
+             */
             "xpl-grid-item": LocalJSX.IntrinsicElements["xpl-grid-item"] & JSXBase.HTMLAttributes<HTMLXplGridItemElement>;
+            /**
+             * @since 1.2.0
+             */
             "xpl-header-accordion": LocalJSX.IntrinsicElements["xpl-header-accordion"] & JSXBase.HTMLAttributes<HTMLXplHeaderAccordionElement>;
+            /**
+             * @since 1.0.0
+             */
             "xpl-icon": LocalJSX.IntrinsicElements["xpl-icon"] & JSXBase.HTMLAttributes<HTMLXplIconElement>;
+            /**
+             * @since 0.3.0
+             */
             "xpl-input": LocalJSX.IntrinsicElements["xpl-input"] & JSXBase.HTMLAttributes<HTMLXplInputElement>;
             "xpl-input-color": LocalJSX.IntrinsicElements["xpl-input-color"] & JSXBase.HTMLAttributes<HTMLXplInputColorElement>;
             "xpl-input-date": LocalJSX.IntrinsicElements["xpl-input-date"] & JSXBase.HTMLAttributes<HTMLXplInputDateElement>;
@@ -6267,10 +7238,22 @@ declare module "@stencil/core" {
             "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>;
+            /**
+             * @since 1.9.1
+             */
             "xpl-large-card": LocalJSX.IntrinsicElements["xpl-large-card"] & JSXBase.HTMLAttributes<HTMLXplLargeCardElement>;
+            /**
+             * @since 0.4.0
+             */
             "xpl-list": LocalJSX.IntrinsicElements["xpl-list"] & JSXBase.HTMLAttributes<HTMLXplListElement>;
             "xpl-list-item": LocalJSX.IntrinsicElements["xpl-list-item"] & JSXBase.HTMLAttributes<HTMLXplListItemElement>;
+            /**
+             * @since 0.1.2
+             */
             "xpl-main-nav": LocalJSX.IntrinsicElements["xpl-main-nav"] & JSXBase.HTMLAttributes<HTMLXplMainNavElement>;
+            /**
+             * @since 1.1.0
+             */
             "xpl-modal": LocalJSX.IntrinsicElements["xpl-modal"] & JSXBase.HTMLAttributes<HTMLXplModalElement>;
             /**
              * Profile / account block (username, email, default slot for **`xpl-top-nav-item`** / **`xpl-divider`**).
@@ -6291,22 +7274,47 @@ declare module "@stencil/core" {
              * 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>;
+            /**
+             * @since 0.1.2
+             */
             "xpl-nav-item": LocalJSX.IntrinsicElements["xpl-nav-item"] & JSXBase.HTMLAttributes<HTMLXplNavItemElement>;
+            /**
+             * @since 0.1.1
+             */
             "xpl-pagination": LocalJSX.IntrinsicElements["xpl-pagination"] & JSXBase.HTMLAttributes<HTMLXplPaginationElement>;
             /**
              * A stateless container that defines a section on a page and can house any
              * type of content. Panels are not dismissible and may contain a top accent.
+             * @since 2.6.0
              */
             "xpl-panel": LocalJSX.IntrinsicElements["xpl-panel"] & JSXBase.HTMLAttributes<HTMLXplPanelElement>;
+            /**
+             * @since 2.0.0
+             */
             "xpl-popover": LocalJSX.IntrinsicElements["xpl-popover"] & JSXBase.HTMLAttributes<HTMLXplPopoverElement>;
+            /**
+             * @since 2.6.0
+             */
             "xpl-progress-bar": LocalJSX.IntrinsicElements["xpl-progress-bar"] & JSXBase.HTMLAttributes<HTMLXplProgressBarElement>;
+            /**
+             * @since 2.7.0
+             */
             "xpl-progress-indicator": LocalJSX.IntrinsicElements["xpl-progress-indicator"] & JSXBase.HTMLAttributes<HTMLXplProgressIndicatorElement>;
+            /**
+             * @since 0.1.1
+             */
             "xpl-radio": LocalJSX.IntrinsicElements["xpl-radio"] & JSXBase.HTMLAttributes<HTMLXplRadioElement>;
+            /**
+             * @since 0.3.0
+             */
             "xpl-secondary-nav": LocalJSX.IntrinsicElements["xpl-secondary-nav"] & JSXBase.HTMLAttributes<HTMLXplSecondaryNavElement>;
+            /**
+             * @since 0.4.0
+             */
             "xpl-select": LocalJSX.IntrinsicElements["xpl-select"] & JSXBase.HTMLAttributes<HTMLXplSelectElement>;
             /**
-             * Slot-based sidebar for app navigation: a scrollable main `section` and a fixed
-             * `nav-footer`. Compose with `xpl-side-nav-item` for rows.
+             * Slot-based sidebar for app navigation: a scrollable `nav-header` + `section`
+             * area and a fixed `nav-footer`. Compose with `xpl-side-nav-item` for rows.
              * **Mobile (v2):** below the Tailwind `md` breakpoint, the sidebar collapses to a
              * ~56px top bar with a toggle button (`sidebar-left-show` / `sidebar-left-hide`).
              * Activating the toggle opens a drawer containing the `section` + `nav-footer`
@@ -6318,8 +7326,33 @@ declare module "@stencil/core" {
              * the `openChange` event, and the `toggle()` / `setOpen()` methods.
              * **v2 breaking change (beta):** consumers who wrapped their own mobile toggle
              * around `xpl-side-nav` should remove it — the toggle and drawer are now built in.
+             * @since 2.6.0
              */
             "xpl-side-nav": LocalJSX.IntrinsicElements["xpl-side-nav"] & JSXBase.HTMLAttributes<HTMLXplSideNavElement>;
+            /**
+             * Header row for `xpl-side-nav`'s `nav-header` slot (Figma `<navHeaderItem>`,
+             * node `51299-9007`). Two types:
+             * - **`product-label` (default)** — a non-interactive `<div>` row that shows the
+             *   current product/area name in a subdued color. No click behavior.
+             * - **`sub-account`** — an interactive `<button>` row (e.g. a location / account
+             *   switcher). Emits `navigate` on activation (pointer click or keyboard); the
+             *   consumer wires this to open a modal or other entity-switching experience.
+             *   When no `slot="trailing"` content is provided, an auto chevron
+             *   (`chevron-expand-y`, a static dual-arrow glyph — no rotation) renders by default.
+             * Both types support `slot="leading"` / `slot="trailing"` (the `icon` prop is a
+             * convenience shorthand for `slot="leading"`, same as `xpl-side-nav-item`) so they
+             * can scale to future uses. Unlike `xpl-side-nav-item`, the leading/trailing
+             * columns are NOT unconditionally reserved — they only render when there is
+             * content, matching the Figma variants where the leading icon is an optional toggle.
+             * **Note on the `sub-account` hover / selected visual:** the interactive row
+             * mirrors `xpl-side-nav-item` — the hover and selected backgrounds fill a single
+             * `__content` pill that wraps the leading icon + label + trailing chevron, with
+             * an 8px (`--xpl-border-radius-default`) radius. The pill insets 8px from the nav
+             * edge (an 8px gutter on the button) so it lines up with the item rows below it,
+             * and hover/selected therefore highlight the whole row content rather than a
+             * partial fragment.
+             */
+            "xpl-side-nav-header-item": LocalJSX.IntrinsicElements["xpl-side-nav-header-item"] & JSXBase.HTMLAttributes<HTMLXplSideNavHeaderItemElement>;
             /**
              * Navigation row for `xpl-side-nav`. Renders a button (default) or a slot-only
              * anchor container (`link` mode). Three slot positions are available:
@@ -6345,25 +7378,85 @@ declare module "@stencil/core" {
              * | (no trailing slot) | `slot="trailing"` | Add for custom trailing content |
              */
             "xpl-side-nav-item": LocalJSX.IntrinsicElements["xpl-side-nav-item"] & JSXBase.HTMLAttributes<HTMLXplSideNavItemElement>;
+            /**
+             * Grouping / accordion header for `xpl-side-nav`. Wraps nested `xpl-side-nav-item`
+             * (and optional divider separators) elements in the default slot and collapses
+             * them as a unit.
+             * Two variants:
+             * - **Collapsible (default, `collapsible=true`)** — a `<button>` header with a
+             *   chevron (`chevron-right` collapsed / `chevron-down` expanded, no rotation —
+             *   the glyph itself swaps). Click toggles `expanded` and emits `expandedChange`.
+             * - **Static (`collapsible=false`)** — a non-interactive title row with no chevron;
+             *   children are always shown. Used for a static section label (e.g. a future
+             *   product-name / location-changer header).
+             * Unlike `xpl-side-nav-item[has-children]`, section children are **not indented**
+             * — they align with top-level items at the same leading-icon column.
+             * `slot="badge"` renders an optional badge (e.g. `xpl-badge`) in the header title
+             * row. The wrapper is suppressed when the slot is empty.
+             */
+            "xpl-side-nav-section": LocalJSX.IntrinsicElements["xpl-side-nav-section"] & JSXBase.HTMLAttributes<HTMLXplSideNavSectionElement>;
+            /**
+             * @since 2.3.6
+             */
             "xpl-skeleton": LocalJSX.IntrinsicElements["xpl-skeleton"] & JSXBase.HTMLAttributes<HTMLXplSkeletonElement>;
+            /**
+             * @since 1.1.0
+             */
             "xpl-slideout": LocalJSX.IntrinsicElements["xpl-slideout"] & JSXBase.HTMLAttributes<HTMLXplSlideoutElement>;
+            /**
+             * @since 2.7.0
+             */
             "xpl-spotlight": LocalJSX.IntrinsicElements["xpl-spotlight"] & JSXBase.HTMLAttributes<HTMLXplSpotlightElement>;
+            /**
+             * @since 2.3.8
+             */
             "xpl-tab": LocalJSX.IntrinsicElements["xpl-tab"] & JSXBase.HTMLAttributes<HTMLXplTabElement>;
+            /**
+             * @since 2.3.8
+             */
             "xpl-tab-panel": LocalJSX.IntrinsicElements["xpl-tab-panel"] & JSXBase.HTMLAttributes<HTMLXplTabPanelElement>;
+            /**
+             * @since 0.1.1
+             */
             "xpl-table": LocalJSX.IntrinsicElements["xpl-table"] & JSXBase.HTMLAttributes<HTMLXplTableElement>;
+            /**
+             * @since 1.0.0
+             */
             "xpl-table-header": LocalJSX.IntrinsicElements["xpl-table-header"] & JSXBase.HTMLAttributes<HTMLXplTableHeaderElement>;
+            /**
+             * @since 1.3.0
+             */
             "xpl-table-header-cell": LocalJSX.IntrinsicElements["xpl-table-header-cell"] & JSXBase.HTMLAttributes<HTMLXplTableHeaderCellElement>;
+            /**
+             * @since 2.3.8
+             */
             "xpl-tabs": LocalJSX.IntrinsicElements["xpl-tabs"] & JSXBase.HTMLAttributes<HTMLXplTabsElement>;
+            /**
+             * @since 0.4.0
+             */
             "xpl-tag": LocalJSX.IntrinsicElements["xpl-tag"] & JSXBase.HTMLAttributes<HTMLXplTagElement>;
+            /**
+             * @since 1.2.0
+             */
             "xpl-toast": LocalJSX.IntrinsicElements["xpl-toast"] & JSXBase.HTMLAttributes<HTMLXplToastElement>;
+            /**
+             * @since 0.3.0
+             */
             "xpl-toggle": LocalJSX.IntrinsicElements["xpl-toggle"] & JSXBase.HTMLAttributes<HTMLXplToggleElement>;
+            /**
+             * @since 1.2.0
+             */
             "xpl-toolbar": LocalJSX.IntrinsicElements["xpl-toolbar"] & JSXBase.HTMLAttributes<HTMLXplToolbarElement>;
+            /**
+             * @since 1.7.0
+             */
             "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).
+             * **Outside click:** With **`nav-control`**, a click outside the drawer panel (**`.xpl-top-nav__left-primary`**) also closes it and emits **`navOpen`** **`false`** (document **capture**, mirroring **`xpl-top-nav-item`**); it skips clicks on the hamburger toggle and while a descendant **`xpl-popover`** is open, and does not move focus.
              * **`xpl-top-nav-item`** **`slot="dropdown"`** uses document **capture** for **Escape** first; the shell uses **bubble**
              * on **`ownerDocument`** so nested dropdowns close before the drawer.
              * **Theming:** The host always includes Foundation’s **`dark`** class so **`--xpl-*`** purpose tokens under this subtree
@@ -6380,25 +7473,52 @@ declare module "@stencil/core" {
              * **`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.
+             * @since 2.7.0
              */
             "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
+             * Single nav row for **`xpl-top-nav`** / **`xpl-nav-header-menu`** / **`xpl-top-nav-menu`**. The host uses
+             * **`role="listitem"`** when the row participates in a list: a **`role="list"`** parent, **`slot="left-aside"`** on
+             * **`xpl-top-nav`** (list host is **`.xpl-top-nav__left-primary`** while slotted nodes stay light-DOM children of
+             * **`xpl-top-nav`**), or default-slot rows under **`xpl-nav-header-menu`** / **`xpl-top-nav-menu`**. That flag is
              * kept in **`@State`** and refreshed after render plus via **`MutationObserver`** on the host (**`class`**, **`slot`**) and
              * on **`parentElement`** (**`role`**) or on **`.xpl-top-nav__left-primary`** (**`role`**) for **`slot="left-aside"`** under **`xpl-top-nav`**) so DOM context changes
              * without a full reconnect still re-sync. The internal
              * **`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`**.
+             * **This component does triple duty:** a plain bar item, a dropdown trigger (**`slot="dropdown"`** present), and a
+             * dropdown/menu **row** (nested inside **`xpl-nav-header-menu`** or **`xpl-top-nav-menu`**). The **`description`** prop
+             * only applies in the row context — bar items and triggers do not show it in Figma.
              * **Default slot (no `label`):** do not put **`xpl-top-nav-item__inner`** or other **`xpl-top-nav-item__*`** classes on
              * custom trigger content — the component renders the inner wrapper and BEM elements.
              * **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>;
+            /**
+             * Thin grouping container for **`xpl-top-nav-item`** rows — the panel content for a desktop flyout
+             * (**`slot="dropdown"`** on the parent **`xpl-top-nav-item`**) and, on small screens, the **mobile
+             * cascade**: the same markup drills in to a **Level 2** view in place, with an auto-rendered **back
+             * row** (leading **`chevron-left`** + this component's **`label`**) as the first row. Tapping the back
+             * row closes the parent trigger's dropdown (**`closeMenu()`**), returning to **Level 1** and restoring
+             * focus to the parent trigger. No item logic otherwise lives here — row behavior (icons, description,
+             * links, nested dropdowns) is entirely **`xpl-top-nav-item`**.
+             * **One authoring markup, two renderings:** consumers write this once; **`isMobileCascade`** (synced
+             * from **`TOP_NAV_MOBILE_MQ`**) decides whether the back row renders. Desktop never sees it — the
+             * flyout is a single level of links (see `xpl-top-nav-item`'s cascade-depth notes).
+             * **Panel chrome** is shared with **`xpl-nav-header-menu`** (the account menu): width
+             * (**`--xpl-top-nav-panel-width`**), surface, shadow, radius, and vertical padding all come from the
+             * same selector in `top-nav.css` so the desktop flyout, mobile cascade, and account menu read as one
+             * visual family.
+             * **Theming:** The host always includes Foundation’s **`dark`** class so **`--xpl-*`** purpose tokens
+             * resolve to dark-mode values even when the page root is light (consistent with the rest of the
+             * **`xpl-top-nav`** family).
+             */
+            "xpl-top-nav-menu": LocalJSX.IntrinsicElements["xpl-top-nav-menu"] & JSXBase.HTMLAttributes<HTMLXplTopNavMenuElement>;
+            /**
+             * @since 0.1.1
+             */
             "xpl-utility-bar": LocalJSX.IntrinsicElements["xpl-utility-bar"] & JSXBase.HTMLAttributes<HTMLXplUtilityBarElement>;
         }
     }