@brandsync/wc 0.0.11 → 0.0.12

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

@@ -0,0 +1,253 @@
+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).
+ *
+ * ## 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 (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.
+ * @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';
+    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: '643a802cfef5b124603056ca409c67e5e9fa0561', class: "bs-navigation-drawer", "aria-label": this.heading }, h("div", { key: '31384937f95737b961aa4f1cb0b535fc78c8fcfd', part: "logo", class: "bs-navigation-drawer__logo bs-navigation-drawer__logo--full" }, h("bs-logo", { key: '834c8a1a031072803815085036ea6b8a744012a2', variant: "full", background: this.logoBackground })), h("div", { key: '50b877188cea0fce86959517f1e14eb4f6869923', part: "logo", class: "bs-navigation-drawer__logo bs-navigation-drawer__logo--mark" }, h("bs-logo", { key: '64b66e3e221d9641026009e0b7b0a0bbdf7b946a', variant: "mark", background: this.logoBackground })), h("div", { key: 'a7634d178a491940cb43ceca3dd93aa83539a316', class: "bs-navigation-drawer__title-row" }, h("span", { key: 'fc018e4474f3a38f96538be9064da6b472193b3f', part: "title", class: "bs-navigation-drawer__title" }, this.heading), this.collapsible && (h("button", { key: '516e28aba1e037b74ac616fbc8f293c0cef9da1a', 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: 'fba23fed9c12283360bd89dddee6248ec45c98fb' })))), h("div", { key: '29279ec0051d495810f177a194f8dc6f3c649f90', part: "search", class: "bs-navigation-drawer__search" }, h("slot", { key: '6eef2761d887ddc776132327c8343626071fc3b3', name: "search" })), h("button", { key: '4ee9e0ca46ca85b17394466b452cba29c0e528cc', type: "button", part: "search-trigger", class: "bs-navigation-drawer__search-trigger", "aria-label": "Search", onClick: this.onSearchTriggerClick }, h(SearchIcon, { key: '844c581c6ea6c496718866150e24415f746daa36' })), h("div", { key: '3f7f3c6bb4eae12aa87c732fbc4da6d5b3a87e40', part: "items", class: "bs-navigation-drawer__items" }, h("slot", { key: '20833d282601ea298a39ead5b928155e2db33a97' }))));
+    }
+    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'"
+            }
+        };
+    }
+    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,202 @@
+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>
+`;
+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}>
+        <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') },
+    },
+    args: {
+        heading: 'Main Menu',
+        collapsible: false,
+        logoBackground: 'auto',
+    },
+};
+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: 'Collapsed',
+    // 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 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>
+  `,
+};

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

