@momentum-design/components 0.136.0 → 0.137.0

package/dist/components/focustrap/focustrap.component.d.ts

@@ -0,0 +1,68 @@
+import { CSSResult, PropertyValues } from 'lit';
+import { Component } from '../../models';
+declare const FocusTrap_base: import("../../utils/mixins/index.types").Constructor<Component & import("../../utils/mixins/focus/FocusTrapMixin").FocusTrapClassInterface> & typeof Component;
+/**
+ * FocusTrap is a container component that manages keyboard focus within a specified region. It prevents focus from moving outside the container via Tab/Shift+Tab and optionally restores focus to the previously focused element when the trap is deactivated. Commonly used in modals, dialogs, popovers, and other overlay patterns to improve accessibility and user experience.
+ * 
+ * **When to use**
+ * 
+ * - **Custom Modals and dialogs** – Trap focus so users interact only with the dialog content.
+ * - **Custom Popovers and menus** – Keep focus within an overlay component.
+ * - **Custom Dropdown menus** – Ensure focus stays within menu options while open.
+ * - **Multi-step forms** – Control focus flow between steps or sub-sections.
+ * - **Accessible disclosure widgets** – Any collapsible or hidden content that should capture focus when revealed.
+ * 
+ * **When not to use**
+ * 
+ * - **Full-page navigation** – Do not trap focus on the main page; only use on transient overlays.
+ * - **Optional or advisory overlays** – If users can dismiss the overlay and continue with the page, consider whether focus trapping is necessary.
+ * - **Nested focus traps** – Avoid nesting multiple FocusTrap instances; the innermost trap will dominate focus behavior. MDC Dialog, popover and menu components already implement FocusTrap internally, so wrapping them in another FocusTrap is unnecessary and may cause unexpected behavior.
+ * 
+ * @tagname mdc-focustrap
+ * 
+ * @event focus-trap-activated - (React: onFocusTrapActivated) Fired when the focus trap is activated.
+ * @event focus-trap-deactivated - (React: onFocusTrapDeactivated) Fired when the focus trap is deactivated.
+ * 
+ * @slot default - Default slot – place any focusable content here.
+ */
+declare class FocusTrap extends FocusTrap_base {
+    /**
+     * When `true`, disables keyboard focus trapping inside this component.
+     * When `false` (default), focus will be trapped.
+     *
+     * @default false
+     */
+    trapDisabled: boolean;
+    /**
+     * Implements the abstract `focusTrap` required by `FocusTrapMixin`.
+     * Kept in sync with the public `trapDisabled` property (inverted).
+     * @internal
+     */
+    protected focusTrap: boolean;
+    /**
+     * When `true`, disables restoring focus to the previously focused element
+     * when `trapDisabled` is set to `true` or the component is disconnected from the DOM.
+     * When `false` (default), focus will be restored.
+     * @default false
+     */
+    restoreFocusDisabled: boolean;
+    /**
+     * When `true`, the first focusable element inside the container receives focus
+     * automatically when focus trapping is enabled (when `trapDisabled` is `false`).
+     *
+     * @default false
+     */
+    autoFocus: boolean;
+    /** @internal – the element that had focus before the trap was activated */
+    private previouslyFocusedElement;
+    disconnectedCallback(): void;
+    protected updated(changedProperties: PropertyValues): void;
+    /**
+     * Restores focus to the element that was focused before the trap was activated,
+     * if `restoreFocusDisabled` is false.
+     */
+    private restorePreviousFocus;
+    render(): import("lit-html").TemplateResult<1>;
+    static styles: Array<CSSResult>;
+}
+export default FocusTrap;

package/dist/components/focustrap/focustrap.component.js

