@winkintel/bootstrap-svelte 1.0.7 → 1.0.8

package/README.md

@@ -174,7 +174,7 @@ Interactive components are implemented as Svelte components rather than requirin
 
 ## Status and feedback
 
-This package is published as `1.0.7`, but feedback from Svelte developers is still very welcome. Useful feedback includes:
+This package is published as `1.0.8`, but feedback from Svelte developers is still very welcome. Useful feedback includes:
 
 - Component API ergonomics
 - Svelte 5 idioms and runes compatibility

package/dist/Dropdown/dropdown-menu.svelte

@@ -21,14 +21,16 @@ The container for dropdown items.
 - `isDark` (boolean): Optional. Makes the dropdown menu dark-themed, default is false.
 - `isEnd` (boolean): Optional. Aligns the dropdown menu to the end of its parent, default is false.
 - `offset` (number[]): Optional. Offset for the dropdown menu position, default is `[0, 2]`.
+- `onkeydown` (EventListener): Optional. Keydown handler, called after the menu's own Escape dismissal.
 -->
 <script lang="ts">import { uniqueClsx } from '../common/css.js';
+import { noop } from '../common/noop.js';
 import { Portal } from '../index.js';
 import { onMount } from 'svelte';
 import { DropdownMenuState, initDropdownMenuState } from './dropdown.svelte.js';
 // Generate a unique ID for the dropdown menu
 const uid = $props.id();
