@momentum-design/components 0.134.20 → 0.134.21

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

@@ -1,219 +1,21 @@
 import { Provider } from '../../models';
 import { ShortestDistanceWeights, SpatialNavigationContextValue, SpatialNavigationActionToKeyMap } from './spatialnavigationprovider.types';
 /**
- * Spatial navigation focus manager
- *
- * [Spatial navigation](https://en.wikipedia.org/wiki/Spatial_navigation) lets users move focus among
- * elements on a 2D plane, common on TVs and game consoles with remotes or gamepads.
- *
- * It should have only one instance, and it should be placed at the root of the application.
- *
- * ## Focus management
- *
- * The provider listens to keyboard events and moves focus among elements based on arrow key input.
- * You can influence or override this behavior.
- *
- * ### Steps
- *
- * Spatial navigation goes through the following steps after each keydown:
- *
- * 1. Handle `keydown` in the capture phase.
- *    - When the active element has a `data-spatial-{direction}` attribute, call the provider's own `keydown` handler (see step 3).
- *      Falls back to component navigation provider did not handle the event.
- *    - When the active element's parent is scrollable and it is not fully visible in the given direction, and it does not
- *      have a `data-spatial-noscroll` attribute, prevent all navigation and scroll in the given 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)
- *    - If a key event was not prevented in step 1. emit `navbeforeprocess` to check if any component wants to handle
- *      the key event itself. If `navbeforeprocess` event is prevented, stop here.
- *    - If the component did not handle `keydown`, it calculates the next focusable item
- *      - If the active element has a `data-spatial-{direction}` attribute,
- *        - Evaluate the attribute value, try element ID, and falls back to css selector if needed
- *          - If it is focusable, move the focus there.
- *          - If it is not focusable and contains focusable elements, calculate the next focused item within that element subtree.
- *      - Otherwise calculate the next focused item based on the direction and distances.
- *    - If there is no next item, it emits `navnotarget` event
- *    - Otherwise emit `navbeforefocus`,
- *      - If this event is prevented, nothing happens
- *      - Otherwise the focus moves to the next element
- *
- * ### Determine next focus
- *
- * The provider uses multiple ways to determine the next focused element. The order defined in the "Steps" section.
- *
- * #### Calculated focus
- *
- * By default, the next focus target is computed from element positions:
- *
- * 1. Find the nearest focus area (scrollable container or active focus trap) relative to the current element.
- * 2. Collect focusable elements in that area.
- * 3. Compute distances from the current element to candidates using the W3C "find the shortest
- *    distance" algorithm: https://www.w3.org/TR/css-nav-1/#find-the-shortest-distance
- * 4. If no candidates are found, repeat from step 1, skipping areas already checked.
- * 5. Focus on the closest candidate.
- *
- * Elements with `data-spatial-focusable` are treated as focusable even if they do 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.
- *
- * Note: The algorithm is distance-based, so the UI should be designed to focusable elements are
- * predictably reachable. Relative element positions should remain stable; responsive layouts can
- * make navigation unpredictable. This is less of an issue on fixed-size TV UIs but can show unexpected
- * behavior in Storybook when resizing. See the "Limitations" section.
- *
- * #### Overwrite the next element
- *
- * Override calculated navigation by adding one of these attributes to a focusable element:
- *
- * - `data-spatial-up`
- * - `data-spatial-down`
- * - `data-spatial-left`
- * - `data-spatial-right`
- *
- * Each attribute value must be the id of the element to focus when the corresponding key is pressed.
- *
- * #### Element internal navigation
- *
- * Complex components (List, Combobox, Tree, etc.) may handle their own navigation. For example, a List moves
- * focus internally on Down until the last item, after which Down should fall back to provider navigation.
- *
- * To prevent the provider from handling a key, listen to `navbeforeprocess` and call `event.preventDefault()`.
- * This event fires after the component handles `keydown`.
- *
- * ### Cancel focus change
- *
- * Before focusing a computed target, the provider dispatches `navbeforefocus` on the current element. Call
- * `event.preventDefault()` on this event to cancel the focus change.
- *
- * ## Enter action
- *
- * Pressing Enter triggers `.click()` on the currently focused element.
- *
- * You can prevent this by listening to `navbeforeprocess` and calling `event.preventDefault()`.
- *
- * ## Escape/Back action
- *
- * Pressing Escape tries to find a focusable element with `data-spatial-go-back` and clicks it. If none exists,
- * the provider calls `history.back()`.
- *
- * You can prevent this by listening to `navbeforeprocess` and calling `event.preventDefault()`.
- *
- * You can also intercept the back click by listening to `navback` and calling `event.preventDefault()`.
- *
- * ## Control data attributes
- *
- * Supported data attributes:
- *
- * | Attribute                    | Value                        | Default | Description                                                                                                                        |
- * |------------------------------|------------------------------|---------|------------------------------------------------------------------------------------------------------------------------------------|
- * | `data-spatial-left`          | empty string / id / selector | N/A     | Prevent native navigation in the Left direction, focus it if it's focusable otherwise limit the search in the selected container.  |
- * | `data-spatial-up`            | empty string / id / selector | N/A     | Prevent native navigation in Up direction, focus it if it's focusable otherwise limit the search in the selected container.        |
- * | `data-spatial-right`         | empty string / id / selector | N/A     | Prevent native navigation in the Right direction, focus it if it's focusable otherwise limit the search in the selected container. |
- * | `data-spatial-down`          | empty string / id / selector | N/A     | Prevent native navigation in Down direction, focus it if it's focusable otherwise limit the search in the selected container.      |
- * | `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 active element in scrollable area even if the is not fit in view                                                |
- * | `data-spatial-scroll-parent` | N/A                          | N/A     | When the focusable item in not a direct child of the scrollable aria use this attribute to mark scrollable area element            |
- *
- * ## Event emitting order
- *
- * On a navigation key press, events fire in this order:
- *
- * 1. `navbeforeprocess` on the currently focused element.
- * 2. If not prevented:
- * a. Arrow keys: `navbeforefocus` on the currently focused element.
- * b. Enter: `.click()` on the currently focused element.
- * c. Escape/Back: `navback` on the provider, then `.click()` on the go-back element or `history.back()`.
- * 3. If no target is found in the requested direction: `navnotarget` on the provider.
- *
- * ## Handle complex components
- *
- * ### Generic components
- *
- * Components that handle navigation internally should prevent the provider from acting. Handle `navbeforeprocess`
- * and call `event.preventDefault()` for keys you process yourself.
- *
- * ### Form inputs
- *
- * Native inputs often submit on Enter, which is not desirable here. Enter should toggle or activate the control
- * (e.g., check/uncheck). Provide a dedicated submit button users can navigate to and press Enter on.
- *
- * ### Utilities for complex components
- *
- * #### KeyToActionMixin
- *
- * Maps key events to action names. Call `getActionForKeyEvent` to get the action for a keyboard event. Also provides
- * `getKeyboardNavMode` to check whether navigation is spatial or default.
- *
- * #### KeyDownHandledMixin
- *
- * Notify the provider when a component handled `keydown` internally. Call `keyDownEventHandled` whenever you process
- * keydown yourself.
- *
- * ## Platform specific behaviors
- *
- * Consider remote/gamepad constraints. Often focus alone is not enough, and users press Enter to "enter" an interactive mode:
- * - Select: Enter opens options rather than arrow keys opening a popover.
- * - Text inputs: see the next section.
- * - Slider: Enter to start adjusting, arrow keys to change value, Enter/Escape to stop.
- *
- * ### Text inputs
- *
- * On TV-like platforms without physical keyboards, Enter/focus on an input should open a virtual keyboard instead of submitting
- * the form. Users must close the keyboard (Escape) to continue spatial navigation.
- *
- * If navigation keys are mapped to letters (e.g., `w/a/s/d`), they should navigate, not change input values. Inputs should
- * be edited via the virtual keyboard.
- *
- * Note: Stories do not emulate virtual keyboards, so letter-based navigation may change input values in Storybook.
- *
- * ## Debugging
- *
- * ### Storybook toolbar
- *
- * Enable "Spatial navigation" in the toolbar. Key mapping:
- * - Up - ArrowUp
- * - Left - ArrowLeft
- * - Down - ArrowDown
- * - Right - ArrowRight
- * - Enter - Enter
- * - Escape - Escape
- *
- * With wrapper: wraps the component in a 3x3 grid with surrounding buttons for testing.
- * Without a wrapper: renders the component alone.
- *
- * ### Visual debugger
- *
- * With spatial navigation enabled, press Shift + navigation key to visualize calculations:
- *
- * - Star: next active element
- * - `#{number}`: candidate order by distance
- * - `D: {distance}`: computed distance
- *
- * ## Limitations
- *
- * ### Completeness
- *
- * The algorithm cannot guarantee reachability to all elements using the four directions. Some components can be isolated.
- *
- * Workarounds:
- * - Use data attributes to explicitly link navigation targets.
- * - Arrange DOM to improve spatial consistency:
- * - Group focusable elements using dedicated components (lists, menus, etc.).
- * - Avoid complex grid-like layouts with variable-sized items.
- * - Avoid overlap along horizontal or vertical axes.
- * - Avoid nested focusable elements where possible.
- * - Tune algorithm weights to match your UI layout.
- *
- * ### Nested providers
- *
- * Only one provider instance is supported in the application at a time.
- *
+ * The spatial navigation provider implements [spatial navigation](https://en.wikipedia.org/wiki/Spatial_navigation): it lets users move focus between elements on a 2D plane using arrow keys, Enter, and Escape, the way TV remotes and game controllers do. It listens to keyboard events at the document level, computes the next focus target from element positions, and dispatches cancellable events around every navigation step.
+ * 
+ * Only one instance is supported per application, placed at the root.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-spatialnavigationprovider` for TV, set-top-box, console, or kiosk apps where the primary input is a remote or directional pad.
+ * - Use it when consumers should be able to override or intercept focus movement via data attributes or DOM events.
+ * 
+ * **When not to use**
+ * 
+ * - Do not use it in a typical pointer-and-keyboard web app where browser-native focus order is sufficient.
+ * - Do not nest providers — only one instance per application is supported.
+ * 
+ * @tagname mdc-spatialnavigationprovider
  * @event navbeforeprocess - (React: onNavBeforeProcess) This event dispatched before spatial navigation process any key event.
  *                           It can be canceled to prevent any action from spatial navigation, e.g.: back, click or calculating the next candidate.
  * @event navbeforefocus - (React: onNavBeforeFocus) This event is dispatched before the focus is changing to the next element.
@@ -223,8 +25,6 @@ import { ShortestDistanceWeights, SpatialNavigationContextValue, SpatialNavigati
  *                  action on the goBackElement.
  * @event navnotarget - (React: onNavNoTarget) This event is dispatched when there is no target to focus in the current focus area and
  *                      in the given direction .
- *
- * @tagname mdc-spatialnavigationprovider
  */
 declare class SpatialNavigationProvider extends Provider<SpatialNavigationContextValue> {
     /**

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

@@ -15,221 +15,8 @@ import SpatialNavigationProviderContext from './spatialnavigationprovider.contex
 import { DATA_ATTRIBUTES, DEFAULTS } from './spatialnavigationprovider.constants';
 import { orderElementsByDistance } from './spatialnavigationprovider.utils';
 import { SpatialNavigationEvent } from './spatialnavigationprovider.events';
-// AI-Assisted
 /**
- * Spatial navigation focus manager
- *
- * [Spatial navigation](https://en.wikipedia.org/wiki/Spatial_navigation) lets users move focus among
- * elements on a 2D plane, common on TVs and game consoles with remotes or gamepads.
- *
- * It should have only one instance, and it should be placed at the root of the application.
- *
- * ## Focus management
- *
- * The provider listens to keyboard events and moves focus among elements based on arrow key input.
- * You can influence or override this behavior.
- *
- * ### Steps
- *
- * Spatial navigation goes through the following steps after each keydown:
- *
- * 1. Handle `keydown` in the capture phase.
- *    - When the active element has a `data-spatial-{direction}` attribute, call the provider's own `keydown` handler (see step 3).
- *      Falls back to component navigation provider did not handle the event.
- *    - When the active element's parent is scrollable and it is not fully visible in the given direction, and it does not
- *      have a `data-spatial-noscroll` attribute, prevent all navigation and scroll in the given 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)
- *    - If a key event was not prevented in step 1. emit `navbeforeprocess` to check if any component wants to handle
- *      the key event itself. If `navbeforeprocess` event is prevented, stop here.
- *    - If the component did not handle `keydown`, it calculates the next focusable item
- *      - If the active element has a `data-spatial-{direction}` attribute,
- *        - Evaluate the attribute value, try element ID, and falls back to css selector if needed
- *          - If it is focusable, move the focus there.
- *          - If it is not focusable and contains focusable elements, calculate the next focused item within that element subtree.
- *      - Otherwise calculate the next focused item based on the direction and distances.
- *    - If there is no next item, it emits `navnotarget` event
- *    - Otherwise emit `navbeforefocus`,
- *      - If this event is prevented, nothing happens
- *      - Otherwise the focus moves to the next element
- *
- * ### Determine next focus
- *
- * The provider uses multiple ways to determine the next focused element. The order defined in the "Steps" section.
- *
- * #### Calculated focus
- *
- * By default, the next focus target is computed from element positions:
- *
- * 1. Find the nearest focus area (scrollable container or active focus trap) relative to the current element.
- * 2. Collect focusable elements in that area.
- * 3. Compute distances from the current element to candidates using the W3C "find the shortest
- *    distance" algorithm: https://www.w3.org/TR/css-nav-1/#find-the-shortest-distance
- * 4. If no candidates are found, repeat from step 1, skipping areas already checked.
- * 5. Focus on the closest candidate.
- *
- * Elements with `data-spatial-focusable` are treated as focusable even if they do 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.
- *
- * Note: The algorithm is distance-based, so the UI should be designed to focusable elements are
- * predictably reachable. Relative element positions should remain stable; responsive layouts can
- * make navigation unpredictable. This is less of an issue on fixed-size TV UIs but can show unexpected
- * behavior in Storybook when resizing. See the "Limitations" section.
- *
- * #### Overwrite the next element
- *
- * Override calculated navigation by adding one of these attributes to a focusable element:
- *
- * - `data-spatial-up`
- * - `data-spatial-down`
- * - `data-spatial-left`
- * - `data-spatial-right`
- *
- * Each attribute value must be the id of the element to focus when the corresponding key is pressed.
- *
- * #### Element internal navigation
- *
- * Complex components (List, Combobox, Tree, etc.) may handle their own navigation. For example, a List moves
- * focus internally on Down until the last item, after which Down should fall back to provider navigation.
- *
- * To prevent the provider from handling a key, listen to `navbeforeprocess` and call `event.preventDefault()`.
- * This event fires after the component handles `keydown`.
- *
- * ### Cancel focus change
- *
- * Before focusing a computed target, the provider dispatches `navbeforefocus` on the current element. Call
- * `event.preventDefault()` on this event to cancel the focus change.
- *
- * ## Enter action
- *
- * Pressing Enter triggers `.click()` on the currently focused element.
- *
- * You can prevent this by listening to `navbeforeprocess` and calling `event.preventDefault()`.
- *
- * ## Escape/Back action
- *
- * Pressing Escape tries to find a focusable element with `data-spatial-go-back` and clicks it. If none exists,
- * the provider calls `history.back()`.
- *
- * You can prevent this by listening to `navbeforeprocess` and calling `event.preventDefault()`.
- *
- * You can also intercept the back click by listening to `navback` and calling `event.preventDefault()`.
- *
- * ## Control data attributes
- *
- * Supported data attributes:
- *
- * | Attribute                    | Value                        | Default | Description                                                                                                                        |
- * |------------------------------|------------------------------|---------|------------------------------------------------------------------------------------------------------------------------------------|
- * | `data-spatial-left`          | empty string / id / selector | N/A     | Prevent native navigation in the Left direction, focus it if it's focusable otherwise limit the search in the selected container.  |
- * | `data-spatial-up`            | empty string / id / selector | N/A     | Prevent native navigation in Up direction, focus it if it's focusable otherwise limit the search in the selected container.        |
- * | `data-spatial-right`         | empty string / id / selector | N/A     | Prevent native navigation in the Right direction, focus it if it's focusable otherwise limit the search in the selected container. |
- * | `data-spatial-down`          | empty string / id / selector | N/A     | Prevent native navigation in Down direction, focus it if it's focusable otherwise limit the search in the selected container.      |
- * | `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 active element in scrollable area even if the is not fit in view                                                |
- * | `data-spatial-scroll-parent` | N/A                          | N/A     | When the focusable item in not a direct child of the scrollable aria use this attribute to mark scrollable area element            |
- *
- * ## Event emitting order
- *
- * On a navigation key press, events fire in this order:
- *
- * 1. `navbeforeprocess` on the currently focused element.
- * 2. If not prevented:
- * a. Arrow keys: `navbeforefocus` on the currently focused element.
- * b. Enter: `.click()` on the currently focused element.
- * c. Escape/Back: `navback` on the provider, then `.click()` on the go-back element or `history.back()`.
- * 3. If no target is found in the requested direction: `navnotarget` on the provider.
- *
- * ## Handle complex components
- *
- * ### Generic components
- *
- * Components that handle navigation internally should prevent the provider from acting. Handle `navbeforeprocess`
- * and call `event.preventDefault()` for keys you process yourself.
- *
- * ### Form inputs
- *
- * Native inputs often submit on Enter, which is not desirable here. Enter should toggle or activate the control
- * (e.g., check/uncheck). Provide a dedicated submit button users can navigate to and press Enter on.
- *
- * ### Utilities for complex components
- *
- * #### KeyToActionMixin
- *
- * Maps key events to action names. Call `getActionForKeyEvent` to get the action for a keyboard event. Also provides
- * `getKeyboardNavMode` to check whether navigation is spatial or default.
- *
- * #### KeyDownHandledMixin
- *
- * Notify the provider when a component handled `keydown` internally. Call `keyDownEventHandled` whenever you process
- * keydown yourself.
- *
- * ## Platform specific behaviors
- *
- * Consider remote/gamepad constraints. Often focus alone is not enough, and users press Enter to "enter" an interactive mode:
- * - Select: Enter opens options rather than arrow keys opening a popover.
- * - Text inputs: see the next section.
- * - Slider: Enter to start adjusting, arrow keys to change value, Enter/Escape to stop.
- *
- * ### Text inputs
- *
- * On TV-like platforms without physical keyboards, Enter/focus on an input should open a virtual keyboard instead of submitting
- * the form. Users must close the keyboard (Escape) to continue spatial navigation.
- *
- * If navigation keys are mapped to letters (e.g., `w/a/s/d`), they should navigate, not change input values. Inputs should
- * be edited via the virtual keyboard.
- *
- * Note: Stories do not emulate virtual keyboards, so letter-based navigation may change input values in Storybook.
- *
- * ## Debugging
- *
- * ### Storybook toolbar
- *
- * Enable "Spatial navigation" in the toolbar. Key mapping:
- * - Up - ArrowUp
- * - Left - ArrowLeft
- * - Down - ArrowDown
- * - Right - ArrowRight
- * - Enter - Enter
- * - Escape - Escape
- *
- * With wrapper: wraps the component in a 3x3 grid with surrounding buttons for testing.
- * Without a wrapper: renders the component alone.
- *
- * ### Visual debugger
- *
- * With spatial navigation enabled, press Shift + navigation key to visualize calculations:
- *
- * - Star: next active element
- * - `#{number}`: candidate order by distance
- * - `D: {distance}`: computed distance
- *
- * ## Limitations
- *
- * ### Completeness
- *
- * The algorithm cannot guarantee reachability to all elements using the four directions. Some components can be isolated.
- *
- * Workarounds:
- * - Use data attributes to explicitly link navigation targets.
- * - Arrange DOM to improve spatial consistency:
- * - Group focusable elements using dedicated components (lists, menus, etc.).
- * - Avoid complex grid-like layouts with variable-sized items.
- * - Avoid overlap along horizontal or vertical axes.
- * - Avoid nested focusable elements where possible.
- * - Tune algorithm weights to match your UI layout.
- *
- * ### Nested providers
- *
- * Only one provider instance is supported in the application at a time.
- *
+ * @tagname mdc-spatialnavigationprovider
  * @event navbeforeprocess - (React: onNavBeforeProcess) This event dispatched before spatial navigation process any key event.
  *                           It can be canceled to prevent any action from spatial navigation, e.g.: back, click or calculating the next candidate.
  * @event navbeforefocus - (React: onNavBeforeFocus) This event is dispatched before the focus is changing to the next element.
@@ -240,7 +27,6 @@ import { SpatialNavigationEvent } from './spatialnavigationprovider.events';
  * @event navnotarget - (React: onNavNoTarget) This event is dispatched when there is no target to focus in the current focus area and
  *                      in the given direction .
  *
- * @tagname mdc-spatialnavigationprovider
  */
 class SpatialNavigationProvider extends Provider {
     /**

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

@@ -2,38 +2,26 @@ import { CSSResult } from 'lit';
 import { Component } from '../../models';
 import { SpinnerSize, SpinnerVariant } from './spinner.types';
 /**
- * `mdc-spinner` is loading spinner which is an indeterminate progress indicator, meaning
- * it's best for cases where the  progress or duration of a process is variable or unknown.
- *
- * Spinner Variants:
- * - **Standalone (Default)**: Track has a blue color.
- * - **Button**: To be used when placed in a button to show that the button’s action is currently in progress.
- * To ensure a minimum 3:1 contrast ratio, the color is changed internally to be the same color as the button’s
- * icon or label text.
- *
- * Spinner Sizes:
- * - **Large (96px)**: Use when replacing entire regions or pages that are still loading
- * - **MidSize (48px) (Default)**: Use for most use cases.
- * - **Small (24px)**: Use for inline with loading text.
- *
- * Customisation of the spinner size is allowed by setting the size to undefined and using the --mdc-spinner-size
- * CSS property.
- *
- * Spinner Colors:
- * - **Default**: Use for most use cases.
- * - **Inverted**: Only to be used within inverted components, such as coachmarks.
- *
- * Regarding accessibility, if an aria-label is provided, the role will be set to 'img'; if it is absent, the role
- * will be unset
- * and aria-hidden will be set to 'true' so the spinner will be ignored by screen readers.
- *
+ * The spinner is an indeterminate progress indicator, best suited for cases where the duration or progress of an operation is variable or unknown. It is rendered as a rotating circular arc and supports multiple sizes, two colour variants, and a button-friendly variant for in-button loading states.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-spinner` to signal that something is happening but you cannot communicate concrete progress.
+ * - Use the `button` variant inside `mdc-button` to indicate that the button's action is in progress.
+ * - Use the small size inline with loading text, the midsize for most cases, and the large size for full-region or full-page loading.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-progressbar` when you can show concrete, measurable progress.
+ * - Use `mdc-skeleton` when you want a placeholder that matches the layout of the content being loaded.
+ * 
  * @tagname mdc-spinner
- *
+ * 
  * @cssproperty --mdc-spinner-default-color - Allows customization of the default spinner color.
  * @cssproperty --mdc-spinner-inverted-color - Allows customization of the inverted spinner color.
  * @cssproperty --mdc-spinner-button-variant-color - Allows customization of the spinner Button variant color.
  * @cssproperty --mdc-spinner-size - Allows customization of the spinner size.
- *
+ * 
  * @csspart container - The svg which contains the circle spinner.
  * @csspart circle - The circle of the spinner.
  */

package/dist/components/spinner/spinner.component.js

@@ -14,31 +14,6 @@ import { ROLE } from '../../utils/roles';
 import styles from './spinner.styles';
 import { DEFAULTS } from './spinner.constants';
 /**
- * `mdc-spinner` is loading spinner which is an indeterminate progress indicator, meaning
- * it's best for cases where the  progress or duration of a process is variable or unknown.
- *
- * Spinner Variants:
- * - **Standalone (Default)**: Track has a blue color.
- * - **Button**: To be used when placed in a button to show that the button’s action is currently in progress.
- * To ensure a minimum 3:1 contrast ratio, the color is changed internally to be the same color as the button’s
- * icon or label text.
- *
- * Spinner Sizes:
- * - **Large (96px)**: Use when replacing entire regions or pages that are still loading
- * - **MidSize (48px) (Default)**: Use for most use cases.
- * - **Small (24px)**: Use for inline with loading text.
- *
- * Customisation of the spinner size is allowed by setting the size to undefined and using the --mdc-spinner-size
- * CSS property.
- *
- * Spinner Colors:
- * - **Default**: Use for most use cases.
- * - **Inverted**: Only to be used within inverted components, such as coachmarks.
- *
- * Regarding accessibility, if an aria-label is provided, the role will be set to 'img'; if it is absent, the role
- * will be unset
- * and aria-hidden will be set to 'true' so the spinner will be ignored by screen readers.
- *
  * @tagname mdc-spinner
  *
  * @cssproperty --mdc-spinner-default-color - Allows customization of the default spinner color.

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

@@ -2,35 +2,30 @@ import { CSSResult } from 'lit';
 import { Component } from '../../models';
 declare const StaticCheckbox_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/DisabledMixin").DisabledMixinInterface> & typeof Component;
 /**
- * The StaticCheckbox component is a decorative, non-interactive checkbox used for visual
- * presentation in read-only scenarios. Unlike the interactive `mdc-checkbox`, it does not
- * handle user interactions or form submissions.
- *
- * This component supports multiple visual states: checked, indeterminate, disabled, readonly,
- * and soft-disabled.
- *
- * ## When to use
- * Use StaticCheckbox to display checkbox states in read-only contexts such as summary views,
- * confirmation screens, or when showing historical form data. For interactive checkboxes, use
- * `mdc-checkbox` instead.
- *
- * ## Accessibility
- * - StaticCheckbox is decorative and non-interactive by design
- * - Always pair with descriptive text labels in the default slot
- * - Do not use this as a replacement for interactive checkboxes in forms
- *
+ * The static checkbox is a decorative, non-interactive checkbox used to display checkbox states in read-only contexts (summary views, confirmation screens, historical form data). It supports checked, indeterminate, disabled, soft-disabled, and read-only visual states but does not handle user interaction or participate in forms.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-staticcheckbox` to render the visual shape of a checkbox in read-only UIs such as summary screens, confirmation screens, or historical form data.
+ * - Use it inside lists or cards where the checkbox is part of the display, not a control.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-checkbox` for any interactive checkbox in a form.
+ * - Do not use `mdc-staticcheckbox` as a replacement for `mdc-checkbox` — it cannot be focused, toggled, or submitted with a form.
+ * 
  * @tagname mdc-staticcheckbox
- *
+ * 
  * @dependency mdc-icon
- *
+ * 
  * @cssproperty --mdc-staticcheckbox-border-color - Border color of the checkbox.
  * @cssproperty --mdc-staticcheckbox-background-color - Background color of the checkbox.
  * @cssproperty --mdc-staticcheckbox-icon-color - Icon color of the checkbox.
  * @cssproperty --mdc-staticcheckbox-size - Size of the checkbox.
- *
+ * 
  * @csspart icon-container - The container for the checkbox icon.
  * @csspart checkbox-icon - The checkbox icon element.
- *
+ * 
  * @slot - Default slot for label text.
  */
 declare class StaticCheckbox extends StaticCheckbox_base {

package/dist/components/staticcheckbox/staticcheckbox.component.js

@@ -14,23 +14,6 @@ import { DisabledMixin } from '../../utils/mixins/DisabledMixin';
 import styles from './staticcheckbox.styles';
 import { ICON_NAME } from './staticcheckbox.constants';
 /**
- * The StaticCheckbox component is a decorative, non-interactive checkbox used for visual
- * presentation in read-only scenarios. Unlike the interactive `mdc-checkbox`, it does not
- * handle user interactions or form submissions.
- *
- * This component supports multiple visual states: checked, indeterminate, disabled, readonly,
- * and soft-disabled.
- *
- * ## When to use
- * Use StaticCheckbox to display checkbox states in read-only contexts such as summary views,
- * confirmation screens, or when showing historical form data. For interactive checkboxes, use
- * `mdc-checkbox` instead.
- *
- * ## Accessibility
- * - StaticCheckbox is decorative and non-interactive by design
- * - Always pair with descriptive text labels in the default slot
- * - Do not use this as a replacement for interactive checkboxes in forms
- *
  * @tagname mdc-staticcheckbox
  *
  * @dependency mdc-icon