@xplortech/apollo-core 2.6.0 → 2.7.1

package/.typings/apollo-components.html-data.json

@@ -85,7 +85,7 @@
       "name": "xpl-avatar",
       "description": {
         "kind": "markdown",
-        "value": "An Avatar is a visual representation of a user or entity. There are 5 types of avatar Figma component; Avatar Default, Avatar Group, Avatar Profile, Avatar Text, and Avatar Clickable. Each comes in a variety of sizes, faces and placeholder colors. \n\nAvatars typically display a user’s image. When no image is available, use the first and last initial of a user’s name. The avatar can handle up to three letters.\n\nThere are 10 avatar faces and 10 corresponding colors. We suggest randomly generating placeholder colors to show a visual differentiator when multiple avatars or an avatar group is displayed."
+        "value": "The **Avatar** component shows a person or entity: a photo, initials on a colored surface, or custom slot content. It aligns with Apollo’s Figma patterns for default avatars, profile layouts, stacked groups, and rows with supporting text."
       },
       "attributes": [
         {
@@ -113,17 +113,21 @@
           "name": "disabled",
           "description": "Sets a disabled state on the avatar when set to true"
         },
+        {
+          "name": "group-data",
+          "description": "When `variant` is `group`, data for each face (max 4 visible + overflow count). Each item: { src?, name?, color? }."
+        },
         {
           "name": "href",
           "description": "The URL if the avatar should be hyperlinked"
         },
         {
           "name": "name",
-          "description": "Alt text for the image if there is an image src"
+          "description": "Alt text for the image; also used for initials when no image and no slot."
         },
         {
           "name": "size",
-          "description": "Size of the avatar",
+          "description": "Size of the avatar (and of each avatar in a group).",
           "values": [
             {
               "name": "md"
@@ -139,22 +143,62 @@
         },
         {
           "name": "status",
-          "description": "Color styles for the dot indicator to indicate varied states",
+          "description": "Shown for the default avatar, `profile`, and `with-text`; not shown when `variant` is `group`.\n**Legacy",
           "values": [
             {
               "name": "active"
             },
+            {
+              "name": "blue"
+            },
+            {
+              "name": "gray"
+            },
+            {
+              "name": "green"
+            },
             {
               "name": "inactive"
             },
+            {
+              "name": "orange"
+            },
+            {
+              "name": "purple"
+            },
+            {
+              "name": "red"
+            },
             {
               "name": "warning"
+            },
+            {
+              "name": "yellow"
             }
           ]
         },
+        {
+          "name": "sub-text",
+          "description": "Secondary text shown when `variant` is `with-text` (e.g. email)."
+        },
         {
           "name": "target",
           "description": "Where to open the URL chosen for the `href` prop:\n`_self` (default), `_blank`, `_parent`, or `_top`"
+        },
+        {
+          "name": "variant",
+          "description": "Optional layout: `profile` (large profile sizes), `group` (stacked faces + `groupData`; `status` not shown),\n`with-text` (avatar with `name` / `subText` beside it). Omit for the default single avatar.",
+          "values": [
+            {
+              "name": "group"
+            },
+            {
+              "name": "profile"
+            },
+            {
+              "name": "with-text"
+            }
+          ]
         }
       ]
     },
@@ -505,7 +549,7 @@
       "name": "xpl-calendar",
       "description": {
         "kind": "markdown",
-        "value": "Calendars allow users to view and select dates.  Use XPL-Calendar when date picking is needed on a page or in a in a container.\nIf a calendar is needed within a form, use [XPL-Datepicker](https://xplor-apollo.herokuapp.com/?path=/story/components-input--datepicker)."
+        "value": "Calendars allow users to view and select dates.  Use XPL-Calendar when date picking is needed on a page or in a in a container.\nIf a calendar is needed within a form, use [XPL-Datepicker](https://apollo.xplordocs.com/?path=/story/components-input--datepicker)."
       },
       "attributes": [
         {
@@ -549,6 +593,10 @@
         "value": "Checkboxes allow users to make selections or choices. Checkboxes can be multi-select, and also act as controls."
       },
       "attributes": [
+        {
+          "name": "aria-label",
+          "description": "Accessible name for the native checkbox input (sets `aria-label` on the `input`).\nUse when there is no visible label text in the default slot.\nDefaults to `''`; empty or whitespace-only values omit `aria-label` on the input so a visible `<label>` remains the sole name source."
+        },
         {
           "name": "checked",
           "description": "Whether the input is checked"
@@ -745,7 +793,7 @@
       "name": "xpl-dropdown",
       "description": {
         "kind": "markdown",
-        "value": "A Dropdown is a menu with a list of actions a user can take. Use a dropdown when you want to present a list of actions in a limited space. Dropdowns are single-select ***actions***, can be presented in groups, and can be triggered by other elements such as a button, icon, text etc. \nA selection within a dropdown does not change the parent trigger.\n\n***If you want to present a list of **options** a user can select, or multi-select options, please use [XPL-Select](https://xplor-apollo.herokuapp.com/?path=/story/components-select--select).***"
+        "value": "A Dropdown is a menu with a list of actions a user can take. Use a dropdown when you want to present a list of actions in a limited space. Dropdowns are single-select ***actions***, can be presented in groups, and can be triggered by other elements such as a button, icon, text etc. \nA selection within a dropdown does not change the parent trigger.\n\n***If you want to present a list of **options** a user can select, or multi-select options, please use [XPL-Select](https://apollo.xplordocs.com/?path=/story/components-select--select).***"
       },
       "attributes": [
         {
@@ -772,6 +820,48 @@
             }
           ]
         },
+        {
+          "name": "placement",
+          "description": "Floating UI placement when `anchorToTrigger` is true (e.g. `bottom-start`, `top-start`).",
+          "values": [
+            {
+              "name": "bottom"
+            },
+            {
+              "name": "bottom-end"
+            },
+            {
+              "name": "bottom-start"
+            },
+            {
+              "name": "left"
+            },
+            {
+              "name": "left-end"
+            },
+            {
+              "name": "left-start"
+            },
+            {
+              "name": "right"
+            },
+            {
+              "name": "right-end"
+            },
+            {
+              "name": "right-start"
+            },
+            {
+              "name": "top"
+            },
+            {
+              "name": "top-end"
+            },
+            {
+              "name": "top-start"
+            }
+          ]
+        },
         {
           "name": "select-on-focus",
           "description": "whether selection should be made when focusing on interactive element"
@@ -970,7 +1060,7 @@
       "name": "xpl-input",
       "description": {
         "kind": "markdown",
-        "value": "A flexible form input that supports multiple `type` values: `text`, `number`, `password`, `date`, `time`, `file`, `color`, and `phone`. Each type delegates to a dedicated sub-component (`xpl-input-date`, `xpl-input-time`, `xpl-input-phone`, etc.) while sharing a common label, description, and error-message wrapper.\n\nFor `type=\"phone\"`, the value is always emitted in **E.164** format (e.g. `+14155551234`). See [`xpl-input-phone`](xpl-input-phone) for full phone-input documentation."
+        "value": "A flexible form input that supports multiple `type` values: `text`, `number`, `password`, `date`, `time`, `file`, `color`, `phone`, and `search`. Each type delegates to a dedicated sub-component (`xpl-input-date`, `xpl-input-time`, `xpl-input-phone`, `xpl-input-search`, etc.) while sharing a common label, description, and error-message wrapper.\n\nFor `type=\"phone\"`, the value is always emitted in **E.164** format (e.g. `+14155551234`). See [`xpl-input-phone`](xpl-input-phone) for full phone-input documentation."
       },
       "attributes": [
         {
@@ -985,9 +1075,13 @@
           "name": "allow-custom-option",
           "description": "For time inputs, whether to allow custom option in the input even if not available in the dropdown.\nExample: A step of 30 minutes will allow 15:03, 15:37, etc.\n\nApplies to time inputs."
         },
+        {
+          "name": "aria-label",
+          "description": "Accessible name for search inputs when there is no visible `label` (after trim).\nIgnored for naming when a visible label is shown.\nDefaults to `''`; whitespace-only values are treated as missing and fall back to `'Search'` so the field is never unnamed when there is no visible label.\n\nApplies to search inputs (`type=\"search\"`)."
+        },
         {
           "name": "autocomplete",
-          "description": "Hint for form autofill feature\n\nApplies to text, password, number."
+          "description": "Hint for form autofill feature\n\nApplies to text, password, number, and search inputs."
         },
         {
           "name": "date-format",
@@ -1071,7 +1165,7 @@
         },
         {
           "name": "placeholder",
-          "description": "Placeholder text that appears when the field has no value\n\nApplies to text, password, number, and date inputs."
+          "description": "Placeholder text that appears when the field has no value\n\nApplies to text, password, number, date, and search inputs."
         },
         {
           "name": "post",
@@ -1083,12 +1177,24 @@
         },
         {
           "name": "readonly",
-          "description": "Whether the input is editable\n\nApplies to text, password, number, and date inputs."
+          "description": "Whether the input is editable\n\nApplies to text, password, number, date, and search inputs."
         },
         {
           "name": "required",
           "description": "Whether the input is required\n\nApplies to all input types."
         },
+        {
+          "name": "shape",
+          "description": "Shell corner radius for search inputs: `rounded` (pill) or `box` (rounded rectangle).\n\nApplies to search inputs (`type=\"search\"`).",
+          "values": [
+            {
+              "name": "box"
+            },
+            {
+              "name": "rounded"
+            }
+          ]
+        },
         {
           "name": "step",
           "description": "The granularity that the value in a `number` input must adhere to when\nincrementing or decrementing. The default stepping value for number\ninputs is 1\n\nApplies to number and time inputs."
@@ -1127,6 +1233,9 @@
             {
               "name": "phone"
             },
+            {
+              "name": "search"
+            },
             {
               "name": "text"
             },
@@ -1137,7 +1246,7 @@
         },
         {
           "name": "value",
-          "description": "Including a `value` will pre-populate the input\nwith the given string.\n\nApplies to text, password, number, and date inputs."
+          "description": "Including a `value` will pre-populate the input\nwith the given string.\n\nApplies to text, password, number, date, and search inputs."
         }
       ]
     },
@@ -1325,6 +1434,75 @@
         }
       ]
     },
