@brandsync/wc 0.0.11 → 0.1.0

package/dist/collection/components/ui-shell/bs-navigation-drawer/bs-navigation-drawer/bs-navigation-drawer.js

@@ -0,0 +1,281 @@
+import { h } from "@stencil/core";
+/**
+ * A left-side persistent navigation sidebar: the BrandSync logo, a "Main Menu" title with a
+ * collapse toggle, a reserved slot for a search field, and a scrollable list of nav items.
+ *
+ * ## When to use
+ * - The primary in-app navigation, shown alongside `bs-navigation-header` (typically that
+ *   header's `with-navigation-drawer` alignment, which omits its own logo since this component
+ *   already renders one -- or the reverse pairing, this drawer's own `showLogo={false}` alongside
+ *   a header that keeps its logo instead, see that prop's own docs).
+ *
+ * ## When not to use
+ * - The top navigation bar itself -- use `bs-navigation-header` instead.
+ *
+ * This component renders a real `<nav>` landmark (no explicit `role` needed -- `<nav>` already
+ * carries the implicit `navigation` role), labeled via `aria-label={heading}` so the landmark
+ * still has a name even when collapsed (see below).
+ *
+ * `collapsed` narrows the drawer to a 96px icon-only rail, per Figma node 8028:135374
+ * ("Type=Collapsed"): the title text disappears, the logo swaps from the full "EG BrandSync"
+ * wordmark (`bs-logo variant="full"`) to the real icon-only mark (`bs-logo variant="mark"` -- a
+ * second, properly-designed asset, not a CSS crop of the full one) via CSS visibility toggling on
+ * both, the same `:host([collapsed])` attribute-selector pattern already used for the
+ * `search`/`search-trigger` swap below, the `search` slot is replaced by a compact built-in
+ * search-trigger button (this component can't meaningfully shrink arbitrary slotted search-field
+ * content down to icon size itself, so it emits `bsSearchClick` instead -- e.g. to open a full
+ * search overlay), and every top-level
+ * `bs-navigation-drawer-item`'s layout switches from icon-beside-label to icon-above-caption.
+ * That last part is real prop propagation, not a CSS trick: this component keeps each direct-child
+ * item's own `collapsed` prop in sync with its own (see `syncItemsCollapsed` below), the same
+ * direct-children-prop-sync approach `bs-tabs` already uses for coordinating `selected` across its
+ * `bs-tab` children. Clicking the toggle self-toggles `collapsed` (simple local UI state, not
+ * something needing cross-component coordination -- closer to `bs-switch`'s self-toggling
+ * `checked` than `bs-tab`'s non-self-toggling `selected`) and emits `bsCollapse` with the new
+ * value. The toggle's own caret icon does NOT rotate when collapsed -- Figma's collapsed mock
+ * reuses the identical left-pointing "CaretLeft" asset unchanged, confirmed by directly inspecting
+ * that state, so this deliberately does not add the same "flip on toggle" idiom the drawer item's
+ * own disclosure chevron does (that one really is an unconfirmed addition; this one was checked).
+ *
+ * @slot search - Reserved for a search field, e.g. a `bs-input type="search"`. This component
+ *   does not build one itself. Hidden while `collapsed` (see above).
+ * @slot - Default slot: the scrollable list of nav items, typically one or more
+ *   `bs-navigation-drawer-item` elements.
+ * @part logo - The wrapper around the BrandSync brand mark. Two of these exist in the shadow DOM
+ *   at once while `showLogo` is `true` (one wrapping a `bs-logo variant="full"`, one wrapping a
+ *   `bs-logo variant="mark"`), both carrying this same part name (the same "multiple elements, one
+ *   shared part name" approach `bs-attachment`'s `star` part uses) -- only one is visible at a
+ *   time, toggled by plain CSS on `collapsed` (see above), so `::part(logo)` always reaches
+ *   whichever is showing. Neither renders at all while `showLogo` is `false`.
+ * @part title - The "Main Menu" heading text wrapper.
+ * @part collapse - The collapse toggle button.
+ * @part search - The wrapper around the `search` slot.
+ * @part search-trigger - The compact search button shown instead of the `search` slot while `collapsed`.
+ * @part items - The wrapper around the default (items) slot.
+ */
+// Note: this component's CSS Custom Properties are documented via @prop comments in
+// bs-navigation-drawer.css, not here -- see bs-navigation-header.css's identical note.
+export class BsNavigationDrawer {
+    el;
+    /** Heading text shown next to the collapse toggle, and used as the `<nav>` landmark's
+     * `aria-label` (so the landmark keeps a name even when `collapsed` hides the visible text). */
+    heading = 'Main Menu';
+    /** Whether this drawer can be collapsed at all. `false` renders no collapse toggle/chevron --
+     * a "fixed" side nav (Carbon's terminology: a `Fixed Side Nav` never collapses, as opposed to a
+     * rail-capable one) that's always fully expanded. `collapsed` is ignored while this is `false`. */
+    collapsible = true;
+    /** Narrows the drawer to a 96px icon-only rail (Figma node 8028:135374). Mutable and reflected
+     * -- clicking the collapse toggle toggles this directly (self-toggling, see the class doc above
+     * for why), and this component keeps every direct-child `bs-navigation-drawer-item`'s own
+     * `collapsed` prop synced to match (see `syncItemsCollapsed`). */
+    collapsed = false;
+    /** Fires with the new `collapsed` value when the collapse toggle button is clicked. */
+    bsCollapse;
+    /** Fires when the compact search-trigger button (shown instead of the `search` slot while
+     * `collapsed`) is clicked -- e.g. to open a full search overlay. This component has no
+     * visibility into what the `search` slot actually contains, so it can't drive a real search
+     * itself once shrunk to icon size. */
+    bsSearchClick;
+    /** Forwarded straight to both internal `bs-logo` elements' own `background` prop. Defaults to
+     * `"auto"`, which follows the ambient `[data-theme="dark"]` state automatically (see `bs-logo`'s
+     * own docs) -- so if this drawer ends up on a dark surface via the normal theming mechanism, the
+     * logo switches to its dedicated dark-background asset with no wiring needed. Set
+     * `"light"`/`"dark"` explicitly only if you've overridden `--bs-navigation-drawer-bg` to
+     * something dark yourself *without* setting `[data-theme="dark"]`, and need to pin the logo
+     * regardless of theme. Has no visible effect on the `variant="mark"` logo shown while
+     * `collapsed` (see `bs-logo`'s own docs -- there's only one real designed mark asset, it's
+     * background-agnostic). */
+    logoBackground = 'auto';
+    /** Whether to render the BrandSync logo at all. Defaults to `true`. This drawer is normally the
+     * one that owns the logo when paired with a `bs-navigation-header` (that header's own
+     * `with-navigation-drawer` alignment omits its logo for exactly this reason) -- but the reverse
+     * pairing works too: a header that keeps its own logo (`alignment="default"`) paired with this
+     * drawer set to `showLogo={false}`, so the brand mark only ever appears once. */
+    showLogo = true;
+    onCollapsedChange(collapsed) {
+        this.syncItemsCollapsed(collapsed);
+    }
+    componentDidLoad() {
+        this.syncItemsCollapsed(this.collapsed);
+    }
+    /** Keeps every direct-child `bs-navigation-drawer-item`'s `collapsed` prop in sync with this
+     * component's own -- same direct-children-prop-sync approach `bs-tabs` uses for `selected`
+     * across its `bs-tab` children. Only direct children (top-level items): Figma's collapsed rail
+     * never shows nested/expanded children in the first place (see bs-navigation-drawer-item.css's
+     * `:host([collapsed])` rule forcing those hidden), so there's nothing to sync on them. */
+    syncItemsCollapsed(collapsed) {
+        const items = this.el.querySelectorAll(':scope > bs-navigation-drawer-item');
+        items.forEach(item => {
+            item.collapsed = collapsed;
+        });
+    }
+    onCollapseClick = () => {
+        this.collapsed = !this.collapsed;
+        this.bsCollapse.emit(this.collapsed);
+    };
+    onSearchTriggerClick = () => {
+        this.bsSearchClick.emit();
+    };
+    render() {
+        return (h("nav", { key: '0b6979dbab9e8b0bfcd1a4bdceead7b87c8d2b88', class: "bs-navigation-drawer", "aria-label": this.heading }, this.showLogo && (h("div", { key: 'f7b4b0238118d95f48a60da815738673db41da9f', part: "logo", class: "bs-navigation-drawer__logo bs-navigation-drawer__logo--full" }, h("bs-logo", { key: '9d40a85424f2931b251eb1e90991f3fa6b6eaccf', variant: "full", background: this.logoBackground }))), this.showLogo && (h("div", { key: '77250a1f5f66e7fcd981bfd6494ee38722a7406f', part: "logo", class: "bs-navigation-drawer__logo bs-navigation-drawer__logo--mark" }, h("bs-logo", { key: '0365624f3796b1c44af10488e8a3cab93e296169', variant: "mark", background: this.logoBackground }))), h("div", { key: '4c5b0de2a90df7f6462fac6d6b79abb62829293e', class: "bs-navigation-drawer__title-row" }, h("span", { key: 'f9507d3c31687abcaa99340ca4e413f8d47559bc', part: "title", class: "bs-navigation-drawer__title" }, this.heading), this.collapsible && (h("button", { key: 'f07c9f1f04d0b3e745273d8f61b3c1af02a5bc08', type: "button", part: "collapse", class: "bs-navigation-drawer__collapse", "aria-label": this.collapsed ? 'Expand' : 'Collapse', "aria-pressed": this.collapsed ? 'true' : 'false', onClick: this.onCollapseClick }, h(CaretLeftIcon, { key: '9731cf6bd727b753c99b5969059997a6800ec3a4' })))), h("div", { key: '7b1cc15eb095988451c32e4ba429fa5f36a5bbb8', part: "search", class: "bs-navigation-drawer__search" }, h("slot", { key: '1cf0fa19d789ea44ef29a9a3fbc7852ea012045e', name: "search" })), h("button", { key: '9a7c7bf69a7ef92144e60641279fbaca47395d4f', type: "button", part: "search-trigger", class: "bs-navigation-drawer__search-trigger", "aria-label": "Search", onClick: this.onSearchTriggerClick }, h(SearchIcon, { key: '6c55207e0b45a07c2be7aa350c07bbab4018696b' })), h("div", { key: 'e22497a133d16a622ef68ff5de4796eaa96a25fb', part: "items", class: "bs-navigation-drawer__items" }, h("slot", { key: '465d9447ef355558ffd0d79306abd9a9204517a1' }))));
+    }
+    static get is() { return "bs-navigation-drawer"; }
+    static get encapsulation() { return "shadow"; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["bs-navigation-drawer.css"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["bs-navigation-drawer.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "heading": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Heading text shown next to the collapse toggle, and used as the `<nav>` landmark's\n`aria-label` (so the landmark keeps a name even when `collapsed` hides the visible text)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "heading",
+                "defaultValue": "'Main Menu'"
+            },
+            "collapsible": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Whether this drawer can be collapsed at all. `false` renders no collapse toggle/chevron --\na \"fixed\" side nav (Carbon's terminology: a `Fixed Side Nav` never collapses, as opposed to a\nrail-capable one) that's always fully expanded. `collapsed` is ignored while this is `false`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "collapsible",
+                "defaultValue": "true"
+            },
+            "collapsed": {
+                "type": "boolean",
+                "mutable": true,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Narrows the drawer to a 96px icon-only rail (Figma node 8028:135374). Mutable and reflected\n-- clicking the collapse toggle toggles this directly (self-toggling, see the class doc above\nfor why), and this component keeps every direct-child `bs-navigation-drawer-item`'s own\n`collapsed` prop synced to match (see `syncItemsCollapsed`)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "collapsed",
+                "defaultValue": "false"
+            },
+            "logoBackground": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'auto' | 'light' | 'dark'",
+                    "resolved": "\"auto\" | \"dark\" | \"light\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Forwarded straight to both internal `bs-logo` elements' own `background` prop. Defaults to\n`\"auto\"`, which follows the ambient `[data-theme=\"dark\"]` state automatically (see `bs-logo`'s\nown docs) -- so if this drawer ends up on a dark surface via the normal theming mechanism, the\nlogo switches to its dedicated dark-background asset with no wiring needed. Set\n`\"light\"`/`\"dark\"` explicitly only if you've overridden `--bs-navigation-drawer-bg` to\nsomething dark yourself *without* setting `[data-theme=\"dark\"]`, and need to pin the logo\nregardless of theme. Has no visible effect on the `variant=\"mark\"` logo shown while\n`collapsed` (see `bs-logo`'s own docs -- there's only one real designed mark asset, it's\nbackground-agnostic)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "logo-background",
+                "defaultValue": "'auto'"
+            },
+            "showLogo": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Whether to render the BrandSync logo at all. Defaults to `true`. This drawer is normally the\none that owns the logo when paired with a `bs-navigation-header` (that header's own\n`with-navigation-drawer` alignment omits its logo for exactly this reason) -- but the reverse\npairing works too: a header that keeps its own logo (`alignment=\"default\"`) paired with this\ndrawer set to `showLogo={false}`, so the brand mark only ever appears once."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "show-logo",
+                "defaultValue": "true"
+            }
+        };
+    }
+    static get events() {
+        return [{
+                "method": "bsCollapse",
+                "name": "bsCollapse",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Fires with the new `collapsed` value when the collapse toggle button is clicked."
+                },
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                }
+            }, {
+                "method": "bsSearchClick",
+                "name": "bsSearchClick",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Fires when the compact search-trigger button (shown instead of the `search` slot while\n`collapsed`) is clicked -- e.g. to open a full search overlay. This component has no\nvisibility into what the `search` slot actually contains, so it can't drive a real search\nitself once shrunk to icon size."
+                },
+                "complexType": {
+                    "original": "void",
+                    "resolved": "void",
+                    "references": {}
+                }
+            }];
+    }
+    static get elementRef() { return "el"; }
+    static get watchers() {
+        return [{
+                "propName": "collapsed",
+                "methodName": "onCollapsedChange"
+            }];
+    }
+}
+// Same inline-icon-helper-function pattern as bs-chatbot-header.tsx's NewChatIcon/ExpandIcon/etc.
+const CaretLeftIcon = () => (h("svg", { viewBox: "0 0 24 24", fill: "none", xmlns: "http://www.w3.org/2000/svg", "aria-hidden": "true" }, h("path", { d: "M15 18L9 12L15 6", stroke: "currentColor", "stroke-width": "2", "stroke-linecap": "round", "stroke-linejoin": "round" })));
+const SearchIcon = () => (h("svg", { viewBox: "0 0 24 24", fill: "none", xmlns: "http://www.w3.org/2000/svg", "aria-hidden": "true" }, h("circle", { cx: "11", cy: "11", r: "7", stroke: "currentColor", "stroke-width": "2" }), h("path", { d: "M16.5 16.5L21 21", stroke: "currentColor", "stroke-width": "2", "stroke-linecap": "round" })));