@@ -0,0 +1,122 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+// AI-Assisted
+import { html } from 'lit';
+import { property } from 'lit/decorators.js';
+import { Component } from '../../models';
+import { FocusTrapMixin } from '../../utils/mixins/focus/FocusTrapMixin';
+import { DEFAULTS } from './focustrap.constants';
+import styles from './focustrap.styles';
+/**
+ * @tagname mdc-focustrap
+ *
+ * @event focus-trap-activated - (React: onFocusTrapActivated) Fired when the focus trap is activated.
+ * @event focus-trap-deactivated - (React: onFocusTrapDeactivated) Fired when the focus trap is deactivated.
+ *
+ * @slot default - Default slot – place any focusable content here.
+ */
+class FocusTrap extends FocusTrapMixin(Component) {
+    constructor() {
+        super(...arguments);
+        /**
+         * When `true`, disables keyboard focus trapping inside this component.
+         * When `false` (default), focus will be trapped.
+         *
+         * @default false
+         */
+        this.trapDisabled = DEFAULTS.TRAP_DISABLED;
+        /**
+         * Implements the abstract `focusTrap` required by `FocusTrapMixin`.
+         * Kept in sync with the public `trapDisabled` property (inverted).
+         * @internal
+         */
+        this.focusTrap = true;
+        /**
+         * When `true`, disables restoring focus to the previously focused element
+         * when `trapDisabled` is set to `true` or the component is disconnected from the DOM.
+         * When `false` (default), focus will be restored.
+         * @default false
+         */
+        this.restoreFocusDisabled = DEFAULTS.RESTORE_FOCUS_DISABLED;
+        /**
+         * When `true`, the first focusable element inside the container receives focus
+         * automatically when focus trapping is enabled (when `trapDisabled` is `false`).
+         *
+         * @default false
+         */
+        this.autoFocus = DEFAULTS.AUTO_FOCUS;
+        /** @internal – the element that had focus before the trap was activated */
+        this.previouslyFocusedElement = null;
+    }
+    disconnectedCallback() {
+        const shouldRestoreFocus = !this.trapDisabled;
+        this.deactivateFocusTrap();
+        if (shouldRestoreFocus) {
+            this.restorePreviousFocus();
+        }
+        super.disconnectedCallback();
+    }
+    updated(changedProperties) {
+        var _a;
+        super.updated(changedProperties);
+        if (changedProperties.has('trapDisabled')) {
+            // Keep focusTrap in sync with trapDisabled (inverted)
+            this.focusTrap = !this.trapDisabled;
+            if (!this.trapDisabled) {
+                this.previouslyFocusedElement = (_a = document.activeElement) !== null && _a !== void 0 ? _a : null;
+                this.activateFocusTrap();
+                if (this.autoFocus) {
+                    // Slotted children (e.g. mdc-input) may not have completed their own first render yet
+                    // at this point, so findFocusable() would find nothing. Defer to the next animation
+                    // frame, by which time all pending Lit updates have flushed.
+                    requestAnimationFrame(() => {
+                        if (this.autoFocus && !this.trapDisabled) {
+                            this.setInitialFocus();
+                        }
+                    });
+                }
+                this.dispatchEvent(new CustomEvent('focus-trap-activated', { bubbles: true, composed: true }));
+            }
+            else {
+                this.deactivateFocusTrap();
+                this.restorePreviousFocus();
+                this.dispatchEvent(new CustomEvent('focus-trap-deactivated', { bubbles: true, composed: true }));
+            }
+        }
+    }
+    /**
+     * Restores focus to the element that was focused before the trap was activated,
+     * if `restoreFocusDisabled` is false.
+     */
+    restorePreviousFocus() {
+        if (!this.restoreFocusDisabled && this.previouslyFocusedElement) {
+            this.previouslyFocusedElement.focus({ preventScroll: true });
+        }
+        this.previouslyFocusedElement = null;
+    }
+    render() {
+        return html `<slot></slot>`;
+    }
+}
+FocusTrap.styles = [...Component.styles, ...styles];
+__decorate([
+    property({ type: Boolean, reflect: true, attribute: 'trap-disabled' }),
+    __metadata("design:type", Boolean)
+], FocusTrap.prototype, "trapDisabled", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true, attribute: 'restore-focus-disabled' }),
+    __metadata("design:type", Boolean)
+], FocusTrap.prototype, "restoreFocusDisabled", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true, attribute: 'auto-focus' }),
+    __metadata("design:type", Boolean)
+], FocusTrap.prototype, "autoFocus", void 0);
+export default FocusTrap;
+// End AI-Assisted

package/dist/components/focustrap/focustrap.constants.d.ts

@@ -0,0 +1,7 @@
+declare const TAG_NAME: "mdc-focustrap";
+declare const DEFAULTS: {
+    TRAP_DISABLED: boolean;
+    RESTORE_FOCUS_DISABLED: boolean;
+    AUTO_FOCUS: boolean;
+};
+export { TAG_NAME, DEFAULTS };