+    {
+      "name": "xpl-input-search",
+      "description": {
+        "kind": "markdown",
+        "value": "Inner search field used by [`xpl-input`](../readme.md) when `type=\"search\"`. It provides a leading magnifier, a native text field with `role=\"searchbox\"`, an optional clear control, and a `shape` shell (`rounded` pill vs `box`). You normally consume search through **`xpl-input`**; use `xpl-input-search` only when composing a custom shell that still matches Apollo search visuals."
+      },
+      "attributes": [
+        {
+          "name": "aria-label",
+          "description": "Accessible name when there is no visible label from the parent; maps to `aria-label` on the input.\nWhen the parent provides a visible label, the input is named by `<label for=\"…\">` — this prop is ignored for naming.\nEmpty or whitespace-only values are treated as missing and fall back to `'Search'` so the field is never unnamed."
+        },
+        {
+          "name": "autocomplete",
+          "description": "Passed to the native input (`autocomplete` attribute). Default `off` matches common\ninline-search UX; browsers may still apply heuristics."
+        },
+        {
+          "name": "disabled",
+          "description": "Disables the field and clear control."
+        },
+        {
+          "name": "error-message-id",
+          "description": "Element id for `aria-describedby` when `hasError` (error message lives on `xpl-input`)."
+        },
+        {
+          "name": "has-error",
+          "description": "Set by `xpl-input` when `error` is shown — drives `aria-invalid` / `aria-describedby`."
+        },
+        {
+          "name": "has-visible-label",
+          "description": "When true, parent `xpl-input` renders a visible label — omit `aria-label` on the input."
+        },
+        {
+          "name": "input-id",
+          "description": "Associates the control with the parent `xpl-input` label (`for` / `id`)."
+        },
+        {
+          "name": "name",
+          "description": "Form field `name` on the native input."
+        },
+        {
+          "name": "placeholder",
+          "description": "Placeholder shown when the value is empty."
+        },
+        {
+          "name": "readonly",
+          "description": "Whether the input is editable."
+        },
+        {
+          "name": "required",
+          "description": "Whether the input is required."
+        },
+        {
+          "name": "shape",
+          "description": "Shell corner radius: `rounded` (pill) or `box` (rounded rectangle).",
+          "values": [
+            {
+              "name": "box"
+            },
+            {
+              "name": "rounded"
+            }
+          ]
+        },
+        {
+          "name": "value",
+          "description": "Current value (controlled-friendly)."
+        }
+      ]
+    },
     {
       "name": "xpl-input-time",
       "description": {
@@ -1427,9 +1605,118 @@
       "name": "xpl-list",
       "description": {
         "kind": "markdown",
-        "value": "A list item is a card with interactive states. List items allow users to select items from a list of items and view more information or make edits."
+        "value": ""
       },
-      "attributes": []
+      "attributes": [
+        {
+          "name": "label",
+          "description": "Accessible name for the list, exposed as `aria-label` on the host when set.\nUse when the list has no visible heading.\nIgnored when `labelledBy` is set (see `labelledBy` for precedence)."
+        },
+        {
+          "name": "labelled-by",
+          "description": "Element id(s) that label this list (space-separated), exposed as `aria-labelledby` when set.\nWhen set, `label` is not applied as `aria-label` so the list has a single naming source."
+        },
+        {
+          "name": "reorderable",
+          "description": "When true, enables reorder UI and behavior for **slot-based** child rows (drag handle + keyboard).\nLegacy rows rendered from the deprecated `items` prop do **not** show a drag handle; migrate to slots if reorder is required."
+        },
+        {
+          "name": "selectable",
+          "description": "Determines if this list is selectable (shows `xpl-radio` per row in a shared group).\nPress Escape while focus is on the **selected** row to clear selection (same as `clearSelection()`)."
+        }
+      ]
+    },
+    {
+      "name": "xpl-list-item",
+      "description": {
+        "kind": "markdown",
+        "value": "Single row for [`xpl-list`](../xpl-list/readme.md). **Slot-based** rows expose `role=\"listitem\"` on the inner row surface (`.xpl-list-item__wrapper` or `.xpl-list-item__listitem-shell` when `href` is set); **legacy** `item` rows use `role=\"listitem\"` on the host. Hand-written integration notes for slots, attributes, and events live in the [list readme](../xpl-list/readme.md); the section below is Stencil-generated API for this component.\n\n**Reorder handle (slot mode):** When `reorderable` is enabled and the row uses **slot-based** content, the handle is an **`xpl-button`** wrapping a native **`<button>`**. Reorder logic is wired on the **`xpl-button` host** (`mousedown` / `keydown`); those events originate on the inner `<button>` and **bubble** to the host, which is how the list item receives them today. If `xpl-button` ever stopped bubbling for those events, reorder handlers would need to attach directly to the inner button (similar to `componentDidRender` syncing `aria-*` on that element).\n\n**Legacy `item` prop:** Prop-driven rows **do not** render the reorder handle, radios, or keyboard reorder affordances. Parent `xpl-list` **does not** set `selectable`, `radio-name`, or `reorderable` on those rows (those attributes are removed so they are not mistaken for supported behavior). Use slots if you need selection, drag, or keyboard reorder."
+      },
+      "attributes": [
+        {
+          "name": "disabled",
+          "description": "Whether the item is disabled."
+        },
+        {
+          "name": "error",
+          "description": "Whether to show the item in an error state."
+        },
+        {
+          "name": "hidden",
+          "description": "When true, the row is not shown and does not participate in visible-only list behavior\n(e.g. `orderChange` / `orderedItemIds`, reorder targets). Use for filtering, conditional\ndisplay, or keeping stable `item-id` while the row is off-screen. See `xpl-list` readme\n“Hidden rows”.\n\n**Accessibility:** Renders an empty host with the native `hidden` attribute only (no\n`role=\"listitem\"`), consistent with the row not participating as a list item while hidden."
+        },
+        {
+          "name": "href",
+          "description": "URL for link behavior. When provided, the entire row becomes clickable.\nClicks on `actions` or `avatar` slots are prevented from triggering navigation."
+        },
+        {
+          "name": "item-id",
+          "description": "Unique identifier for this item. Used for selection and drag/drop.\nMutable so the host can sync from `item-id` / `id` in `componentWillLoad` without breaking one-way data flow."
+        },
+        {
+          "name": "keyboard-active",
+          "description": "When set by the parent, indicates this item is the active keyboard reorder item."
+        },
+        {
+          "name": "radio-name",
+          "description": "Name attribute for radio inputs (shared across selectable items in a list)."
+        },
+        {
+          "name": "reorderable",
+          "description": "Whether this item is reorderable (shows a drag handle in **slot-based** layout).\nWhen the deprecated `item` prop is used, legacy markup has **no** reorder handle even if this is true."
+        },
+        {
+          "name": "selectable",
+          "description": "Whether this item is selectable (shows `xpl-radio` in a shared group)."
+        },
+        {
+          "name": "selected",
+          "description": "Whether this item is selected (radio checked state)."
+        },
+        {
+          "name": "show-divider",
+          "description": "Whether to show a divider below the item."
+        },
+        {
+          "name": "title-badge-variant",
+          "description": "Optional badge to display next to the title (dot badge).\nOnly used when `item` prop is not provided (slot mode).\nMatches `xpl-badge` variant values (e.g. purple, green, red).",
+          "values": [
+            {
+              "name": "blue"
+            },
+            {
+              "name": "error"
+            },
+            {
+              "name": "gray"
+            },
+            {
+              "name": "green"
+            },
+            {
+              "name": "inactive"
+            },
+            {
+              "name": "orange"
+            },
+            {
+              "name": "purple"
+            },
+            {
+              "name": "red"
+            },
+            {
+              "name": "success"
+            },
+            {
+              "name": "warning"
+            },
+            {
+              "name": "yellow"
+            }
+          ]
+        }
+      ]
     },
     {
       "name": "xpl-main-nav",
@@ -1495,6 +1782,23 @@
         }
       ]
     },
