@momentum-design/components 0.134.7 → 0.134.9

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

@@ -32,6 +32,9 @@ import { ShortestDistanceWeights, SpatialNavigationContextValue, SpatialNavigati
  * Elements with `data-spatial-focusable` are treated as focusable even if they would otherwise not be
  * (e.g., `tabindex="-1"`).
  *
+ * Elements with `data-spatial-exclude` are excluded (with its subtree) from the navigation, even if they
+ * are focusable.
+ *
  * ### Overwrite next element
  *
  * Override automatic navigation by adding one of these attributes to a focusable element:
@@ -82,7 +85,8 @@ import { ShortestDistanceWeights, SpatialNavigationContextValue, SpatialNavigati
  * | `data-spatial-right`   | element id  | N/A     | Focus this element when Right is pressed                                            |
  * | `data-spatial-down`    | element id  | N/A     | Focus this element when Down is pressed                                             |
  * | `data-spatial-go-back` | N/A         | N/A     | First focusable element with this attribute is clicked on Back/Escape               |
- * | `data-spatial-focusable` | N/A       | N/A     | Treat element as focusable even if it normally is not (e.g., `tabindex="-1"`)      |
+ * | `data-spatial-focusable` | N/A       | N/A     | Treat element as focusable even if it normally is not (e.g., `tabindex="-1"`)       |
+ * | `data-spatial-exclude` | N/A         | N/A     | Exclude focusable element (and its subtree) from the navigation                     |
  *
  * ## Event emitting order
  *

package/dist/components/spatialnavigationprovider/spatialnavigationprovider.component.js

@@ -48,6 +48,9 @@ import { SpatialNavigationEvent } from './spatialnavigationprovider.events';
  * Elements with `data-spatial-focusable` are treated as focusable even if they would otherwise not be
  * (e.g., `tabindex="-1"`).
  *
+ * Elements with `data-spatial-exclude` are excluded (with its subtree) from the navigation, even if they
+ * are focusable.
+ *
  * ### Overwrite next element
  *
  * Override automatic navigation by adding one of these attributes to a focusable element:
@@ -98,7 +101,8 @@ import { SpatialNavigationEvent } from './spatialnavigationprovider.events';
  * | `data-spatial-right`   | element id  | N/A     | Focus this element when Right is pressed                                            |
  * | `data-spatial-down`    | element id  | N/A     | Focus this element when Down is pressed                                             |
  * | `data-spatial-go-back` | N/A         | N/A     | First focusable element with this attribute is clicked on Back/Escape               |
- * | `data-spatial-focusable` | N/A       | N/A     | Treat element as focusable even if it normally is not (e.g., `tabindex="-1"`)      |
+ * | `data-spatial-focusable` | N/A       | N/A     | Treat element as focusable even if it normally is not (e.g., `tabindex="-1"`)       |
+ * | `data-spatial-exclude` | N/A         | N/A     | Exclude focusable element (and its subtree) from the navigation                     |
  *
  * ## Event emitting order
  *
@@ -423,6 +427,7 @@ class SpatialNavigationProvider extends Provider {
                 focusableElements.push(...findFocusable(el, {
                     excludedElements: checkedFocusArea ? [checkedFocusArea] : undefined,
                     includeSelectors: ['[data-spatial-focusable]'],
+                    excludeSelectors: ['[data-spatial-exclude]'],
                 }));
                 const result = this.focusNextInFocusableAria(focusableElements, direction);
                 // If there is a focusable element found, or reached the active trap or the root, stop searching

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

@@ -58,9 +58,26 @@ declare class Tooltip extends Popover {
      */
     private setTooltipType;
     /**
-     * Updates the tooltip id if it is empty.
+     * Cached auto-generated id so that if the consumer (or a React wrapper that re-passes props
+     * on every render) clears the id we restore the same value instead of minting a fresh UUID
+     * on every cycle.
      */
-    private onIdUpdated;
+    private autoGeneratedId;
+    /**
+     * Ensures the tooltip has a non-empty id. Called from `willUpdate` so the assignment is folded
+     * into the in-flight update cycle (no extra render pass, no risk of an update loop).
+     *
+     * - If the consumer provides an explicit id, we drop the cached auto id so a future clear can
+     *   regenerate a fresh one.
+     * - If the id is empty, we reuse the cached auto id when present, otherwise generate one.
+     */
+    private ensureId;
+    /**
+     * Writes the appropriate aria attribute on the trigger element based on the current tooltipType.
+     * Used when only the id changed (tooltipType-driven aria updates are handled in
+     * `onTooltipTypeUpdated`).
+     */
+    private syncTriggerAriaForId;
     /**
      * Updates the placement attribute if it is not a valid placement.
      * Overriding the default from Popover
@@ -72,7 +89,7 @@ declare class Tooltip extends Popover {
      */
     private onTooltipTypeUpdated;
     protected isOpenUpdated(oldValue: boolean, newValue: boolean): Promise<void>;
-    update(changedProperties: PropertyValues<this>): Promise<void>;
+    protected willUpdate(changedProperties: PropertyValues<this>): void;
     show(): void;
     static styles: Array<CSSResult>;
 }

package/dist/components/tooltip/tooltip.component.js

@@ -63,6 +63,12 @@ class Tooltip extends Popover {
          * @default false
          */
         this.onlyShowWhenTriggerOverflows = DEFAULTS.ONLY_SHOW_WHEN_TRIGGER_OVERFLOWS;
+        /**
+         * Cached auto-generated id so that if the consumer (or a React wrapper that re-passes props
+         * on every render) clears the id we restore the same value instead of minting a fresh UUID
+         * on every cycle.
+         */
+        this.autoGeneratedId = null;
     }
     connectedCallback() {
         super.connectedCallback();
@@ -99,26 +105,42 @@ class Tooltip extends Popover {
         this.setAttribute('tooltip-type', Object.values(TOOLTIP_TYPES).includes(type) ? type : DEFAULTS.TOOLTIP_TYPE);
     }
     /**
-     * Updates the tooltip id if it is empty.
+     * Ensures the tooltip has a non-empty id. Called from `willUpdate` so the assignment is folded
+     * into the in-flight update cycle (no extra render pass, no risk of an update loop).
+     *
+     * - If the consumer provides an explicit id, we drop the cached auto id so a future clear can
+     *   regenerate a fresh one.
+     * - If the id is empty, we reuse the cached auto id when present, otherwise generate one.
      */
-    async onIdUpdated() {
-        // Set tooltip ID if not set.
-        if (this.id.length === 0) {
-            this.id = `mdc-tooltip-${uuidv4()}`;
-        }
-        await this.updateComplete;
-        // Update the aria props on the trigger component to updated tooltip id.
-        if (this.triggerElement) {
-            switch (this.tooltipType) {
-                case TOOLTIP_TYPES.DESCRIPTION:
-                    this.triggerElement.setAttribute('aria-describedby', this.id);
-                    break;
-                case TOOLTIP_TYPES.LABEL:
-                    this.triggerElement.setAttribute('aria-labelledby', this.id);
-                    break;
-                default:
-                    break;
+    ensureId() {
+        if (this.id.length > 0) {
+            if (this.autoGeneratedId && this.id !== this.autoGeneratedId) {
+                this.autoGeneratedId = null;
             }
+            return;
+        }
+        if (!this.autoGeneratedId) {
+            this.autoGeneratedId = `mdc-tooltip-${uuidv4()}`;
+        }
+        this.id = this.autoGeneratedId;
+    }
+    /**
+     * Writes the appropriate aria attribute on the trigger element based on the current tooltipType.
+     * Used when only the id changed (tooltipType-driven aria updates are handled in
+     * `onTooltipTypeUpdated`).
+     */
+    syncTriggerAriaForId() {
+        if (!this.triggerElement)
+            return;
+        switch (this.tooltipType) {
+            case TOOLTIP_TYPES.DESCRIPTION:
+                this.triggerElement.setAttribute('aria-describedby', this.id);
+                break;
+            case TOOLTIP_TYPES.LABEL:
+                this.triggerElement.setAttribute('aria-labelledby', this.id);
+                break;
+            default:
+                break;
         }
     }
     /**
@@ -181,17 +203,26 @@ class Tooltip extends Popover {
         }
         await super.isOpenUpdated(oldValue, newValue);
     }
-    async update(changedProperties) {
-        super.update(changedProperties);
-        if (changedProperties.has('id')) {
-            await this.onIdUpdated();
+    willUpdate(changedProperties) {
+        super.willUpdate(changedProperties);
+        // Ensure an id exists before render. Assigning `this.id` inside willUpdate is folded into
+        // the current update cycle, so there is no extra render and no loop risk (the previous
+        // implementation set the id from inside `update()` and awaited `updateComplete`, which
+        // produced an infinite re-render loop under @lit/react wrappers that keep clearing the id).
+        const idChanged = changedProperties.has('id');
+        if (idChanged) {
+            this.ensureId();
         }
         if (changedProperties.has('placement')) {
             this.onPlacementUpdated();
         }
         if (changedProperties.has('tooltipType')) {
+            // onTooltipTypeUpdated also refreshes the trigger aria attribute, so it covers the id sync.
             this.onTooltipTypeUpdated(changedProperties);
         }
+        else if (idChanged) {
+            this.syncTriggerAriaForId();
+        }
     }
     show() {
         if (this.onlyShowWhenTriggerOverflows && this.triggerElement && hasOverflowMixin(this.triggerElement)) {

package/dist/custom-elements.json

@@ -44925,7 +44925,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "This component manages focus using spatial navigation and provides context for child components.\n\nPlace it at the root of the application.\n\n[Spatial navigation](https://en.wikipedia.org/wiki/Spatial_navigation) lets users move focus among\nelements on a 2D plane, common on TVs and game consoles with remotes or gamepads.\n\n## Focus management\n\nThe provider listens to keyboard events and moves focus among elements based on arrow key input.\nYou can influence or override this behavior.\n\nNote: The algorithm is distance-based, so the UI should be designed so focusable elements are\npredictably reachable. Relative element positions should remain stable; responsive layouts can\nmake navigation unpredictable. This is less of an issue on fixed-size TV UIs but can show unexpected\nbehavior in Storybook when resizing. See the \"Limitations\" section.\n\n### Automatic\n\nBy default, the next focus target is computed from element positions:\n\n1. Find the nearest focus area (scrollable container or active focus trap) relative to the current element.\n2. Collect focusable elements in that area.\n3. Compute distances from the current element to candidates using the W3C \"find the shortest\n   distance\" algorithm: https://www.w3.org/TR/css-nav-1/#find-the-shortest-distance\n4. If no candidates are found, repeat from step 1, skipping areas already checked.\n5. Focus the closest candidate.\n\nElements with `data-spatial-focusable` are treated as focusable even if they would otherwise not be\n(e.g., `tabindex=\"-1\"`).\n\n### Overwrite next element\n\nOverride automatic navigation by adding one of these attributes to a focusable element:\n\n- `data-spatial-up`\n- `data-spatial-down`\n- `data-spatial-left`\n- `data-spatial-right`\n\nEach attribute value must be the id of the element to focus when the corresponding key is pressed.\n\n### Element internal navigation\n\nComplex components (List, Combobox, Tree, etc.) may handle their own navigation. For example, a List moves\nfocus internally on Down until the last item, after which Down should fall back to provider navigation.\n\nTo prevent the provider from handling a key, listen to `navbeforeprocess` and call `event.preventDefault()`.\nThis event fires after the component handles `keydown`.\n\n### Cancel focus change\n\nBefore focusing a computed target, the provider dispatches `navbeforefocus` on the current element. Call\n`event.preventDefault()` on this event to cancel the focus change.\n\n## Enter action\n\nPressing Enter triggers `.click()` on the currently focused element.\n\nYou can prevent this by listening to `navbeforeprocess` and calling `event.preventDefault()`.\n\n## Escape/Back action\n\nPressing Escape tries to find a focusable element with `data-spatial-go-back` and clicks it. If none exists,\nthe provider calls `history.back()`.\n\nYou can prevent this by listening to `navbeforeprocess` and calling `event.preventDefault()`.\n\nYou can also intercept the back click by listening to `navback` and calling `event.preventDefault()`.\n\n## Control data attributes\n\nSupported data attributes:\n\n| Attribute              | Value       | Default | Description                                                                         |\n|------------------------|-------------|---------|-------------------------------------------------------------------------------------|\n| `data-spatial-left`    | element id  | N/A     | Focus this element when Left is pressed                                             |\n| `data-spatial-up`      | element id  | N/A     | Focus this element when Up is pressed                                               |\n| `data-spatial-right`   | element id  | N/A     | Focus this element when Right is pressed                                            |\n| `data-spatial-down`    | element id  | N/A     | Focus this element when Down is pressed                                             |\n| `data-spatial-go-back` | N/A         | N/A     | First focusable element with this attribute is clicked on Back/Escape               |\n| `data-spatial-focusable` | N/A       | N/A     | Treat element as focusable even if it normally is not (e.g., `tabindex=\"-1\"`)      |\n\n## Event emitting order\n\nOn a navigation key press, events fire in this order:\n\n1. `navbeforeprocess` on the currently focused element.\n2. If not prevented:\na. Arrow keys: `navbeforefocus` on the currently focused element.\nb. Enter: `.click()` on the currently focused element.\nc. Escape/Back: `navback` on the provider, then `.click()` on the go-back element or `history.back()`.\n3. If no target is found in the requested direction: `navnotarget` on the provider.\n\n## Handle complex components\n\n### Generic components\n\nComponents that handle navigation internally should prevent the provider from acting. Handle `navbeforeprocess`\nand call `event.preventDefault()` for keys you process yourself.\n\n### Form inputs\n\nNative inputs often submit on Enter, which is not desirable here. Enter should toggle or activate the control\n(e.g., check/uncheck). Provide a dedicated submit button users can navigate to and press Enter on.\n\n### Utilities for complex components\n\n#### KeyToActionMixin\n\nMaps key events to action names. Call `getActionForKeyEvent` to get the action for a keyboard event. Also provides\n`getKeyboardNavMode` to check whether navigation is spatial or default.\n\n#### KeyDownHandledMixin\n\nNotify the provider when a component handled `keydown` internally. Call `keyDownEventHandled` whenever you process\nkeydown yourself.\n\n## Platform specific behaviors\n\nConsider remote/gamepad constraints. Often focus alone is not enough and users press Enter to \"enter\" an interactive mode:\n- Select: Enter opens options rather than arrow keys opening a popover.\n- Text inputs: see the next section.\n- Slider: Enter to start adjusting, arrow keys to change value, Enter/Escape to stop.\n\n### Text inputs\n\nOn TV-like platforms without physical keyboards, Enter/focus on an input should open a virtual keyboard instead of submitting\nthe form. Users must close the keyboard (Escape) to continue spatial navigation.\n\nIf navigation keys are mapped to letters (e.g., `w/a/s/d`), they should navigate, not change input values. Inputs should\nbe edited via the virtual keyboard.\n\nNote: Stories do not emulate virtual keyboards, so letter-based navigation may change input values in Storybook.\n\n## Debugging\n\n### Storybook toolbar\n\nEnable \"Spatial navigation\" in the toolbar. Key mapping:\n- Up - ArrowUp\n- Left - ArrowLeft\n- Down - ArrowDown\n- Right - ArrowRight\n- Enter - Enter\n- Escape - Escape\n\nWith wrapper: wraps the component in a 3x3 grid with surrounding buttons for testing.\nWithout wrapper: renders the component alone.\n\n### Visual debugger\n\nWith spatial navigation enabled, press Shift + navigation key to visualize calculations:\n\n- Star: next active element\n- `#{number}`: candidate order by distance\n- `D: {distance}`: computed distance\n\n## Limitations\n\n### Completeness\n\nThe algorithm cannot guarantee reachability to all elements using the four directions. Some components can be isolated.\n\nWorkarounds:\n- Use data attributes to explicitly link navigation targets.\n- Arrange DOM to improve spatial consistency:\n- Group focusable elements using dedicated components (lists, menus, etc.).\n- Avoid complex grid-like layouts with variable-sized items.\n- Avoid overlap along horizontal or vertical axes.\n- Avoid nested focusable elements where possible.\n- Tune algorithm weights to match your UI layout.\n\n### Scrollable containers\n\nContent scrolling is not supported yet, e.g.:\n- Focused element larger than the viewport.\n- Scrollable content without interactive children.\n\n### Nested providers\n\nOnly one provider instance is supported in the application at a time.",
+          "description": "This component manages focus using spatial navigation and provides context for child components.\n\nPlace it at the root of the application.\n\n[Spatial navigation](https://en.wikipedia.org/wiki/Spatial_navigation) lets users move focus among\nelements on a 2D plane, common on TVs and game consoles with remotes or gamepads.\n\n## Focus management\n\nThe provider listens to keyboard events and moves focus among elements based on arrow key input.\nYou can influence or override this behavior.\n\nNote: The algorithm is distance-based, so the UI should be designed so focusable elements are\npredictably reachable. Relative element positions should remain stable; responsive layouts can\nmake navigation unpredictable. This is less of an issue on fixed-size TV UIs but can show unexpected\nbehavior in Storybook when resizing. See the \"Limitations\" section.\n\n### Automatic\n\nBy default, the next focus target is computed from element positions:\n\n1. Find the nearest focus area (scrollable container or active focus trap) relative to the current element.\n2. Collect focusable elements in that area.\n3. Compute distances from the current element to candidates using the W3C \"find the shortest\n   distance\" algorithm: https://www.w3.org/TR/css-nav-1/#find-the-shortest-distance\n4. If no candidates are found, repeat from step 1, skipping areas already checked.\n5. Focus the closest candidate.\n\nElements with `data-spatial-focusable` are treated as focusable even if they would otherwise not be\n(e.g., `tabindex=\"-1\"`).\n\nElements with `data-spatial-exclude` are excluded (with its subtree) from the navigation, even if they\nare focusable.\n\n### Overwrite next element\n\nOverride automatic navigation by adding one of these attributes to a focusable element:\n\n- `data-spatial-up`\n- `data-spatial-down`\n- `data-spatial-left`\n- `data-spatial-right`\n\nEach attribute value must be the id of the element to focus when the corresponding key is pressed.\n\n### Element internal navigation\n\nComplex components (List, Combobox, Tree, etc.) may handle their own navigation. For example, a List moves\nfocus internally on Down until the last item, after which Down should fall back to provider navigation.\n\nTo prevent the provider from handling a key, listen to `navbeforeprocess` and call `event.preventDefault()`.\nThis event fires after the component handles `keydown`.\n\n### Cancel focus change\n\nBefore focusing a computed target, the provider dispatches `navbeforefocus` on the current element. Call\n`event.preventDefault()` on this event to cancel the focus change.\n\n## Enter action\n\nPressing Enter triggers `.click()` on the currently focused element.\n\nYou can prevent this by listening to `navbeforeprocess` and calling `event.preventDefault()`.\n\n## Escape/Back action\n\nPressing Escape tries to find a focusable element with `data-spatial-go-back` and clicks it. If none exists,\nthe provider calls `history.back()`.\n\nYou can prevent this by listening to `navbeforeprocess` and calling `event.preventDefault()`.\n\nYou can also intercept the back click by listening to `navback` and calling `event.preventDefault()`.\n\n## Control data attributes\n\nSupported data attributes:\n\n| Attribute              | Value       | Default | Description                                                                         |\n|------------------------|-------------|---------|-------------------------------------------------------------------------------------|\n| `data-spatial-left`    | element id  | N/A     | Focus this element when Left is pressed                                             |\n| `data-spatial-up`      | element id  | N/A     | Focus this element when Up is pressed                                               |\n| `data-spatial-right`   | element id  | N/A     | Focus this element when Right is pressed                                            |\n| `data-spatial-down`    | element id  | N/A     | Focus this element when Down is pressed                                             |\n| `data-spatial-go-back` | N/A         | N/A     | First focusable element with this attribute is clicked on Back/Escape               |\n| `data-spatial-focusable` | N/A       | N/A     | Treat element as focusable even if it normally is not (e.g., `tabindex=\"-1\"`)       |\n| `data-spatial-exclude` | N/A         | N/A     | Exclude focusable element (and its subtree) from the navigation                     |\n\n## Event emitting order\n\nOn a navigation key press, events fire in this order:\n\n1. `navbeforeprocess` on the currently focused element.\n2. If not prevented:\na. Arrow keys: `navbeforefocus` on the currently focused element.\nb. Enter: `.click()` on the currently focused element.\nc. Escape/Back: `navback` on the provider, then `.click()` on the go-back element or `history.back()`.\n3. If no target is found in the requested direction: `navnotarget` on the provider.\n\n## Handle complex components\n\n### Generic components\n\nComponents that handle navigation internally should prevent the provider from acting. Handle `navbeforeprocess`\nand call `event.preventDefault()` for keys you process yourself.\n\n### Form inputs\n\nNative inputs often submit on Enter, which is not desirable here. Enter should toggle or activate the control\n(e.g., check/uncheck). Provide a dedicated submit button users can navigate to and press Enter on.\n\n### Utilities for complex components\n\n#### KeyToActionMixin\n\nMaps key events to action names. Call `getActionForKeyEvent` to get the action for a keyboard event. Also provides\n`getKeyboardNavMode` to check whether navigation is spatial or default.\n\n#### KeyDownHandledMixin\n\nNotify the provider when a component handled `keydown` internally. Call `keyDownEventHandled` whenever you process\nkeydown yourself.\n\n## Platform specific behaviors\n\nConsider remote/gamepad constraints. Often focus alone is not enough and users press Enter to \"enter\" an interactive mode:\n- Select: Enter opens options rather than arrow keys opening a popover.\n- Text inputs: see the next section.\n- Slider: Enter to start adjusting, arrow keys to change value, Enter/Escape to stop.\n\n### Text inputs\n\nOn TV-like platforms without physical keyboards, Enter/focus on an input should open a virtual keyboard instead of submitting\nthe form. Users must close the keyboard (Escape) to continue spatial navigation.\n\nIf navigation keys are mapped to letters (e.g., `w/a/s/d`), they should navigate, not change input values. Inputs should\nbe edited via the virtual keyboard.\n\nNote: Stories do not emulate virtual keyboards, so letter-based navigation may change input values in Storybook.\n\n## Debugging\n\n### Storybook toolbar\n\nEnable \"Spatial navigation\" in the toolbar. Key mapping:\n- Up - ArrowUp\n- Left - ArrowLeft\n- Down - ArrowDown\n- Right - ArrowRight\n- Enter - Enter\n- Escape - Escape\n\nWith wrapper: wraps the component in a 3x3 grid with surrounding buttons for testing.\nWithout wrapper: renders the component alone.\n\n### Visual debugger\n\nWith spatial navigation enabled, press Shift + navigation key to visualize calculations:\n\n- Star: next active element\n- `#{number}`: candidate order by distance\n- `D: {distance}`: computed distance\n\n## Limitations\n\n### Completeness\n\nThe algorithm cannot guarantee reachability to all elements using the four directions. Some components can be isolated.\n\nWorkarounds:\n- Use data attributes to explicitly link navigation targets.\n- Arrange DOM to improve spatial consistency:\n- Group focusable elements using dedicated components (lists, menus, etc.).\n- Avoid complex grid-like layouts with variable-sized items.\n- Avoid overlap along horizontal or vertical axes.\n- Avoid nested focusable elements where possible.\n- Tune algorithm weights to match your UI layout.\n\n### Scrollable containers\n\nContent scrolling is not supported yet, e.g.:\n- Focused element larger than the viewport.\n- Scrollable content without interactive children.\n\n### Nested providers\n\nOnly one provider instance is supported in the application at a time.",
           "name": "SpatialNavigationProvider",
           "members": [
             {
@@ -45025,7 +45025,7 @@
             "module": "/src/models"
           },
           "tagName": "mdc-spatialnavigationprovider",
-          "jsDoc": "/**\n * This component manages focus using spatial navigation and provides context for child components.\n *\n * Place it at the root of the application.\n *\n * [Spatial navigation](https://en.wikipedia.org/wiki/Spatial_navigation) lets users move focus among\n * elements on a 2D plane, common on TVs and game consoles with remotes or gamepads.\n *\n * ## Focus management\n *\n * The provider listens to keyboard events and moves focus among elements based on arrow key input.\n * You can influence or override this behavior.\n *\n * Note: The algorithm is distance-based, so the UI should be designed so focusable elements are\n * predictably reachable. Relative element positions should remain stable; responsive layouts can\n * make navigation unpredictable. This is less of an issue on fixed-size TV UIs but can show unexpected\n * behavior in Storybook when resizing. See the \"Limitations\" section.\n *\n * ### Automatic\n *\n * By default, the next focus target is computed from element positions:\n *\n * 1. Find the nearest focus area (scrollable container or active focus trap) relative to the current element.\n * 2. Collect focusable elements in that area.\n * 3. Compute distances from the current element to candidates using the W3C \"find the shortest\n *    distance\" algorithm: https://www.w3.org/TR/css-nav-1/#find-the-shortest-distance\n * 4. If no candidates are found, repeat from step 1, skipping areas already checked.\n * 5. Focus the closest candidate.\n *\n * Elements with `data-spatial-focusable` are treated as focusable even if they would otherwise not be\n * (e.g., `tabindex=\"-1\"`).\n *\n * ### Overwrite next element\n *\n * Override automatic navigation by adding one of these attributes to a focusable element:\n *\n * - `data-spatial-up`\n * - `data-spatial-down`\n * - `data-spatial-left`\n * - `data-spatial-right`\n *\n * Each attribute value must be the id of the element to focus when the corresponding key is pressed.\n *\n * ### Element internal navigation\n *\n * Complex components (List, Combobox, Tree, etc.) may handle their own navigation. For example, a List moves\n * focus internally on Down until the last item, after which Down should fall back to provider navigation.\n *\n * To prevent the provider from handling a key, listen to `navbeforeprocess` and call `event.preventDefault()`.\n * This event fires after the component handles `keydown`.\n *\n * ### Cancel focus change\n *\n * Before focusing a computed target, the provider dispatches `navbeforefocus` on the current element. Call\n * `event.preventDefault()` on this event to cancel the focus change.\n *\n * ## Enter action\n *\n * Pressing Enter triggers `.click()` on the currently focused element.\n *\n * You can prevent this by listening to `navbeforeprocess` and calling `event.preventDefault()`.\n *\n * ## Escape/Back action\n *\n * Pressing Escape tries to find a focusable element with `data-spatial-go-back` and clicks it. If none exists,\n * the provider calls `history.back()`.\n *\n * You can prevent this by listening to `navbeforeprocess` and calling `event.preventDefault()`.\n *\n * You can also intercept the back click by listening to `navback` and calling `event.preventDefault()`.\n *\n * ## Control data attributes\n *\n * Supported data attributes:\n *\n * | Attribute              | Value       | Default | Description                                                                         |\n * |------------------------|-------------|---------|-------------------------------------------------------------------------------------|\n * | `data-spatial-left`    | element id  | N/A     | Focus this element when Left is pressed                                             |\n * | `data-spatial-up`      | element id  | N/A     | Focus this element when Up is pressed                                               |\n * | `data-spatial-right`   | element id  | N/A     | Focus this element when Right is pressed                                            |\n * | `data-spatial-down`    | element id  | N/A     | Focus this element when Down is pressed                                             |\n * | `data-spatial-go-back` | N/A         | N/A     | First focusable element with this attribute is clicked on Back/Escape               |\n * | `data-spatial-focusable` | N/A       | N/A     | Treat element as focusable even if it normally is not (e.g., `tabindex=\"-1\"`)      |\n *\n * ## Event emitting order\n *\n * On a navigation key press, events fire in this order:\n *\n * 1. `navbeforeprocess` on the currently focused element.\n * 2. If not prevented:\n * a. Arrow keys: `navbeforefocus` on the currently focused element.\n * b. Enter: `.click()` on the currently focused element.\n * c. Escape/Back: `navback` on the provider, then `.click()` on the go-back element or `history.back()`.\n * 3. If no target is found in the requested direction: `navnotarget` on the provider.\n *\n * ## Handle complex components\n *\n * ### Generic components\n *\n * Components that handle navigation internally should prevent the provider from acting. Handle `navbeforeprocess`\n * and call `event.preventDefault()` for keys you process yourself.\n *\n * ### Form inputs\n *\n * Native inputs often submit on Enter, which is not desirable here. Enter should toggle or activate the control\n * (e.g., check/uncheck). Provide a dedicated submit button users can navigate to and press Enter on.\n *\n * ### Utilities for complex components\n *\n * #### KeyToActionMixin\n *\n * Maps key events to action names. Call `getActionForKeyEvent` to get the action for a keyboard event. Also provides\n * `getKeyboardNavMode` to check whether navigation is spatial or default.\n *\n * #### KeyDownHandledMixin\n *\n * Notify the provider when a component handled `keydown` internally. Call `keyDownEventHandled` whenever you process\n * keydown yourself.\n *\n * ## Platform specific behaviors\n *\n * Consider remote/gamepad constraints. Often focus alone is not enough and users press Enter to \"enter\" an interactive mode:\n * - Select: Enter opens options rather than arrow keys opening a popover.\n * - Text inputs: see the next section.\n * - Slider: Enter to start adjusting, arrow keys to change value, Enter/Escape to stop.\n *\n * ### Text inputs\n *\n * On TV-like platforms without physical keyboards, Enter/focus on an input should open a virtual keyboard instead of submitting\n * the form. Users must close the keyboard (Escape) to continue spatial navigation.\n *\n * If navigation keys are mapped to letters (e.g., `w/a/s/d`), they should navigate, not change input values. Inputs should\n * be edited via the virtual keyboard.\n *\n * Note: Stories do not emulate virtual keyboards, so letter-based navigation may change input values in Storybook.\n *\n * ## Debugging\n *\n * ### Storybook toolbar\n *\n * Enable \"Spatial navigation\" in the toolbar. Key mapping:\n * - Up - ArrowUp\n * - Left - ArrowLeft\n * - Down - ArrowDown\n * - Right - ArrowRight\n * - Enter - Enter\n * - Escape - Escape\n *\n * With wrapper: wraps the component in a 3x3 grid with surrounding buttons for testing.\n * Without wrapper: renders the component alone.\n *\n * ### Visual debugger\n *\n * With spatial navigation enabled, press Shift + navigation key to visualize calculations:\n *\n * - Star: next active element\n * - `#{number}`: candidate order by distance\n * - `D: {distance}`: computed distance\n *\n * ## Limitations\n *\n * ### Completeness\n *\n * The algorithm cannot guarantee reachability to all elements using the four directions. Some components can be isolated.\n *\n * Workarounds:\n * - Use data attributes to explicitly link navigation targets.\n * - Arrange DOM to improve spatial consistency:\n * - Group focusable elements using dedicated components (lists, menus, etc.).\n * - Avoid complex grid-like layouts with variable-sized items.\n * - Avoid overlap along horizontal or vertical axes.\n * - Avoid nested focusable elements where possible.\n * - Tune algorithm weights to match your UI layout.\n *\n * ### Scrollable containers\n *\n * Content scrolling is not supported yet, e.g.:\n * - Focused element larger than the viewport.\n * - Scrollable content without interactive children.\n *\n * ### Nested providers\n *\n * Only one provider instance is supported in the application at a time.\n *\n * @event navbeforeprocess - (React: onNavBeforeProcess) This event dispatched before spatial navigation process any key event.\n *                           It can be canceled to prevent any action from spatial navigation, e.g.: back, click or calculating the next candidate.\n * @event navbeforefocus - (React: onNavBeforeFocus) This event is dispatched before the focus is changing to the next element.\n *                         It can be canceled to prevent the focus change. @see https://www.w3.org/TR/css-nav-1/#event-type-navbeforefocus\n * @event navback - (React: onNavBack) This event dispatched a back navigation triggered by the user.\n *                  The event's detail contains the goBackElement if any. It is cancelable to prevent click\n *                  action on the goBackElement.\n * @event navnotarget - (React: onNavNoTarget) This event is dispatched when there is no target to focus in the current focus area and\n *                      in the given direction .\n *\n * @tagname mdc-spatialnavigationprovider\n */",
+          "jsDoc": "/**\n * This component manages focus using spatial navigation and provides context for child components.\n *\n * Place it at the root of the application.\n *\n * [Spatial navigation](https://en.wikipedia.org/wiki/Spatial_navigation) lets users move focus among\n * elements on a 2D plane, common on TVs and game consoles with remotes or gamepads.\n *\n * ## Focus management\n *\n * The provider listens to keyboard events and moves focus among elements based on arrow key input.\n * You can influence or override this behavior.\n *\n * Note: The algorithm is distance-based, so the UI should be designed so focusable elements are\n * predictably reachable. Relative element positions should remain stable; responsive layouts can\n * make navigation unpredictable. This is less of an issue on fixed-size TV UIs but can show unexpected\n * behavior in Storybook when resizing. See the \"Limitations\" section.\n *\n * ### Automatic\n *\n * By default, the next focus target is computed from element positions:\n *\n * 1. Find the nearest focus area (scrollable container or active focus trap) relative to the current element.\n * 2. Collect focusable elements in that area.\n * 3. Compute distances from the current element to candidates using the W3C \"find the shortest\n *    distance\" algorithm: https://www.w3.org/TR/css-nav-1/#find-the-shortest-distance\n * 4. If no candidates are found, repeat from step 1, skipping areas already checked.\n * 5. Focus the closest candidate.\n *\n * Elements with `data-spatial-focusable` are treated as focusable even if they would otherwise not be\n * (e.g., `tabindex=\"-1\"`).\n *\n * Elements with `data-spatial-exclude` are excluded (with its subtree) from the navigation, even if they\n * are focusable.\n *\n * ### Overwrite next element\n *\n * Override automatic navigation by adding one of these attributes to a focusable element:\n *\n * - `data-spatial-up`\n * - `data-spatial-down`\n * - `data-spatial-left`\n * - `data-spatial-right`\n *\n * Each attribute value must be the id of the element to focus when the corresponding key is pressed.\n *\n * ### Element internal navigation\n *\n * Complex components (List, Combobox, Tree, etc.) may handle their own navigation. For example, a List moves\n * focus internally on Down until the last item, after which Down should fall back to provider navigation.\n *\n * To prevent the provider from handling a key, listen to `navbeforeprocess` and call `event.preventDefault()`.\n * This event fires after the component handles `keydown`.\n *\n * ### Cancel focus change\n *\n * Before focusing a computed target, the provider dispatches `navbeforefocus` on the current element. Call\n * `event.preventDefault()` on this event to cancel the focus change.\n *\n * ## Enter action\n *\n * Pressing Enter triggers `.click()` on the currently focused element.\n *\n * You can prevent this by listening to `navbeforeprocess` and calling `event.preventDefault()`.\n *\n * ## Escape/Back action\n *\n * Pressing Escape tries to find a focusable element with `data-spatial-go-back` and clicks it. If none exists,\n * the provider calls `history.back()`.\n *\n * You can prevent this by listening to `navbeforeprocess` and calling `event.preventDefault()`.\n *\n * You can also intercept the back click by listening to `navback` and calling `event.preventDefault()`.\n *\n * ## Control data attributes\n *\n * Supported data attributes:\n *\n * | Attribute              | Value       | Default | Description                                                                         |\n * |------------------------|-------------|---------|-------------------------------------------------------------------------------------|\n * | `data-spatial-left`    | element id  | N/A     | Focus this element when Left is pressed                                             |\n * | `data-spatial-up`      | element id  | N/A     | Focus this element when Up is pressed                                               |\n * | `data-spatial-right`   | element id  | N/A     | Focus this element when Right is pressed                                            |\n * | `data-spatial-down`    | element id  | N/A     | Focus this element when Down is pressed                                             |\n * | `data-spatial-go-back` | N/A         | N/A     | First focusable element with this attribute is clicked on Back/Escape               |\n * | `data-spatial-focusable` | N/A       | N/A     | Treat element as focusable even if it normally is not (e.g., `tabindex=\"-1\"`)       |\n * | `data-spatial-exclude` | N/A         | N/A     | Exclude focusable element (and its subtree) from the navigation                     |\n *\n * ## Event emitting order\n *\n * On a navigation key press, events fire in this order:\n *\n * 1. `navbeforeprocess` on the currently focused element.\n * 2. If not prevented:\n * a. Arrow keys: `navbeforefocus` on the currently focused element.\n * b. Enter: `.click()` on the currently focused element.\n * c. Escape/Back: `navback` on the provider, then `.click()` on the go-back element or `history.back()`.\n * 3. If no target is found in the requested direction: `navnotarget` on the provider.\n *\n * ## Handle complex components\n *\n * ### Generic components\n *\n * Components that handle navigation internally should prevent the provider from acting. Handle `navbeforeprocess`\n * and call `event.preventDefault()` for keys you process yourself.\n *\n * ### Form inputs\n *\n * Native inputs often submit on Enter, which is not desirable here. Enter should toggle or activate the control\n * (e.g., check/uncheck). Provide a dedicated submit button users can navigate to and press Enter on.\n *\n * ### Utilities for complex components\n *\n * #### KeyToActionMixin\n *\n * Maps key events to action names. Call `getActionForKeyEvent` to get the action for a keyboard event. Also provides\n * `getKeyboardNavMode` to check whether navigation is spatial or default.\n *\n * #### KeyDownHandledMixin\n *\n * Notify the provider when a component handled `keydown` internally. Call `keyDownEventHandled` whenever you process\n * keydown yourself.\n *\n * ## Platform specific behaviors\n *\n * Consider remote/gamepad constraints. Often focus alone is not enough and users press Enter to \"enter\" an interactive mode:\n * - Select: Enter opens options rather than arrow keys opening a popover.\n * - Text inputs: see the next section.\n * - Slider: Enter to start adjusting, arrow keys to change value, Enter/Escape to stop.\n *\n * ### Text inputs\n *\n * On TV-like platforms without physical keyboards, Enter/focus on an input should open a virtual keyboard instead of submitting\n * the form. Users must close the keyboard (Escape) to continue spatial navigation.\n *\n * If navigation keys are mapped to letters (e.g., `w/a/s/d`), they should navigate, not change input values. Inputs should\n * be edited via the virtual keyboard.\n *\n * Note: Stories do not emulate virtual keyboards, so letter-based navigation may change input values in Storybook.\n *\n * ## Debugging\n *\n * ### Storybook toolbar\n *\n * Enable \"Spatial navigation\" in the toolbar. Key mapping:\n * - Up - ArrowUp\n * - Left - ArrowLeft\n * - Down - ArrowDown\n * - Right - ArrowRight\n * - Enter - Enter\n * - Escape - Escape\n *\n * With wrapper: wraps the component in a 3x3 grid with surrounding buttons for testing.\n * Without wrapper: renders the component alone.\n *\n * ### Visual debugger\n *\n * With spatial navigation enabled, press Shift + navigation key to visualize calculations:\n *\n * - Star: next active element\n * - `#{number}`: candidate order by distance\n * - `D: {distance}`: computed distance\n *\n * ## Limitations\n *\n * ### Completeness\n *\n * The algorithm cannot guarantee reachability to all elements using the four directions. Some components can be isolated.\n *\n * Workarounds:\n * - Use data attributes to explicitly link navigation targets.\n * - Arrange DOM to improve spatial consistency:\n * - Group focusable elements using dedicated components (lists, menus, etc.).\n * - Avoid complex grid-like layouts with variable-sized items.\n * - Avoid overlap along horizontal or vertical axes.\n * - Avoid nested focusable elements where possible.\n * - Tune algorithm weights to match your UI layout.\n *\n * ### Scrollable containers\n *\n * Content scrolling is not supported yet, e.g.:\n * - Focused element larger than the viewport.\n * - Scrollable content without interactive children.\n *\n * ### Nested providers\n *\n * Only one provider instance is supported in the application at a time.\n *\n * @event navbeforeprocess - (React: onNavBeforeProcess) This event dispatched before spatial navigation process any key event.\n *                           It can be canceled to prevent any action from spatial navigation, e.g.: back, click or calculating the next candidate.\n * @event navbeforefocus - (React: onNavBeforeFocus) This event is dispatched before the focus is changing to the next element.\n *                         It can be canceled to prevent the focus change. @see https://www.w3.org/TR/css-nav-1/#event-type-navbeforefocus\n * @event navback - (React: onNavBack) This event dispatched a back navigation triggered by the user.\n *                  The event's detail contains the goBackElement if any. It is cancelable to prevent click\n *                  action on the goBackElement.\n * @event navnotarget - (React: onNavNoTarget) This event is dispatched when there is no target to focus in the current focus area and\n *                      in the given direction .\n *\n * @tagname mdc-spatialnavigationprovider\n */",
           "customElement": true
         }
       ],
@@ -53149,6 +53149,16 @@
                 "module": "components/popover/popover.component.js"
               }
             },
+            {
+              "kind": "field",
+              "name": "autoGeneratedId",
+              "type": {
+                "text": "string | null"
+              },
+              "privacy": "private",
+              "default": "null",
+              "description": "Cached auto-generated id so that if the consumer (or a React wrapper that re-passes props\non every render) clears the id we restore the same value instead of minting a fresh UUID\non every cycle."
+            },
             {
               "kind": "field",
               "name": "backdrop",
@@ -53338,6 +53348,17 @@
                 "module": "components/popover/popover.component.js"
               }
             },
+            {
+              "kind": "method",
+              "name": "ensureId",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Ensures the tooltip has a non-empty id. Called from `willUpdate` so the assignment is folded\ninto the in-flight update cycle (no extra render pass, no risk of an update loop).\n\n- If the consumer provides an explicit id, we drop the cached auto id so a future clear can\n  regenerate a fresh one.\n- If the id is empty, we reuse the cached auto id when present, otherwise generate one."
+            },
             {
               "kind": "field",
               "name": "focusBackToTrigger",
@@ -53558,17 +53579,6 @@
                 "module": "components/popover/popover.component.js"
               }
             },
-            {
-              "kind": "method",
-              "name": "onIdUpdated",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "Promise<void>"
-                }
-              },
-              "description": "Updates the tooltip id if it is empty."
-            },
             {
               "kind": "field",
               "name": "onlyShowWhenTriggerOverflows",
@@ -53761,6 +53771,17 @@
                 "module": "components/popover/popover.component.js"
               }
             },