package/dist/components/focustrap/focustrap.constants.js

@@ -0,0 +1,10 @@
+// AI-Assisted
+import utils from '../../utils/tag-name';
+const TAG_NAME = utils.constructTagName('focustrap');
+const DEFAULTS = {
+    TRAP_DISABLED: false,
+    RESTORE_FOCUS_DISABLED: false,
+    AUTO_FOCUS: false,
+};
+export { TAG_NAME, DEFAULTS };
+// End AI-Assisted

package/dist/components/focustrap/focustrap.styles.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("lit").CSSResult[];
+export default _default;

package/dist/components/focustrap/focustrap.styles.js

@@ -0,0 +1,9 @@
+// AI-Assisted
+import { css } from 'lit';
+const styles = css `
+  :host {
+    display: contents;
+  }
+`;
+export default [styles];
+// End AI-Assisted

package/dist/components/focustrap/focustrap.types.d.ts

@@ -0,0 +1,13 @@
+interface Events {
+    /** Fired when the focus trap is activated (React: onFocusTrapActivated) */
+    onFocusTrapActivatedEvent: Event;
+    /** Fired when the focus trap is deactivated (React: onFocusTrapDeactivated) */
+    onFocusTrapDeactivatedEvent: Event;
+}
+declare global {
+    interface GlobalEventHandlersEventMap {
+        focustrapactivated: Event;
+        focustrapdeactivated: Event;
+    }
+}
+export type { Events };

package/dist/components/focustrap/focustrap.types.js

@@ -0,0 +1,2 @@
+export {};
+// End AI-Assisted

package/dist/components/focustrap/index.d.ts

@@ -0,0 +1,7 @@
+import FocusTrap from './focustrap.component';
+declare global {
+    interface HTMLElementTagNameMap {
+        ['mdc-focustrap']: FocusTrap;
+    }
+}
+export default FocusTrap;

package/dist/components/focustrap/index.js

@@ -0,0 +1,4 @@
+import FocusTrap from './focustrap.component';
+import { TAG_NAME } from './focustrap.constants';
+FocusTrap.register(TAG_NAME);
+export default FocusTrap;

package/dist/components/toast/toast.component.d.ts