+    {
+      "name": "xpl-nav-header-menu",
+      "description": {
+        "kind": "markdown",
+        "value": "Profile / account block (username, email, default slot for **`xpl-top-nav-item`** / **`xpl-divider`**).\nTag **`xpl-nav-header-menu`**; implementation folder **`xpl-nav-header-menu`**. **`.xpl-nav-header-menu__slot`** is\n**`role=\"list\"`** for slotted **`xpl-top-nav-item`** (**`role=\"listitem\"`**).\n\n**Slotted content:** do not add **`xpl-nav-header-menu__*`** BEM classes on nodes you pass into the default slot —\nprofile, list shell, and **`xpl-top-nav-item`** **`role=\"listitem\"`** are handled by the component. Use\n**`xpl-top-nav-item`** (or plain elements that are not Apollo **`xpl-*`** BEM hooks) in the slot only.\n\n**`slot=\"right-aside-mobile\"`** — optional block **between** the profile header and the default-slot list (e.g. narrow-only\nduplicate of **every** **`slot=\"right-aside\"`** control per Figma when **`xpl-top-nav`** hides **`right-aside`** on narrow viewports (always)).\nNot **`role=\"list\"`**; use **`xpl-button`** / **`xpl-top-nav-item`** as needed. Shown only on **narrow viewports** (one pixel below Tailwind **`md`** — **`top-nav.css`**) so bar actions stay in **`slot=\"right-aside\"`** on wider viewports.\nLight-DOM **`slotchange`** is unreliable; a host **`MutationObserver`** (child / subtree / **`slot`** attribute) keeps\n**`xpl-nav-header-menu--has-right-aside-mobile`** in sync when nodes are added or retargeted after mount (same pattern as **`xpl-top-nav`**).\nStencil **`newSpecPage`** / mock-doc does not define **`MutationObserver`**; slot presence still updates on the next\ndeferred flush (**`setTimeout(0)`** coalesced with **`componentDidRender`**). In real browsers the observer handles child /\n**`slot`** mutations without stacking uncancellable microtasks.\n\n**Theming:** The host always includes Foundation’s **`dark`** class so **`--xpl-*`** purpose tokens resolve to dark-mode\nvalues even when the page root is light (same contract as **`xpl-top-nav`** / **`xpl-top-nav-item`**)."
+      },
+      "attributes": [
+        {
+          "name": "email",
+          "description": "Email address shown below the username."
+        },
+        {
+          "name": "username",
+          "description": "Display name shown in the profile block."
+        }
+      ]
+    },
     {
       "name": "xpl-nav-item",
       "description": {
@@ -1570,7 +1874,7 @@
         },
         {
           "name": "padding",
-          "description": "Padding density applied to the content area.\nResponsive: scales down at tablet and mobile breakpoints.\n\n- `default` – 24 px desktop / 16 px tablet+mobile\n- `tight`   – 16 px desktop / 8 px tablet+mobile\n- `loose`   – 40 px desktop / 32 px tablet / 24 px mobile",
+          "description": "Padding density applied to the content area.\n(default and tight keep desktop padding through tablet; mobile ≤480px).\n\n- `default` – 24 px desktop & tablet / 16 px mobile\n- `tight`   – 16 px desktop & tablet / 8 px mobile\n- `loose`   – 40 px desktop / 32 px tablet / 24 px mobile",
           "values": [
             {
               "name": "default"
@@ -1656,19 +1960,6 @@
         }
       ]
     },
-    {
-      "name": "xpl-progress",
-      "description": {
-        "kind": "markdown",
-        "value": "A progress indicator guides users through any linear, multi-step task by showing the user their completed, current, and future steps.\n\nProgress indicators help manage a user’s expectations when completing a multistep process. They show which step the user is currently on, the total number of steps, and overall progress in completing a task.\n\nHorizontal Progress Indicator is used in most desktop applications where a stepped process is required to finish a task and it is beneficial to the user to see their progress. This creates confidence in the user and sets expectations for the length and complexity of the process."
-      },
-      "attributes": [
-        {
-          "name": "current-step",
-          "description": "Current step, is the index of the current active step"
-        }
-      ]
-    },
     {
       "name": "xpl-progress-bar",
       "description": {
@@ -1724,6 +2015,39 @@
         }
       ]
     },
