@xplortech/apollo-core 2.9.0 → 2.11.0

package/dist/types/components.d.ts

@@ -382,7 +382,7 @@ export namespace Components {
          */
         "styled"?: boolean;
         /**
-          * The value attribute for the checkbox input. (submittted in form as name/value pair)
+          * The value attribute for the checkbox input. (submitted in form as name/value pair)
          */
         "value"?: string;
     }
@@ -969,6 +969,10 @@ export namespace Components {
           * Whether the field is disabled
          */
         "disabled"?: boolean;
+        /**
+          * Whether the field is in an error state. When true, the input renders with the error border styling. The error message itself is owned by the parent `xpl-input` wrapper.
+         */
+        "error"?: boolean;
         /**
           * The `inputId` is used to associate the input with a label.
          */
@@ -1523,48 +1527,100 @@ 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.
+     * **Mobile (v2):** below the Tailwind `md` breakpoint, the sidebar collapses to a
+     * ~56px top bar with a toggle button (`sidebar-left-show` / `sidebar-left-hide`).
+     * Activating the toggle opens a drawer containing the `section` + `nav-footer`
+     * content behind an `xpl-backdrop` scrim. The drawer traps focus while open;
+     * Escape or a backdrop click closes it and returns focus to the toggle. Above
+     * `md` the toggle and backdrop are hidden via CSS and the sidebar renders inline.
+     * The toggle is always rendered (no gating prop) and hidden above the breakpoint
+     * in CSS. Open state is exposed via the `open` prop (controlled or uncontrolled),
+     * the `openChange` event, and the `toggle()` / `setOpen()` methods.
+     * **v2 breaking change (beta):** consumers who wrapped their own mobile toggle
+     * around `xpl-side-nav` should remove it — the toggle and drawer are now built in.
+     */
     interface XplSideNav {
         /**
           * Accessible label for the navigation landmark. Maps to `aria-label` on the `<nav>` element. Recommended when multiple navigation landmarks exist on a page (e.g., side nav + top nav + breadcrumbs) to help screen readers distinguish them.
          */
         "label"?: string;
+        /**
+          * Whether the mobile drawer is open. Reflected to the `open` attribute so CSS and host state stay in sync. Controlled (consumer owns `open`) or uncontrolled (built-in toggle flips it). Has no visible effect above the `md` breakpoint, where the sidebar always renders inline.
+          * @default false
+         */
+        "open": boolean;
+        /**
+          * Programmatically set the mobile drawer open state. Emits `openChange` when it changes.
+         */
+        "setOpen": (open: boolean) => Promise<void>;
+        /**
+          * Programmatically toggle the mobile drawer open/closed. Emits `openChange`.
+         */
+        "toggle": () => Promise<void>;
     }
+    /**
+     * Navigation row for `xpl-side-nav`. Renders a button (default) or a slot-only
+     * anchor container (`link` mode). Three slot positions are available:
+     * - `slot="leading"` — leading icon column (renamed from `slot="icon"` in v2).
+     *   The `icon` prop is a convenience shorthand that renders an `xpl-icon` here
+     *   when no slotted `leading` content is present.
+     * - `slot="trailing"` — trailing content (e.g. `xpl-icon icon="external-link"`).
+     *   When `has-children` is true and no `trailing` slot content is provided, an
+     *   auto chevron is rendered automatically in this position: `chevron-down` when
+     *   collapsed, `chevron-up` when expanded.
+     * - default slot — nested `xpl-side-nav-item` children (expandable parents only).
+     * **v2 breaking changes (beta):**
+     * - `slot="icon"` renamed to `slot="leading"` — no alias kept.
+     * - Parent rows (`has-children`) now render the leading icon alongside the chevron.
+     *   Previously parents showed chevron + label only (no leading icon).
+     * - The chevron has moved from the leading position to the trailing position.
+     * - A slotted `slot="trailing"` replaces the auto chevron on parent rows.
+     * **Migration:**
+     * | Before (v1) | After (v2) | Action |
+     * |---|---|---|
+     * | `slot="icon"` | `slot="leading"` | Rename the slot attribute |
+     * | Parent row: chevron only (no leading) | Parent row: leading icon + chevron | Pass `icon` prop or `slot="leading"` |
+     * | (no trailing slot) | `slot="trailing"` | Add for custom trailing content |
+     */
     interface XplSideNavItem {
         /**
-          * Whether the component is disabled
+          * Whether the item is currently disabled.
           * @default false
          */
         "disabled": boolean;
         /**
-          * Whether the item is currently expanded (only applies when hasChildren is true)
+          * Whether the item is currently expanded (only applies when `has-children` is true).
           * @default false
          */
         "expanded": boolean;
         /**
-          * Whether the item has child items; when true, shows expand/collapse and a default slot for nested items. Mutually exclusive with <code>link</code>. If <code>link</code> is already true, setting <code>has-children</code> is reverted (<code>@Watch('hasChildren')</code>, <code>@Watch('link')</code>, <code>componentWillLoad</code>, and <code>componentWillRender</code>) so reflected attributes match CSS.
+          * Whether the item has child items; when true, shows expand/collapse and a default slot for nested items. Mutually exclusive with `link`. If `link` is already true, setting `has-children` is reverted.
           * @default false
          */
         "hasChildren": boolean;
         /**
-          * Whether the component is hidden
+          * Whether the component is hidden.
           * @default false
          */
         "hidden": boolean;
         /**
-          * Optional icon name; default content for <code>slot="icon"</code> (leaf and footer rows only). Expandable parents (<code>has-children</code>) do not show an icon column — only the chevron and label. Omit for nested children under a <code>has-children</code> parent — the icon column is hidden for sub-items.
+          * Optional icon name; renders as the default content for `slot="leading"`. When `slot="leading"` content is present, this prop is ignored. In v2, this prop applies to all item types including parent rows (`has-children`).
          */
         "icon"?: string;
         /**
-          * The display label for the navigation item (button / expandable rows; omit in <code>link</code> mode).
+          * The display label for the navigation item (button / expandable rows; omit in `link` mode).
          */
         "label"?: string;
         /**
-          * When true, the row becomes a slot-only container for consumer-provided links. The consumer provides the full anchor element (or router link) via the default slot. In link mode, <code>label</code> and <code>icon</code> props should not be used. Link mode does not support <code>has-children</code>; use the default button mode for expandable items. When <code>link</code> is true, <code>hasChildren</code> is always false (enforced by <code>@Watch('link')</code>, <code>@Watch('hasChildren')</code>, <code>componentWillLoad</code>, and <code>componentWillRender</code>).
+          * When true, the row becomes a slot-only container for consumer-provided links. The consumer provides the full anchor element (or router link) via the default slot. In link mode, `label` and `icon` props should not be used. Link mode does not support `has-children`; use the default button mode for expandable items. When `link` is true, `hasChildren` is always false.
           * @default false
          */
         "link": boolean;
         /**
-          * Whether the item is currently in a selected state
+          * Whether the item is currently in a selected state.
           * @default false
          */
         "selected": boolean;
@@ -2013,16 +2069,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
@@ -2034,12 +2093,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;
@@ -2051,11 +2118,54 @@ 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;
     }
     interface XplUtilityBar {
         /**
@@ -2160,6 +2270,10 @@ export interface XplSelectCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLXplSelectElement;
 }
+export interface XplSideNavCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLXplSideNavElement;
+}
 export interface XplSideNavItemCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLXplSideNavItemElement;
@@ -2819,7 +2933,33 @@ declare global {
         prototype: HTMLXplSelectElement;
         new (): HTMLXplSelectElement;
     };
+    interface HTMLXplSideNavElementEventMap {
+        "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.
+     * **Mobile (v2):** below the Tailwind `md` breakpoint, the sidebar collapses to a
+     * ~56px top bar with a toggle button (`sidebar-left-show` / `sidebar-left-hide`).
+     * Activating the toggle opens a drawer containing the `section` + `nav-footer`
+     * content behind an `xpl-backdrop` scrim. The drawer traps focus while open;
+     * Escape or a backdrop click closes it and returns focus to the toggle. Above
+     * `md` the toggle and backdrop are hidden via CSS and the sidebar renders inline.
+     * The toggle is always rendered (no gating prop) and hidden above the breakpoint
+     * in CSS. Open state is exposed via the `open` prop (controlled or uncontrolled),
+     * the `openChange` event, and the `toggle()` / `setOpen()` methods.
+     * **v2 breaking change (beta):** consumers who wrapped their own mobile toggle
+     * around `xpl-side-nav` should remove it — the toggle and drawer are now built in.
+     */
     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;
+        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 HTMLXplSideNavElementEventMap>(type: K, listener: (this: HTMLXplSideNavElement, ev: XplSideNavCustomEvent<HTMLXplSideNavElementEventMap[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 HTMLXplSideNavElement: {
         prototype: HTMLXplSideNavElement;
@@ -2829,6 +2969,30 @@ declare global {
         "expandedChange": boolean;
         "navClick": void;
     }
+    /**
+     * Navigation row for `xpl-side-nav`. Renders a button (default) or a slot-only
+     * anchor container (`link` mode). Three slot positions are available:
+     * - `slot="leading"` — leading icon column (renamed from `slot="icon"` in v2).
+     *   The `icon` prop is a convenience shorthand that renders an `xpl-icon` here
+     *   when no slotted `leading` content is present.
+     * - `slot="trailing"` — trailing content (e.g. `xpl-icon icon="external-link"`).
+     *   When `has-children` is true and no `trailing` slot content is provided, an
+     *   auto chevron is rendered automatically in this position: `chevron-down` when
+     *   collapsed, `chevron-up` when expanded.
+     * - default slot — nested `xpl-side-nav-item` children (expandable parents only).
+     * **v2 breaking changes (beta):**
+     * - `slot="icon"` renamed to `slot="leading"` — no alias kept.
+     * - Parent rows (`has-children`) now render the leading icon alongside the chevron.
+     *   Previously parents showed chevron + label only (no leading icon).
+     * - The chevron has moved from the leading position to the trailing position.
+     * - A slotted `slot="trailing"` replaces the auto chevron on parent rows.
+     * **Migration:**
+     * | Before (v1) | After (v2) | Action |
+     * |---|---|---|
+     * | `slot="icon"` | `slot="leading"` | Rename the slot attribute |
+     * | Parent row: chevron only (no leading) | Parent row: leading icon + chevron | Pass `icon` prop or `slot="leading"` |
+     * | (no trailing slot) | `slot="trailing"` | Add for custom trailing content |
+     */
     interface HTMLXplSideNavItemElement extends Components.XplSideNavItem, HTMLStencilElement {
         addEventListener<K extends keyof HTMLXplSideNavItemElementEventMap>(type: K, listener: (this: HTMLXplSideNavItemElement, ev: XplSideNavItemCustomEvent<HTMLXplSideNavItemElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -3068,18 +3232,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
@@ -3099,6 +3267,31 @@ 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;
     }
@@ -3185,6 +3378,7 @@ declare global {
         "xpl-tooltip": HTMLXplTooltipElement;
         "xpl-top-nav": HTMLXplTopNavElement;
         "xpl-top-nav-item": HTMLXplTopNavItemElement;
+        "xpl-top-nav-menu": HTMLXplTopNavMenuElement;
         "xpl-utility-bar": HTMLXplUtilityBarElement;
     }
 }
@@ -3570,7 +3764,7 @@ declare namespace LocalJSX {
          */
         "styled"?: boolean;
         /**
-          * The value attribute for the checkbox input. (submittted in form as name/value pair)
+          * The value attribute for the checkbox input. (submitted in form as name/value pair)
          */
         "value"?: string;
     }
@@ -4207,6 +4401,10 @@ declare namespace LocalJSX {
           * Whether the field is disabled
          */
         "disabled"?: boolean;
+        /**
+          * Whether the field is in an error state. When true, the input renders with the error border styling. The error message itself is owned by the parent `xpl-input` wrapper.
+         */
+        "error"?: boolean;
         /**
           * The `inputId` is used to associate the input with a label.
          */
@@ -4856,56 +5054,104 @@ 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.
+     * **Mobile (v2):** below the Tailwind `md` breakpoint, the sidebar collapses to a
+     * ~56px top bar with a toggle button (`sidebar-left-show` / `sidebar-left-hide`).
+     * Activating the toggle opens a drawer containing the `section` + `nav-footer`
+     * content behind an `xpl-backdrop` scrim. The drawer traps focus while open;
+     * Escape or a backdrop click closes it and returns focus to the toggle. Above
+     * `md` the toggle and backdrop are hidden via CSS and the sidebar renders inline.
+     * The toggle is always rendered (no gating prop) and hidden above the breakpoint
+     * in CSS. Open state is exposed via the `open` prop (controlled or uncontrolled),
+     * the `openChange` event, and the `toggle()` / `setOpen()` methods.
+     * **v2 breaking change (beta):** consumers who wrapped their own mobile toggle
+     * around `xpl-side-nav` should remove it — the toggle and drawer are now built in.
+     */
     interface XplSideNav {
         /**
           * Accessible label for the navigation landmark. Maps to `aria-label` on the `<nav>` element. Recommended when multiple navigation landmarks exist on a page (e.g., side nav + top nav + breadcrumbs) to help screen readers distinguish them.
          */
         "label"?: string;
+        /**
+          * Emitted when the mobile drawer open state changes: toggle activation, Escape, or a backdrop click. Detail is the new open state (`true` = open, `false` = closed).
+         */
+        "onOpenChange"?: (event: XplSideNavCustomEvent<boolean>) => void;
+        /**
+          * Whether the mobile drawer is open. Reflected to the `open` attribute so CSS and host state stay in sync. Controlled (consumer owns `open`) or uncontrolled (built-in toggle flips it). Has no visible effect above the `md` breakpoint, where the sidebar always renders inline.
+          * @default false
+         */
+        "open"?: boolean;
     }
+    /**
+     * Navigation row for `xpl-side-nav`. Renders a button (default) or a slot-only
+     * anchor container (`link` mode). Three slot positions are available:
+     * - `slot="leading"` — leading icon column (renamed from `slot="icon"` in v2).
+     *   The `icon` prop is a convenience shorthand that renders an `xpl-icon` here
+     *   when no slotted `leading` content is present.
+     * - `slot="trailing"` — trailing content (e.g. `xpl-icon icon="external-link"`).
+     *   When `has-children` is true and no `trailing` slot content is provided, an
+     *   auto chevron is rendered automatically in this position: `chevron-down` when
+     *   collapsed, `chevron-up` when expanded.
+     * - default slot — nested `xpl-side-nav-item` children (expandable parents only).
+     * **v2 breaking changes (beta):**
+     * - `slot="icon"` renamed to `slot="leading"` — no alias kept.
+     * - Parent rows (`has-children`) now render the leading icon alongside the chevron.
+     *   Previously parents showed chevron + label only (no leading icon).
+     * - The chevron has moved from the leading position to the trailing position.
+     * - A slotted `slot="trailing"` replaces the auto chevron on parent rows.
+     * **Migration:**
+     * | Before (v1) | After (v2) | Action |
+     * |---|---|---|
+     * | `slot="icon"` | `slot="leading"` | Rename the slot attribute |
+     * | Parent row: chevron only (no leading) | Parent row: leading icon + chevron | Pass `icon` prop or `slot="leading"` |
+     * | (no trailing slot) | `slot="trailing"` | Add for custom trailing content |
+     */
     interface XplSideNavItem {
         /**
-          * Whether the component is disabled
+          * Whether the item is currently disabled.
           * @default false
          */
         "disabled"?: boolean;
         /**
-          * Whether the item is currently expanded (only applies when hasChildren is true)
+          * Whether the item is currently expanded (only applies when `has-children` is true).
           * @default false
          */
         "expanded"?: boolean;
         /**
-          * Whether the item has child items; when true, shows expand/collapse and a default slot for nested items. Mutually exclusive with <code>link</code>. If <code>link</code> is already true, setting <code>has-children</code> is reverted (<code>@Watch('hasChildren')</code>, <code>@Watch('link')</code>, <code>componentWillLoad</code>, and <code>componentWillRender</code>) so reflected attributes match CSS.
+          * Whether the item has child items; when true, shows expand/collapse and a default slot for nested items. Mutually exclusive with `link`. If `link` is already true, setting `has-children` is reverted.
           * @default false
          */
         "hasChildren"?: boolean;
         /**
-          * Whether the component is hidden
+          * Whether the component is hidden.
           * @default false
          */
         "hidden"?: boolean;
         /**
-          * Optional icon name; default content for <code>slot="icon"</code> (leaf and footer rows only). Expandable parents (<code>has-children</code>) do not show an icon column — only the chevron and label. Omit for nested children under a <code>has-children</code> parent — the icon column is hidden for sub-items.
+          * Optional icon name; renders as the default content for `slot="leading"`. When `slot="leading"` content is present, this prop is ignored. In v2, this prop applies to all item types including parent rows (`has-children`).
          */
         "icon"?: string;
         /**
-          * The display label for the navigation item (button / expandable rows; omit in <code>link</code> mode).
+          * The display label for the navigation item (button / expandable rows; omit in `link` mode).
          */
         "label"?: string;
         /**
-          * When true, the row becomes a slot-only container for consumer-provided links. The consumer provides the full anchor element (or router link) via the default slot. In link mode, <code>label</code> and <code>icon</code> props should not be used. Link mode does not support <code>has-children</code>; use the default button mode for expandable items. When <code>link</code> is true, <code>hasChildren</code> is always false (enforced by <code>@Watch('link')</code>, <code>@Watch('hasChildren')</code>, <code>componentWillLoad</code>, and <code>componentWillRender</code>).
+          * When true, the row becomes a slot-only container for consumer-provided links. The consumer provides the full anchor element (or router link) via the default slot. In link mode, `label` and `icon` props should not be used. Link mode does not support `has-children`; use the default button mode for expandable items. When `link` is true, `hasChildren` is always false.
           * @default false
          */
         "link"?: boolean;
         /**
-          * Emitted when the expanded state changes (hasChildren items only). Detail is the new expanded value.
+          * Emitted when the expanded state changes (`has-children` items only). Detail is the new expanded value.
          */
         "onExpandedChange"?: (event: XplSideNavItemCustomEvent<boolean>) => void;
         /**
-          * Emitted when a leaf item is clicked. Expandable parents use expandedChange instead.
+          * Emitted when a leaf item is clicked. Expandable parents use `expandedChange` instead.
          */
         "onNavClick"?: (event: XplSideNavItemCustomEvent<void>) => void;
         /**
-          * Whether the item is currently in a selected state
+          * Whether the item is currently in a selected state.
           * @default false
          */
         "selected"?: boolean;
@@ -5405,16 +5651,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
@@ -5426,12 +5675,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;
@@ -5444,15 +5697,54 @@ 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;
+    }
     interface XplUtilityBar {
         /**
           * @property {boolean} - Optional property that defines whether or not the main nav is open at startup.
@@ -5714,6 +6006,7 @@ declare namespace LocalJSX {
     interface XplInputPhoneAttributes {
         "defaultCountry": string;
         "disabled": boolean;
+        "error": boolean;
         "inputId": string;
         "isInternational": boolean;
         "name": string;
@@ -5850,6 +6143,7 @@ declare namespace LocalJSX {
     }
     interface XplSideNavAttributes {
         "label": string;
+        "open": boolean;
     }
     interface XplSideNavItemAttributes {
         "disabled": boolean;
@@ -5978,12 +6272,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;
@@ -6058,6 +6358,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] };
     }
 }
@@ -6140,7 +6441,46 @@ declare module "@stencil/core" {
             "xpl-radio": LocalJSX.IntrinsicElements["xpl-radio"] & JSXBase.HTMLAttributes<HTMLXplRadioElement>;
             "xpl-secondary-nav": LocalJSX.IntrinsicElements["xpl-secondary-nav"] & JSXBase.HTMLAttributes<HTMLXplSecondaryNavElement>;
             "xpl-select": LocalJSX.IntrinsicElements["xpl-select"] & JSXBase.HTMLAttributes<HTMLXplSelectElement>;
+            /**
+             * Slot-based sidebar for app navigation: a scrollable main `section` and a fixed
+             * `nav-footer`. Compose with `xpl-side-nav-item` for rows.
+             * **Mobile (v2):** below the Tailwind `md` breakpoint, the sidebar collapses to a
+             * ~56px top bar with a toggle button (`sidebar-left-show` / `sidebar-left-hide`).
+             * Activating the toggle opens a drawer containing the `section` + `nav-footer`
+             * content behind an `xpl-backdrop` scrim. The drawer traps focus while open;
+             * Escape or a backdrop click closes it and returns focus to the toggle. Above
+             * `md` the toggle and backdrop are hidden via CSS and the sidebar renders inline.
+             * The toggle is always rendered (no gating prop) and hidden above the breakpoint
+             * in CSS. Open state is exposed via the `open` prop (controlled or uncontrolled),
+             * the `openChange` event, and the `toggle()` / `setOpen()` methods.
+             * **v2 breaking change (beta):** consumers who wrapped their own mobile toggle
+             * around `xpl-side-nav` should remove it — the toggle and drawer are now built in.
+             */
             "xpl-side-nav": LocalJSX.IntrinsicElements["xpl-side-nav"] & JSXBase.HTMLAttributes<HTMLXplSideNavElement>;
+            /**
+             * Navigation row for `xpl-side-nav`. Renders a button (default) or a slot-only
+             * anchor container (`link` mode). Three slot positions are available:
+             * - `slot="leading"` — leading icon column (renamed from `slot="icon"` in v2).
+             *   The `icon` prop is a convenience shorthand that renders an `xpl-icon` here
+             *   when no slotted `leading` content is present.
+             * - `slot="trailing"` — trailing content (e.g. `xpl-icon icon="external-link"`).
+             *   When `has-children` is true and no `trailing` slot content is provided, an
+             *   auto chevron is rendered automatically in this position: `chevron-down` when
+             *   collapsed, `chevron-up` when expanded.
+             * - default slot — nested `xpl-side-nav-item` children (expandable parents only).
+             * **v2 breaking changes (beta):**
+             * - `slot="icon"` renamed to `slot="leading"` — no alias kept.
+             * - Parent rows (`has-children`) now render the leading icon alongside the chevron.
+             *   Previously parents showed chevron + label only (no leading icon).
+             * - The chevron has moved from the leading position to the trailing position.
+             * - A slotted `slot="trailing"` replaces the auto chevron on parent rows.
+             * **Migration:**
+             * | Before (v1) | After (v2) | Action |
+             * |---|---|---|
+             * | `slot="icon"` | `slot="leading"` | Rename the slot attribute |
+             * | Parent row: chevron only (no leading) | Parent row: leading icon + chevron | Pass `icon` prop or `slot="leading"` |
+             * | (no trailing slot) | `slot="trailing"` | Add for custom trailing content |
+             */
             "xpl-side-nav-item": LocalJSX.IntrinsicElements["xpl-side-nav-item"] & JSXBase.HTMLAttributes<HTMLXplSideNavItemElement>;
             "xpl-skeleton": LocalJSX.IntrinsicElements["xpl-skeleton"] & JSXBase.HTMLAttributes<HTMLXplSkeletonElement>;
             "xpl-slideout": LocalJSX.IntrinsicElements["xpl-slideout"] & JSXBase.HTMLAttributes<HTMLXplSlideoutElement>;
@@ -6180,22 +6520,45 @@ declare module "@stencil/core" {
              */
             "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>;
             "xpl-utility-bar": LocalJSX.IntrinsicElements["xpl-utility-bar"] & JSXBase.HTMLAttributes<HTMLXplUtilityBarElement>;
         }
     }