package/dist/collection/components/ui-shell/bs-navigation-drawer/bs-navigation-drawer/bs-navigation-drawer.stories.js

@@ -0,0 +1,274 @@
+import { html } from "lit";
+import { componentDescription, propDescription } from "../../../../stories-utils";
+const bookIcon = html `
+  <svg slot="icon" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+    <path
+      d="M4 4.5C4 3.67157 4.67157 3 5.5 3H18.5C19.3284 3 20 3.67157 20 4.5V19.5C20 20.3284 19.3284 21 18.5 21H5.5C4.67157 21 4 20.3284 4 19.5V4.5Z"
+      stroke="currentColor"
+      stroke-width="1.5"
+    />
+    <path d="M8 3V21" stroke="currentColor" stroke-width="1.5" />
+  </svg>
+`;
+const gridIcon = html `
+  <svg slot="icon" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+    <rect x="3.5" y="3.5" width="7" height="7" rx="1" stroke="currentColor" stroke-width="1.5" />
+    <rect x="13.5" y="3.5" width="7" height="7" rx="1" stroke="currentColor" stroke-width="1.5" />
+    <rect x="3.5" y="13.5" width="7" height="7" rx="1" stroke="currentColor" stroke-width="1.5" />
+    <rect x="13.5" y="13.5" width="7" height="7" rx="1" stroke="currentColor" stroke-width="1.5" />
+  </svg>
+`;
+const accessibilityIcon = html `
+  <svg slot="icon" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+    <circle cx="12" cy="12" r="9" stroke="currentColor" stroke-width="1.5" />
+    <circle cx="12" cy="8" r="1.25" fill="currentColor" />
+    <path d="M6.5 10.5H17.5M12 10.5V17M9.5 17L11 13M14.5 17L13 13" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" />
+  </svg>
+`;
+// The items list, shared across stories -- one plain leaf item (selected), one plain leaf item
+// (unselected), and one expandable group header with nested children, matching the task spec's
+// requirement of demonstrating all three states assembled together.
+// ariaLabel is optional (the visible caption stays visible even when collapsed), set here anyway
+// just to demonstrate the prop exists.
+const ITEMS = html `
+  <bs-navigation-drawer-item selected ariaLabel="Introduction">${accessibilityIcon} Introduction</bs-navigation-drawer-item>
+  <bs-navigation-drawer-item ariaLabel="Accessibility">${bookIcon} Accessibility</bs-navigation-drawer-item>
+  <bs-navigation-drawer-item expandable expanded ariaLabel="Foundation">
+    ${gridIcon} Foundation
+    <bs-navigation-drawer-item slot="children" nested>Colors</bs-navigation-drawer-item>
+    <bs-navigation-drawer-item slot="children" nested>Typography</bs-navigation-drawer-item>
+    <bs-navigation-drawer-item slot="children" nested>Spacing</bs-navigation-drawer-item>
+  </bs-navigation-drawer-item>
+  <bs-navigation-drawer-item expandable ariaLabel="Components">
+    ${gridIcon} Components
+    <bs-navigation-drawer-item slot="children" nested>Button</bs-navigation-drawer-item>
+    <bs-navigation-drawer-item slot="children" nested>Checkbox</bs-navigation-drawer-item>
+    <bs-navigation-drawer-item slot="children" nested>Switch</bs-navigation-drawer-item>
+  </bs-navigation-drawer-item>
+`;
+// Same items, without any icon slot content -- bs-navigation-drawer-item's icon wrapper only
+// reserves space when populated, so these render as plain text rows (Figma's own "nested" rows
+// already never have icons; this additionally omits them from the top-level rows too, for the
+// icon-less "Fixed Side Nav" stories below).
+const ITEMS_NO_ICONS = html `
+  <bs-navigation-drawer-item selected>Introduction</bs-navigation-drawer-item>
+  <bs-navigation-drawer-item>Accessibility</bs-navigation-drawer-item>
+  <bs-navigation-drawer-item expandable expanded>
+    Foundation
+    <bs-navigation-drawer-item slot="children" nested>Colors</bs-navigation-drawer-item>
+    <bs-navigation-drawer-item slot="children" nested>Typography</bs-navigation-drawer-item>
+    <bs-navigation-drawer-item slot="children" nested>Spacing</bs-navigation-drawer-item>
+  </bs-navigation-drawer-item>
+  <bs-navigation-drawer-item expandable>
+    Components
+    <bs-navigation-drawer-item slot="children" nested>Button</bs-navigation-drawer-item>
+    <bs-navigation-drawer-item slot="children" nested>Checkbox</bs-navigation-drawer-item>
+    <bs-navigation-drawer-item slot="children" nested>Switch</bs-navigation-drawer-item>
+  </bs-navigation-drawer-item>
+`;
+// A plain divider between item groups (e.g. Carbon's cds-side-nav-divider: a 1px rule with 8px
+// vertical / 16px horizontal margin) -- not a Figma-specified element in this design system, so
+// it's kept as story-only markup rather than a new formal bs-* component.
+const DIVIDER = html `<hr style="width: 100%; border: none; border-top: 1px solid var(--bs-border-default); margin: var(--bs-spacing-100) 0;" />`;
+const ITEMS_WITH_DIVIDER = html `
+  <bs-navigation-drawer-item selected>Introduction</bs-navigation-drawer-item>
+  <bs-navigation-drawer-item>Accessibility</bs-navigation-drawer-item>
+  ${DIVIDER}
+  <bs-navigation-drawer-item expandable expanded>
+    Foundation
+    <bs-navigation-drawer-item slot="children" nested>Colors</bs-navigation-drawer-item>
+    <bs-navigation-drawer-item slot="children" nested>Typography</bs-navigation-drawer-item>
+    <bs-navigation-drawer-item slot="children" nested>Spacing</bs-navigation-drawer-item>
+  </bs-navigation-drawer-item>
+  <bs-navigation-drawer-item expandable>
+    Components
+    <bs-navigation-drawer-item slot="children" nested>Button</bs-navigation-drawer-item>
+    <bs-navigation-drawer-item slot="children" nested>Checkbox</bs-navigation-drawer-item>
+    <bs-navigation-drawer-item slot="children" nested>Switch</bs-navigation-drawer-item>
+  </bs-navigation-drawer-item>
+`;
+// A longer, deeper item list than the other demo lists above -- more top-level groups, more
+// nested children per group, and every group expanded at once -- for demonstrating this
+// component's own scroll behavior (a fixed-height drawer with a naturally-taller-than-viewport
+// item list) rather than a distinct "large" item size/prop, which bs-navigation-drawer-item
+// doesn't have.
+const LARGE_ITEMS = html `
+  <bs-navigation-drawer-item selected ariaLabel="Introduction">${accessibilityIcon} Introduction</bs-navigation-drawer-item>
+  <bs-navigation-drawer-item ariaLabel="Accessibility">${bookIcon} Accessibility</bs-navigation-drawer-item>
+  <bs-navigation-drawer-item expandable expanded ariaLabel="Foundation">
+    ${gridIcon} Foundation
+    <bs-navigation-drawer-item slot="children" nested>Colors</bs-navigation-drawer-item>
+    <bs-navigation-drawer-item slot="children" nested>Typography</bs-navigation-drawer-item>
+    <bs-navigation-drawer-item slot="children" nested>Spacing</bs-navigation-drawer-item>
+    <bs-navigation-drawer-item slot="children" nested>Elevation</bs-navigation-drawer-item>
+    <bs-navigation-drawer-item slot="children" nested>Iconography</bs-navigation-drawer-item>
+  </bs-navigation-drawer-item>
+  <bs-navigation-drawer-item expandable expanded ariaLabel="Components">
+    ${gridIcon} Components
+    <bs-navigation-drawer-item slot="children" nested>Button</bs-navigation-drawer-item>
+    <bs-navigation-drawer-item slot="children" nested>Checkbox</bs-navigation-drawer-item>
+    <bs-navigation-drawer-item slot="children" nested>Switch</bs-navigation-drawer-item>
+    <bs-navigation-drawer-item slot="children" nested>Radio</bs-navigation-drawer-item>
+    <bs-navigation-drawer-item slot="children" nested>Slider</bs-navigation-drawer-item>
+    <bs-navigation-drawer-item slot="children" nested>Modal</bs-navigation-drawer-item>
+    <bs-navigation-drawer-item slot="children" nested>Tooltip</bs-navigation-drawer-item>
+  </bs-navigation-drawer-item>
+  <bs-navigation-drawer-item expandable expanded ariaLabel="Patterns">
+    ${gridIcon} Patterns
+    <bs-navigation-drawer-item slot="children" nested>Dashboard</bs-navigation-drawer-item>
+    <bs-navigation-drawer-item slot="children" nested>Filter Table</bs-navigation-drawer-item>
+    <bs-navigation-drawer-item slot="children" nested>Empty State</bs-navigation-drawer-item>
+  </bs-navigation-drawer-item>
+  <bs-navigation-drawer-item ariaLabel="Settings">${bookIcon} Settings</bs-navigation-drawer-item>
+`;
+const meta = {
+    title: 'UI Shell/bs-navigation-drawer/bs-navigation-drawer',
+    parameters: { docs: { description: { component: componentDescription('bs-navigation-drawer') } }, layout: 'fullscreen' },
+    // "Fixed Side Nav" (Carbon's own naming) means never collapsible, so args.collapsible defaults
+    // to false below for this default render every "Fixed Side Nav*" story shares. The dedicated
+    // Collapsed story further down opts back in explicitly.
+    //
+    // Plain attribute binding (collapsible=${args.collapsible}), NOT lit's ?collapsible= boolean
+    // directive -- collapsible defaults to true on the component, and ?attr= booleans OMIT the
+    // attribute for a falsy value. Stencil can't tell "never set" apart from "explicitly false" for
+    // a prop that defaults true, so it would silently keep its own default (true) -- the exact same
+    // bug found and fixed in bs-slider's showLabel earlier this session.
+    render: args => html `
+    <div style="height: 100vh; display: flex;">
+      <bs-navigation-drawer
+        heading=${args.heading}
+        collapsible=${args.collapsible}
+        logo-background=${args.logoBackground}
+        show-logo=${args.showLogo}
+      >
+        <bs-input slot="search" type="search" placeholder="Search"></bs-input>
+        ${ITEMS_NO_ICONS}
+      </bs-navigation-drawer>
+    </div>
+  `,
+    argTypes: {
+        heading: { control: 'text', description: propDescription('bs-navigation-drawer', 'heading') },
+        collapsible: { control: 'boolean', description: propDescription('bs-navigation-drawer', 'collapsible') },
+        logoBackground: { control: 'select', options: ['auto', 'light', 'dark'], description: propDescription('bs-navigation-drawer', 'logoBackground') },
+        showLogo: { control: 'boolean', description: propDescription('bs-navigation-drawer', 'showLogo') },
+    },
+    args: {
+        heading: 'Main Menu',
+        collapsible: false,
+        logoBackground: 'auto',
+        showLogo: true,
+    },
+};
+export default meta;
+// Story naming follows the same "[Base] [with X]" convention as bs-navigation-header's stories,
+// matching Carbon's own side-nav story names (Fixed Side Nav / with Divider / with Icons) as a
+// naming convention reference -- not a design/token match, just the naming pattern.
+export const FixedSideNav = {
+    name: 'Fixed Side Nav',
+};
+export const FixedSideNavWithDivider = {
+    name: 'Fixed Side Nav with Divider',
+    render: args => html `
+    <div style="height: 100vh; display: flex;">
+      <bs-navigation-drawer heading=${args.heading} collapsible=${args.collapsible}>
+        <bs-input slot="search" type="search" placeholder="Search"></bs-input>
+        ${ITEMS_WITH_DIVIDER}
+      </bs-navigation-drawer>
+    </div>
+  `,
+};
+export const FixedSideNavWithIcons = {
+    name: 'Fixed Side Nav with Icons',
+    render: args => html `
+    <div style="height: 100vh; display: flex;">
+      <bs-navigation-drawer heading=${args.heading} collapsible=${args.collapsible}>
+        <bs-input slot="search" type="search" placeholder="Search"></bs-input>
+        ${ITEMS}
+      </bs-navigation-drawer>
+    </div>
+  `,
+};
+export const Collapsed = {
+    name: 'Side Nav Rail',
+    // Click the collapse toggle (the caret button next to the heading) to see it expand back --
+    // `collapsed` is mutable/self-toggling, so this works with no extra story wiring.
+    render: args => html `
+    <div style="height: 100vh; display: flex;">
+      <bs-navigation-drawer heading=${args.heading} collapsed>
+        <bs-input slot="search" type="search" placeholder="Search"></bs-input>
+        ${ITEMS}
+      </bs-navigation-drawer>
+    </div>
+  `,
+};
+export const CollapsedWithHeader = {
+    name: 'Side Nav Rail with Header',
+    // The rail (collapsed) drawer composed alongside bs-navigation-header, forming the same
+    // app-shell layout as bs-navigation-header's own "with Side Nav" stories, but with the drawer
+    // starting in its collapsed/icon-only rail state instead of fully expanded.
+    render: args => html `
+    <div style="height: 100vh; display: flex; flex-direction: column;">
+      <bs-navigation-header alignment="with-navigation-drawer"></bs-navigation-header>
+      <div style="flex: 1; min-height: 0; display: flex;">
+        <bs-navigation-drawer heading=${args.heading} collapsed>
+          <bs-input slot="search" type="search" placeholder="Search"></bs-input>
+          ${ITEMS}
+        </bs-navigation-drawer>
+        <main style="flex: 1; min-width: 0; overflow: auto; padding: var(--bs-spacing-400); font-family: sans-serif; color: var(--bs-text-muted);">
+          Page content
+        </main>
+      </div>
+    </div>
+  `,
+};
+export const Dark = {
+    name: 'Fixed Side Nav (Dark)',
+    // `data-theme="dark"` is set on a wrapper scoped to just this story, NOT via a globals override
+    // on the toolbar's Theme switch -- that switch's decorator (see .storybook/preview.ts) sets the
+    // attribute on the shared document root, which is fine in isolation but breaks down on this
+    // component's Docs page: every story renders together in one document there, so one story
+    // forcing a document-wide theme while its siblings render alongside it under the *other* theme
+    // causes exactly the kind of thrash/hang a shared mutable global produces. A local wrapper gets
+    // the identical CSS custom property cascade (tokens.css's dark block matches any
+    // `[data-theme="dark"]` element, not specifically <html>) without touching shared state.
+    // logoBackground is left at its "auto" default here deliberately -- this story demonstrates that
+    // no manual prop is needed for the logo to follow the theme; see logoBackground's own docs for
+    // the explicit-override case.
+    render: args => html `
+    <div data-theme="dark" style="height: 100vh; display: flex; background: var(--bs-surface-base);">
+      <bs-navigation-drawer heading=${args.heading} collapsible=${args.collapsible} logo-background=${args.logoBackground}>
+        <bs-input slot="search" type="search" placeholder="Search"></bs-input>
+        ${ITEMS_NO_ICONS}
+      </bs-navigation-drawer>
+    </div>
+  `,
+};
+export const WithoutSearch = {
+    name: 'Without a search slot',
+    render: args => html `
+    <div style="height: 100vh; display: flex;">
+      <bs-navigation-drawer heading=${args.heading}>${ITEMS}</bs-navigation-drawer>
+    </div>
+  `,
+};
+export const EmptyItems = {
+    name: 'Empty items list',
+    render: args => html `
+    <div style="height: 100vh; display: flex;">
+      <bs-navigation-drawer heading=${args.heading}>
+        <bs-input slot="search" type="search" placeholder="Search"></bs-input>
+      </bs-navigation-drawer>
+    </div>
+  `,
+};
+export const LargeItemList = {
+    name: 'Side Nav with Large Side Nav Items',
+    render: args => html `
+    <div style="height: 100vh; display: flex;">
+      <bs-navigation-drawer heading=${args.heading} collapsible=${args.collapsible}>
+        <bs-input slot="search" type="search" placeholder="Search"></bs-input>
+        ${LARGE_ITEMS}
+      </bs-navigation-drawer>
+    </div>
+  `,
+};