@@ -0,0 +1,172 @@
+import { render, h, describe, it, expect } from "@stencil/vitest";
+describe('bs-navigation-drawer-item', () => {
+    it('renders a real button with part="item"', async () => {
+        const { root } = await render(h("bs-navigation-drawer-item", null, "Introduction"));
+        const button = root.shadowRoot.querySelector('[part="item"]');
+        expect(button).not.toBeNull();
+        expect(button.tagName).toBe('BUTTON');
+        expect(button).toEqualAttribute('type', 'button');
+    });
+    describe('click behavior: expandable vs. non-expandable', () => {
+        it('emits bsSelect (not bsToggle) when expandable is false', async () => {
+            const { root, spyOnEvent } = await render(h("bs-navigation-drawer-item", null, "Introduction"));
+            const selectSpy = spyOnEvent('bsSelect');
+            const toggleSpy = spyOnEvent('bsToggle');
+            root.shadowRoot.querySelector('[part="item"]').click();
+            expect(selectSpy).toHaveReceivedEventTimes(1);
+            expect(toggleSpy).toHaveReceivedEventTimes(0);
+        });
+        it('emits bsToggle (not bsSelect) when expandable is true', async () => {
+            const { root, spyOnEvent } = await render(h("bs-navigation-drawer-item", { expandable: true }, "Components"));
+            const selectSpy = spyOnEvent('bsSelect');
+            const toggleSpy = spyOnEvent('bsToggle');
+            root.shadowRoot.querySelector('[part="item"]').click();
+            expect(toggleSpy).toHaveReceivedEventTimes(1);
+            expect(selectSpy).toHaveReceivedEventTimes(0);
+        });
+        it('emits bsToggle with the new expanded value', async () => {
+            const { root, spyOnEvent } = await render(h("bs-navigation-drawer-item", { expandable: true }, "Components"));
+            const toggleSpy = spyOnEvent('bsToggle');
+            root.shadowRoot.querySelector('[part="item"]').click();
+            expect(toggleSpy).toHaveReceivedEventDetail(true);
+        });
+        it('does not self-toggle selected when non-expandable is clicked', async () => {
+            const { root, waitForChanges } = await render(h("bs-navigation-drawer-item", null, "Introduction"));
+            root.shadowRoot.querySelector('[part="item"]').click();
+            await waitForChanges();
+            expect(root.selected).toBe(false);
+        });
+    });
+    describe('expanded (self-toggling)', () => {
+        it('defaults to false', async () => {
+            const { root } = await render(h("bs-navigation-drawer-item", { expandable: true }, "Components"));
+            expect(root.hasAttribute('expanded')).toBe(false);
+        });
+        it('self-toggles to true on click and reflects the attribute', async () => {
+            const { root, waitForChanges } = await render(h("bs-navigation-drawer-item", { expandable: true }, "Components"));
+            root.shadowRoot.querySelector('[part="item"]').click();
+            await waitForChanges();
+            expect(root.expanded).toBe(true);
+            expect(root).toHaveAttribute('expanded');
+        });
+        it('self-toggles back to false on a second click', async () => {
+            const { root, waitForChanges } = await render(h("bs-navigation-drawer-item", { expandable: true, expanded: true }, "Components"));
+            root.shadowRoot.querySelector('[part="item"]').click();
+            await waitForChanges();
+            expect(root.expanded).toBe(false);
+            expect(root).not.toHaveAttribute('expanded');
+        });
+        it('sets aria-expanded on the button when expandable', async () => {
+            const { root, waitForChanges } = await render(h("bs-navigation-drawer-item", { expandable: true }, "Components"));
+            const button = root.shadowRoot.querySelector('[part="item"]');
+            expect(button).toEqualAttribute('aria-expanded', 'false');
+            button.click();
+            await waitForChanges();
+            expect(button).toEqualAttribute('aria-expanded', 'true');
+        });
+        it('does not set aria-expanded when not expandable', async () => {
+            const { root } = await render(h("bs-navigation-drawer-item", null, "Introduction"));
+            const button = root.shadowRoot.querySelector('[part="item"]');
+            expect(button).not.toHaveAttribute('aria-expanded');
+        });
+    });
+    describe('selected', () => {
+        it('applies selected styling and reflects the attribute', async () => {
+            const { root } = await render(h("bs-navigation-drawer-item", { selected: true }, "Introduction"));
+            expect(root).toHaveAttribute('selected');
+            const button = root.shadowRoot.querySelector('[part="item"]');
+            expect(button).toHaveClass('bs-navigation-drawer-item--selected');
+        });
+        it('does not apply the selected class when expandable, even if selected is set', async () => {
+            const { root } = await render(h("bs-navigation-drawer-item", { selected: true, expandable: true }, "Components"));
+            const button = root.shadowRoot.querySelector('[part="item"]');
+            expect(button).not.toHaveClass('bs-navigation-drawer-item--selected');
+        });
+    });
+    describe('nested rows', () => {
+        it('applies the nested class', async () => {
+            const { root } = await render(h("bs-navigation-drawer-item", { nested: true }, "Button"));
+            const button = root.shadowRoot.querySelector('[part="item"]');
+            expect(button).toHaveClass('bs-navigation-drawer-item--nested');
+        });
+        it('does not render an icon slot wrapper at all for nested rows, even if icon content is provided', async () => {
+            const { root } = await render(h("bs-navigation-drawer-item", { nested: true }, h("span", { slot: "icon" }, "ICON"), "Button"));
+            expect(root.shadowRoot.querySelector('[part="icon"]')).toBeNull();
+        });
+        it('renders an icon slot wrapper for top-level (non-nested) rows', async () => {
+            const { root } = await render(h("bs-navigation-drawer-item", null, "Introduction"));
+            expect(root.shadowRoot.querySelector('[part="icon"]')).not.toBeNull();
+        });
+    });
+    describe('icon slot: only reserves space when populated', () => {
+        it('does not reserve icon space by default', async () => {
+            const { root } = await render(h("bs-navigation-drawer-item", null, "Introduction"));
+            const icon = root.shadowRoot.querySelector('[part="icon"]');
+            expect(icon).not.toHaveClass('bs-navigation-drawer-item__icon--has-content');
+            expect(getComputedStyle(icon).display).toBe('none');
+        });
+        it('reserves icon space when the icon slot is populated', async () => {
+            const { root } = await render(h("bs-navigation-drawer-item", null, h("span", { slot: "icon" }, "ICON"), "Introduction"));
+            const icon = root.shadowRoot.querySelector('[part="icon"]');
+            expect(icon).toHaveClass('bs-navigation-drawer-item__icon--has-content');
+        });
+    });
+    describe('children slot (expandable only)', () => {
+        it('does not render a children slot wrapper when not expandable', async () => {
+            const { root } = await render(h("bs-navigation-drawer-item", null, "Introduction"));
+            expect(root.shadowRoot.querySelector('[part="children"]')).toBeNull();
+        });
+        it('renders a children slot wrapper when expandable', async () => {
+            const { root } = await render(h("bs-navigation-drawer-item", { expandable: true }, "Components"));
+            expect(root.shadowRoot.querySelector('[part="children"]')).not.toBeNull();
+        });
+        it('hides the children slot wrapper when not expanded', async () => {
+            const { root } = await render(h("bs-navigation-drawer-item", { expandable: true }, "Components", h("bs-navigation-drawer-item", { slot: "children", nested: true }, "Button")));
+            const children = root.shadowRoot.querySelector('[part="children"]');
+            expect(getComputedStyle(children).display).toBe('none');
+        });
+        it('shows the children slot wrapper when expanded', async () => {
+            const { root } = await render(h("bs-navigation-drawer-item", { expandable: true, expanded: true }, "Components", h("bs-navigation-drawer-item", { slot: "children", nested: true }, "Button")));
+            const children = root.shadowRoot.querySelector('[part="children"]');
+            expect(getComputedStyle(children).display).not.toBe('none');
+        });
+    });
+    describe('collapsed', () => {
+        it('keeps the label visible (restyled as a caption), not hidden', async () => {
+            const { root } = await render(h("bs-navigation-drawer-item", { collapsed: true }, "Introduction"));
+            const label = root.shadowRoot.querySelector('[part="label"]');
+            expect(getComputedStyle(label).display).not.toBe('none');
+            // .textContent on the shadow-DOM label wrapper doesn't reflect slotted content (a DOM quirk:
+            // textContent walks the light tree, not the flattened/slotted one) -- check the host's own
+            // text instead, which is what's actually visible on screen via the slot.
+            expect(root.textContent.trim()).toBe('Introduction');
+        });
+        it('forces the chevron hidden even when expandable and expanded', async () => {
+            const { root } = await render(h("bs-navigation-drawer-item", { collapsed: true, expandable: true, expanded: true }, "Components"));
+            const chevron = root.shadowRoot.querySelector('[part="chevron"]');
+            expect(getComputedStyle(chevron).display).toBe('none');
+        });
+        it('forces the children slot wrapper hidden even when expanded', async () => {
+            const { root } = await render(h("bs-navigation-drawer-item", { collapsed: true, expandable: true, expanded: true }, "Components", h("bs-navigation-drawer-item", { slot: "children", nested: true }, "Button")));
+            const children = root.shadowRoot.querySelector('[part="children"]');
+            expect(getComputedStyle(children).display).toBe('none');
+        });
+        it('moves the selected tint onto the icon chip instead of the whole row', async () => {
+            const { root } = await render(h("bs-navigation-drawer-item", { collapsed: true, selected: true }, h("span", { slot: "icon" }, "ICON"), "Introduction"));
+            const button = root.shadowRoot.querySelector('[part="item"]');
+            const icon = root.shadowRoot.querySelector('[part="icon"]');
+            expect(getComputedStyle(button).backgroundColor).toBe('rgba(0, 0, 0, 0)');
+            expect(getComputedStyle(icon).backgroundColor).not.toBe('rgba(0, 0, 0, 0)');
+        });
+    });
+    describe('ariaLabel', () => {
+        it('sets aria-label on the row when provided', async () => {
+            const { root } = await render(h("bs-navigation-drawer-item", { ariaLabel: "Introduction page" }, "Introduction"));
+            expect(root.shadowRoot.querySelector('[part="item"]')).toEqualAttribute('aria-label', 'Introduction page');
+        });
+        it('omits aria-label when not provided, falling back to the visible text as the accessible name', async () => {
+            const { root } = await render(h("bs-navigation-drawer-item", null, "Introduction"));
+            expect(root.shadowRoot.querySelector('[part="item"]').hasAttribute('aria-label')).toBe(false);
+        });
+    });
+});