@momentum-design/components 0.134.10 → 0.134.12

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

@@ -415,8 +415,16 @@ declare class Popover extends Popover_base implements StackedOverlayComponent {
      * Sets up the trigger related event listeners, based on the trigger type.
      * Includes fallback for mouseenter trigger to also handle focusin for non-interactive popovers.
      *
-     * We are using capture phase for to make sure we capture trigger events even when they are not propagated during the
-     * bubble phase (e.g.: buttons in list item)
+     * We use capture phase on `document` for all trigger listeners to make sure we capture trigger
+     * events even when they are not propagated during the bubble phase (e.g.: buttons in list item).
+     *
+     * Hover is detected via `mouseover`/`mouseout` (not `mouseenter`/`mouseleave`). The latter are
+     * spec'd as `composed: false` and do not bubble, so a document-level listener never sees them
+     * when the trigger lives inside a shadow root (e.g. wrapped in `mdc-iconprovider` or
+     * `mdc-themeprovider`). `mouseover`/`mouseout` are `composed: true` and bubble, so they cross
+     * shadow boundaries and reach `document`, letting us keep event delegation (no direct reference
+     * to the trigger element and no dependency on its mount/unmount lifecycle). The handlers filter
+     * out movements that stay within the trigger's subtree, recreating enter/leave semantics.
      * @internal
      */
     private setupTriggerListeners;
@@ -465,13 +473,25 @@ declare class Popover extends Popover_base implements StackedOverlayComponent {
      */
     protected isOpenUpdated(oldValue: boolean, newValue: boolean): Promise<void>;
     /**
-     * Handles mouse enter event on the trigger element.
-     * This method sets the `isHovered` flag to true and shows the popover
+     * Determines whether a delegated `mouseover`/`mouseout` event is movement that stays within the
+     * trigger's subtree rather than a genuine enter/leave of the trigger.
+     *
+     * Both events fire repeatedly while the pointer moves between elements inside the trigger
+     * (e.g. an icon with internal SVG elements). `relatedTarget` is the element on the other side of
+     * the boundary (the element being left for `mouseover`, or entered for `mouseout`); if it
+     * resolves to the trigger or one of its shadow hosts, the pointer has not crossed the trigger
+     * boundary and the event should be ignored.
+     * @internal
+     */
+    private isHoverWithinTrigger;
+    /**
+     * Handles the pointer moving over the trigger element (delegated `mouseover`).
+     * This method sets the `isHovered` flag to true and shows the popover.
      * @internal
      */
     private handleMouseEnter;
     /**
-     * Handles mouse leave event on the trigger element.
+     * Handles the pointer leaving the trigger element (delegated `mouseout`).
      * This method sets the `isHovered` flag to false and starts the close delay
      * timer to hide the popover.
      * @internal

package/dist/components/popover/popover.component.js

@@ -437,8 +437,16 @@ class Popover extends KeyDownHandledMixin(KeyToActionMixin(BackdropMixin(Prevent
          * Sets up the trigger related event listeners, based on the trigger type.
          * Includes fallback for mouseenter trigger to also handle focusin for non-interactive popovers.
          *
-         * We are using capture phase for to make sure we capture trigger events even when they are not propagated during the
-         * bubble phase (e.g.: buttons in list item)
+         * We use capture phase on `document` for all trigger listeners to make sure we capture trigger
+         * events even when they are not propagated during the bubble phase (e.g.: buttons in list item).
+         *
+         * Hover is detected via `mouseover`/`mouseout` (not `mouseenter`/`mouseleave`). The latter are
+         * spec'd as `composed: false` and do not bubble, so a document-level listener never sees them
+         * when the trigger lives inside a shadow root (e.g. wrapped in `mdc-iconprovider` or
+         * `mdc-themeprovider`). `mouseover`/`mouseout` are `composed: true` and bubble, so they cross
+         * shadow boundaries and reach `document`, letting us keep event delegation (no direct reference
+         * to the trigger element and no dependency on its mount/unmount lifecycle). The handlers filter
+         * out movements that stay within the trigger's subtree, recreating enter/leave semantics.
          * @internal
          */
         this.setupTriggerListeners = () => {
@@ -451,10 +459,10 @@ class Popover extends KeyDownHandledMixin(KeyToActionMixin(BackdropMixin(Prevent
             if (this.trigger.includes('mouseenter')) {
                 const hoverBridge = this.renderRoot.querySelector('div[part="popover-hover-bridge"]');
                 hoverBridge === null || hoverBridge === void 0 ? void 0 : hoverBridge.addEventListener('mouseenter', this.show);
-                document.addEventListener('mouseenter', this.handleMouseEnter, { capture: true });
-                document.addEventListener('mouseleave', this.handleMouseLeave, { capture: true });
                 this.addEventListener('mouseenter', this.cancelCloseDelay);
                 this.addEventListener('mouseleave', this.startCloseDelay);
+                document.addEventListener('mouseover', this.handleMouseEnter, { capture: true });
+                document.addEventListener('mouseout', this.handleMouseLeave, { capture: true });
             }
             if (this.trigger.includes('focusin')) {
                 document.addEventListener('focusin', this.handleFocusIn, { capture: true });
@@ -473,8 +481,8 @@ class Popover extends KeyDownHandledMixin(KeyToActionMixin(BackdropMixin(Prevent
             // mouseenter trigger
             const hoverBridge = this.renderRoot.querySelector('div[part="popover-hover-bridge"]');
             hoverBridge === null || hoverBridge === void 0 ? void 0 : hoverBridge.removeEventListener('mouseenter', this.show);
-            document.removeEventListener('mouseenter', this.handleMouseEnter, { capture: true });
-            document.removeEventListener('mouseleave', this.handleMouseLeave, { capture: true });
+            document.removeEventListener('mouseover', this.handleMouseEnter, { capture: true });
+            document.removeEventListener('mouseout', this.handleMouseLeave, { capture: true });
             this.removeEventListener('mouseenter', this.cancelCloseDelay);
             this.removeEventListener('mouseleave', this.startCloseDelay);
             // focusin trigger
@@ -551,18 +559,39 @@ class Popover extends KeyDownHandledMixin(KeyToActionMixin(BackdropMixin(Prevent
             }
         };
         /**
-         * Handles mouse enter event on the trigger element.
-         * This method sets the `isHovered` flag to true and shows the popover
+         * Determines whether a delegated `mouseover`/`mouseout` event is movement that stays within the
+         * trigger's subtree rather than a genuine enter/leave of the trigger.
+         *
+         * Both events fire repeatedly while the pointer moves between elements inside the trigger
+         * (e.g. an icon with internal SVG elements). `relatedTarget` is the element on the other side of
+         * the boundary (the element being left for `mouseover`, or entered for `mouseout`); if it
+         * resolves to the trigger or one of its shadow hosts, the pointer has not crossed the trigger
+         * boundary and the event should be ignored.
+         * @internal
+         */
+        this.isHoverWithinTrigger = (event) => {
+            const { triggerElement } = this;
+            const { relatedTarget } = event;
+            if (triggerElement && relatedTarget instanceof Element) {
+                return getHostComposePath(relatedTarget).includes(triggerElement);
+            }
+            return false;
+        };
+        /**
+         * Handles the pointer moving over the trigger element (delegated `mouseover`).
+         * This method sets the `isHovered` flag to true and shows the popover.
          * @internal
          */
         this.handleMouseEnter = (event) => {
             if (!this.isEventFromTrigger(event))
                 return;
+            if (this.isHoverWithinTrigger(event))
+                return;
             this.isHovered = true;
             this.show();
         };
         /**
-         * Handles mouse leave event on the trigger element.
+         * Handles the pointer leaving the trigger element (delegated `mouseout`).
          * This method sets the `isHovered` flag to false and starts the close delay
          * timer to hide the popover.
          * @internal
@@ -570,16 +599,8 @@ class Popover extends KeyDownHandledMixin(KeyToActionMixin(BackdropMixin(Prevent
         this.handleMouseLeave = (event) => {
             if (!this.isEventFromTrigger(event))
                 return;
-            // When the trigger contains shadow DOM children (e.g. an icon with internal SVG elements),
-            // mouseleave fires on internal elements as the mouse moves between them.
-            // Only close if the mouse has actually left the trigger element.
-            const mouseEvent = event;
-            const { triggerElement } = this;
-            if (triggerElement && mouseEvent.relatedTarget instanceof Element) {
-                if (getHostComposePath(mouseEvent.relatedTarget).includes(triggerElement)) {
-                    return;
-                }
-            }
+            if (this.isHoverWithinTrigger(event))
+                return;
             this.isHovered = false;
             this.startCloseDelay();
         };

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

@@ -18,8 +18,11 @@ import { ShortestDistanceWeights, SpatialNavigationContextValue, SpatialNavigati
  * Spatial navigation goes trough the following steps after each keydown:
  *
  * 1. Handle `keydown` in the capture phase.
- *    When active element has `data-spatial-{direction}` attribute then prevent all component navigation and call the
- *    provider own `keydown` handler (see step 3).
+ *    - When active element has `data-spatial-{direction}` attribute then prevent all component navigation and call the
+ *      provider own `keydown` handler (see step 3).
+ *    - When active element's parent is scrollable and it is not fully visible in the given direction and it does not
+ *      have `data-spatial-noscroll` attribute, prevent all navigation and scroll in the give direction half size of the
+ *      scroll view.
  * 2. Component own `keydown` handler executed (bubble phase) (e.g., list moves focus internally) it it was not
  *    prevented.
  * 3. Spatial Navigation Provider's `keydown` handler executed (bubble phase)
@@ -102,15 +105,16 @@ import { ShortestDistanceWeights, SpatialNavigationContextValue, SpatialNavigati
  *
  * Supported data attributes:
  *
- * | Attribute                | Value                     | Default | Description                                                                   |
- * |--------------------------|---------------------------|---------|-------------------------------------------------------------------------------|
- * | `data-spatial-left`      | empty string / element id | N/A     | Prevent native navigation in Left direction and focus element if exists       |
- * | `data-spatial-up`        | empty string / element id | N/A     | Prevent native navigation in Up direction and focus element if exists         |
- * | `data-spatial-right`     | empty string / element id | N/A     | Prevent native navigation in Right direction and focus element if exists      |
- * | `data-spatial-down`      | empty string / element id | N/A     | Prevent native navigation in Down direction and focus element if exists       |
- * | `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-exclude`   | N/A                       | N/A     | Exclude focusable element (and its subtree) from the navigation               |
+ * | Attribute                | Value                     | Default | Description                                                                        |
+ * |--------------------------|---------------------------|---------|------------------------------------------------------------------------------------|
+ * | `data-spatial-left`      | empty string / element id | N/A     | Prevent native navigation in Left direction and focus element if exists            |
+ * | `data-spatial-up`        | empty string / element id | N/A     | Prevent native navigation in Up direction and focus element if exists              |
+ * | `data-spatial-right`     | empty string / element id | N/A     | Prevent native navigation in Right direction and focus element if exists           |
+ * | `data-spatial-down`      | empty string / element id | N/A     | Prevent native navigation in Down direction and focus element if exists            |
+ * | `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-exclude`   | N/A                       | N/A     | Exclude focusable element (and its subtree) from the navigation                    |
+ * | `data-spatial-noscroll`  | N/A                       | N/A     | Prevent scroll for ative element in scrollable area even if the is not fit in view |
  *
  * ## Event emitting order
  *
@@ -202,12 +206,6 @@ import { ShortestDistanceWeights, SpatialNavigationContextValue, SpatialNavigati
  * - Avoid nested focusable elements where possible.
  * - Tune algorithm weights to match your UI layout.
  *
- * ### Scrollable containers
- *
- * Content scrolling is not supported yet, e.g.:
- * - Focused element larger than the viewport.
- * - Scrollable content without interactive children.
- *
  * ### Nested providers
  *
  * Only one provider instance is supported in the application at a time.

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

@@ -9,7 +9,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 import { property } from 'lit/decorators.js';
 import { Provider } from '../../models';
-import { findFocusable, getDomActiveElement, getHostComposePath, isScrollable } from '../../utils/dom';
+import { findFocusable, getDomActiveElement, getHostComposePath, getScrollableAxis } from '../../utils/dom';
 import { FocusTrapStack } from '../../utils/mixins/focus/FocusTrapStack';
 import SpatialNavigationProviderContext from './spatialnavigationprovider.context';
 import { DEFAULTS } from './spatialnavigationprovider.constants';
@@ -34,8 +34,11 @@ import { SpatialNavigationEvent } from './spatialnavigationprovider.events';
  * Spatial navigation goes trough the following steps after each keydown:
  *
  * 1. Handle `keydown` in the capture phase.
- *    When active element has `data-spatial-{direction}` attribute then prevent all component navigation and call the
- *    provider own `keydown` handler (see step 3).
+ *    - When active element has `data-spatial-{direction}` attribute then prevent all component navigation and call the
+ *      provider own `keydown` handler (see step 3).
+ *    - When active element's parent is scrollable and it is not fully visible in the given direction and it does not
+ *      have `data-spatial-noscroll` attribute, prevent all navigation and scroll in the give direction half size of the
+ *      scroll view.
  * 2. Component own `keydown` handler executed (bubble phase) (e.g., list moves focus internally) it it was not
  *    prevented.
  * 3. Spatial Navigation Provider's `keydown` handler executed (bubble phase)
@@ -118,15 +121,16 @@ import { SpatialNavigationEvent } from './spatialnavigationprovider.events';
  *
  * Supported data attributes:
  *
- * | Attribute                | Value                     | Default | Description                                                                   |
- * |--------------------------|---------------------------|---------|-------------------------------------------------------------------------------|
- * | `data-spatial-left`      | empty string / element id | N/A     | Prevent native navigation in Left direction and focus element if exists       |
- * | `data-spatial-up`        | empty string / element id | N/A     | Prevent native navigation in Up direction and focus element if exists         |
- * | `data-spatial-right`     | empty string / element id | N/A     | Prevent native navigation in Right direction and focus element if exists      |
- * | `data-spatial-down`      | empty string / element id | N/A     | Prevent native navigation in Down direction and focus element if exists       |
- * | `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-exclude`   | N/A                       | N/A     | Exclude focusable element (and its subtree) from the navigation               |
+ * | Attribute                | Value                     | Default | Description                                                                        |
+ * |--------------------------|---------------------------|---------|------------------------------------------------------------------------------------|
+ * | `data-spatial-left`      | empty string / element id | N/A     | Prevent native navigation in Left direction and focus element if exists            |
+ * | `data-spatial-up`        | empty string / element id | N/A     | Prevent native navigation in Up direction and focus element if exists              |
+ * | `data-spatial-right`     | empty string / element id | N/A     | Prevent native navigation in Right direction and focus element if exists           |
+ * | `data-spatial-down`      | empty string / element id | N/A     | Prevent native navigation in Down direction and focus element if exists            |
+ * | `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-exclude`   | N/A                       | N/A     | Exclude focusable element (and its subtree) from the navigation                    |
+ * | `data-spatial-noscroll`  | N/A                       | N/A     | Prevent scroll for ative element in scrollable area even if the is not fit in view |
  *
  * ## Event emitting order
  *
@@ -218,12 +222,6 @@ import { SpatialNavigationEvent } from './spatialnavigationprovider.events';
  * - Avoid nested focusable elements where possible.
  * - Tune algorithm weights to match your UI layout.
  *
- * ### Scrollable containers
- *
- * Content scrolling is not supported yet, e.g.:
- * - Focused element larger than the viewport.
- * - Scrollable content without interactive children.
- *
  * ### Nested providers
  *
  * Only one provider instance is supported in the application at a time.
@@ -305,15 +303,51 @@ class SpatialNavigationProvider extends Provider {
             if (evt.shiftKey || evt.ctrlKey || evt.altKey || evt.metaKey || !this.isNavigationKey(evt.key)) {
                 return;
             }
+            let eventHandled = false;
+            const target = evt.target;
             const action = this.context.value.keyToActionMap[evt.key];
             if (this.isDirectionKey(evt.key) &&
-                this.getElementIdForDirectionAttr(evt.target, action) !== undefined) {
+                this.getElementIdForDirectionAttr(target, action) !== undefined) {
+                eventHandled = true;
+                // Need to call Spatial navigation key handler manually after all propagation stopped
+                this.handleKeyDown(evt);
+            }
+            // Handle over sized elements inside scrollable area
+            if (target.parentElement && !target.hasAttribute('data-spatial-noscroll')) {
+                const parent = target.parentElement;
+                const targetScrollAxis = getScrollableAxis(parent);
+                if (targetScrollAxis) {
+                    const targetBB = target.getBoundingClientRect();
+                    const parentBB = parent.getBoundingClientRect();
+                    // Vertical scrolling
+                    if (targetScrollAxis === 'vertical' || targetScrollAxis === 'both') {
+                        if (action === 'up' && targetBB.top < parentBB.top && parent.scrollTop > 0) {
+                            parent.scrollTo({ top: parent.scrollTop - parentBB.height / 2, behavior: 'auto' });
+                            eventHandled = true;
+                        }
+                        if (action === 'down' && targetBB.bottom > parentBB.bottom && (parent.scrollTop + parentBB.height) < parent.scrollHeight) {
+                            parent.scrollTo({ top: parent.scrollTop + parentBB.height / 2, behavior: 'auto' });
+                            eventHandled = true;
+                        }
+                    }
+                    // horizontal scrolling
+                    if (targetScrollAxis === 'horizontal' || targetScrollAxis === 'both') {
+                        if (action === 'right' && targetBB.left < parentBB.left && parent.scrollLeft > 0) {
+                            parent.scrollTo({ left: parent.scrollLeft - parentBB.width / 2, behavior: 'auto' });
+                            eventHandled = true;
+                        }
+                        if (action === 'left' && targetBB.right > parentBB.right && (parent.scrollLeft + parentBB.width) < parent.scrollWidth) {
+                            parent.scrollTo({ left: parent.scrollLeft + parentBB.width / 2, behavior: 'auto' });
+                            eventHandled = true;
+                        }
+                    }
+                }
+            }
+            if (eventHandled) {
                 // prevent native key events
                 evt.preventDefault();
                 // prevent MDC component key events
                 evt.stopImmediatePropagation();
-                // Need to call Spatial navigation key handler manually after all propagation stopped
-                this.handleKeyDown(evt);
             }
         };
         /**
@@ -474,7 +508,7 @@ class SpatialNavigationProvider extends Provider {
         path = path.includes(this.root) ? path : [this.root];
         // Walk through the composed path to find the focus areas (scrollable or focus trap)
         for (const el of path) {
-            if (el === activeTrap || el === this.root || isScrollable(el)) {
+            if (el === activeTrap || el === this.root || getScrollableAxis(el)) {
                 // Find focusable elements within the current focus area (excluding the already checked focus areas)
                 focusableElements.push(...findFocusable(el, {
                     excludedElements: checkedFocusArea ? [checkedFocusArea] : undefined,

package/dist/custom-elements.json

@@ -173,8 +173,8 @@
               "attribute": "disabled",
               "reflects": true,
               "inheritedFrom": {
-                "name": "AccordionButton",
-                "module": "components/accordionbutton/accordionbutton.component.js"
+                "name": "DisabledMixin",
+                "module": "utils/mixins/DisabledMixin.js"
               }
             },
             {
@@ -493,8 +493,8 @@
               "default": "undefined",
               "fieldName": "disabled",
               "inheritedFrom": {
-                "name": "AccordionButton",
-                "module": "src/components/accordionbutton/accordionbutton.component.ts"
+                "name": "DisabledMixin",
+                "module": "src/utils/mixins/DisabledMixin.ts"
               }
             },
             {
@@ -44925,7 +44925,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Spatial navigation focus manager\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\nIt should have only one instance and it should placed at the root of the application.\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\n### Steps\n\nSpatial navigation goes trough the following steps after each keydown:\n\n1. Handle `keydown` in the capture phase.\n   When active element has `data-spatial-{direction}` attribute then prevent all component navigation and call the\n   provider own `keydown` handler (see step 3).\n2. Component own `keydown` handler executed (bubble phase) (e.g., list moves focus internally) it it was not\n   prevented.\n3. Spatial Navigation Provider's `keydown` handler executed (bubble phase)\n   - If key event was not prevented in step 1. emit `navbeforeprocess` to check if any component want to handle\n     the key event itself. If `navbeforeprocess` event is prevented, stop here.\n   - If the component did not handle `keydown`, it calculate the next focusable item\n     - if the active element has `data-spatial-{direction}` attribute, it will try to focus the element with the id.\n     - Otherwise calculate the next focused item based on the direction and distances.\n   - If there is no next item, it emits `navnotarget` event\n   - Otherwise emit `navbeforefocus`,\n     - If this event prevented, nothing happens\n     - Otherwise the focus moves to the next element\n\n### Determine next focus\n\nThe provider use multiple ways to determine the next focused element. The order defined in the \"Steps\" section.\n\n#### Calculated focus\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\nNote: The algorithm is distance-based, so the UI should be designed to 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#### Overwrite next element\n\nOverride calculated 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`      | empty string / element id | N/A     | Prevent native navigation in Left direction and focus element if exists       |\n| `data-spatial-up`        | empty string / element id | N/A     | Prevent native navigation in Up direction and focus element if exists         |\n| `data-spatial-right`     | empty string / element id | N/A     | Prevent native navigation in Right direction and focus element if exists      |\n| `data-spatial-down`      | empty string / element id | N/A     | Prevent native navigation in Down direction and focus element if exists       |\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.",
+          "description": "Spatial navigation focus manager\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\nIt should have only one instance and it should placed at the root of the application.\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\n### Steps\n\nSpatial navigation goes trough the following steps after each keydown:\n\n1. Handle `keydown` in the capture phase.\n   - When active element has `data-spatial-{direction}` attribute then prevent all component navigation and call the\n     provider own `keydown` handler (see step 3).\n   - When active element's parent is scrollable and it is not fully visible in the given direction and it does not\n     have `data-spatial-noscroll` attribute, prevent all navigation and scroll in the give direction half size of the\n     scroll view.\n2. Component own `keydown` handler executed (bubble phase) (e.g., list moves focus internally) it it was not\n   prevented.\n3. Spatial Navigation Provider's `keydown` handler executed (bubble phase)\n   - If key event was not prevented in step 1. emit `navbeforeprocess` to check if any component want to handle\n     the key event itself. If `navbeforeprocess` event is prevented, stop here.\n   - If the component did not handle `keydown`, it calculate the next focusable item\n     - if the active element has `data-spatial-{direction}` attribute, it will try to focus the element with the id.\n     - Otherwise calculate the next focused item based on the direction and distances.\n   - If there is no next item, it emits `navnotarget` event\n   - Otherwise emit `navbeforefocus`,\n     - If this event prevented, nothing happens\n     - Otherwise the focus moves to the next element\n\n### Determine next focus\n\nThe provider use multiple ways to determine the next focused element. The order defined in the \"Steps\" section.\n\n#### Calculated focus\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\nNote: The algorithm is distance-based, so the UI should be designed to 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#### Overwrite next element\n\nOverride calculated 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`      | empty string / element id | N/A     | Prevent native navigation in Left direction and focus element if exists            |\n| `data-spatial-up`        | empty string / element id | N/A     | Prevent native navigation in Up direction and focus element if exists              |\n| `data-spatial-right`     | empty string / element id | N/A     | Prevent native navigation in Right direction and focus element if exists           |\n| `data-spatial-down`      | empty string / element id | N/A     | Prevent native navigation in Down direction and focus element if exists            |\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| `data-spatial-noscroll`  | N/A                       | N/A     | Prevent scroll for ative element in scrollable area even if the is not fit in view |\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### Nested providers\n\nOnly one provider instance is supported in the application at a time.",
           "name": "SpatialNavigationProvider",
           "members": [
             {
@@ -45087,7 +45087,7 @@
             "module": "/src/models"
           },
           "tagName": "mdc-spatialnavigationprovider",
-          "jsDoc": "/**\n * Spatial navigation focus manager\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 * It should have only one instance and it should placed at the root of the application.\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 * ### Steps\n *\n * Spatial navigation goes trough the following steps after each keydown:\n *\n * 1. Handle `keydown` in the capture phase.\n *    When active element has `data-spatial-{direction}` attribute then prevent all component navigation and call the\n *    provider own `keydown` handler (see step 3).\n * 2. Component own `keydown` handler executed (bubble phase) (e.g., list moves focus internally) it it was not\n *    prevented.\n * 3. Spatial Navigation Provider's `keydown` handler executed (bubble phase)\n *    - If key event was not prevented in step 1. emit `navbeforeprocess` to check if any component want to handle\n *      the key event itself. If `navbeforeprocess` event is prevented, stop here.\n *    - If the component did not handle `keydown`, it calculate the next focusable item\n *      - if the active element has `data-spatial-{direction}` attribute, it will try to focus the element with the id.\n *      - Otherwise calculate the next focused item based on the direction and distances.\n *    - If there is no next item, it emits `navnotarget` event\n *    - Otherwise emit `navbeforefocus`,\n *      - If this event prevented, nothing happens\n *      - Otherwise the focus moves to the next element\n *\n * ### Determine next focus\n *\n * The provider use multiple ways to determine the next focused element. The order defined in the \"Steps\" section.\n *\n * #### Calculated focus\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 * Note: The algorithm is distance-based, so the UI should be designed to 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 * #### Overwrite next element\n *\n * Override calculated 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`      | empty string / element id | N/A     | Prevent native navigation in Left direction and focus element if exists       |\n * | `data-spatial-up`        | empty string / element id | N/A     | Prevent native navigation in Up direction and focus element if exists         |\n * | `data-spatial-right`     | empty string / element id | N/A     | Prevent native navigation in Right direction and focus element if exists      |\n * | `data-spatial-down`      | empty string / element id | N/A     | Prevent native navigation in Down direction and focus element if exists       |\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 */",
+          "jsDoc": "/**\n * Spatial navigation focus manager\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 * It should have only one instance and it should placed at the root of the application.\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 * ### Steps\n *\n * Spatial navigation goes trough the following steps after each keydown:\n *\n * 1. Handle `keydown` in the capture phase.\n *    - When active element has `data-spatial-{direction}` attribute then prevent all component navigation and call the\n *      provider own `keydown` handler (see step 3).\n *    - When active element's parent is scrollable and it is not fully visible in the given direction and it does not\n *      have `data-spatial-noscroll` attribute, prevent all navigation and scroll in the give direction half size of the\n *      scroll view.\n * 2. Component own `keydown` handler executed (bubble phase) (e.g., list moves focus internally) it it was not\n *    prevented.\n * 3. Spatial Navigation Provider's `keydown` handler executed (bubble phase)\n *    - If key event was not prevented in step 1. emit `navbeforeprocess` to check if any component want to handle\n *      the key event itself. If `navbeforeprocess` event is prevented, stop here.\n *    - If the component did not handle `keydown`, it calculate the next focusable item\n *      - if the active element has `data-spatial-{direction}` attribute, it will try to focus the element with the id.\n *      - Otherwise calculate the next focused item based on the direction and distances.\n *    - If there is no next item, it emits `navnotarget` event\n *    - Otherwise emit `navbeforefocus`,\n *      - If this event prevented, nothing happens\n *      - Otherwise the focus moves to the next element\n *\n * ### Determine next focus\n *\n * The provider use multiple ways to determine the next focused element. The order defined in the \"Steps\" section.\n *\n * #### Calculated focus\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 * Note: The algorithm is distance-based, so the UI should be designed to 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 * #### Overwrite next element\n *\n * Override calculated 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`      | empty string / element id | N/A     | Prevent native navigation in Left direction and focus element if exists            |\n * | `data-spatial-up`        | empty string / element id | N/A     | Prevent native navigation in Up direction and focus element if exists              |\n * | `data-spatial-right`     | empty string / element id | N/A     | Prevent native navigation in Right direction and focus element if exists           |\n * | `data-spatial-down`      | empty string / element id | N/A     | Prevent native navigation in Down direction and focus element if exists            |\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 * | `data-spatial-noscroll`  | N/A                       | N/A     | Prevent scroll for ative element in scrollable area even if the is not fit in view |\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 * ### 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
         }
       ],

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

@@ -19,8 +19,11 @@ import type { Events } from '../../components/spatialnavigationprovider/spatialn
  * Spatial navigation goes trough the following steps after each keydown:
  *
  * 1. Handle `keydown` in the capture phase.
- *    When active element has `data-spatial-{direction}` attribute then prevent all component navigation and call the
- *    provider own `keydown` handler (see step 3).
+ *    - When active element has `data-spatial-{direction}` attribute then prevent all component navigation and call the
+ *      provider own `keydown` handler (see step 3).
+ *    - When active element's parent is scrollable and it is not fully visible in the given direction and it does not
+ *      have `data-spatial-noscroll` attribute, prevent all navigation and scroll in the give direction half size of the
+ *      scroll view.
  * 2. Component own `keydown` handler executed (bubble phase) (e.g., list moves focus internally) it it was not
  *    prevented.
  * 3. Spatial Navigation Provider's `keydown` handler executed (bubble phase)
@@ -103,15 +106,16 @@ import type { Events } from '../../components/spatialnavigationprovider/spatialn
  *
  * Supported data attributes:
  *
- * | Attribute                | Value                     | Default | Description                                                                   |
- * |--------------------------|---------------------------|---------|-------------------------------------------------------------------------------|
- * | `data-spatial-left`      | empty string / element id | N/A     | Prevent native navigation in Left direction and focus element if exists       |
- * | `data-spatial-up`        | empty string / element id | N/A     | Prevent native navigation in Up direction and focus element if exists         |
- * | `data-spatial-right`     | empty string / element id | N/A     | Prevent native navigation in Right direction and focus element if exists      |
- * | `data-spatial-down`      | empty string / element id | N/A     | Prevent native navigation in Down direction and focus element if exists       |
- * | `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-exclude`   | N/A                       | N/A     | Exclude focusable element (and its subtree) from the navigation               |
+ * | Attribute                | Value                     | Default | Description                                                                        |
+ * |--------------------------|---------------------------|---------|------------------------------------------------------------------------------------|
+ * | `data-spatial-left`      | empty string / element id | N/A     | Prevent native navigation in Left direction and focus element if exists            |
+ * | `data-spatial-up`        | empty string / element id | N/A     | Prevent native navigation in Up direction and focus element if exists              |
+ * | `data-spatial-right`     | empty string / element id | N/A     | Prevent native navigation in Right direction and focus element if exists           |
+ * | `data-spatial-down`      | empty string / element id | N/A     | Prevent native navigation in Down direction and focus element if exists            |
+ * | `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-exclude`   | N/A                       | N/A     | Exclude focusable element (and its subtree) from the navigation                    |
+ * | `data-spatial-noscroll`  | N/A                       | N/A     | Prevent scroll for ative element in scrollable area even if the is not fit in view |
  *
  * ## Event emitting order
  *
@@ -203,12 +207,6 @@ import type { Events } from '../../components/spatialnavigationprovider/spatialn
  * - Avoid nested focusable elements where possible.
  * - Tune algorithm weights to match your UI layout.
  *
- * ### Scrollable containers
- *
- * Content scrolling is not supported yet, e.g.:
- * - Focused element larger than the viewport.
- * - Scrollable content without interactive children.
- *
  * ### Nested providers
  *
  * Only one provider instance is supported in the application at a time.

package/dist/react/spatialnavigationprovider/index.js

@@ -20,8 +20,11 @@ import { TAG_NAME } from '../../components/spatialnavigationprovider/spatialnavi
  * Spatial navigation goes trough the following steps after each keydown:
  *
  * 1. Handle `keydown` in the capture phase.
- *    When active element has `data-spatial-{direction}` attribute then prevent all component navigation and call the
- *    provider own `keydown` handler (see step 3).
+ *    - When active element has `data-spatial-{direction}` attribute then prevent all component navigation and call the
+ *      provider own `keydown` handler (see step 3).
+ *    - When active element's parent is scrollable and it is not fully visible in the given direction and it does not
+ *      have `data-spatial-noscroll` attribute, prevent all navigation and scroll in the give direction half size of the
+ *      scroll view.
  * 2. Component own `keydown` handler executed (bubble phase) (e.g., list moves focus internally) it it was not
  *    prevented.
  * 3. Spatial Navigation Provider's `keydown` handler executed (bubble phase)
@@ -104,15 +107,16 @@ import { TAG_NAME } from '../../components/spatialnavigationprovider/spatialnavi
  *
  * Supported data attributes:
  *
- * | Attribute                | Value                     | Default | Description                                                                   |
- * |--------------------------|---------------------------|---------|-------------------------------------------------------------------------------|
- * | `data-spatial-left`      | empty string / element id | N/A     | Prevent native navigation in Left direction and focus element if exists       |
- * | `data-spatial-up`        | empty string / element id | N/A     | Prevent native navigation in Up direction and focus element if exists         |
- * | `data-spatial-right`     | empty string / element id | N/A     | Prevent native navigation in Right direction and focus element if exists      |
- * | `data-spatial-down`      | empty string / element id | N/A     | Prevent native navigation in Down direction and focus element if exists       |
- * | `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-exclude`   | N/A                       | N/A     | Exclude focusable element (and its subtree) from the navigation               |
+ * | Attribute                | Value                     | Default | Description                                                                        |
+ * |--------------------------|---------------------------|---------|------------------------------------------------------------------------------------|
+ * | `data-spatial-left`      | empty string / element id | N/A     | Prevent native navigation in Left direction and focus element if exists            |
+ * | `data-spatial-up`        | empty string / element id | N/A     | Prevent native navigation in Up direction and focus element if exists              |
+ * | `data-spatial-right`     | empty string / element id | N/A     | Prevent native navigation in Right direction and focus element if exists           |
+ * | `data-spatial-down`      | empty string / element id | N/A     | Prevent native navigation in Down direction and focus element if exists            |
+ * | `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-exclude`   | N/A                       | N/A     | Exclude focusable element (and its subtree) from the navigation                    |
+ * | `data-spatial-noscroll`  | N/A                       | N/A     | Prevent scroll for ative element in scrollable area even if the is not fit in view |
  *
  * ## Event emitting order
  *
@@ -204,12 +208,6 @@ import { TAG_NAME } from '../../components/spatialnavigationprovider/spatialnavi
  * - Avoid nested focusable elements where possible.
  * - Tune algorithm weights to match your UI layout.
  *
- * ### Scrollable containers
- *
- * Content scrolling is not supported yet, e.g.:
- * - Focused element larger than the viewport.
- * - Scrollable content without interactive children.
- *
  * ### Nested providers
  *
  * Only one provider instance is supported in the application at a time.

package/dist/utils/dom.d.ts

@@ -64,7 +64,7 @@ export declare const hasZeroDimensions: (element: HTMLElement) => boolean;
  * @param element - The element to check.
  * @returns True if the element is scrollable.
  */
-export declare const isScrollable: (element: HTMLElement) => boolean;
+export declare const getScrollableAxis: (element: HTMLElement) => null | "horizontal" | "vertical" | "both";
 /**
  * Determines if the element is not visible in the DOM.
  *

package/dist/utils/dom.js

@@ -49,13 +49,20 @@ export const hasZeroDimensions = (element) => {
  * @param element - The element to check.
  * @returns True if the element is scrollable.
  */
-export const isScrollable = (element) => {
+export const getScrollableAxis = (element) => {
     if (!(element instanceof Element))
-        return false;
+        return null;
     const computedStyle = getComputedStyle(element);
     const { overflowX, overflowY } = computedStyle;
-    // Check if overflow is set to scrollable values
-    return overflowX === 'auto' || overflowX === 'scroll' || overflowY === 'auto' || overflowY === 'scroll';
+    const horizontal = overflowX === 'auto' || overflowX === 'scroll';
+    const vertical = overflowY === 'auto' || overflowY === 'scroll';
+    if (horizontal && vertical)
+        return 'both';
+    if (horizontal)
+        return 'horizontal';
+    if (vertical)
+        return 'vertical';
+    return null;
 };
 /**
  * Determines if the element is not visible in the DOM.