+            {
+              "kind": "method",
+              "name": "syncTriggerAriaForId",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Writes the appropriate aria attribute on the trigger element based on the current tooltipType.\nUsed when only the id changed (tooltipType-driven aria updates are handled in\n`onTooltipTypeUpdated`)."
+            },
             {
               "kind": "field",
               "name": "togglePopoverVisible",

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

@@ -33,6 +33,9 @@ import type { Events } from '../../components/spatialnavigationprovider/spatialn
  * Elements with `data-spatial-focusable` are treated as focusable even if they would otherwise not be
  * (e.g., `tabindex="-1"`).
  *
+ * Elements with `data-spatial-exclude` are excluded (with its subtree) from the navigation, even if they
+ * are focusable.
+ *
  * ### Overwrite next element
  *
  * Override automatic navigation by adding one of these attributes to a focusable element:
@@ -83,7 +86,8 @@ import type { Events } from '../../components/spatialnavigationprovider/spatialn
  * | `data-spatial-right`   | element id  | N/A     | Focus this element when Right is pressed                                            |
  * | `data-spatial-down`    | element id  | N/A     | Focus this element when Down is pressed                                             |
  * | `data-spatial-go-back` | N/A         | N/A     | First focusable element with this attribute is clicked on Back/Escape               |
- * | `data-spatial-focusable` | N/A       | N/A     | Treat element as focusable even if it normally is not (e.g., `tabindex="-1"`)      |
+ * | `data-spatial-focusable` | N/A       | N/A     | Treat element as focusable even if it normally is not (e.g., `tabindex="-1"`)       |
+ * | `data-spatial-exclude` | N/A         | N/A     | Exclude focusable element (and its subtree) from the navigation                     |
  *
  * ## Event emitting order
  *

package/dist/react/spatialnavigationprovider/index.js

@@ -34,6 +34,9 @@ import { TAG_NAME } from '../../components/spatialnavigationprovider/spatialnavi
  * Elements with `data-spatial-focusable` are treated as focusable even if they would otherwise not be
  * (e.g., `tabindex="-1"`).
  *
+ * Elements with `data-spatial-exclude` are excluded (with its subtree) from the navigation, even if they
+ * are focusable.
+ *
  * ### Overwrite next element
  *
  * Override automatic navigation by adding one of these attributes to a focusable element:
@@ -84,7 +87,8 @@ import { TAG_NAME } from '../../components/spatialnavigationprovider/spatialnavi
  * | `data-spatial-right`   | element id  | N/A     | Focus this element when Right is pressed                                            |
  * | `data-spatial-down`    | element id  | N/A     | Focus this element when Down is pressed                                             |
  * | `data-spatial-go-back` | N/A         | N/A     | First focusable element with this attribute is clicked on Back/Escape               |
- * | `data-spatial-focusable` | N/A       | N/A     | Treat element as focusable even if it normally is not (e.g., `tabindex="-1"`)      |
+ * | `data-spatial-focusable` | N/A       | N/A     | Treat element as focusable even if it normally is not (e.g., `tabindex="-1"`)       |
+ * | `data-spatial-exclude` | N/A         | N/A     | Exclude focusable element (and its subtree) from the navigation                     |
  *
  * ## Event emitting order
  *

package/dist/utils/dom.d.ts

@@ -3,10 +3,14 @@ import type { OverflowMixinInterface } from './mixins/OverflowMixin';
  * Options for finding focusable elements.
  */
 type FindFocusableOptions = {
-    /** Elements to exclude from the search. */
+    /** Elements to include (and its subtree) in the search. */
+    includeElements?: HTMLElement[];
+    /** Elements to exclude (and its subtree) from the search. */
     excludedElements?: HTMLElement[];
     /** Selectors to include in the search. */
     includeSelectors?: string[];
+    /** Selectors to exclude from the search. */
+    excludeSelectors?: string[];
     /**
      * When true, elements with `tabindex="-1"` and their subtrees are excluded from the search.
      * This supports composite widget patterns (e.g., roving tabindex in lists) where

package/dist/utils/dom.js

@@ -166,16 +166,18 @@ export const isFocusable = (element) => !isDisabled(element) && isTabbable(eleme
  * @returns The list of focusable elements.
  */
 export const findFocusable = (root, options = {}) => {
-    var _a, _b, _c;
+    var _a, _b, _c, _d, _e;
     if (!root) {
         return [];
     }
     const excludesSet = new Set((_a = options === null || options === void 0 ? void 0 : options.excludedElements) !== null && _a !== void 0 ? _a : []);
     const includeSelectors = (_b = options === null || options === void 0 ? void 0 : options.includeSelectors) !== null && _b !== void 0 ? _b : [];
-    const stopAtNonTabbable = (_c = options === null || options === void 0 ? void 0 : options.stopAtNonTabbable) !== null && _c !== void 0 ? _c : false;
-    const matches = new Set();
+    const excludeSelectors = (_c = options === null || options === void 0 ? void 0 : options.excludeSelectors) !== null && _c !== void 0 ? _c : [];
+    const stopAtNonTabbable = (_d = options === null || options === void 0 ? void 0 : options.stopAtNonTabbable) !== null && _d !== void 0 ? _d : false;
+    const matches = new Set((_e = options.includeElements) !== null && _e !== void 0 ? _e : []);
     const focusableCheck = (element) => {
-        if (!(element instanceof HTMLSlotElement) && (isHidden(element) || isDisabled(element))) {
+        if (!(element instanceof HTMLSlotElement) &&
+            (isHidden(element) || isDisabled(element) || isMatchAny(element, excludeSelectors))) {
             return 'stop';
         }
         if (stopAtNonTabbable && !(element instanceof HTMLSlotElement) && element.getAttribute('tabindex') === '-1') {
@@ -194,7 +196,7 @@ export const findFocusable = (root, options = {}) => {
             : 'continue';
     };
     const finder = (root) => {
-        if (excludesSet.has(root)) {
+        if (excludesSet.has(root) || (root instanceof HTMLElement && isMatchAny(root, excludeSelectors))) {
             return;
         }
         if (root instanceof HTMLElement && focusableCheck(root) === 'focusable') {

package/package.json

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