@xplortech/apollo-core 2.8.1 → 2.10.0

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

@@ -7,25 +7,26 @@ const escapeHtmlAttribute = (value) => value
 const defaultItems = [
     { label: 'Dashboard', icon: 'house-4', selected: true },
     { label: 'Product', icon: 'bag-shopping-2' },
-    { label: 'Reports', icon: 'chart-line', link: true, href: '#reports' },
+    { label: 'Reports', icon: 'chart-line' },
     { label: 'Disabled Item', icon: 'lock', disabled: true },
     { label: 'Hidden Item', icon: 'eye', hidden: true },
     {
         label: 'Settings',
+        icon: 'gear',
         hasChildren: true,
         expanded: true,
         children: [{ label: 'Location' }, { label: 'Schedule', selected: true }],
     },
     {
         label: 'Integrations',
+        icon: 'plug',
         hasChildren: true,
         children: [{ label: 'Webhooks' }, { label: 'API Keys' }],
     },
     {
-        label: 'Archived',
-        hasChildren: true,
-        disabled: true,
-        children: [{ label: 'Old Reports' }],
+        label: 'Xplor Growth',
+        icon: 'chart-line-up',
+        trailingIcon: 'external-link',
     },
 ];
 const defaultFooterItems = [
@@ -41,7 +42,7 @@ const renderNavItem = (item) => {
     var _a, _b;
     const attrs = [
         item.label ? `label="${escapeHtmlAttribute(item.label)}"` : '',
-        item.icon && !item.hasChildren ? `icon="${escapeHtmlAttribute(item.icon)}"` : '',
+        item.icon ? `icon="${escapeHtmlAttribute(item.icon)}"` : '',
         item.selected ? 'selected' : '',
         item.disabled ? 'disabled' : '',
         item.hidden ? 'hidden' : '',
@@ -52,17 +53,20 @@ const renderNavItem = (item) => {
         .filter(Boolean)
         .join(' ');
     if (item.link && item.href) {
+        const leadingIcon = item.icon
+            ? `<xpl-icon icon="${escapeHtmlAttribute(item.icon)}" size="16"></xpl-icon>`
+            : '';
         return `
     <xpl-side-nav-item ${attrs}>
-        <a href="${escapeHtmlAttribute(item.href)}">
-            ${item.icon ? `<xpl-icon icon="${escapeHtmlAttribute(item.icon)}" size="16"></xpl-icon>` : ''}
-            ${escapeHtmlAttribute(item.label)}
-        </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 trailingSlot = item.trailingIcon && !item.hasChildren
+        ? `\n        <xpl-icon slot="trailing" icon="${escapeHtmlAttribute(item.trailingIcon)}" size="16" aria-hidden="true"></xpl-icon>`
+        : '';
     return `
-    <xpl-side-nav-item ${attrs}>${childrenHtml}
+    <xpl-side-nav-item ${attrs}>${trailingSlot}${childrenHtml}
     </xpl-side-nav-item>`;
 };
 const renderHtmlNavItem = (item, depth = 0) => {
@@ -78,17 +82,23 @@ const renderHtmlNavItem = (item, depth = 0) => {
     if (item.link) {
         return `${indent}<div class="xpl-side-nav-item">
 ${indent}  <a href="${item.href || '#'}" class="${linkClass}"${item.selected ? ' aria-current="page"' : ''}${item.disabled ? ' aria-disabled="true" tabindex="-1"' : ''}>
-${indent}    <span class="xpl-side-nav-item__icon">${item.icon || ''}</span>
+${indent}    <span class="xpl-side-nav-item__leading">${item.icon ? `<xpl-icon icon="${item.icon}" size="16"></xpl-icon>` : ''}</span>
 ${indent}    <span class="xpl-side-nav-item__label">${item.label}</span>
 ${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 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
+            ? `<span class="xpl-side-nav-item__trailing"><xpl-icon icon="${item.trailingIcon}" size="16" aria-hidden="true"></xpl-icon></span>`
+            : '';
     return `${indent}<div class="xpl-side-nav-item">
 ${indent}  <button type="button" class="${linkClass}"${item.selected ? ' aria-current="page"' : ''}${hasChildren ? ` aria-expanded="${item.expanded ? 'true' : 'false'}"` : ''}${item.disabled ? ' disabled' : ''}>
-${indent}    ${hasChildren ? '<span class="xpl-side-nav-item__arrow"><!-- chevron --></span>' : `<span class="xpl-side-nav-item__icon">${item.icon || ''}</span>`}
+${indent}    <span class="xpl-side-nav-item__leading">${item.icon ? `<xpl-icon icon="${item.icon}" size="16"></xpl-icon>` : ''}</span>
 ${indent}    <span class="xpl-side-nav-item__label">${item.label}</span>
+${indent}    ${trailingHtml}
 ${indent}  </button>${hasChildren && !item.link
         ? `
 ${indent}  <div class="xpl-side-nav-item__children ${item.expanded ? 'expanded' : ''}">
@@ -128,30 +138,65 @@ const SideNavigationWebComponent = (config) => {
     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>`;
 };
-export const SideNavigation = ({ navConfig }) => {
-    const { navLabel, items, footerItems } = navConfig;
-    const itemsHtml = items.map(renderNavItem).join('');
-    const footerHtml = footerItems.map(renderNavItem).join('');
-    return `
+let sideNavClickController;
+export const SideNavigation = {
+    args: {
+        navConfig: Object.assign({}, defaultNavConfig),
+    },
+    argTypes: {
+        navConfig: {
+            control: 'object',
+            description: 'Full sidebar config (router-style): `navLabel`, `items[]`, `footerItems[]`. Arrays map to `xpl-side-nav-item` markup.',
+        },
+    },
+    render: ({ navConfig }) => {
+        const { navLabel, items, footerItems } = navConfig;
+        const itemsHtml = items.map(renderNavItem).join('');
+        const footerHtml = footerItems.map(renderNavItem).join('');
+        return `
 <style>
     .side-nav-demo-wrapper {
-        height: 600px;
         display: flex;
+        height: 600px;
         background-color: var(--xpl-background-surface-subtle);
         border: var(--xpl-border-small) solid var(--xpl-border-default);
     }
+    /* Above md: nav is a fixed-width column; main fills the rest of the row. */
+    @media (min-width: 768px) {
+        .side-nav-demo-wrapper {
+            flex-direction: row;
+        }
+        .side-nav-demo-main {
+            flex: 1;
+        }
+    }
+    /* Below md: nav collapses to a top bar; main flows beneath it. */
+    @media (max-width: 767px) {
+        .side-nav-demo-wrapper {
+            flex-direction: column;
+        }
+    }
     .side-nav-demo-main {
-        flex: 1;
         padding: var(--xpl-space-32);
+        font-family: var(--xpl-font-family-default);
         color: var(--xpl-text-default);
     }
     .side-nav-demo-main h1 { margin: 0; }
+    .side-nav-demo-note {
+        font-family: var(--xpl-font-family-default);
+        font-size: var(--xpl-font-size-callout);
+        color: var(--xpl-text-subdued);
+        margin: var(--xpl-space-8) 0 0;
+        line-height: 1.5;
+    }
     .side-nav-demo-legend {
         margin-top: var(--xpl-space-24);
         padding: var(--xpl-space-16);
         border-radius: var(--xpl-border-radius-default);
         background: var(--xpl-background-surface-transparent-5);
+        font-family: var(--xpl-font-family-default);
         font-size: var(--xpl-font-size-callout);
+        color: var(--xpl-text-subdued);
         line-height: 1.8;
     }
     .side-nav-demo-legend code {
@@ -171,48 +216,63 @@ export const SideNavigation = ({ navConfig }) => {
 
     <div class="side-nav-demo-main">
         <h1>Side Navigation Demo</h1>
-        <p>Data-driven navigation: edit the <code>navConfig</code> object in Controls (same shape you would build from router metadata — <code>navLabel</code>, <code>items[]</code>, <code>footerItems[]</code>) and map it to markup with <code>renderNavItem</code>-style helpers in your app.</p>
+        <p class="side-nav-demo-note">Click any item in the nav to select it. Parent items expand and collapse on click.</p>
         <div class="side-nav-demo-legend">
-            <strong><code>NavDemoConfig</code></strong><br/>
-            <code>{ navLabel, items: NavItem[], footerItems: NavItem[] }</code>
+            <strong>v2 anatomy per row:</strong><br/>
+            <code>slot="leading"</code> — leading icon (or <code>icon</code> prop)<br/>
+            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><code>NavItem</code></strong><br/>
-            <code>{ label, icon?, selected?, disabled?, hidden?, hasChildren?, expanded?, link?, href?, children? }</code>
+            <code>{ label, icon?, trailingIcon?, selected?, disabled?, hidden?, hasChildren?, expanded?, link?, href?, children? }</code>
         </div>
         <div class="side-nav-demo-legend">
-            <strong>Slots:</strong><br/>
-            <code>slot="section"</code> — main navigation items<br/>
-            <code>slot="nav-footer"</code> — footer items
+            <strong>Responsive (below <code>md</code> / 768 px):</strong><br/>
+            The sidebar collapses to a ~56 px top bar with a built-in toggle button.<br/>
+            Activating the toggle opens an 80 vw drawer (min 300 px) that slides in from the left — the remaining 20 vw shows a backdrop scrim.<br/>
+            <strong>Closing:</strong> toggle button, <code>Escape</code> key, or backdrop click — all return focus to the toggle.<br/>
+            <strong>Focus trap:</strong> <code>Tab</code> cycles within the open drawer.<br/>
+            <strong>API:</strong> <code>open</code> prop/attr (reflected) · <code>openChange</code> event · <code>toggle()</code> / <code>setOpen()</code> methods
         </div>
     </div>
 </div>`;
-};
-SideNavigation.args = {
-    navConfig: Object.assign({}, defaultNavConfig),
-};
-SideNavigation.argTypes = {
-    navConfig: {
-        control: 'object',
-        description: 'Full sidebar config (router-style): `navLabel`, `items[]`, `footerItems[]`. Arrays map to `xpl-side-nav-item` markup.',
     },
-};
-SideNavigation.parameters = {
-    layout: 'fullscreen',
-    design: {
-        type: 'figma',
-        url: 'https://www.figma.com/design/MjjYek73MFnHmVNdm45Sd1/Apollo-Web?node-id=33873-23128&m=dev',
+    play: async ({ canvasElement }) => {
+        sideNavClickController === null || sideNavClickController === void 0 ? void 0 : sideNavClickController.abort();
+        sideNavClickController = new AbortController();
+        const nav = canvasElement.querySelector('xpl-side-nav');
+        if (!nav)
+            return;
+        nav.addEventListener('click', (e) => {
+            const item = e.target.closest('xpl-side-nav-item');
+            if (!item)
+                return;
+            if (item.hasAttribute('disabled'))
+                return;
+            if (item.hasAttribute('has-children'))
+                return;
+            nav.querySelectorAll('xpl-side-nav-item').forEach((el) => el.removeAttribute('selected'));
+            item.setAttribute('selected', '');
+        }, { signal: sideNavClickController.signal });
     },
-    docs: {
-        description: {
-            story: 'Full navigation demo: typed `navConfig` object control maps array data to `xpl-side-nav` / `xpl-side-nav-item` markup — same pattern as mapping router config to nav in production.',
+    parameters: {
+        layout: 'fullscreen',
+        design: {
+            type: 'figma',
+            url: 'https://www.figma.com/design/MjjYek73MFnHmVNdm45Sd1/Apollo-Web?node-id=33873-23128&m=dev',
+        },
+        docs: {
+            description: {
+                story: 'Fully interactive navigation demo. Click leaf items to select them; click parent items to expand/collapse. Edit the `navConfig` control to add, remove, or reconfigure items — same data-driven pattern as mapping router config to nav in production.',
+            },
+        },
+        'web-component': {
+            render: SideNavigationWebComponent(defaultNavConfig),
+        },
+        html: {
+            render: renderHtmlSideNav(defaultNavConfig),
         },
-    },
-    'web-component': {
-        render: SideNavigationWebComponent(SideNavigation.args.navConfig),
-    },
-    html: {
-        render: renderHtmlSideNav(SideNavigation.args.navConfig),
     },
 };
 export const ItemPlayground = {
@@ -223,7 +283,11 @@ export const ItemPlayground = {
         },
         icon: {
             control: 'text',
-            description: 'Icon name (leaf/footer rows only; ignored when hasChildren — expandable rows use chevron only)',
+            description: 'Icon name — default content for `slot="leading"`. Applies to all item types including parents (`has-children`) in v2.',
+        },
+        trailingIcon: {
+            control: 'text',
+            description: 'Icon name for `slot="trailing"`. On parent items (`has-children`), providing this replaces the auto chevron (`chevron-down` collapsed / `chevron-up` expanded).',
         },
         selected: {
             control: 'boolean',
@@ -261,6 +325,7 @@ export const ItemPlayground = {
     args: {
         label: 'Playground Item',
         icon: 'house-4',
+        trailingIcon: '',
         selected: false,
         disabled: false,
         hidden: false,
@@ -270,42 +335,48 @@ export const ItemPlayground = {
         childLabel1: 'Child Item A',
         childLabel2: 'Child Item B',
     },
-    render: ({ label, icon, selected, disabled, hidden, expanded, hasChildren, link, childLabel1, childLabel2, }) => {
+    render: ({ label, icon, trailingIcon, selected, disabled, hidden, expanded, hasChildren, link, childLabel1, childLabel2, }) => {
         const attrs = [
             label ? `label="${label}"` : '',
-            icon && !hasChildren ? `icon="${icon}"` : '',
+            icon ? `icon="${icon}"` : '',
             selected ? 'selected' : '',
             disabled ? 'disabled' : '',
             hidden ? 'hidden' : '',
             expanded ? 'expanded' : '',
-            hasChildren ? 'has-children' : '',
+            !link && hasChildren ? 'has-children' : '',
             link ? 'link' : '',
         ]
             .filter(Boolean)
             .join(' ');
         let content = '';
+        const trailingSlot = trailingIcon && !link
+            ? `\n        <xpl-icon slot="trailing" icon="${trailingIcon}" size="16" aria-hidden="true"></xpl-icon>`
+            : '';
         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'}">
-            ${icon ? `<xpl-icon icon="${icon}" size="16"></xpl-icon>` : ''}
-            ${label}
-        </a>`;
+        <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>`;
         }
         else if (hasChildren) {
-            content = `
-        <xpl-side-nav-item label="${childLabel1}" ></xpl-side-nav-item>
-        <xpl-side-nav-item label="${childLabel2}" ></xpl-side-nav-item>`;
+            content = `${trailingSlot}
+        <xpl-side-nav-item label="${childLabel1}" icon="circle-dot"></xpl-side-nav-item>
+        <xpl-side-nav-item label="${childLabel2}" icon="circle-dot"></xpl-side-nav-item>`;
+        }
+        else {
+            content = trailingSlot;
         }
         return `
 <style>
     .item-playground-wrapper {
-        width: 280px;
         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;
     }
     .item-playground-note {
+        font-family: var(--xpl-font-family-default);
         font-size: var(--xpl-font-size-caption);
         color: var(--xpl-text-subdued);
         margin-top: var(--xpl-space-12);
@@ -317,7 +388,7 @@ export const ItemPlayground = {
     </xpl-side-nav-item>
 </div>
 <p class="item-playground-note">
-    Interactive playground for <code>xpl-side-nav-item</code>. Toggle props in the Controls panel to see state changes in real-time.
+    Interactive playground for <code>xpl-side-nav-item</code>. Toggle props in the Controls panel.
 </p>`;
     },
     parameters: {
@@ -329,96 +400,76 @@ export const ItemPlayground = {
         },
     },
 };
-const ItemPlaygroundWebComponent = (args) => {
-    var _a;
-    const attrs = [
-        args.label ? `label="${args.label}"` : '',
-        args.icon && !args.hasChildren ? `icon="${args.icon}"` : '',
-        args.selected ? 'selected' : '',
-        args.disabled ? 'disabled' : '',
-        args.hidden ? 'hidden' : '',
-        args.expanded ? 'expanded' : '',
-        args.hasChildren ? 'has-children' : '',
-        args.link ? 'link' : '',
-    ]
-        .filter(Boolean)
-        .join(' ');
-    let content = '';
-    if (args.link) {
-        content = `
-        <a href="#${((_a = args.label) === null || _a === void 0 ? void 0 : _a.toLowerCase().replace(/\s+/g, '-')) || 'item'}">
-            ${args.icon ? `<xpl-icon icon="${args.icon}" size="16"></xpl-icon>` : ''}
-            ${args.label}
-        </a>`;
-    }
-    else if (args.hasChildren) {
-        content = `
-        <xpl-side-nav-item label="${args.childLabel1}"></xpl-side-nav-item>
-        <xpl-side-nav-item label="${args.childLabel2}"></xpl-side-nav-item>`;
-    }
-    return `
+export const ExternalLinkItem = () => `
 <style>
-    .item-playground-wrapper {
-        width: 280px;
+    .external-link-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;
+    }
+    .external-link-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>
-<div class="xpl-side-nav item-playground-wrapper">
-    <xpl-side-nav-item ${attrs}>${content}
+<p class="external-link-caption">Leaf item with leading icon + trailing external-link icon</p>
+<div class="xpl-side-nav external-link-demo">
+    <xpl-side-nav-item label="Xplor Growth" icon="chart-line-up">
+        <xpl-icon slot="trailing" icon="external-link" size="16" aria-hidden="true"></xpl-icon>
     </xpl-side-nav-item>
+    <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>
 </div>`;
+ExternalLinkItem.parameters = {
+    layout: 'centered',
+    docs: {
+        description: {
+            story: 'Leaf item with a leading icon (`icon` prop) and a trailing `slot="trailing"` icon (`external-link`). The trailing slot replaces the auto chevron on parents, or adds a trailing icon to leaf items. Note: trailing icons that convey meaning (e.g. external link) should be accompanied by accessible labeling in the surrounding context.',
+        },
+    },
 };
-const renderHtmlItemPlayground = (args) => {
-    const { label = 'Item', selected = false, disabled = false, hasChildren = false, expanded = false, link = false, childLabel1 = 'Child A', childLabel2 = 'Child B', } = args;
-    const linkClass = [
-        'xpl-side-nav-item__link',
-        selected ? 'selected' : '',
-        expanded ? 'expanded' : '',
-    ]
-        .filter(Boolean)
-        .join(' ');
-    if (link) {
-        return `<div class="xpl-side-nav-item">
-  <a href="#item" class="${linkClass}"${selected ? ' aria-current="page"' : ''}${disabled ? ' aria-disabled="true" tabindex="-1"' : ''}>
-    <span class="xpl-side-nav-item__icon"><!-- icon --></span>
-    <span class="xpl-side-nav-item__label">${label}</span>
-  </a>
-</div>`;
+export const ParentWithLeadingIcon = () => `
+<style>
+    .parent-leading-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;
     }
-    const childrenContent = hasChildren
-        ? `
-  <div class="xpl-side-nav-item__children ${expanded ? 'expanded' : ''}">
-    <div class="xpl-side-nav-item__children-inner">
-      <div class="xpl-side-nav-item">
-        <button type="button" class="xpl-side-nav-item__link">
-          <span class="xpl-side-nav-item__icon"><!-- icon --></span>
-          <span class="xpl-side-nav-item__label">${childLabel1}</span>
-        </button>
-      </div>
-      <div class="xpl-side-nav-item">
-        <button type="button" class="xpl-side-nav-item__link">
-          <span class="xpl-side-nav-item__icon"><!-- icon --></span>
-          <span class="xpl-side-nav-item__label">${childLabel2}</span>
-        </button>
-      </div>
-    </div>
-  </div>`
-        : '';
-    return `<div class="xpl-side-nav-item">
-  <button type="button" class="${linkClass}"${selected ? ' aria-current="page"' : ''}${hasChildren ? ` aria-expanded="${expanded ? 'true' : 'false'}"` : ''}${disabled ? ' disabled' : ''}>
-    ${hasChildren ? '<span class="xpl-side-nav-item__arrow"><!-- chevron --></span>' : '<span class="xpl-side-nav-item__icon"><!-- icon --></span>'}
-    <span class="xpl-side-nav-item__label">${label}</span>
-  </button>${childrenContent}
+    .parent-leading-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="parent-leading-caption">Parents now show leading icon AND chevron (v2 behavior)</p>
+<div class="xpl-side-nav parent-leading-demo">
+    <xpl-side-nav-item label="Settings" icon="gear" has-children expanded>
+        <xpl-side-nav-item label="Location"></xpl-side-nav-item>
+        <xpl-side-nav-item label="Schedule" selected></xpl-side-nav-item>
+    </xpl-side-nav-item>
+    <xpl-side-nav-item label="Integrations" icon="plug" has-children>
+        <xpl-side-nav-item label="Webhooks"></xpl-side-nav-item>
+        <xpl-side-nav-item label="API Keys"></xpl-side-nav-item>
+    </xpl-side-nav-item>
+    <xpl-side-nav-item label="Dashboard" icon="house-4" selected></xpl-side-nav-item>
 </div>`;
+ParentWithLeadingIcon.parameters = {
+    layout: 'centered',
+    docs: {
+        description: {
+            story: '**v2 behavior change:** parent rows (`has-children`) now render the leading icon alongside the auto chevron in the trailing position (`chevron-down` when collapsed, `chevron-up` when expanded). In v1, parents showed chevron + label only (no leading icon). Pass `icon` prop or `slot="leading"` content to set the leading icon.',
+        },
+    },
 };
-ItemPlayground.parameters = Object.assign(Object.assign({}, ItemPlayground.parameters), { 'web-component': {
-        render: ItemPlaygroundWebComponent(ItemPlayground.args),
-    }, html: {
-        render: renderHtmlItemPlayground(ItemPlayground.args),
-    } });
 export const FooterSlot = {
     argTypes: {
         footerItems: {
@@ -430,85 +481,64 @@ export const FooterSlot = {
         footerItems: [
             { label: 'Settings', icon: 'gear' },
             { label: 'Help', icon: 'headset' },
-            { label: 'Logout', icon: 'open-rect-arrow-out', disabled: false },
+            { label: 'Logout', icon: 'open-rect-arrow-out' },
         ],
     },
     render: ({ footerItems }) => {
         const footerHtml = footerItems.map(renderNavItem).join('');
         return `
 <style>
-    .footer-demo-wrapper {
-        width: 280px;
-        padding: var(--xpl-space-16);
+    /*
+     * Focused preview of the nav-footer slot only. Renders the static
+     * .xpl-side-nav__footer markup at sidebar width so the footer styling
+     * (top divider, padding) is shown in isolation -- no host xpl-side-nav
+     * wrapper, so no mobile top-bar collapse intrudes on the docs view.
+     */
+    /*
+     * Override the .xpl-side-nav host defaults (height: 100%, overflow: hidden)
+     * so the demo card shrink-wraps its content vertically and never crops.
+     */
+    .footer-demo-container {
+        display: inline-flex;
+        flex-direction: column;
+        height: auto;
+        background: var(--xpl-background-surface-subtlest);
         border: var(--xpl-border-small) solid var(--xpl-border-default);
-        background-color: var(--xpl-background-surface-subtlest);
         border-radius: var(--xpl-border-radius-default);
+        overflow: visible;
     }
     .footer-demo-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>
-<div class="footer-demo-caption">Nav Footer Slot</div>
-<xpl-side-nav class="footer-demo-wrapper">
-    <div slot="section">
-        <xpl-side-nav-item label="Dashboard" icon="house-4" selected></xpl-side-nav-item>
+<p class="footer-demo-caption">Nav Footer Slot</p>
+<div class="xpl-side-nav footer-demo-container">
+    <div class="xpl-side-nav__footer">${footerHtml}
     </div>
-    <div slot="nav-footer">${footerHtml}
-    </div>
-</xpl-side-nav>`;
+</div>`;
     },
     parameters: {
         layout: 'centered',
         design: {
             type: 'figma',
-            url: 'https://www.figma.com/design/MjjYek73MFnHmVNdm45Sd1/Apollo-Web',
+            url: 'https://www.figma.com/design/MjjYek73MFnHmVNdm45Sd1/Apollo-Web?node-id=24425-16384',
         },
     },
 };
 const FooterSlotWebComponent = (args) => {
     const footerHtml = args.footerItems.map(renderNavItem).join('');
-    return `
-<style>
-    .footer-demo-wrapper {
-        width: 280px;
-        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);
-    }
-    .footer-demo-caption {
-        font-size: var(--xpl-font-size-caption);
-        color: var(--xpl-text-subdued);
-        margin-bottom: var(--xpl-space-8);
-    }
-</style>
-<div class="footer-demo-caption">Nav Footer Slot</div>
-<xpl-side-nav class="footer-demo-wrapper">
-    <div slot="section">
-        <xpl-side-nav-item label="Dashboard" icon="house-4" selected></xpl-side-nav-item>
-    </div>
+    return `<xpl-side-nav>
     <div slot="nav-footer">${footerHtml}</div>
 </xpl-side-nav>`;
 };
 const FooterSlotHtml = (args) => {
     const footerHtml = args.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">
-      <div class="xpl-side-nav__section">
-        <div class="xpl-side-nav-item">
-          <button type="button" class="xpl-side-nav-item__link selected" aria-current="page">
-            <span class="xpl-side-nav-item__icon"><!-- icon --></span>
-            <span class="xpl-side-nav-item__label">Dashboard</span>
-          </button>
-        </div>
-      </div>
-      <div class="xpl-side-nav__footer">
+  <div class="xpl-side-nav__footer">
 ${footerHtml}
-      </div>
-    </nav>
   </div>
 </div>`;
 };
@@ -517,3 +547,88 @@ FooterSlot.parameters = Object.assign(Object.assign({}, FooterSlot.parameters),
     }, html: {
         render: FooterSlotHtml(FooterSlot.args),
     } });
+const mobileItems = [
+    { label: 'Dashboard', icon: 'house-4', selected: true },
+    { label: 'Product', icon: 'bag-shopping-2' },
+    {
+        label: 'Settings',
+        icon: 'gear-3',
+        hasChildren: true,
+        children: [{ label: 'Location' }, { label: 'Schedule' }],
+    },
+    { label: 'Xplor Growth', icon: 'chart-line-up', trailingIcon: 'external-link' },
+];
+const mobileFooterItems = [
+    { label: 'Support', icon: 'headset' },
+    { label: 'Logout', icon: 'open-rect-arrow-out' },
+];
+const renderMobileSideNav = (open) => {
+    const itemsHtml = mobileItems.map(renderNavItem).join('');
+    const footerHtml = mobileFooterItems.map(renderNavItem).join('');
+    return `
+<style>
+    .side-nav-mobile-root {
+        position: relative;
+        width: 100%;
+        height: 100vh;
+        overflow: hidden;
+        background: var(--xpl-background-surface-subtle);
+    }
+    /* Force the mobile bar layout regardless of Storybook viewport width. */
+    .side-nav-mobile-root .xpl-side-nav {
+        width: 100%;
+        height: var(--xpl-size-350);
+        min-height: var(--xpl-size-350);
+        padding: var(--xpl-space-8) var(--xpl-space-16);
+        border-right: var(--xpl-border-none);
+        border-bottom: var(--xpl-border-small) solid var(--xpl-border-default);
+    }
+    .side-nav-mobile-root .xpl-side-nav__toggle {
+        display: flex;
+        width: var(--xpl-size-250);
+        height: var(--xpl-size-250);
+    }
+    /* Page content placeholder fills the remaining height behind the closed bar. */
+    .side-nav-mobile-page {
+        padding: var(--xpl-space-24) var(--xpl-space-16);
+        font-family: var(--xpl-font-family-default);
+        font-size: var(--xpl-font-size-body);
+        color: var(--xpl-text-subdued);
+    }
+</style>
+<div class="side-nav-mobile-root">
+    <xpl-side-nav label="Main navigation"${open ? ' open' : ''}>
+        <div slot="section">${itemsHtml}</div>
+        <div slot="nav-footer">${footerHtml}</div>
+    </xpl-side-nav>
+    <div class="side-nav-mobile-page">
+        ${open ? 'Drawer open — the 80 vw drawer slides over this content; the 20 vw backdrop scrim is visible on the right. Press Escape or tap the backdrop to close.' : 'Tap the toggle in the bar above to open the drawer.'}
+    </div>
+</div>`;
+};
+export const MobileClosed = () => renderMobileSideNav(false);
+MobileClosed.parameters = {
+    layout: 'fullscreen',
+    design: {
+        type: 'figma',
+        url: 'https://www.figma.com/design/MjjYek73MFnHmVNdm45Sd1/Apollo-Web?node-id=48928-8582',
+    },
+    docs: {
+        description: {
+            story: 'Mobile closed state (full viewport). Below the `md` breakpoint the sidebar collapses to a ~56 px top bar with a `sidebar-left-show` toggle. Resize the Storybook canvas below 768 px, or use the "Mobile" viewport preset, to see the responsive layout.',
+        },
+    },
+};
+export const MobileOpen = () => renderMobileSideNav(true);
+MobileOpen.parameters = {
+    layout: 'fullscreen',
+    design: {
+        type: 'figma',
+        url: 'https://www.figma.com/design/MjjYek73MFnHmVNdm45Sd1/Apollo-Web?node-id=48928-8581',
+    },
+    docs: {
+        description: {
+            story: 'Mobile open state (`open` attribute, full viewport). The 80 vw drawer slides in from the left; the remaining 20 vw shows the `xpl-backdrop` scrim. Escape or a backdrop click closes the drawer and returns focus to the toggle.',
+        },
+    },
+};