@xplortech/apollo-core 2.10.0 → 2.12.0

package/dist/collection/components/xpl-side-nav/side-nav.stories.js

@@ -1,9 +1,59 @@
+import { setAutoSnapshotOptions } from "vitest-plugin-vis";
+import { waitForHydration } from "../../../../.storybook/utils/wait-for-hydration";
 const escapeHtmlAttribute = (value) => value
     .replace(/&/g, '&')
     .replace(/"/g, '"')
     .replace(/'/g, ''')
     .replace(/</g, '&lt;')
     .replace(/>/g, '&gt;');
+const renderHeaderItemWebComponent = (headerItem) => {
+    const attrs = [
+        `type="${headerItem.type}"`,
+        headerItem.label ? `label="${escapeHtmlAttribute(headerItem.label)}"` : '',
+        headerItem.icon ? `icon="${escapeHtmlAttribute(headerItem.icon)}"` : '',
+        headerItem.type === 'sub-account' && headerItem.selected ? 'selected' : '',
+    ]
+        .filter(Boolean)
+        .join(' ');
+    return `<xpl-side-nav-header-item ${attrs}></xpl-side-nav-header-item>`;
+};
+const renderHeaderItemsWebComponent = (headerItems) => {
+    if (!headerItems?.length)
+        return '';
+    const rows = headerItems.map(renderHeaderItemWebComponent).join('');
+    return `<div slot="nav-header">${rows}</div>`;
+};
+const renderHeaderItemHtml = (headerItem) => {
+    const isSubAccount = headerItem.type === 'sub-account';
+    const leading = headerItem.icon
+        ? `<span class="xpl-side-nav-header-item__leading"><xpl-icon icon="${escapeHtmlAttribute(headerItem.icon)}" size="16"></xpl-icon></span>`
+        : '';
+    const trailing = isSubAccount
+        ? `<span class="xpl-side-nav-header-item__trailing" aria-hidden="true"><xpl-icon icon="chevron-expand-y" size="16"></xpl-icon></span>`
+        : '';
+    const label = `<span class="xpl-side-nav-header-item__label">${escapeHtmlAttribute(headerItem.label)}</span>`;
+    const content = `<span class="xpl-side-nav-header-item__content">${leading}${label}${trailing}</span>`;
+    const inner = isSubAccount
+        ? `<button type="button" class="xpl-side-nav-header-item__header">${content}</button>`
+        : `<div class="xpl-side-nav-header-item__header">${content}</div>`;
+    const modifiers = [
+        isSubAccount
+            ? 'xpl-side-nav-header-item--sub-account'
+            : 'xpl-side-nav-header-item--product-label',
+        isSubAccount && headerItem.selected ? 'xpl-side-nav-header-item--selected' : '',
+    ]
+        .filter(Boolean)
+        .join(' ');
+    return `<div class="xpl-side-nav-header-item ${modifiers}">${inner}</div>`;
+};
+const renderHeaderItemsHtml = (headerItems) => {
+    if (!headerItems?.length)
+        return '';
+    const rows = headerItems.map(renderHeaderItemHtml).join('\n      ');
+    return `<div class="xpl-side-nav__header">
+      ${rows}
+    </div>`;
+};
 const defaultItems = [
     { label: 'Dashboard', icon: 'house-4', selected: true },
     { label: 'Product', icon: 'bag-shopping-2' },
@@ -28,6 +78,18 @@ const defaultItems = [
         icon: 'chart-line-up',
         trailingIcon: 'external-link',
     },
+    { kind: 'divider' },
+    {
+        kind: 'section',
+        label: 'Admin',
+        expanded: true,
+        badgeCount: '2',
+        children: [
+            { label: 'Team Members', icon: 'user' },
+            { label: 'Billing', icon: 'credit-card' },
+        ],
+    },
+    { kind: 'divider' },
 ];
 const defaultFooterItems = [
     { label: 'Support', icon: 'headset' },
@@ -35,11 +97,33 @@ const defaultFooterItems = [
 ];
 const defaultNavConfig = {
     navLabel: 'Main navigation',
+    headerItems: [
+        { type: 'product-label', label: 'Product Label' },
+        { type: 'sub-account', label: 'Acme Inc', icon: 'office-3' },
+    ],
     items: defaultItems,
     footerItems: defaultFooterItems,
 };
 const renderNavItem = (item) => {
-    var _a, _b;
+    if (item.kind === 'divider') {
+        return `\n    <hr class="xpl-side-nav-divider" />`;
+    }
+    if (item.kind === 'section') {
+        const sectionAttrs = [
+            item.label ? `heading="${escapeHtmlAttribute(item.label)}"` : '',
+            item.collapsible === false ? 'collapsible="false"' : '',
+            item.expanded ? 'expanded' : '',
+        ]
+            .filter(Boolean)
+            .join(' ');
+        const badgeSlot = item.badgeCount
+            ? `\n        <xpl-badge slot="badge" variant="purple" size="small">${escapeHtmlAttribute(item.badgeCount)}</xpl-badge>`
+            : '';
+        const sectionChildrenHtml = item.children?.map(renderNavItem).join('') ?? '';
+        return `
+    <xpl-side-nav-section ${sectionAttrs}>${badgeSlot}${sectionChildrenHtml}
+    </xpl-side-nav-section>`;
+    }
     const attrs = [
         item.label ? `label="${escapeHtmlAttribute(item.label)}"` : '',
         item.icon ? `icon="${escapeHtmlAttribute(item.icon)}"` : '',
@@ -58,10 +142,10 @@ const renderNavItem = (item) => {
             : '';
         return `
     <xpl-side-nav-item ${attrs}>
-        <a href="${escapeHtmlAttribute(item.href)}" class="xpl-side-nav-item__link"${item.selected ? ' aria-current="page"' : ''}><span class="xpl-side-nav-item__leading">${leadingIcon}</span><span class="xpl-side-nav-item__label">${escapeHtmlAttribute(item.label)}</span></a>
+        <a href="${escapeHtmlAttribute(item.href)}" class="xpl-side-nav-item__link"${item.selected ? ' aria-current="page"' : ''}><span class="xpl-side-nav-item__leading">${leadingIcon}</span><span class="xpl-side-nav-item__label">${escapeHtmlAttribute(item.label ?? '')}</span></a>
     </xpl-side-nav-item>`;
     }
-    const childrenHtml = (_b = (_a = item.children) === null || _a === void 0 ? void 0 : _a.map(renderNavItem).join('')) !== null && _b !== void 0 ? _b : '';
+    const childrenHtml = item.children?.map(renderNavItem).join('') ?? '';
     const trailingSlot = item.trailingIcon && !item.hasChildren
         ? `\n        <xpl-icon slot="trailing" icon="${escapeHtmlAttribute(item.trailingIcon)}" size="16" aria-hidden="true"></xpl-icon>`
         : '';
@@ -69,9 +153,35 @@ const renderNavItem = (item) => {
     <xpl-side-nav-item ${attrs}>${trailingSlot}${childrenHtml}
     </xpl-side-nav-item>`;
 };
+let htmlSectionIdCounter = 0;
 const renderHtmlNavItem = (item, depth = 0) => {
-    var _a, _b;
     const indent = '  '.repeat(depth);
+    if (item.kind === 'divider') {
+        return `${indent}<hr class="xpl-side-nav-divider" />`;
+    }
+    if (item.kind === 'section') {
+        const collapsible = item.collapsible !== false;
+        const expanded = !collapsible || Boolean(item.expanded);
+        const childrenId = `side-nav-demo-section-children-${(htmlSectionIdCounter += 1)}`;
+        const sectionChildrenHtml = item.children?.map((child) => renderHtmlNavItem(child, depth + 2)).join('\n') ?? '';
+        const badgeHtml = item.badgeCount
+            ? `${indent}    <span class="xpl-side-nav-section__badge"><xpl-badge variant="purple" size="small">${item.badgeCount}</xpl-badge></span>\n`
+            : '';
+        const chevronHtml = collapsible
+            ? `${indent}    <span class="xpl-side-nav-section__chevron"><xpl-icon icon="${expanded ? 'chevron-down' : 'chevron-right'}" size="16" aria-hidden="true"></xpl-icon></span>\n`
+            : '';
+        const titleRowHtml = `${indent}    <span class="xpl-side-nav-section__title">${item.label ?? ''}</span>\n${badgeHtml}${chevronHtml}`;
+        const headerHtml = collapsible
+            ? `${indent}  <button type="button" class="xpl-side-nav-section__header" aria-expanded="${expanded ? 'true' : 'false'}" aria-controls="${childrenId}">\n${titleRowHtml}${indent}  </button>`
+            : `${indent}  <div class="xpl-side-nav-section__header">\n${titleRowHtml}${indent}  </div>`;
+        return `${indent}<div class="xpl-side-nav-section${collapsible ? '' : ' xpl-side-nav-section--static'}">
+${headerHtml}
+${indent}  <div id="${childrenId}" class="xpl-side-nav-section__children${expanded ? ' expanded' : ''}">
+${indent}    <div class="xpl-side-nav-section__children-inner">
+${sectionChildrenHtml ? `\n${sectionChildrenHtml}\n${indent}    ` : ''}</div>
+${indent}  </div>
+${indent}</div>`;
+    }
     const linkClass = [
         'xpl-side-nav-item__link',
         item.selected ? 'selected' : '',
@@ -88,7 +198,7 @@ ${indent}  </a>
 ${indent}</div>`;
     }
     const hasChildren = item.hasChildren || (item.children && item.children.length > 0);
-    const childrenHtml = (_b = (_a = item.children) === null || _a === void 0 ? void 0 : _a.map((child) => renderHtmlNavItem(child, depth + 2)).join('\n')) !== null && _b !== void 0 ? _b : '';
+    const childrenHtml = item.children?.map((child) => renderHtmlNavItem(child, depth + 2)).join('\n') ?? '';
     const trailingHtml = hasChildren
         ? `<span class="xpl-side-nav-item__trailing xpl-side-nav-item__trailing--chevron${item.expanded ? ' expanded' : ''}"><xpl-icon icon="${item.expanded ? 'chevron-up' : 'chevron-down'}" size="16" aria-hidden="true"></xpl-icon></span>`
         : item.trailingIcon
@@ -109,6 +219,13 @@ ${indent}  </div>`
 ${indent}</div>`;
 };
 export default {
+    tags: ['vrt'],
+    beforeEach() {
+        setAutoSnapshotOptions({ enable: true });
+    },
+    async play({ canvasElement }) {
+        await waitForHydration(canvasElement);
+    },
     title: 'Components/Navigation/Side Navigation',
     component: 'xpl-side-nav',
     parameters: {
@@ -116,14 +233,18 @@ export default {
     },
 };
 const renderHtmlSideNav = (config) => {
-    const { navLabel, items, footerItems } = config;
+    const { navLabel, headerItems, items, footerItems } = config;
+    const headerHtml = renderHeaderItemsHtml(headerItems);
     const itemsHtml = items.map((item) => renderHtmlNavItem(item, 4)).join('\n');
     const footerHtml = footerItems.map((item) => renderHtmlNavItem(item, 4)).join('\n');
     return `<div class="xpl-side-nav">
   <div class="xpl-side-nav__wrapper">
     <nav class="xpl-side-nav__content" aria-label="${escapeHtmlAttribute(navLabel)}">
-      <div class="xpl-side-nav__section">
+      <div class="xpl-side-nav__scroll-area">
+        ${headerHtml}
+        <div class="xpl-side-nav__section">
 ${itemsHtml}
+        </div>
       </div>
       <div class="xpl-side-nav__footer">
 ${footerHtml}
@@ -133,24 +254,26 @@ ${footerHtml}
 </div>`;
 };
 const SideNavigationWebComponent = (config) => {
-    const { navLabel, items, footerItems } = config;
+    const { navLabel, headerItems, items, footerItems } = config;
+    const headerHtml = renderHeaderItemsWebComponent(headerItems);
     const itemsHtml = items.map(renderNavItem).join('');
     const footerHtml = footerItems.map(renderNavItem).join('');
-    return `<xpl-side-nav label="${escapeHtmlAttribute(navLabel)}"><div slot="section">${itemsHtml}</div><div slot="nav-footer">${footerHtml}</div></xpl-side-nav>`;
+    return `<xpl-side-nav label="${escapeHtmlAttribute(navLabel)}">${headerHtml}<div slot="section">${itemsHtml}</div><div slot="nav-footer">${footerHtml}</div></xpl-side-nav>`;
 };
 let sideNavClickController;
 export const SideNavigation = {
     args: {
-        navConfig: Object.assign({}, defaultNavConfig),
+        navConfig: { ...defaultNavConfig },
     },
     argTypes: {
         navConfig: {
             control: 'object',
-            description: 'Full sidebar config (router-style): `navLabel`, `items[]`, `footerItems[]`. Arrays map to `xpl-side-nav-item` markup.',
+            description: 'Full sidebar config (router-style): `navLabel`, `headerItems?[]`, `items[]`, `footerItems[]`. Each entry maps to `xpl-side-nav-item` markup by default; set `kind: \'section\'` for an `xpl-side-nav-section` accordion or `kind: \'divider\'` for a standalone `<hr class="xpl-side-nav-divider">` (no dedicated component). `headerItems` renders `slot="nav-header"` as one or more `xpl-side-nav-header-item` rows — omit or leave empty to hide the header.',
         },
     },
     render: ({ navConfig }) => {
-        const { navLabel, items, footerItems } = navConfig;
+        const { navLabel, headerItems, items, footerItems } = navConfig;
+        const headerHtml = renderHeaderItemsWebComponent(headerItems);
         const itemsHtml = items.map(renderNavItem).join('');
         const footerHtml = footerItems.map(renderNavItem).join('');
         return `
@@ -208,6 +331,7 @@ export const SideNavigation = {
 </style>
 <div class="side-nav-demo-wrapper">
     <xpl-side-nav label="${escapeHtmlAttribute(navLabel)}">
+        ${headerHtml}
         <div slot="section">${itemsHtml}
         </div>
         <div slot="nav-footer">${footerHtml}
@@ -223,9 +347,16 @@ export const SideNavigation = {
             label (flex-1)<br/>
             <code>slot="trailing"</code> — trailing icon; auto chevron for parents (<code>chevron-down</code> collapsed, <code>chevron-up</code> expanded)
         </div>
+        <div class="side-nav-demo-legend">
+            <strong>Sections &amp; dividers</strong> (near the bottom of this demo's items): <code>kind: 'section'</code> renders an <code>xpl-side-nav-section</code> accordion — its <code>children</code> are NOT indented and keep their leading icon, unlike a <code>hasChildren</code> item. <code>kind: 'divider'</code> renders a standalone, full-bleed <code>&lt;hr class="xpl-side-nav-divider"&gt;</code> — no dedicated component. Sections don't render their own dividers — place them as siblings.
+        </div>
+        <div class="side-nav-demo-legend">
+            <strong><code>slot="nav-header"</code></strong> (top of the sidebar, above the section): renders one or more <code>xpl-side-nav-header-item</code> rows. Hidden entirely — no wrapper, no border — when <code>navConfig.headerItems</code> is omitted or empty. This demo stacks a <code>'product-label'</code> row (static) above a <code>'sub-account'</code> row (interactive; emits <code>navigate</code>, auto <code>chevron-expand-y</code> trailing icon), per the Figma spec.
+        </div>
         <div class="side-nav-demo-legend">
             <strong><code>NavItem</code></strong><br/>
-            <code>{ label, icon?, trailingIcon?, selected?, disabled?, hidden?, hasChildren?, expanded?, link?, href?, children? }</code>
+            <code>{ kind?, label?, icon?, trailingIcon?, selected?, disabled?, hidden?, hasChildren?, expanded?, link?, href?, children?, collapsible?, badgeCount? }</code><br/>
+            <code>kind</code> defaults to <code>'item'</code>; <code>collapsible</code> / <code>badgeCount</code> apply only to <code>kind: 'section'</code> entries.
         </div>
         <div class="side-nav-demo-legend">
             <strong>Responsive (below <code>md</code> / 768 px):</strong><br/>
@@ -239,7 +370,8 @@ export const SideNavigation = {
 </div>`;
     },
     play: async ({ canvasElement }) => {
-        sideNavClickController === null || sideNavClickController === void 0 ? void 0 : sideNavClickController.abort();
+        await waitForHydration(canvasElement);
+        sideNavClickController?.abort();
         sideNavClickController = new AbortController();
         const nav = canvasElement.querySelector('xpl-side-nav');
         if (!nav)
@@ -355,7 +487,7 @@ export const ItemPlayground = {
         if (link) {
             const leadingIcon = icon ? `<xpl-icon icon="${icon}" size="16"></xpl-icon>` : '';
             content = `
-        <a href="#${(label === null || label === void 0 ? void 0 : label.toLowerCase().replace(/\s+/g, '-')) || 'item'}" class="xpl-side-nav-item__link"><span class="xpl-side-nav-item__leading">${leadingIcon}</span><span class="xpl-side-nav-item__label">${label}</span></a>`;
+        <a href="#${label?.toLowerCase().replace(/\s+/g, '-') || 'item'}" class="xpl-side-nav-item__link"><span class="xpl-side-nav-item__leading">${leadingIcon}</span><span class="xpl-side-nav-item__label">${label}</span></a>`;
         }
         else if (hasChildren) {
             content = `${trailingSlot}
@@ -433,6 +565,306 @@ ExternalLinkItem.parameters = {
         },
     },
 };
+export const Divider = () => `
+<style>
+    .divider-demo {
+        padding: var(--xpl-space-16);
+        border: var(--xpl-border-small) solid var(--xpl-border-default);
+        background-color: var(--xpl-background-surface-subtlest);
+        border-radius: var(--xpl-border-radius-default);
+        height: auto;
+        min-height: 0;
+        overflow: hidden;
+    }
+    .divider-caption {
+        font-family: var(--xpl-font-family-default);
+        font-size: var(--xpl-font-size-caption);
+        color: var(--xpl-text-subdued);
+        margin-bottom: var(--xpl-space-8);
+    }
+</style>
+<p class="divider-caption">1px full-bleed separator: a plain <code>&lt;hr class="xpl-side-nav-divider"&gt;</code>, no component. Place directly between items or sections inside <code>slot="section"</code>.</p>
+<div class="xpl-side-nav divider-demo">
+    <div class="xpl-side-nav__section">
+        <xpl-side-nav-item label="Dashboard" icon="house-4" selected></xpl-side-nav-item>
+        <xpl-side-nav-item label="Reports" icon="chart-line"></xpl-side-nav-item>
+        <hr class="xpl-side-nav-divider" />
+        <xpl-side-nav-item label="Settings" icon="gear"></xpl-side-nav-item>
+        <xpl-side-nav-item label="Integrations" icon="plug"></xpl-side-nav-item>
+    </div>
+</div>`;
+Divider.parameters = {
+    layout: 'centered',
+    design: {
+        type: 'figma',
+        url: 'https://www.figma.com/design/MjjYek73MFnHmVNdm45Sd1/Apollo-Web?node-id=25334-29185',
+    },
+    docs: {
+        description: {
+            story: 'A 1px full-bleed separator (`--xpl-border-default`) consumers place between `xpl-side-nav-item` / `xpl-side-nav-section` elements inside `slot="section"`. There is no dedicated component — it\'s a plain `<hr class="xpl-side-nav-divider">`, styled by `side-nav.css` (which leans on `reset.css`\'s default `<hr>` border rather than fighting it), giving it the native implicit `role="separator"` for free.',
+        },
+    },
+};
+export const SectionPlayground = {
+    argTypes: {
+        heading: {
+            control: 'text',
+            description: 'Section title text',
+        },
+        collapsible: {
+            control: 'boolean',
+            description: 'Whether the section can be collapsed/expanded. When false, renders a static title (no chevron) and children are always shown.',
+        },
+        expanded: {
+            control: 'boolean',
+            description: 'Whether the section is expanded (only meaningful when collapsible)',
+        },
+        badgeCount: {
+            control: 'text',
+            description: 'Optional badge text composed into slot="badge" via xpl-badge. Leave empty to hide the badge.',
+        },
+    },
+    args: {
+        heading: 'Settings',
+        collapsible: true,
+        expanded: false,
+        badgeCount: '',
+    },
+    render: ({ heading, collapsible, expanded, badgeCount }) => {
+        const attrs = [
+            heading ? `heading="${escapeHtmlAttribute(heading)}"` : '',
+            !collapsible ? 'collapsible="false"' : '',
+            collapsible && expanded ? 'expanded' : '',
+        ]
+            .filter(Boolean)
+            .join(' ');
+        const badgeSlot = badgeCount
+            ? `\n        <xpl-badge slot="badge" variant="purple" size="small">${escapeHtmlAttribute(badgeCount)}</xpl-badge>`
+            : '';
+        return `
+<style>
+    .section-playground-wrapper {
+        padding: var(--xpl-space-16);
+        border: var(--xpl-border-small) solid var(--xpl-border-default);
+        background-color: var(--xpl-background-surface-subtlest);
+        border-radius: var(--xpl-border-radius-default);
+        height: auto;
+        min-height: 0;
+        width: 240px;
+    }
+</style>
+<div class="xpl-side-nav section-playground-wrapper">
+    <xpl-side-nav-section ${attrs}>${badgeSlot}
+        <xpl-side-nav-item label="Location" icon="pin"></xpl-side-nav-item>
+        <xpl-side-nav-item label="Schedule" icon="calendar"></xpl-side-nav-item>
+    </xpl-side-nav-section>
+</div>`;
+    },
+    parameters: {
+        layout: 'centered',
+        design: {
+            type: 'figma',
+            url: 'https://www.figma.com/design/MjjYek73MFnHmVNdm45Sd1/Apollo-Web?node-id=25334-29188',
+        },
+        docs: {
+            description: {
+                story: 'Interactive playground for `xpl-side-nav-section`. Toggle `collapsible` to switch between the accordion header (with chevron, `chevron-right` collapsed / `chevron-down` expanded) and the static title variant (no chevron, children always shown). Set `badgeCount` to compose an `xpl-badge` into `slot="badge"` — the wrapper is suppressed when empty. Section children keep their leading icon and are NOT indented, unlike `xpl-side-nav-item[has-children]`.',
+            },
+        },
+    },
+};
+export const SectionsAndDividers = () => `
+<style>
+    .sections-dividers-demo {
+        display: flex;
+        height: 600px;
+        background-color: var(--xpl-background-surface-subtle);
+        border: var(--xpl-border-small) solid var(--xpl-border-default);
+    }
+</style>
+<div class="sections-dividers-demo">
+    <div class="xpl-side-nav">
+        <div class="xpl-side-nav__wrapper">
+            <nav class="xpl-side-nav__content" aria-label="Main navigation">
+                <div class="xpl-side-nav__scroll-area">
+                <div class="xpl-side-nav__section">
+                    <xpl-side-nav-item label="Nav Item 1" icon="house-4" selected></xpl-side-nav-item>
+                    <xpl-side-nav-item label="Nav Item 2" icon="bag-shopping-2"></xpl-side-nav-item>
+
+                    <hr class="xpl-side-nav-divider" />
+
+                    <xpl-side-nav-item has-children expanded label="Nav Item Parent Open" icon="gear">
+                        <xpl-side-nav-item label="Child 1"></xpl-side-nav-item>
+                        <xpl-side-nav-item label="Child 2"></xpl-side-nav-item>
+                    </xpl-side-nav-item>
+                    <xpl-side-nav-item label="Nav Item 4" icon="star"></xpl-side-nav-item>
+
+                    <hr class="xpl-side-nav-divider" />
+
+                    <xpl-side-nav-section heading="Section Closed">
+                        <xpl-side-nav-item has-children label="Nav Item Parent">
+                            <xpl-side-nav-item label="Child A"></xpl-side-nav-item>
+                        </xpl-side-nav-item>
+                        <xpl-side-nav-item has-children label="Nav Item Parent">
+                            <xpl-side-nav-item label="Child B"></xpl-side-nav-item>
+                        </xpl-side-nav-item>
+                    </xpl-side-nav-section>
+
+                    <hr class="xpl-side-nav-divider" />
+
+                    <xpl-side-nav-section heading="Section Open" expanded>
+                        <xpl-side-nav-item label="Nav Item 6" icon="chart-line"></xpl-side-nav-item>
+                        <xpl-side-nav-item label="Nav Item 7" icon="plug"></xpl-side-nav-item>
+                    </xpl-side-nav-section>
+
+                    <hr class="xpl-side-nav-divider" />
+
+                    <xpl-side-nav-section heading="Section Label Only" collapsible="false">
+                        <xpl-side-nav-item label="Nav Item 8" icon="headset"></xpl-side-nav-item>
+                    </xpl-side-nav-section>
+                </div>
+                </div>
+                <div class="xpl-side-nav__footer">
+                    <xpl-side-nav-item label="Settings" icon="gear"></xpl-side-nav-item>
+                    <xpl-side-nav-item label="Help" icon="headset"></xpl-side-nav-item>
+                </div>
+            </nav>
+        </div>
+    </div>
+</div>`;
+SectionsAndDividers.parameters = {
+    layout: 'fullscreen',
+    design: {
+        type: 'figma',
+        url: 'https://www.figma.com/design/MjjYek73MFnHmVNdm45Sd1/Apollo-Web?node-id=50573-8171',
+    },
+    docs: {
+        description: {
+            story: 'Composite example mirroring the Figma "Example with Sections and dividers" node (`50573-8171`): top-level items, a divider, an expanded `has-children` item, a divider, a closed `xpl-side-nav-section` with two parent items, a divider, an open section, a divider, a static label-only section, and a footer. Dividers (`<hr class="xpl-side-nav-divider">`, no dedicated component) are standalone and consumer-placed — sections do not render their own.',
+        },
+    },
+};
+export const HeaderItemPlayground = {
+    argTypes: {
+        type: {
+            control: 'select',
+            options: ['product-label', 'sub-account'],
+            description: '`product-label` is a static, non-interactive label. `sub-account` is an interactive button that emits `navigate`.',
+        },
+        label: {
+            control: 'text',
+            description: 'Display label for the header item',
+        },
+        icon: {
+            control: 'text',
+            description: 'Icon name — default content for `slot="leading"`. Leave empty to omit the leading column entirely (matches the Figma optional-icon variants).',
+        },
+        selected: {
+            control: 'boolean',
+            description: 'Selected state — only meaningful for `type="sub-account"`; applies the information-surface pill.',
+        },
+    },
+    args: {
+        type: 'product-label',
+        label: 'Product Label',
+        icon: '',
+        selected: false,
+    },
+    render: ({ type, label, icon, selected }) => {
+        const attrs = [
+            `type="${type}"`,
+            label ? `label="${escapeHtmlAttribute(label)}"` : '',
+            icon ? `icon="${escapeHtmlAttribute(icon)}"` : '',
+            type === 'sub-account' && selected ? 'selected' : '',
+        ]
+            .filter(Boolean)
+            .join(' ');
+        return `
+<style>
+    /*
+     * Standalone preview at sidebar width. Deliberately does NOT use the
+     * .xpl-side-nav host class: below the md breakpoint that class collapses to
+     * the mobile top-bar (fixed bar height, overflow, borders) and would clip /
+     * restyle this docs card. The header item's own CSS is self-contained.
+     */
+    .header-item-playground-wrapper {
+        display: flex;
+        flex-direction: column;
+        padding: var(--xpl-space-16);
+        border: var(--xpl-border-small) solid var(--xpl-border-default);
+        background-color: var(--xpl-background-surface-subtlest);
+        border-radius: var(--xpl-border-radius-default);
+        height: auto;
+        min-height: 0;
+        width: 240px;
+    }
+</style>
+<div class="header-item-playground-wrapper">
+    <xpl-side-nav-header-item ${attrs}></xpl-side-nav-header-item>
+</div>`;
+    },
+    parameters: {
+        layout: 'centered',
+        design: {
+            type: 'figma',
+            url: 'https://www.figma.com/design/MjjYek73MFnHmVNdm45Sd1/Apollo-Web?node-id=51299-9007',
+        },
+        docs: {
+            description: {
+                story: 'Interactive playground for `xpl-side-nav-header-item` (Figma `<navHeaderItem>`). `product-label` renders a static, subdued label; `sub-account` renders an interactive button that emits `navigate` and auto-renders a `chevron-expand-y` trailing icon when no `slot="trailing"` content is provided. In context it slots into `xpl-side-nav`\'s `nav-header` slot — see the full **Side Navigation** story.',
+            },
+        },
+    },
+};
+export const HeaderItemAllVariants = () => `
+<style>
+    .header-item-variants-demo {
+        display: flex;
+        flex-direction: column;
+        gap: var(--xpl-space-8);
+        padding: var(--xpl-space-16);
+        border: var(--xpl-border-small) solid var(--xpl-border-default);
+        background-color: var(--xpl-background-surface-subtlest);
+        border-radius: var(--xpl-border-radius-default);
+        height: auto;
+        min-height: 0;
+        width: 240px;
+    }
+    .header-item-variants-caption {
+        font-family: var(--xpl-font-family-default);
+        font-size: var(--xpl-font-size-caption);
+        color: var(--xpl-text-subdued);
+        margin: 0 0 var(--xpl-space-4);
+    }
+</style>
+<div class="header-item-variants-demo">
+    <p class="header-item-variants-caption">product-label</p>
+    <xpl-side-nav-header-item label="My Product"></xpl-side-nav-header-item>
+    <xpl-side-nav-header-item label="My Product" icon="house-4"></xpl-side-nav-header-item>
+
+    <p class="header-item-variants-caption">sub-account (resting)</p>
+    <xpl-side-nav-header-item type="sub-account" label="Acme Inc"></xpl-side-nav-header-item>
+    <xpl-side-nav-header-item type="sub-account" label="Acme Inc" icon="pin"></xpl-side-nav-header-item>
+    <xpl-side-nav-header-item type="sub-account" label="Xplor Growth">
+        <xpl-icon slot="trailing" icon="external-link" size="16" aria-hidden="true"></xpl-icon>
+    </xpl-side-nav-header-item>
+
+    <p class="header-item-variants-caption">sub-account (selected)</p>
+    <xpl-side-nav-header-item type="sub-account" label="Acme Inc" selected></xpl-side-nav-header-item>
+    <xpl-side-nav-header-item type="sub-account" label="Acme Inc" icon="pin" selected></xpl-side-nav-header-item>
+</div>`;
+HeaderItemAllVariants.parameters = {
+    layout: 'centered',
+    design: {
+        type: 'figma',
+        url: 'https://www.figma.com/design/MjjYek73MFnHmVNdm45Sd1/Apollo-Web?node-id=51299-9007',
+    },
+    docs: {
+        description: {
+            story: 'All `xpl-side-nav-header-item` variants side by side: `product-label` with and without a leading icon, `sub-account` resting (default auto chevron, with a leading icon, and with a custom slotted trailing icon replacing the auto chevron), and `sub-account` selected (8px-radius information-surface pill around the whole row content — leading icon, label, and trailing chevron — matching the item rows).',
+        },
+    },
+};
 export const ParentWithLeadingIcon = () => `
 <style>
     .parent-leading-demo {
@@ -542,11 +974,15 @@ ${footerHtml}
   </div>
 </div>`;
 };
-FooterSlot.parameters = Object.assign(Object.assign({}, FooterSlot.parameters), { 'web-component': {
+FooterSlot.parameters = {
+    ...FooterSlot.parameters,
+    'web-component': {
         render: FooterSlotWebComponent(FooterSlot.args),
-    }, html: {
+    },
+    html: {
         render: FooterSlotHtml(FooterSlot.args),
-    } });
+    },
+};
 const mobileItems = [
     { label: 'Dashboard', icon: 'house-4', selected: true },
     { label: 'Product', icon: 'bag-shopping-2' },