@brandsync/wc 1.8.0 → 1.10.0

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

@@ -1,5 +1,21 @@
 import { render, h, describe, it, expect } from "@stencil/vitest";
+import { afterEach, beforeEach } from "vitest";
 import { page } from "vitest/browser";
+import { runAxeCheck } from "../../../../test/helpers/conventions";
+// The test browser (and its viewport) is shared across test files, so every test here starts from a
+// known viewport and restores whatever it found. The default 414px viewport is inside the drawer's
+// small-screen (<= 768px) overlay mode, so the original tests -- written for the desktop drawer --
+// run at 1024px; the overlay has its own describe at 390px below.
+const previousViewport = { w: 0, h: 0 };
+beforeEach(async () => {
+    previousViewport.w = window.innerWidth;
+    previousViewport.h = window.innerHeight;
+    await page.viewport(1024, 768);
+});
+afterEach(async () => {
+    await page.viewport(previousViewport.w, previousViewport.h);
+    document.body.style.overflow = '';
+});
 describe('bs-navigation-drawer', () => {
     it('renders a <nav> landmark with the logo', async () => {
         const { root } = await render(h("bs-navigation-drawer", null));
@@ -110,11 +126,8 @@ describe('bs-navigation-drawer', () => {
             expect(searchClickSpy).toHaveReceivedEventTimes(1);
         });
         it('hides the search-trigger button when not collapsed', async () => {
-            // The default test viewport (414px) is inside this component's own <= 768px small-screen
-            // breakpoint (see bs-navigation-drawer.css), which forces the same visual treatment as
-            // `collapsed` regardless of the prop -- widen the viewport here so this test is isolated to
-            // the `collapsed` *prop*'s own behavior, not the viewport-driven treatment.
-            await page.viewport(1024, 768);
+            // Desktop viewport (set for the whole file above), so this is isolated to the `collapsed`
+            // *prop*'s own behavior, not the small-screen overlay.
             const { root } = await render(h("bs-navigation-drawer", null));
             const trigger = root.shadowRoot.querySelector('[part="search-trigger"]');
             expect(getComputedStyle(trigger).display).toBe('none');
@@ -147,3 +160,158 @@ describe('bs-navigation-drawer', () => {
         });
     });
 });
+describe('bs-navigation-drawer: small-screen overlay (<= 768px)', () => {
+    const frame = () => new Promise(r => requestAnimationFrame(() => requestAnimationFrame(() => r())));
+    const nav = (root) => root.shadowRoot.querySelector('nav');
+    const backdrop = (root) => root.shadowRoot.querySelector('[part="backdrop"]');
+    const css = (el) => getComputedStyle(el);
+    const renderDrawer = async (props = {}) => {
+        await page.viewport(390, 800);
+        const result = await render(h("bs-navigation-drawer", { ...props }, h("bs-navigation-drawer-item", null, "Home"), h("bs-navigation-drawer-item", { expandable: true, expanded: true }, "Reports", h("bs-navigation-drawer-item", { slot: "children", nested: true }, "Sales"))));
+        await result.waitForChanges();
+        return result;
+    };
+    it('is closed by default: off-canvas, hidden from the tab order and the accessibility tree', async () => {
+        const { root } = await renderDrawer();
+        expect(css(nav(root)).visibility).toBe('hidden');
+        expect(nav(root)).not.toHaveClass('bs-navigation-drawer--open');
+        expect(nav(root).getAttribute('role')).toBeNull();
+        expect(css(backdrop(root)).visibility).toBe('hidden');
+    });
+    it('takes no space in the page flow (position: fixed)', async () => {
+        const { root } = await renderDrawer();
+        expect(css(nav(root)).position).toBe('fixed');
+    });
+    it('open shows the drawer fully expanded over a backdrop', async () => {
+        const { root, waitForChanges } = await renderDrawer();
+        root.open = true;
+        await waitForChanges();
+        await new Promise(r => setTimeout(r, 350)); // let the slide-in finish
+        expect(css(nav(root)).visibility).toBe('visible');
+        expect(Math.round(nav(root).getBoundingClientRect().left)).toBe(0);
+        expect(Math.round(nav(root).getBoundingClientRect().width)).toBe(280);
+        // still the plain nav landmark: ARIA does not allow role="dialog" on <nav>
+        expect(nav(root).getAttribute('role')).toBeNull();
+        expect(css(backdrop(root)).visibility).toBe('visible');
+        // full wordmark + title, not the rail's mark; no collapse toggle or compact search trigger
+        expect(css(root.shadowRoot.querySelector('.bs-navigation-drawer__logo--full')).display).not.toBe('none');
+        expect(css(root.shadowRoot.querySelector('.bs-navigation-drawer__logo--mark')).display).toBe('none');
+        expect(css(root.shadowRoot.querySelector('[part="title"]')).display).not.toBe('none');
+        expect(css(root.shadowRoot.querySelector('[part="collapse"]')).display).toBe('none');
+        expect(css(root.shadowRoot.querySelector('[part="search-trigger"]')).display).toBe('none');
+    });
+    it('forces the items to their expanded layout, even when the drawer has collapsed set', async () => {
+        const { root, waitForChanges } = await renderDrawer({ collapsed: true });
+        root.open = true;
+        await waitForChanges();
+        const topLevel = Array.from(root.querySelectorAll(':scope > bs-navigation-drawer-item'));
+        expect(topLevel.map(i => i.collapsed)).toEqual([false, false]);
+        // the expandable item's children are reachable (its children wrapper is shown)
+        const children = topLevel[1].shadowRoot.querySelector('[part="children"]');
+        expect(children).not.toBeNull();
+        expect(css(children).display).not.toBe('none');
+    });
+    it('Escape closes the overlay, sets open back to false and emits bsClose once', async () => {
+        const { root, waitForChanges, spyOnEvent } = await renderDrawer();
+        const spy = spyOnEvent('bsClose');
+        root.open = true;
+        await waitForChanges();
+        document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+        await waitForChanges();
+        expect(root.open).toBe(false);
+        expect(root.hasAttribute('open')).toBe(false);
+        expect(spy).toHaveReceivedEventTimes(1);
+    });
+    it('clicking the backdrop closes the overlay and emits bsClose', async () => {
+        const { root, waitForChanges, spyOnEvent } = await renderDrawer();
+        const spy = spyOnEvent('bsClose');
+        root.open = true;
+        await waitForChanges();
+        backdrop(root).click();
+        await waitForChanges();
+        expect(root.open).toBe(false);
+        expect(spy).toHaveReceivedEventTimes(1);
+    });
+    it('setting open = false from code does not emit bsClose', async () => {
+        const { root, waitForChanges, spyOnEvent } = await renderDrawer({ open: true });
+        const spy = spyOnEvent('bsClose');
+        root.open = false;
+        await waitForChanges();
+        expect(spy).not.toHaveReceivedEvent();
+    });
+    it('Escape does nothing while the overlay is closed', async () => {
+        const { waitForChanges, spyOnEvent } = await renderDrawer();
+        const spy = spyOnEvent('bsClose');
+        document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+        await waitForChanges();
+        expect(spy).not.toHaveReceivedEvent();
+    });
+    it('moves focus into the overlay on open and returns it to the trigger on close', async () => {
+        await page.viewport(390, 800);
+        const { root, waitForChanges } = await render(h("div", null, h("button", { id: "hamburger" }, "Menu"), h("bs-navigation-drawer", null, h("bs-navigation-drawer-item", null, "Home"))));
+        const trigger = root.querySelector('#hamburger');
+        const drawer = root.querySelector('bs-navigation-drawer');
+        trigger.focus();
+        drawer.open = true;
+        await waitForChanges();
+        await frame();
+        expect(drawer.shadowRoot.activeElement).toBe(nav(drawer));
+        drawer.open = false;
+        await waitForChanges();
+        expect(document.activeElement).toBe(trigger);
+    });
+    it('keeps focus inside the open overlay: focus that lands outside is pulled back in', async () => {
+        await page.viewport(390, 800);
+        const { root, waitForChanges } = await render(h("div", null, h("button", { id: "outside" }, "Outside"), h("bs-navigation-drawer", { open: true }, h("bs-navigation-drawer-item", null, "Home"))));
+        await waitForChanges();
+        await frame();
+        const drawer = root.querySelector('bs-navigation-drawer');
+        root.querySelector('#outside').focus();
+        await frame();
+        expect(drawer.shadowRoot.activeElement).toBe(nav(drawer));
+    });
+    it('locks page scroll while open and restores it on close', async () => {
+        const { root, waitForChanges } = await renderDrawer();
+        expect(document.body.style.overflow).toBe('');
+        root.open = true;
+        await waitForChanges();
+        expect(document.body.style.overflow).toBe('hidden');
+        root.open = false;
+        await waitForChanges();
+        expect(document.body.style.overflow).toBe('');
+    });
+    it('on wider screens open is ignored: in the page flow, no backdrop, no scroll lock', async () => {
+        await page.viewport(1024, 768);
+        const { root, waitForChanges } = await render(h("bs-navigation-drawer", { open: true }));
+        await waitForChanges();
+        expect(css(nav(root)).position).not.toBe('fixed');
+        expect(css(nav(root)).visibility).toBe('visible');
+        expect(backdrop(root)).toBeNull();
+        expect(document.body.style.overflow).toBe('');
+        expect(nav(root).getAttribute('role')).toBeNull();
+    });
+    it('widening the viewport while the overlay is open returns to the normal drawer and releases scroll', async () => {
+        const { root, waitForChanges } = await renderDrawer({ open: true });
+        expect(document.body.style.overflow).toBe('hidden');
+        await page.viewport(1024, 768);
+        await new Promise(r => setTimeout(r, 150));
+        await waitForChanges();
+        expect(css(nav(root)).position).not.toBe('fixed');
+        expect(document.body.style.overflow).toBe('');
+        expect(backdrop(root)).toBeNull();
+    });
+    it('is off-canvas on the inline-end side in RTL', async () => {
+        await page.viewport(390, 800);
+        const { root, waitForChanges } = await render(h("div", { dir: "rtl" }, h("bs-navigation-drawer", null)));
+        await waitForChanges();
+        const drawer = root.querySelector('bs-navigation-drawer');
+        // closed: translated by +100% of its width (to the right, off-screen) rather than -100%
+        expect(new DOMMatrix(css(nav(drawer)).transform).m41).toBeGreaterThan(0);
+    });
+    it('has no axe-core violations while open', async () => {
+        const { root, waitForChanges } = await renderDrawer({ open: true });
+        await waitForChanges();
+        await new Promise(r => setTimeout(r, 350));
+        await runAxeCheck(root);
+    });
+});

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

@@ -12,10 +12,9 @@
  *   rhythm) -- bumped up from the originally Figma-measured --bs-spacing-150 (12px) at the user's
  *   request after seeing it rendered (felt cramped in practice), not a Figma re-measurement.
  * @prop --bs-navigation-drawer-width: Default width of the drawer. 280px, matching Figma's own
- *   frame -- overridable by a consumer that needs a different fixed width. Below a 768px viewport
- *   width, this is overridden by a `@media (max-width: 768px)` rule that forces the existing
- *   `collapsed` 96px icon-only rail treatment instead (see --bs-navigation-drawer-collapsed-width
- *   below), so the drawer stops reserving a permanent 280px of layout width on small screens.
+ *   frame -- overridable by a consumer that needs a different fixed width. At 768px and below the
+ *   drawer is an off-canvas overlay (see `open`) of this same width (capped at the viewport
+ *   width), so it stops reserving a permanent 280px of layout width on small screens.
  * @prop --bs-navigation-drawer-title-font-family: Title text font family. Aliased to
  *   --bs-typography-font-family-heading.
  * @prop --bs-navigation-drawer-title-font-weight: Title text font weight. Aliased to
@@ -50,6 +49,14 @@
  *   --bs-border-neutral-container (same border color as the drawer's own right edge).
  * @prop --bs-navigation-drawer-search-trigger-icon: Search-trigger icon color. Aliased to
  *   --bs-icon-default.
+ * @prop --bs-navigation-drawer-backdrop: Scrim behind the small-screen overlay. Aliased to
+ *   --bs-surface-overlay-level-2.
+ * @prop --bs-navigation-drawer-overlay-shadow: Shadow of the small-screen overlay panel. Aliased
+ *   to --bs-shadow-lg.
+ * @prop --bs-navigation-drawer-overlay-z-index: Stacking order of the small-screen overlay (the
+ *   panel sits one above its backdrop). Aliased to --bs-z-index-modal.
+ * @prop --bs-navigation-drawer-overlay-duration: Slide/fade duration of the small-screen overlay.
+ *   Aliased to --bs-duration-default.
  */
 :host {
   display: block;
@@ -82,6 +89,11 @@
   --bs-navigation-drawer-search-trigger-bg: var(--bs-color-neutral-container);
   --bs-navigation-drawer-search-trigger-border: var(--bs-border-neutral-container);
   --bs-navigation-drawer-search-trigger-icon: var(--bs-icon-default);
+
+  --bs-navigation-drawer-backdrop: var(--bs-surface-overlay-level-2);
+  --bs-navigation-drawer-overlay-shadow: var(--bs-shadow-lg);
+  --bs-navigation-drawer-overlay-z-index: var(--bs-z-index-modal);
+  --bs-navigation-drawer-overlay-duration: var(--bs-duration-default);
 }
 
 .bs-navigation-drawer {
@@ -259,41 +271,101 @@
   display: none;
 }
 
-/* Below 768px (a standard tablet/small-screen breakpoint, and the narrow end of this component's
-   normal tablet-and-up usage) a permanently-reserved 280px-wide drawer pushes page content down to
-   an unusably narrow remainder on real small-screen viewports (e.g. 390px). This library has no
-   existing width-based @media breakpoint convention to follow (grepping every other component's
-   CSS only turns up `@media (prefers-reduced-motion: reduce)`), so rather than inventing new
-   open/closed overlay API, this reuses the drawer's own existing `collapsed` 96px icon-only rail
-   treatment (see the `:host([collapsed])` rules above) and applies it unconditionally at this
-   width -- same rail, now driven by viewport instead of only by the `collapsed` prop/toggle. Placed
-   last in this file so it wins over the unscoped `.bs-navigation-drawer`/`__title`/etc. rules above
-   on specificity ties, regardless of whether `collapsed` happens to be reflected on the host. */
-@media (max-width: 768px) {
-  .bs-navigation-drawer {
-    width: var(--bs-navigation-drawer-collapsed-width);
-    padding-left: 0;
-    padding-right: 0;
-    align-items: center;
-  }
+/* Small screens (768px and below, tracked in bs-navigation-drawer.tsx with matchMedia, which sets
+   the `data-overlay` attribute on the host): instead of a permanent rail the drawer becomes an
+   off-canvas overlay -- hidden until `open`, then sliding in over the page with a backdrop. A rail
+   clipped item labels inside 96px and offered no way to reach nested items, so the overlay shows the
+   drawer fully expanded (the items are switched to their expanded layout in the component). The
+   overrides below intentionally come after, and match the specificity of, the `:host([collapsed])`
+   rules above, so a `collapsed` set for desktop never leaks into the overlay. */
+.bs-navigation-drawer:focus {
+  outline: none; /* programmatic focus target only (tabindex="-1"), see the component */
+}
 
-  .bs-navigation-drawer__logo--full {
-    display: none;
-  }
+:host([data-overlay]) .bs-navigation-drawer {
+  position: fixed;
+  inset-block: 0;
+  inset-inline-start: 0;
+  z-index: calc(var(--bs-navigation-drawer-overlay-z-index) + 1);
+  width: var(--bs-navigation-drawer-width);
+  max-width: 100vw;
+  padding: var(--bs-navigation-drawer-padding-y) var(--bs-navigation-drawer-padding-right) var(--bs-navigation-drawer-padding-y)
+    var(--bs-navigation-drawer-padding-left);
+  align-items: stretch;
+  box-shadow: var(--bs-navigation-drawer-overlay-shadow);
+  /* Closed: off-canvas and hidden from the tab order / accessibility tree. `visibility` flips after
+     the slide-out finishes (delayed transition) so the exit is still seen. */
+  transform: translateX(-100%);
+  visibility: hidden;
+  transition:
+    transform var(--bs-navigation-drawer-overlay-duration) var(--bs-easing-standard),
+    visibility 0s linear var(--bs-navigation-drawer-overlay-duration);
+}
 
-  .bs-navigation-drawer__logo--mark {
-    display: flex;
-  }
+:host([data-overlay]:dir(rtl)) .bs-navigation-drawer {
+  transform: translateX(100%);
+}
 
-  .bs-navigation-drawer__title {
-    display: none;
-  }
+:host([data-overlay]) .bs-navigation-drawer.bs-navigation-drawer--open {
+  transform: none;
+  visibility: visible;
+  transition:
+    transform var(--bs-navigation-drawer-overlay-duration) var(--bs-easing-standard),
+    visibility 0s;
+}
+
+/* Fully expanded inside the overlay, whatever `collapsed` says. Nothing sits behind the collapse
+   toggle or the compact search trigger here, so neither is shown. */
+:host([data-overlay]) .bs-navigation-drawer__logo--full {
+  display: flex;
+}
+
+:host([data-overlay]) .bs-navigation-drawer__logo--mark {
+  display: none;
+}
+
+:host([data-overlay]) .bs-navigation-drawer__title {
+  display: block;
+}
+
+:host([data-overlay]) .bs-navigation-drawer__search {
+  display: block;
+}
+
+:host([data-overlay]) .bs-navigation-drawer__search-trigger,
+:host([data-overlay]) .bs-navigation-drawer__collapse {
+  display: none;
+}
+
+.bs-navigation-drawer__backdrop {
+  position: fixed;
+  inset: 0;
+  z-index: var(--bs-navigation-drawer-overlay-z-index);
+  background: var(--bs-navigation-drawer-backdrop);
+  opacity: 0;
+  visibility: hidden;
+  transition:
+    opacity var(--bs-navigation-drawer-overlay-duration) var(--bs-easing-standard),
+    visibility 0s linear var(--bs-navigation-drawer-overlay-duration);
+}
 
-  .bs-navigation-drawer__search {
-    display: none;
+:host([open]) .bs-navigation-drawer__backdrop {
+  opacity: 1;
+  visibility: visible;
+  transition:
+    opacity var(--bs-navigation-drawer-overlay-duration) var(--bs-easing-standard),
+    visibility 0s;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :host([data-overlay]) .bs-navigation-drawer,
+  .bs-navigation-drawer__backdrop {
+    transition: none;
   }
+}
 
-  .bs-navigation-drawer__search-trigger {
-    display: inline-flex;
+@media (forced-colors: active) {
+  :host([data-overlay]) .bs-navigation-drawer {
+    border: 1px solid CanvasText;
   }
 }

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

@@ -1,4 +1,4 @@
-import { h } from "@stencil/core";
+import { Host, 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.
@@ -37,6 +37,14 @@ import { h } from "@stencil/core";
  * 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).
  *
+ * **Small screens (768px and below)** switch to an off-canvas overlay instead of a permanent rail:
+ * the drawer is hidden until `open` is set, then slides in over the page with a backdrop, fully
+ * expanded (labels visible, nested items reachable). Escape or a click on the backdrop closes it and
+ * emits `bsClose`; focus moves into it on open and back to whatever opened it on close. The
+ * collapse toggle and the compact search trigger are not shown in this mode (nothing sits behind
+ * them). The drawer has no trigger of its own -- put a button in your header and set `open` from it.
+ * On wider screens `open` is ignored and nothing changes.
+ *
  * @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
@@ -52,6 +60,7 @@ import { h } from "@stencil/core";
  * @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.
+ * @part backdrop - The scrim behind the overlay (small screens only; clicking it closes the overlay).
  */
 // 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.
@@ -92,11 +101,112 @@ export class BsNavigationDrawer {
      * 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);
+    /** Small screens only (768px and below): whether the off-canvas overlay is shown. Mutable and
+     * reflected -- the drawer sets it back to `false` itself when the user dismisses it (Escape or
+     * the backdrop), and emits `bsClose`. Ignored on wider screens, where the drawer is always in
+     * the page flow. There is no built-in trigger: set this from your own button. */
+    open = false;
+    /** Fires when the user dismisses the overlay (Escape, or a click on the backdrop), after `open`
+     * has been set back to `false`. Does not fire when you set `open = false` yourself. */
+    bsClose;
+    /** Whether the viewport is in the small-screen range (<= 768px), tracked with `matchMedia`. */
+    mobile = false;
+    mediaQuery;
+    focusPending = false;
+    navRef;
+    previouslyFocused;
+    bodyOverflowBefore;
+    get overlayOpen() {
+        return this.mobile && this.open;
+    }
+    connectedCallback() {
+        this.mediaQuery = window.matchMedia?.('(max-width: 768px)');
+        if (this.mediaQuery) {
+            this.mobile = this.mediaQuery.matches;
+            this.mediaQuery.addEventListener('change', this.onMediaChange);
+        }
+    }
+    disconnectedCallback() {
+        this.mediaQuery?.removeEventListener('change', this.onMediaChange);
+        this.unlockScroll();
+    }
+    onMediaChange = (ev) => {
+        this.mobile = ev.matches;
+    };
+    onCollapsedChange() {
+        this.syncItems();
+    }
+    onMobileChange() {
+        this.syncItems();
+        this.applyOverlayState();
+    }
+    onOpenChange() {
+        this.applyOverlayState();
     }
     componentDidLoad() {
-        this.syncItemsCollapsed(this.collapsed);
+        this.syncItems();
+        this.applyOverlayState();
+        this.flushFocus();
+    }
+    componentDidRender() {
+        this.flushFocus();
+    }
+    /** Focus is moved only after the render that makes the panel visible -- focusing earlier races the
+     * re-render (the panel is still `visibility: hidden`), and a hidden element can't take focus. */
+    flushFocus() {
+        if (this.focusPending && this.overlayOpen) {
+            this.focusPending = false;
+            requestAnimationFrame(() => this.navRef?.focus());
+        }
+    }
+    /** In the small-screen overlay the items always use their expanded layout -- the collapsed
+     * (icon-above-caption) layout is for the desktop rail, and would clip labels in a full-width
+     * panel and hide nested items. */
+    syncItems() {
+        this.syncItemsCollapsed(this.mobile ? false : this.collapsed);
+    }
+    /** Scroll lock, focus entry and focus return for the overlay, mirroring `bs-dialog`: the focus
+     * move is deferred a frame because focusing right after the panel becomes visible does not
+     * reliably land. */
+    applyOverlayState() {
+        if (this.overlayOpen) {
+            if (this.bodyOverflowBefore === undefined) {
+                this.bodyOverflowBefore = document.body.style.overflow;
+                document.body.style.overflow = 'hidden';
+            }
+            if (!this.previouslyFocused) {
+                this.previouslyFocused = document.activeElement;
+            }
+            this.focusPending = true;
+        }
+        else {
+            this.focusPending = false;
+            this.unlockScroll();
+            if (this.previouslyFocused?.isConnected)
+                this.previouslyFocused.focus();
+            this.previouslyFocused = undefined;
+        }
+    }
+    unlockScroll() {
+        if (this.bodyOverflowBefore !== undefined) {
+            document.body.style.overflow = this.bodyOverflowBefore;
+            this.bodyOverflowBefore = undefined;
+        }
+    }
+    requestClose = () => {
+        this.open = false;
+        this.bsClose.emit();
+    };
+    onDocumentKeydown(ev) {
+        if (this.overlayOpen && ev.key === 'Escape')
+            this.requestClose();
+    }
+    /** Keeps focus inside the open overlay: focus that lands anywhere outside this component is
+     * pulled back in. `composedPath()` is used so this works across shadow-DOM boundaries (same
+     * approach as `bs-dialog`). */
+    onDocumentFocusIn(ev) {
+        if (this.overlayOpen && !ev.composedPath().includes(this.el))
+            this.navRef?.focus();
     }
     /** 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`
@@ -117,7 +227,12 @@ export class BsNavigationDrawer {
         this.bsSearchClick.emit();
     };
     render() {
-        return (h("nav", { key: '8be5fb4e45d6919408ff7057b963c2d95281b470', class: "bs-navigation-drawer", "aria-label": this.heading }, this.showLogo && (h("div", { key: 'f66ec1272c4c226d1a67fb7321b1247c3be54fb1', part: "logo", class: "bs-navigation-drawer__logo bs-navigation-drawer__logo--full" }, h("bs-logo", { key: '88cddd1d8696f895b33dd141bc2f5bfd3bd260b4', variant: "full", background: this.logoBackground }))), this.showLogo && (h("div", { key: '89b4efebeac6b934cbdd6cf3d25caaf5a36c86e8', part: "logo", class: "bs-navigation-drawer__logo bs-navigation-drawer__logo--mark" }, h("bs-logo", { key: '4f9ef53f8a02d9bb21b134e6a73caf28d9e864fc', variant: "mark", background: this.logoBackground }))), h("div", { key: '841040ad4770b0590ce632db1ce7122766c27ef6', class: "bs-navigation-drawer__title-row" }, h("span", { key: '857e9420aae428b44c2086bec5a2b4205a3dda04', part: "title", class: "bs-navigation-drawer__title" }, this.heading), this.collapsible && (h("button", { key: 'c109b6f3b54268cf729e114a249864fbd57203cc', 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: 'e46c9d2569b59e76398772d7a48e7a02d6b36ba3' })))), h("div", { key: '88031f0fd6cffb8480f2a086efb93a9d6418b4fc', part: "search", class: "bs-navigation-drawer__search" }, h("slot", { key: 'c86cb8c32f754fe81d91b76d8e1a352f9de5b31b', name: "search" })), h("button", { key: '90ade94c988aac8a1b2c855da7b193167b4eeee6', type: "button", part: "search-trigger", class: "bs-navigation-drawer__search-trigger", "aria-label": "Search", onClick: this.onSearchTriggerClick }, h(SearchIcon, { key: 'ff02c6f7f07de15b98bc5799914756e2245e36b9' })), h("div", { key: '41203613ef27dba8768c2755b8653d17c65d02c6', part: "items", class: "bs-navigation-drawer__items" }, h("slot", { key: 'd120d4a7477e748f5be81a5af742bfa558bf00bd' }))));
+        const classes = ['bs-navigation-drawer', this.mobile ? 'bs-navigation-drawer--overlay' : '', this.overlayOpen ? 'bs-navigation-drawer--open' : ''].filter(Boolean).join(' ');
+        return (h(Host, { key: 'c1e563e7b2a9474286671a3f6e1f2d3aed312620', "data-overlay": this.mobile ? '' : undefined }, this.mobile && h("div", { key: 'f6885e88df1607bb9e85a27c4e1cb616ce6b6c0d', part: "backdrop", class: "bs-navigation-drawer__backdrop", onClick: this.requestClose }), h("nav", { key: 'a3086b5203fd3724fce5fe82be394a77a6d9a1e1', ref: el => (this.navRef = el), class: classes, "aria-label": this.heading,
+            // Stays a plain <nav> landmark in every state: ARIA does not allow role="dialog" on <nav>
+            // (axe: aria-allowed-role). Modality is behavioral -- focus is held inside, the page behind is
+            // scrimmed, Escape closes -- rather than announced through aria-modal.
+            tabIndex: this.mobile ? -1 : undefined }, this.showLogo && (h("div", { key: 'c1b8700d6936ae14acf900d3cc83c6a8a7d79a20', part: "logo", class: "bs-navigation-drawer__logo bs-navigation-drawer__logo--full" }, h("bs-logo", { key: '27f4205dcdd609c4709a09dbeb7d4d59a41340db', variant: "full", background: this.logoBackground }))), this.showLogo && (h("div", { key: 'b8474734a50dbd690a9a8d8febd6cda084498d02', part: "logo", class: "bs-navigation-drawer__logo bs-navigation-drawer__logo--mark" }, h("bs-logo", { key: 'c89909a16f7255d24ddaae54ddd2c6cfca361572', variant: "mark", background: this.logoBackground }))), h("div", { key: '83b7641c3c1f8b8307bf8006bbef147ccfdc917c', class: "bs-navigation-drawer__title-row" }, h("span", { key: '97075d0df805b02f3f520c42ef4eceaa377e7064', part: "title", class: "bs-navigation-drawer__title" }, this.heading), this.collapsible && (h("button", { key: '184f4f2f35f74f145621d2854a6a50e52006ebd1', 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: '168c4a4f30f9cf92afd5cffc63e989e0a3d4e45a' })))), h("div", { key: 'd93ec72e4f6ba6f01d4fdc8fc3d9e0c9f0649242', part: "search", class: "bs-navigation-drawer__search" }, h("slot", { key: '3441fb753d206b84e68bb777e60ec849185882b9', name: "search" })), h("button", { key: '98b3bf5e4807afb1ba5a91e2b5238d917f584ab8', type: "button", part: "search-trigger", class: "bs-navigation-drawer__search-trigger", "aria-label": "Search", onClick: this.onSearchTriggerClick }, h(SearchIcon, { key: 'c61c32465503084caab0b3741bc95e3f0f274214' })), h("div", { key: 'f75111a609795d6ed83e3e843a433440a932b730', part: "items", class: "bs-navigation-drawer__items" }, h("slot", { key: '50f7cee1ae4e352b56561740bfc6ff035d521354' })))));
     }
     static get is() { return "bs-navigation-drawer"; }
     static get encapsulation() { return "shadow"; }
@@ -232,9 +347,34 @@ export class BsNavigationDrawer {
                 "reflect": false,
                 "attribute": "show-logo",
                 "defaultValue": "true"
+            },
+            "open": {
+                "type": "boolean",
+                "mutable": true,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Small screens only (768px and below): whether the off-canvas overlay is shown. Mutable and\nreflected -- the drawer sets it back to `false` itself when the user dismisses it (Escape or\nthe backdrop), and emits `bsClose`. Ignored on wider screens, where the drawer is always in\nthe page flow. There is no built-in trigger: set this from your own button."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "open",
+                "defaultValue": "false"
             }
         };
     }
+    static get states() {
+        return {
+            "mobile": {}
+        };
+    }
     static get events() {
         return [{
                 "method": "bsCollapse",
@@ -266,6 +406,21 @@ export class BsNavigationDrawer {
                     "resolved": "void",
                     "references": {}
                 }
+            }, {
+                "method": "bsClose",
+                "name": "bsClose",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Fires when the user dismisses the overlay (Escape, or a click on the backdrop), after `open`\nhas been set back to `false`. Does not fire when you set `open = false` yourself."
+                },
+                "complexType": {
+                    "original": "void",
+                    "resolved": "void",
+                    "references": {}
+                }
             }];
     }
     static get elementRef() { return "el"; }
@@ -273,6 +428,27 @@ export class BsNavigationDrawer {
         return [{
                 "propName": "collapsed",
                 "methodName": "onCollapsedChange"
+            }, {
+                "propName": "mobile",
+                "methodName": "onMobileChange"
+            }, {
+                "propName": "open",
+                "methodName": "onOpenChange"
+            }];
+    }
+    static get listeners() {
+        return [{
+                "name": "keydown",
+                "method": "onDocumentKeydown",
+                "target": "document",
+                "capture": false,
+                "passive": false
+            }, {
+                "name": "focusin",
+                "method": "onDocumentFocusIn",
+                "target": "document",
+                "capture": false,
+                "passive": false
             }];
     }
 }