-let { children, class: classValues, container = false, elementRef = $bindable(null), id = `dropdown-menu-${uid}`, isDark = false, isEnd = false, offset = [0, 2], ...restOfProps } = $props();
+let { children, class: classValues, container = false, elementRef = $bindable(null), id = `dropdown-menu-${uid}`, isDark = false, isEnd = false, offset = [0, 2], onkeydown = noop, ...restOfProps } = $props();
 let containerElement = $derived(container === false ? 'body' : container);
 const menuState = initDropdownMenuState({
     get elementRef() {
@@ -63,9 +65,14 @@ $effect(() => {
 $effect(() => {
     menuState.isEnd = isEnd;
 });
+const handleKeydown = (event) => {
+    menuState.onkeydown(event);
+    onkeydown(event);
+};
 </script>
 
 <svelte:body onclick={menuState.bodyOnclick} />
+<svelte:window onkeyup={menuState.windowOnkeyup} />
 
 <Portal target={containerElement} disabled={container === false}>
     <ul
@@ -75,6 +82,7 @@ $effect(() => {
         data-bs-popper={menuState.isShown && menuState.root.isNavItem ? 'static' : undefined}
         data-popper-placement={menuState.popperPlacement}
         {id}
+        onkeydown={handleKeydown}
         role={menuState.root.hasItems ? 'menu' : undefined}
         {...restOfProps}>
         {@render children?.()}

package/dist/Dropdown/dropdown-menu.svelte.d.ts

@@ -21,6 +21,7 @@ import type { Dropdown } from './index.js';
  * - `isDark` (boolean): Optional. Makes the dropdown menu dark-themed, default is false.
  * - `isEnd` (boolean): Optional. Aligns the dropdown menu to the end of its parent, default is false.
  * - `offset` (number[]): Optional. Offset for the dropdown menu position, default is `[0, 2]`.
+ * - `onkeydown` (EventListener): Optional. Keydown handler, called after the menu's own Escape dismissal.
  */
 declare const DropdownMenu: import("svelte").Component<Dropdown.MenuProps, {}, "elementRef">;
 type DropdownMenu = ReturnType<typeof DropdownMenu>;

package/dist/Dropdown/dropdown-toggle.svelte

@@ -28,6 +28,9 @@ import { DropdownToggleState, initDropdownToggleState } from './dropdown.svelte.
 const uid = $props.id();
 let { children, class: classValues, colorVariant, disabled = false, elementRef = $bindable(null), href, id = `dropdown-toggle-${uid}`, isSplit = false, onclick = noop, onkeydown = noop, size, type, ...restOfProps } = $props();
 const toggleState = initDropdownToggleState({
+    get elementRef() {
+        return elementRef;
+    },
     get id() {
         return id;
     },

package/dist/Dropdown/dropdown.svelte.js

@@ -13,7 +13,9 @@ export class DropdownRootState {
     #isNavItem = $state(false);
     #isShown = $state(false);
     #items = $state([]);
+    #menu = null; // The menu belonging to this dropdown, registered on construction.
     #reorderScheduled = false;
+    #toggle = null; // The toggle that controls this dropdown, registered on construction.
     ariaLabelledBy = $state(undefined); // Used for accessibility, linking the dropdown to a label.
     constructor(props) {
         this.props = props;
@@ -25,6 +27,8 @@ export class DropdownRootState {
         // Bind the method to ensure `this` context is correct when passed as a callback.
         this.focusOnNextItem = this.focusOnNextItem.bind(this);
         this.focusOnPreviousItem = this.focusOnPreviousItem.bind(this);
+        this.focusOnToggle = this.focusOnToggle.bind(this);
+        this.hide = this.hide.bind(this);
         this.registerItem = this.registerItem.bind(this);
         this.reorderItems = this.reorderItems.bind(this);
         this.scheduleReorderItems = this.scheduleReorderItems.bind(this);
@@ -82,12 +86,43 @@ export class DropdownRootState {
     get isShown() {
         return this.#isShown;
     }
+    get menu() {
+        return this.#menu;
+    }
+    set menu(menu) {
+        this.#menu = menu;
+    }
+    get toggle() {
+        return this.#toggle;
+    }
+    set toggle(toggle) {
+        this.#toggle = toggle;
+    }
+    // True when the given element is part of this dropdown — its root (toggle included)
+    // or its menu, which may be portaled outside the root via the menu's `container` prop.
+    containsElement(element) {
+        if (!element) {
+            return false;
+        }
+        return Boolean(this.#elementRef?.contains(element) || this.#menu?.elementRef?.contains(element));
+    }
     focusOnNextItem() {
         this.focusOnItemInDirection(1);
     }
     focusOnPreviousItem() {
         this.focusOnItemInDirection(-1);
     }
+    focusOnToggle() {
+        this.#toggle?.props.elementRef?.focus();
+    }
+    // Closes the dropdown if it is open, firing the onHide/onHidden callbacks.
+    // Unlike toggleIsShown this is a no-op when the dropdown is already closed.
+    hide(event) {
+        if (!this.#isShown) {
+            return;
+        }
+        this.toggleIsShown(event);
+    }
     registerItem(item) {
         item.itemIndex = this.#items.length; // Set the item's index based on current length.
         this.#items = [...this.#items, item];
@@ -174,6 +209,7 @@ export class DropdownToggleState {
         // Bind the method to ensure `this` context is correct when used as an event handler.
         this.onclick = this.onclick.bind(this);
         this.onkeydown = this.onkeydown.bind(this);
+        this.root.toggle = this; // Let the root find the toggle again, e.g. to restore focus on Escape.
         if (this.props.isSplit && !this.root.isButtonGroup) {
             // If the toggle is a split button, the root must be treated as a button group
             // to ensure correct Bootstrap styling and layout.
@@ -215,7 +251,10 @@ export class DropdownMenuState {
         this.destroyPopper = this.destroyPopper.bind(this);
         this.determinePopperPlacement = this.determinePopperPlacement.bind(this);
         this.dispose = this.dispose.bind(this);
+        this.onkeydown = this.onkeydown.bind(this);
         this.syncIsEndWithRoot = this.syncIsEndWithRoot.bind(this);
+        this.windowOnkeyup = this.windowOnkeyup.bind(this);
+        this.root.menu = this; // Let the root reach the menu element, which may be portaled outside the root.
         // Ensure the dropdown menu's end alignment is consistent with the root's direction.
         this.syncIsEndWithRoot();
         // Effect to manage the Popper.js instance lifecycle.
@@ -274,9 +313,38 @@ export class DropdownMenuState {
             this.root.toggleIsShown(event);
         }
     }
+    // Backstop for Escape pressed on focusable content inside the menu that is not a
+    // Dropdown.Item — a form input, a plain link, a consumer's own button. Items and the
+    // toggle consume Escape before it can bubble this far, so this never double-handles.
+    onkeydown(event) {
+        if (event.key !== 'Escape') {
+            return;
+        }
+        handleEscape(event, this.root);
+    }
+    // Closes the dropdown once Tab has moved focus out of it. Handled on keyup rather than
+    // keydown because focus has not moved yet while the key is down, and at window level
+    // because the newly focused element is usually outside this component's markup.
+    windowOnkeyup(event) {
+        if (!this.isShown || event.key !== 'Tab') {
+            return;
+        }
+        if (this.root.containsElement(document.activeElement)) {
+            // Focus moved between items inside the dropdown, so it stays open.
+            return;
+        }
+        // Tabbing away is an interaction outside the dropdown, so it follows the same
+        // autoClose rules as an outside click.
+        if (this.autoClose === true || this.autoClose === 'outside') {
+            this.root.hide(event);
+        }
+    }
     // Cleans up resources, particularly the Popper.js instance and element references.
     dispose() {
         this.destroyPopper();
+        if (this.root.menu === this) {
+            this.root.menu = null;
+        }
         this.#elementRef = null;
         this.#rootElementRef = null; // Clearing derived state source if it were directly settable.
         this.#popperInstance = null;
@@ -449,15 +517,52 @@ export function initDropdownItemState(props) {
     rootState.registerItem(itemState);
     return itemState;
 }
+/**
+ * Dismisses an open dropdown in response to Escape, returning focus to the toggle.
+ *
+ * Shared by the toggle, the items, and the menu itself. The menu is the backstop that
+ * catches Escape from focusable content a consumer renders inside it — inputs, links,
+ * arbitrary buttons — which are not Dropdown.Items and carry no handler of their own.
+ * Because the toggle and items stop a consumed Escape from propagating, the menu-level
+ * handler never sees the same key twice.
+ *
+ * Escape ignores autoClose: it is an explicit dismissal rather than an incidental one.
+ *
+ * @param event KeyboardEvent
+ * @param root DropdownRootState
+ */
+function handleEscape(event, root) {
+    if (!root.isShown) {
+        return;
+    }
+    event.preventDefault();
+    // Stop the event here so an ancestor that also dismisses on Escape (a modal, an
+    // offcanvas, an app-level sidebar) does not close as well. Escape should unwind one
+    // layer at a time, which is what Bootstrap's own dropdown does.
+    //
+    // This covers listeners in the bubble path only. A listener bound on document or
+    // window in the *capture* phase runs before the event ever reaches the dropdown and
+    // cannot be stopped from here — notably Bootstrap's own data-API handlers, which are
+    // registered with capture. Loading Bootstrap's JS bundle alongside this package makes
+    // both implementations respond to the same markup and is not a supported setup.
+    event.stopPropagation();
+    root.hide(event);
+    root.focusOnToggle();
+}
 /**
  * Handles keyboard navigation for the toggle and items within the dropdown.
- * Supports opening the dropdown with ArrowUp/ArrowDown and navigating between items.
+ * Supports opening the dropdown with ArrowUp/ArrowDown, navigating between items,
+ * and dismissing an open dropdown with Escape.
  *
  * @param event KeyboardEvent
  * @param root DropdownRootState
  */
 function handleKeydown(event, root) {
     const { key } = event;
+    if (key === 'Escape') {
+        handleEscape(event, root);
+        return;
+    }
     const isUpOrDownEvent = ['ArrowUp', 'ArrowDown'].includes(event.key);
     if (isUpOrDownEvent && !root.isShown) {
         event.preventDefault();

package/dist/Dropdown/types.d.ts

@@ -25,6 +25,7 @@ export type DropdownMenuProps = UListElement & {
     isDark?: boolean;
     isEnd?: boolean;
     offset?: PopperOffset;
+    onkeydown?: EventListener;
 };
 export type DropdownItemProps = AnchorElement & {
     href?: HTMLAnchorAttributes['href'];

package/package.json

@@ -1,7 +1,7 @@
 {
     "author": "Wink, Inc.",
     "name": "@winkintel/bootstrap-svelte",
-    "version": "1.0.7",
+    "version": "1.0.8",
     "description": "Bootstrap components for Svelte 5 with TypeScript support.",
     "license": "Apache-2.0",
     "repository": {