+    {
+      "name": "xpl-progress-indicator",
+      "description": {
+        "kind": "markdown",
+        "value": "A progress indicator that guides users through linear, multi-step tasks by displaying completed, current, and future steps. Progress indicators help manage user expectations by showing their position in a multi-step process, the total number of steps, and overall progress toward task completion."
+      },
+      "attributes": [
+        {
+          "name": "current-step",
+          "description": "Current step index. Steps with index < currentStep are \"finished\",\nthe step at currentStep is \"active\", and steps beyond are \"waiting\".\nSet to steps.length to mark all steps as finished.\nAutomatically clamped to [0, steps.length]."
+        },
+        {
+          "name": "layout",
+          "description": "Layout direction - 'horizontal' or 'vertical'",
+          "values": [
+            {
+              "name": "horizontal"
+            },
+            {
+              "name": "vertical"
+            }
+          ]
+        },
+        {
+          "name": "show-labels",
+          "description": "Whether to show step labels"
+        },
+        {
+          "name": "show-numbers",
+          "description": "Whether to show step numbers inside circles"
+        }
+      ]
+    },
     {
       "name": "xpl-radio",
       "description": {
@@ -1773,7 +2097,7 @@
       "name": "xpl-select",
       "description": {
         "kind": "markdown",
-        "value": "Select allows users to make a single selection or multiple selections from a list of options.  Items can be a simple list, grouped, simple multi-select. User selections typically appear within the Select Box once created unless multiple selections are made, where truncation or another method of showing these selections is required.\n\n***When the list of options contains “Actions”, use a ***[Dropdown component](https://xplor-apollo.herokuapp.com/?path=/story/components-dropdown--simple). \n\nThe `selectIcon` property accepts icon names as strings. See [xpl-icon available icons](../xpl-icon/ICONS.md) for the complete list.\n\n---"
+        "value": "Select allows users to make a single selection or multiple selections from a list of options.  Items can be a simple list, grouped, simple multi-select. User selections typically appear within the Select Box once created unless multiple selections are made, where truncation or another method of showing these selections is required.\n\n***When the list of options contains “Actions”, use a ***[Dropdown component](https://apollo.xplordocs.com/?path=/story/components-dropdown--simple).\n\nThe `selectIcon` property accepts icon names as strings. See [xpl-icon available icons](../xpl-icon/ICONS.md) for the complete list.\n\n---"
       },
       "attributes": [
         {
@@ -1792,6 +2116,48 @@
           "name": "disabled",
           "description": "Whether the field is disabled"
         },
+        {
+          "name": "dropdown-placement",
+          "description": "Initial Floating UI placement for the options panel (e.g. `top-start`, `bottom-start`).\nForwarded to the inner `xpl-dropdown` when the menu is open.",
+          "values": [
+            {
+              "name": "bottom"
+            },
+            {
+              "name": "bottom-end"
+            },
+            {
+              "name": "bottom-start"
+            },
+            {
+              "name": "left"
+            },
+            {
+              "name": "left-end"
+            },
+            {
+              "name": "left-start"
+            },
+            {
+              "name": "right"
+            },
+            {
+              "name": "right-end"
+            },
+            {
+              "name": "right-start"
+            },
+            {
+              "name": "top"
+            },
+            {
+              "name": "top-end"
+            },
+            {
+              "name": "top-start"
+            }
+          ]
+        },
         {
           "name": "error",
           "description": "If an empty string (attribute present with no value),\nwill display visually as an error. If a string is\nincluded, will display visually as an error and include\nthe value as an error message."
@@ -1966,7 +2332,7 @@
       "name": "xpl-slideout",
       "description": {
         "kind": "markdown",
-        "value": "Content and Footer subcomponents are optional and can be hidden.  Slideout always has a header with an X close button upper right. Slide Out Panel OPTIONALLY uses the [<xpl-backdrop>](https://xplor-apollo.herokuapp.com/?path=/story/components-backdrop--backdrop) component to overlay content and create focus on the Slide Out Panel content."
+        "value": "Content and Footer subcomponents are optional and can be hidden.  Slideout always has a header with an X close button upper right. Slide Out Panel OPTIONALLY uses the [<xpl-backdrop>](https://apollo.xplordocs.com/?path=/story/components-backdrop--backdrop) component to overlay content and create focus on the Slide Out Panel content."
       },
       "attributes": [
         {
@@ -1995,13 +2361,127 @@
         }
       ]
     },
+    {
+      "name": "xpl-spotlight",
+      "description": {
+        "kind": "markdown",
+        "value": "`xpl-spotlight` renders a guided-tour callout with an anchor dot, optional media, step messaging, and prop-driven footer actions. It can either render inline using the requested `anchorPosition` or attach to a target element with Floating UI when `target` is provided."
+      },
+      "attributes": [
+        {
+          "name": "action-layout",
+          "description": "Footer action layout. `default` and `dual` both render the standard Back/Next layout, while\n`single` renders a single acknowledgement CTA (e.g. \"Got it!\").\nOnly applies when `showActions` is `true`.",
+          "values": [
+            {
+              "name": "default"
+            },
+            {
+              "name": "dual"
+            },
+            {
+              "name": "single"
+            }
+          ]
+        },
+        {
+          "name": "anchor-position",
+          "description": "Which corner of the card the anchor dot uses when not using `target`, or as the preferred side for Floating UI.",
+          "values": [
+            {
+              "name": "bottom-left"
+            },
+            {
+              "name": "bottom-right"
+            },
+            {
+              "name": "top-left"
+            },
+            {
+              "name": "top-right"
+            }
+          ]
+        },
+        {
+          "name": "body",
+          "description": "Body copy when the `body` slot has no slotted content. Whitespace-only values are treated as empty (no fallback paragraph)."
+        },
+        {
+          "name": "current-step",
+          "description": "Current step index (1-based). Used with `totalSteps` for the step label and for disabling\ndefault Back/Next when `showSteps` is true."
+        },
+        {
+          "name": "heading",
+          "description": "Heading when the `title` slot has no slotted content. Whitespace-only values are treated as empty (no fallback title span)."
+        },
+        {
+          "name": "is-dismissible",
+          "description": "Whether to show the dismiss (close) control."
+        },
+        {
+          "name": "is-open",
+          "description": "Controls whether the spotlight is rendered. When false, the host remains in the DOM but the spotlight UI is hidden."
+        },
+        {
+          "name": "primary-action-label",
+          "description": "Label used for the default primary action button. Only applies when `showActions` is `true`."
+        },
+        {
+          "name": "secondary-action-label",
+          "description": "Label used for the default secondary action button. Only applies when `showActions` is `true`."
+        },
+        {
+          "name": "show-actions",
+          "description": "Whether to show the actions row (primary / secondary and optional step counter).\nWhen `false`, the spotlight has no action buttons — useful for single-step\ninformational callouts that rely solely on the dismiss control."
+        },
+        {
+          "name": "show-image",
+          "description": "When true, the media region is shown. Slotted `image` content is rendered when present;\notherwise the built-in placeholder UI is shown. When false, the entire media block is hidden."
+        },
+        {
+          "name": "show-steps",
+          "description": "Whether to show the step counter between actions (`currentStep` of `totalSteps`) and whether\ndefault Back/Next use step-based disabled state."
+        },
+        {
+          "name": "target",
+          "description": "CSS selector for the element this spotlight anchors to. When set, placement uses Floating UI\n(`computePosition` with `strategy: 'fixed'`, plus `flip`, `shift`, `offset`) and `autoUpdate`\nfor scroll/resize. The host receives `left` / `top` and the `xpl-spotlight--anchored` class.\nInvalid selectors are ignored; layout falls back to `anchor-position`."
+        },
+        {
+          "name": "total-steps",
+          "description": "Total number of steps (1-based upper bound). Used with `currentStep` for the step label and\nfor disabling default Back/Next when `showSteps` is true."
+        }
+      ]
+    },
     {
       "name": "xpl-tab",
       "description": {
         "kind": "markdown",
-        "value": ""
+        "value": "`xpl-tab` is the **label / trigger** for one tab in an `xpl-tabs` group. Place each instance in the **`heading`** slot of `xpl-tabs`. The **`target`** string links this tab to the matching **`xpl-tab-panel`** (same `target` value). The parent sets **`selected`** and syncs **`value`**; you normally do not set `selected` by hand.\n\nUnderline tabs render a native **`<button role=\"tab\">`**; segment tabs render **`xpl-button`** with the same tab semantics on the inner control. For variant-specific examples, icon usage, and token tables, see the matching section on the **Tabs** or **Segment control** Storybook page.\n\n**`group-disabled`** is applied by `xpl-tabs` when the group has **`disabled`**; it keeps pills and underline buttons in a disabled state together with the parent."
       },
       "attributes": [
+        {
+          "name": "disabled",
+          "description": "Disables this tab (pill or underline)."
+        },
+        {
+          "name": "data-group-disabled",
+          "description": "Set when the parent `xpl-tabs` has `disabled` (group-disabled)."
+        },
+        {
+          "name": "icon",
+          "description": "Optional icon name for segment-style pills (`type=\"segment\"` on parent `xpl-tabs`). Ignored for default tabs."
+        },
+        {
+          "name": "icon-position",
+          "description": "Icon position for segment-style pills.",
+          "values": [
+            {
+              "name": "end"
+            },
+            {
+              "name": "start"
+            }
+          ]
+        },
         {
           "name": "selected",
           "description": "Whether the tab is selected"
@@ -2016,7 +2496,7 @@
       "name": "xpl-tab-panel",
       "description": {
         "kind": "markdown",
-        "value": ""
+        "value": "`xpl-tab-panel` is the **content region** for one tab. Place each panel in the **`panel`** slot of `xpl-tabs` and set **`target`** to the same string as its paired **`xpl-tab`**. Only the panel whose `target` matches the group’s selection is visible; others stay hidden via CSS until selected."
       },
       "attributes": [
         {
@@ -2106,13 +2586,29 @@
       "name": "xpl-tabs",
       "description": {
         "kind": "markdown",
-        "value": "Tabs organize content across different screens, data sets, and other interactions."
+        "value": "`xpl-tabs` groups related views into a single surface: users pick a **tab** to show the matching **panel**. It implements the WAI-ARIA tabs pattern with a horizontal tab list, optional full-width layout, and two visual styles—**underline** (`type=\"tabs\"`, default) and **segment** (`type=\"segment\"`, pill controls in a bordered track)—selected with the **`type`** prop. On narrow viewports the heading row is replaced by an `xpl-select` so the same targets and keyboard behavior stay consistent.\n\nThe **Tabs** and **Segment control** Storybook entries document this **one component** with different defaults and Figma references. Each page adds variant-specific guidance (when to use, examples, tokens); the sections below describe behavior that is **the same for both** styles.\n\nPair **`xpl-tab` (slot `heading`)** with **`xpl-tab-panel` (slot `panel`)** and use the same **`target`** string on each pair so selection stays in sync."
       },
       "attributes": [
+        {
+          "name": "disabled",
+          "description": "Disables the whole tab group (headings, mobile select, and segment pills)."
+        },
         {
           "name": "full-width",
           "description": "Whether to make the tabs full width"
         },
+        {
+          "name": "type",
+          "description": "Visual and layout variant: classic underline tabs or segment (pill) controls.",
+          "values": [
+            {
+              "name": "segment"
+            },
+            {
+              "name": "tabs"
+            }
+          ]
+        },
         {
           "name": "value",
           "description": "The selected tab target value, defaults to the first tab"
@@ -2123,15 +2619,44 @@
       "name": "xpl-tag",
       "description": {
         "kind": "markdown",
-        "value": "Tags represent a set of interactive keywords that help label, organize, and categorize objects. Tags can be added or removed from an object by the user. Unlike Badges, Tags are clickable, draggable, used in dropdowns, multi-select, search bars, etc.."
+        "value": "Tags represent a set of interactive keywords that help label, organize, and categorize objects. Tags can be added or removed from an object by the user. Unlike Badges, Tags are clickable, used in dropdowns, multi-select, search bars, etc."
       },
-      "attributes": []
+      "attributes": [
+        {
+          "name": "disabled",
+          "description": "Whether the tag is disabled"
+        },
+        {
+          "name": "dismissible",
+          "description": "Whether the tag shows a dismiss button"
+        },
+        {
+          "name": "is-draggable",
+          "description": "When true, the tag label uses native HTML5 drag (the inner label is the drag source).\nNamed `isDraggable` so the Stencil prop does not collide with the native `HTMLElement.draggable`\nAPI. `reflect: false` avoids syncing a `draggable` attribute onto the host; the inner label\nremains the drag source. Host `onDragStart` still suppresses stray native drags from host chrome."
+        },
+        {
+          "name": "size",
+          "description": "The size of the tag",
+          "values": [
+            {
+              "name": "default"
+            },
+            {
+              "name": "sm"
+            }
+          ]
+        },
+        {
+          "name": "tag-id",
+          "description": "Optional stable id for the tag. When set, it is included in `tagDragStart` / `tagDragEnd` detail\nand written to `dataTransfer` as `application/x-tag-id`."
+        }
+      ]
     },
     {
       "name": "xpl-toast",
       "description": {
         "kind": "markdown",
-        "value": "Toasts are brief, non-disruptive messages that provide quick, at-a-glance feedback. They can have 3 sentiments; neutral, positive and negative and contain actions such as a button or link, or a close button. Messaging can include a title and caption limited to 85 characters. Keep your toast messaging short and to the point and tone in line with the sentiment of the Toast. \n\nThe Toast component is configurable by Sentiment plus show/hide properties for Icon, Caption, Button and Dismissible. Use the nested component’s properties to customize further as needed. \n\nWhen possible, Toasts should auto-dismiss after 8 seconds. When an action is present, it may not be desirable to time out the Toast depending on your specific context.  \n\nMatch your messaging with the sentiment of the toast. Most messages will have a neutral sentiment. Reserve negative sentiments for when an explicit failure has occurred. Give users the information they need to correct the issue. \n\nToasts only support a single action and up to 85 characters. If multiple actions can be taken, or the message is longer than a few words, use a [Modal component](https://xplor-apollo.herokuapp.com/?path=/story/components-modal--modal) instead."
+        "value": "Toasts are brief, non-disruptive messages that provide quick, at-a-glance feedback. They can have 3 sentiments; neutral, positive and negative and contain actions such as a button or link, or a close button. Messaging can include a title and caption limited to 85 characters. Keep your toast messaging short and to the point and tone in line with the sentiment of the Toast. \n\nThe Toast component is configurable by Sentiment plus show/hide properties for Icon, Caption, Button and Dismissible. Use the nested component’s properties to customize further as needed. \n\nWhen possible, Toasts should auto-dismiss after 8 seconds. When an action is present, it may not be desirable to time out the Toast depending on your specific context.  \n\nMatch your messaging with the sentiment of the toast. Most messages will have a neutral sentiment. Reserve negative sentiments for when an explicit failure has occurred. Give users the information they need to correct the issue. \n\nToasts only support a single action and up to 85 characters. If multiple actions can be taken, or the message is longer than a few words, use a [Modal component](https://apollo.xplordocs.com/?path=/story/components-modal--modal) instead."
       },
       "attributes": [
         {
@@ -2272,6 +2797,72 @@
         }
       ]
     },
+    {
+      "name": "xpl-top-nav",
+      "description": {
+        "kind": "markdown",
+        "value": "Horizontal top navigation with **`left-aside`** and a **right rail**: **`right-aside`** then **user menu**\n(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`**).\nOptional **`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.\n\n**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).\n**`xpl-top-nav-item`** **`slot=\"dropdown\"`** uses document **capture** for **Escape** first; the shell uses **bubble**\non **`ownerDocument`** so nested dropdowns close before the drawer.\n\n**Theming:** The host always includes Foundation’s **`dark`** class so **`--xpl-*`** purpose tokens under this subtree\nresolve to dark-mode values even when the page root is light. Floating overlays (e.g. **`xpl-popover`** / **`xpl-dropdown`**\ncontent teleported outside the host) do not inherit this scope — add **`dark`** on those panels if they should match.\n\n**Layout:** **`right-aside`** and the user-menu region are wrapped internally (**`.xpl-top-nav__right-lead`**, etc.).\nConsumers should not add those BEM classes — slot content only.\n\n**Brand logo:** use **`brand-logo`** (URL) for a built-in **`<img>`**, or **`slot=\"brand-logo\"`** for custom markup (e.g. **`xpl-icon`**, SVG). When the URL prop is set, it takes precedence and the slot is not used for the image. On **narrow viewports** (one pixel below Tailwind **`md`** — see **`top-nav.css`**), **`brand-name`** text is hidden in the bar (logo / slot mark only); keep a meaningful **`alt`** on **`brand-logo`** or accessible slotted mark for context.\n\n**Narrow / mobile** (same breakpoint as above): **`slot=\"left-aside\"`** is **hidden** in the bar until **`nav-control`**\nis set **and** the drawer is open (floating panel per Figma). **Without **`nav-control`**, there is no mobile drawer** —\nprimary links remain hidden below **`md`** until the viewport is wide enough for the horizontal bar. The built-in **brand**\nstays in the top bar (**hamburger → brand** when **`nav-control`** is set). **`right-aside`** is hidden in the bar on narrow\nviewports (**`top-nav.css`**, one pixel below Tailwind **`md`**); duplicate those actions into **`xpl-nav-header-menu`**\n**`slot=\"right-aside-mobile\"`** (below profile, above the list; narrow-only CSS in **`top-nav.css`**) per Figma.\n\n**Account menu vs drawer:** Opening the built-in account **`xpl-popover`** while the mobile drawer is open **closes the drawer**\nand emits **`navOpen(false)`** so the two layers do not stack."
+      },
+      "attributes": [
+        {
+          "name": "brand-href",
+          "description": "Destination URL for the brand control when using native navigation (**`<a href>`**). When unset, the brand is a\n**`role=\"button\"`** control and **`brandClick`** fires on activation instead."
+        },
+        {
+          "name": "brand-logo",
+          "description": "Optional image URL for the brand mark (leading the brand row, before **`brand-name`** text). When set, renders\n**`<img class=\"xpl-top-nav__brand-logo\">`** and ignores **`slot=\"brand-logo\"`** for the mark. When unset, use\n**`slot=\"brand-logo\"`** for custom logo content."
+        },
+        {
+          "name": "brand-name",
+          "description": "Visible product / app name next to **`brand-logo`**. Omit for logo-only; provide **`brand-logo`** and/or this\nstring to show the built-in brand row (**`left-aside`** is then primary nav links only)."
+        },
+        {
+          "name": "child-account-label",
+          "description": "Label text for the built-in account menu trigger (shown **before** the **`chevron-down`** icon) when **`slot=\"user-menu\"`**\nis present and **`slot=\"user-menu-trigger\"`** is not used. When empty or whitespace-only, the trigger shows only the\nchevron and uses **`aria-label=\"Open account menu\"`** on the button."
+        },
+        {
+          "name": "label",
+          "description": "Accessible name for the `<nav>` landmark (maps to `aria-label`).\nUse a unique label when the page has multiple navigation regions (e.g. side nav + top nav).\nWhen unset, defaults to `top-navigation-bar`."
+        },
+        {
+          "name": "nav-control",
+          "description": "When true, renders the navigation control (hamburger) for toggling the left slot on small viewports.\nThe control is **hidden from the Tailwind `md` breakpoint up**; collapse/show for **`left-aside`** uses **`max-width: calc(theme('screens.md') - 1px)`** in **`top-nav.css`** (Figma’s 767px at a 16px root and default **`screens.md`**).\nReflected to the **`nav-control`** attribute so host updates (framework props) re-run **`@Watch`**: drawer state and\ndocument **Escape** handling stay in sync, the host **`xpl-top-nav--nav-control`** class toggles for **`top-nav.css`**, and\n**`navOpen(false)`** is emitted if **`nav-control`** is cleared while the drawer was open."
+        }
+      ]
+    },
+    {
+      "name": "xpl-top-nav-item",
+      "description": {
+        "kind": "markdown",
+        "value": "Single nav row for **`xpl-top-nav`** / **`xpl-nav-header-menu`**. The host uses **`role=\"listitem\"`** when the row\nparticipates in a list: a **`role=\"list\"`** parent, **`slot=\"left-aside\"`** on **`xpl-top-nav`** (list host is\n**`.xpl-top-nav__left-primary`** while slotted nodes stay light-DOM children of **`xpl-top-nav`**), or default-slot rows\nunder **`xpl-nav-header-menu`**. That flag is\nkept in **`@State`** and refreshed after render plus via **`MutationObserver`** on the host (**`class`**, **`slot`**) and\non **`parentElement`** (**`role`**) or on **`.xpl-top-nav__left-primary`** (**`role`**) for **`slot=\"left-aside\"`** under **`xpl-top-nav`**) so DOM context changes\nwithout a full reconnect still re-sync. The internal\n**`xpl-top-nav__brand`** row omits **`listitem`** (it sits in **`.xpl-top-nav__brand-bar`**, not **`.xpl-top-nav__left-primary`**),\nas do **`slot=\"right-aside-mobile\"`** rows (not a list). **`slot=\"dropdown\"`** uses a local **`.xpl-top-nav-item__dropdown`**\npanel (not **`xpl-dropdown`**); see **`TECH_DEBT.md`**.\n\n**Default slot (no `label`):** do not put **`xpl-top-nav-item__inner`** or other **`xpl-top-nav-item__*`** classes on\ncustom trigger content — the component renders the inner wrapper and BEM elements.\n\n**Theming:** The host always includes Foundation’s **`dark`** class so **`--xpl-*`** purpose tokens resolve to dark-mode\nvalues even when the page root is light (consistent with **`xpl-top-nav`**)."
+      },
+      "attributes": [
+        {
+          "name": "active",
+          "description": "When true, adds **`xpl-top-nav-item--active`** for persistent accent styling (e.g. link color on the bar, or\nchrome inside **`xpl-nav-header-menu`**). Separate from **`selected`**, which sets **`aria-current=\"page\"`** and\n**`--selected`**. Use both when the design needs “current page” semantics plus the active visual treatment."
+        },
+        {
+          "name": "href",
+          "description": "If set without **`slot=\"dropdown\"`**, the inner control renders as a native **`<a href>`** (link mode)."
+        },
+        {
+          "name": "icon",
+          "description": "Icon name from **`@xplortech/apollo-icons`** (shown before the label when **`label`** is set)."
+        },
+        {
+          "name": "item-aria-label",
+          "description": "Accessible name for the inner control when there is no **`label`** and no default-slot text (e.g. icon-only).\nIf omitted in that case, **`aria-label`** defaults to **`Navigation item`**. Ignored when **`label`** or default-slot\ncontent supplies a visible name."
+        },
+        {
+          "name": "label",
+          "description": "Text label. If omitted, use the default slot for custom trigger content. Long labels use **`text-ellipsis`**\non **`.xpl-top-nav-item__label`** (see `top-nav.css`); **`title`** is set to the full string for hover tooltips\nwhen the visual line clips."
+        },
+        {
+          "name": "selected",
+          "description": "When true, sets **`aria-current=\"page\"`** and selected styling."
+        }
+      ]
+    },
     {
       "name": "xpl-utility-bar",
       "description": {