@@ -111,7 +111,7 @@ declare class Toast extends Toast_base {
     private updateDetailedSlotPresence;
     private updateFooterButtonsPresence;
     protected firstUpdated(changedProperties: PropertyValues): Promise<void>;
-    protected updated(changedProperties: PropertyValues): void;
+    protected updated(changedProperties: PropertyValues): Promise<void>;
     protected renderIcon(iconName: string): import("lit-html").TemplateResult<1> | typeof nothing;
     private canRenderToggleButton;
     private shouldRenderToggleButton;

package/dist/components/toast/toast.component.js

@@ -122,15 +122,17 @@ class Toast extends FooterMixin(Component) {
         super.firstUpdated(changedProperties);
         this.updateDetailedSlotPresence();
         this.updateDataExpanded();
-        await this.updateComplete;
-        if (hasOverflowMixin(this.headerTextElement)) {
-            this.hasOverflowingHeaderText = this.headerTextElement.isHeightOverflowing();
-        }
     }
-    updated(changedProperties) {
+    async updated(changedProperties) {
         if (changedProperties.has('showMoreText') || changedProperties.has('showLessText')) {
             this.updateDataExpanded();
         }
+        if (changedProperties.has('headerText')) {
+            await this.updateComplete;
+            if (hasOverflowMixin(this.headerTextElement)) {
+                this.hasOverflowingHeaderText = this.headerTextElement.isHeightOverflowing();
+            }
+        }
     }
     renderIcon(iconName) {
         if (!iconName)

package/dist/custom-elements.json

@@ -18189,6 +18189,134 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "components/focustrap/focustrap.component.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "",
+          "name": "FocusTrap",
+          "slots": [
+            {
+              "description": "Default slot – place any focusable content here.",
+              "name": "default"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "autoFocus",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "When `true`, the first focusable element inside the container receives focus\nautomatically when focus trapping is enabled (when `trapDisabled` is `false`).",
+              "default": "false",
+              "attribute": "auto-focus",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "restoreFocusDisabled",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "When `true`, disables restoring focus to the previously focused element\nwhen `trapDisabled` is set to `true` or the component is disconnected from the DOM.\nWhen `false` (default), focus will be restored.",
+              "default": "false",
+              "attribute": "restore-focus-disabled",
+              "reflects": true
+            },
+            {
+              "kind": "method",
+              "name": "restorePreviousFocus",
+              "privacy": "private",
+              "description": "Restores focus to the element that was focused before the trap was activated,\nif `restoreFocusDisabled` is false."
+            },
+            {
+              "kind": "field",
+              "name": "trapDisabled",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "When `true`, disables keyboard focus trapping inside this component.\nWhen `false` (default), focus will be trapped.",
+              "default": "false",
+              "attribute": "trap-disabled",
+              "reflects": true
+            }
+          ],
+          "events": [
+            {
+              "name": "focus-trap-activated",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "(React: onFocusTrapActivated) Fired when the focus trap is activated.",
+              "reactName": "onFocusTrapActivated"
+            },
+            {
+              "name": "focus-trap-deactivated",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "(React: onFocusTrapDeactivated) Fired when the focus trap is deactivated.",
+              "reactName": "onFocusTrapDeactivated"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "trap-disabled",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "When `true`, disables keyboard focus trapping inside this component.\nWhen `false` (default), focus will be trapped.",
+              "default": "false",
+              "fieldName": "trapDisabled"
+            },
+            {
+              "name": "restore-focus-disabled",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "When `true`, disables restoring focus to the previously focused element\nwhen `trapDisabled` is set to `true` or the component is disconnected from the DOM.\nWhen `false` (default), focus will be restored.",
+              "default": "false",
+              "fieldName": "restoreFocusDisabled"
+            },
+            {
+              "name": "auto-focus",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "When `true`, the first focusable element inside the container receives focus\nautomatically when focus trapping is enabled (when `trapDisabled` is `false`).",
+              "default": "false",
+              "fieldName": "autoFocus"
+            }
+          ],
+          "mixins": [
+            {
+              "name": "FocusTrapMixin",
+              "module": "/src/utils/mixins/focus/FocusTrapMixin"
+            }
+          ],
+          "superclass": {
+            "name": "Component",
+            "module": "/src/models"
+          },
+          "tagName": "mdc-focustrap",
+          "jsDoc": "/**\n * @tagname mdc-focustrap\n *\n * @event focus-trap-activated - (React: onFocusTrapActivated) Fired when the focus trap is activated.\n * @event focus-trap-deactivated - (React: onFocusTrapDeactivated) Fired when the focus trap is deactivated.\n *\n * @slot default - Default slot – place any focusable content here.\n */",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "default",
+          "declaration": {
+            "name": "FocusTrap",
+            "module": "components/focustrap/focustrap.component.js"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "components/formfieldgroup/formfieldgroup.component.js",

package/dist/index.d.ts

@@ -91,6 +91,7 @@ import Banner from './components/banner';
 import Buttonsimple from './components/buttonsimple';
 import Verticaltablist from './components/verticaltablist';
 import StatusMessage from './components/statusmessage';
+import FocusTrap from './components/focustrap';
 import type { AvatarSize } from './components/avatar/avatar.types';
 import type { BadgeType } from './components/badge/badge.types';
 import type { ColorType as ChipColorType } from './components/staticchip/staticchip.types';
@@ -121,6 +122,6 @@ import type { TimePickerChangeEvent, TimePickerInputEvent } from './components/t
 import type { DatePickerChangeEvent, DatePickerInputEvent } from './components/datepicker/datepicker.types';
 import type { CalendarDateSelectedEvent, CalendarMonthChangedEvent } from './components/calendar/calendar.types';
 import type { ListBoxChangeEvent } from './components/listbox/listbox.types';
-export { Accordion, AccordionButton, AccordionGroup, AlertChip, Animation, AnnouncementDialog, Appheader, Avatar, AvatarButton, Badge, Brandvisual, Bullet, Button, ButtonGroup, ButtonLink, Calendar, Card, CardButton, CardCheckbox, CardRadio, Checkbox, Chip, Coachmark, ControlTypeProvider, DatePicker, Dialog, Divider, FilterChip, FormfieldGroup, Icon, IconProvider, Illustration, IllustrationProvider, Input, InputChip, Link, LinkButton, Linksimple, List, Listheader, ListItem, Marker, MenuBar, MenuItem, MenuItemCheckbox, MenuItemRadio, MenuPopover, MenuSection, NavMenuItem, OptGroup, Option, Password, Popover, Presence, Progressbar, Progressspinner, Radio, RadioGroup, ResponsiveSettingsProvider, ScreenreaderAnnouncer, Searchfield, Searchpopover, Select, SelectListbox, SideNavigation, Skeleton, Spinner, StaticChip, StaticCheckbox, StaticRadio, StaticToggle, Stepper, StepperConnector, StepperItem, Tab, TabList, Text, Textarea, TimePicker, ThemeProvider, Toast, Toggle, Typewriter, ToggleTip, Tooltip, VirtualizedList, Combobox, Slider, ListBox, Banner, Buttonsimple, Verticaltablist, StatusMessage, };
+export { Accordion, AccordionButton, AccordionGroup, AlertChip, Animation, AnnouncementDialog, Appheader, Avatar, AvatarButton, Badge, Brandvisual, Bullet, Button, ButtonGroup, ButtonLink, Calendar, Card, CardButton, CardCheckbox, CardRadio, Checkbox, Chip, Coachmark, ControlTypeProvider, DatePicker, Dialog, Divider, FilterChip, FormfieldGroup, Icon, IconProvider, Illustration, IllustrationProvider, Input, InputChip, Link, LinkButton, Linksimple, List, Listheader, ListItem, Marker, MenuBar, MenuItem, MenuItemCheckbox, MenuItemRadio, MenuPopover, MenuSection, NavMenuItem, OptGroup, Option, Password, Popover, Presence, Progressbar, Progressspinner, Radio, RadioGroup, ResponsiveSettingsProvider, ScreenreaderAnnouncer, Searchfield, Searchpopover, Select, SelectListbox, SideNavigation, Skeleton, Spinner, StaticChip, StaticCheckbox, StaticRadio, StaticToggle, Stepper, StepperConnector, StepperItem, Tab, TabList, Text, Textarea, TimePicker, ThemeProvider, Toast, Toggle, Typewriter, ToggleTip, Tooltip, VirtualizedList, Combobox, Slider, ListBox, Banner, Buttonsimple, Verticaltablist, StatusMessage, FocusTrap, };
 export type { AvatarSize, BadgeType, ChipColorType, ButtonColor, ButtonVariant, IconButtonSize, MenuPopoverActionEvent, MenuPopoverChangeEvent, MenuSectionChangeEvent, PillButtonSize, PopoverPlacement, PresenceType, SkeletonVariant, SelectChangeEvent, SelectInputEvent, SpinnerSize, SpinnerVariant, SliderChangeEvent, StatusMessageSeverity, TextType, TypewriterType, InputInputEvent, InputChangeEvent, InputFocusEvent, InputBlurEvent, InputClearEvent, VirtualizedListScrollEvent, TablistChangeEvent, TextareaInputEvent, TextareaChangeEvent, TextareaFocusEvent, TextareaBlurEvent, TextareaLimitExceededEvent, ToggleOnChangeEvent, CheckboxOnChangeEvent, LinkButtonSize, TimePickerChangeEvent, TimePickerInputEvent, DatePickerChangeEvent, DatePickerInputEvent, CalendarDateSelectedEvent, CalendarMonthChangedEvent, VerticaltablistChangeEvent, ListBoxChangeEvent, };
 export { BUTTON_COLORS, BUTTON_VARIANTS, ICON_BUTTON_SIZES, inMemoryCache, PILL_BUTTON_SIZES, SKELETON_VARIANTS, webAPIAssetsCache, };

package/dist/index.js

@@ -93,11 +93,12 @@ import Banner from './components/banner';
 import Buttonsimple from './components/buttonsimple';
 import Verticaltablist from './components/verticaltablist';
 import StatusMessage from './components/statusmessage';
+import FocusTrap from './components/focustrap';
 // Constants / Utils Imports
 import { BUTTON_COLORS, BUTTON_VARIANTS, ICON_BUTTON_SIZES, PILL_BUTTON_SIZES, } from './components/button/button.constants';
 import { SKELETON_VARIANTS } from './components/skeleton/skeleton.constants';
 import { inMemoryCache, webAPIAssetsCache } from './utils/assets-cache';
 // Components Exports
-export { Accordion, AccordionButton, AccordionGroup, AlertChip, Animation, AnnouncementDialog, Appheader, Avatar, AvatarButton, Badge, Brandvisual, Bullet, Button, ButtonGroup, ButtonLink, Calendar, Card, CardButton, CardCheckbox, CardRadio, Checkbox, Chip, Coachmark, ControlTypeProvider, DatePicker, Dialog, Divider, FilterChip, FormfieldGroup, Icon, IconProvider, Illustration, IllustrationProvider, Input, InputChip, Link, LinkButton, Linksimple, List, Listheader, ListItem, Marker, MenuBar, MenuItem, MenuItemCheckbox, MenuItemRadio, MenuPopover, MenuSection, NavMenuItem, OptGroup, Option, Password, Popover, Presence, Progressbar, Progressspinner, Radio, RadioGroup, ResponsiveSettingsProvider, ScreenreaderAnnouncer, Searchfield, Searchpopover, Select, SelectListbox, SideNavigation, Skeleton, Spinner, StaticChip, StaticCheckbox, StaticRadio, StaticToggle, Stepper, StepperConnector, StepperItem, Tab, TabList, Text, Textarea, TimePicker, ThemeProvider, Toast, Toggle, Typewriter, ToggleTip, Tooltip, VirtualizedList, Combobox, Slider, ListBox, Banner, Buttonsimple, Verticaltablist, StatusMessage, };
+export { Accordion, AccordionButton, AccordionGroup, AlertChip, Animation, AnnouncementDialog, Appheader, Avatar, AvatarButton, Badge, Brandvisual, Bullet, Button, ButtonGroup, ButtonLink, Calendar, Card, CardButton, CardCheckbox, CardRadio, Checkbox, Chip, Coachmark, ControlTypeProvider, DatePicker, Dialog, Divider, FilterChip, FormfieldGroup, Icon, IconProvider, Illustration, IllustrationProvider, Input, InputChip, Link, LinkButton, Linksimple, List, Listheader, ListItem, Marker, MenuBar, MenuItem, MenuItemCheckbox, MenuItemRadio, MenuPopover, MenuSection, NavMenuItem, OptGroup, Option, Password, Popover, Presence, Progressbar, Progressspinner, Radio, RadioGroup, ResponsiveSettingsProvider, ScreenreaderAnnouncer, Searchfield, Searchpopover, Select, SelectListbox, SideNavigation, Skeleton, Spinner, StaticChip, StaticCheckbox, StaticRadio, StaticToggle, Stepper, StepperConnector, StepperItem, Tab, TabList, Text, Textarea, TimePicker, ThemeProvider, Toast, Toggle, Typewriter, ToggleTip, Tooltip, VirtualizedList, Combobox, Slider, ListBox, Banner, Buttonsimple, Verticaltablist, StatusMessage, FocusTrap, };
 // Constants / Utils Exports
 export { BUTTON_COLORS, BUTTON_VARIANTS, ICON_BUTTON_SIZES, inMemoryCache, PILL_BUTTON_SIZES, SKELETON_VARIANTS, webAPIAssetsCache, };

package/dist/react/focustrap/index.d.ts

@@ -0,0 +1,32 @@
+import { type EventName } from '@lit/react';
+import Component from '../../components/focustrap';
+import type { Events } from '../../components/focustrap/focustrap.types';
+/**
+ * FocusTrap is a container component that manages keyboard focus within a specified region. It prevents focus from moving outside the container via Tab/Shift+Tab and optionally restores focus to the previously focused element when the trap is deactivated. Commonly used in modals, dialogs, popovers, and other overlay patterns to improve accessibility and user experience.
+ * 
+ * **When to use**
+ * 
+ * - **Custom Modals and dialogs** – Trap focus so users interact only with the dialog content.
+ * - **Custom Popovers and menus** – Keep focus within an overlay component.
+ * - **Custom Dropdown menus** – Ensure focus stays within menu options while open.
+ * - **Multi-step forms** – Control focus flow between steps or sub-sections.
+ * - **Accessible disclosure widgets** – Any collapsible or hidden content that should capture focus when revealed.
+ * 
+ * **When not to use**
+ * 
+ * - **Full-page navigation** – Do not trap focus on the main page; only use on transient overlays.
+ * - **Optional or advisory overlays** – If users can dismiss the overlay and continue with the page, consider whether focus trapping is necessary.
+ * - **Nested focus traps** – Avoid nesting multiple FocusTrap instances; the innermost trap will dominate focus behavior. MDC Dialog, popover and menu components already implement FocusTrap internally, so wrapping them in another FocusTrap is unnecessary and may cause unexpected behavior.
+ * 
+ * @tagname mdc-focustrap
+ * 
+ * @event focus-trap-activated - (React: onFocusTrapActivated) Fired when the focus trap is activated.
+ * @event focus-trap-deactivated - (React: onFocusTrapDeactivated) Fired when the focus trap is deactivated.
+ * 
+ * @slot default - Default slot – place any focusable content here.
+ */
+declare const reactWrapper: import("@lit/react").ReactWebComponent<Component, {
+    onFocusTrapActivated: EventName<Events["onFocusTrapActivatedEvent"]>;
+    onFocusTrapDeactivated: EventName<Events["onFocusTrapDeactivatedEvent"]>;
+}>;
+export default reactWrapper;

package/dist/react/focustrap/index.js

@@ -0,0 +1,23 @@
+import * as React from 'react';
+import { createComponent } from '@lit/react';
+import Component from '../../components/focustrap';
+import { TAG_NAME } from '../../components/focustrap/focustrap.constants';
+/**
+ * @tagname mdc-focustrap
+ *
+ * @event focus-trap-activated - (React: onFocusTrapActivated) Fired when the focus trap is activated.
+ * @event focus-trap-deactivated - (React: onFocusTrapDeactivated) Fired when the focus trap is deactivated.
+ *
+ * @slot default - Default slot – place any focusable content here.
+ */
+const reactWrapper = createComponent({
+    tagName: TAG_NAME,
+    elementClass: Component,
+    react: React,
+    events: {
+        onFocusTrapActivated: 'focus-trap-activated',
+        onFocusTrapDeactivated: 'focus-trap-deactivated',
+    },
+    displayName: 'FocusTrap',
+});
+export default reactWrapper;

package/dist/react/index.d.ts

@@ -29,6 +29,7 @@ export { default as DatePicker } from './datepicker';
 export { default as Dialog } from './dialog';
 export { default as Divider } from './divider';
 export { default as FilterChip } from './filterchip';
+export { default as FocusTrap } from './focustrap';
 export { default as FormfieldGroup } from './formfieldgroup';
 export { default as FormfieldWrapper } from './formfieldwrapper';
 export { default as Icon } from './icon';

package/dist/react/index.js

@@ -29,6 +29,7 @@ export { default as DatePicker } from './datepicker';
 export { default as Dialog } from './dialog';
 export { default as Divider } from './divider';
 export { default as FilterChip } from './filterchip';
+export { default as FocusTrap } from './focustrap';
 export { default as FormfieldGroup } from './formfieldgroup';
 export { default as FormfieldWrapper } from './formfieldwrapper';
 export { default as Icon } from './icon';

package/dist/utils/mixins/focus/FocusTrapMixin.js

@@ -148,6 +148,12 @@ export const FocusTrapMixin = (superClass) => {
             }
             const activeElement = this.getDeepActiveElement();
             const activeIndex = this.findElement(activeElement);
+            // If focus currently sits outside this trap's focusable elements (e.g. on a sibling
+            // element in the document), do not hijack Tab navigation - let the browser's default
+            // behavior move focus naturally, including into the trap.
+            if (activeIndex === -1) {
+                return;
+            }
             const direction = event.shiftKey;
             if (direction) {
                 this.focusTrapIndex = this.calculateNextIndex(activeIndex, -1);

package/dist/utils/mixins/focus/FocusTrapStack.js

@@ -22,6 +22,7 @@ export class FocusTrapStack {
     static removeKeydownListener() {
         if (this.currentKeydownListener) {
             document.removeEventListener('keydown', this.currentKeydownListener);
+            this.currentKeydownListener = null;
         }
     }
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@momentum-design/components",
   "packageManager": "yarn@3.2.4",
-  "version": "0.136.0",
+  "version": "0.137.0",
   "engines": {
     "node": ">=24.0.0",
     "npm": ">=8.0.0"