@momentum-design/components 0.134.20 → 0.134.22

package/dist/components/screenreaderannouncer/screenreaderannouncer.component.js

@@ -22,57 +22,6 @@ import styles from './screenreaderannouncer.styles';
 const identityRefCount = new Map();
 // End AI-Assisted
 /**
- * `mdc-screenreaderannouncer` can be used to announce messages with the screen reader.
- *
- * To make an announcement set `announcement` attribute on the `mdc-screenreaderannouncer` element.
- *
- * Consumers can also use the public `announce` function to trigger announcements programmatically
- * by passing an options object where `announcement` is required and all other fields are optional.
- *
- * **Internal logic**
- *
- * When the screenreader announcer is connected to the DOM, if the `identity` attribute is not
- * provided, it is set to `mdc-screenreaderannouncer-identity` and a `<div>` element with this id is created
- * in the DOM. If the `identity` attribute is provided, the identity element is used and no new element
- * is created in the DOM.
- *
- * If you provide a custom `identity`, you must ensure that the element exists and is visually hidden.
- *
- * Example CSS:
- *
- * ```css
- * #your-custom-announcer-id {
- *   clip: rect(0 0 0 0);
- *   clip-path: inset(50%);
- *   height: 1px;
- *   overflow: hidden;
- *   position: absolute;
- *   white-space: nowrap;
- *   width: 1px;
- * }
- * ```
- *
- * When the `announcement` attribute is set, the screenreader announcer will create a `<div>` element with
- * `aria-live` attribute set to the value of `data-aria-live` attribute and append it to the `identity` element.
- * After delay of `delay` milliseconds, a `<p>` element with the announcement text is appended to the `<div>` element.
- *
- * The announcement `<div>` element is removed from the DOM after `timeout` milliseconds.
- *
- * When the screen announcer component is disconnected from the DOM, all the timeouts are cleared and
- * all the announcement elements added are removed from the DOM and timeouts cleared.
- *
- * **Note**
- * 1. The default delay of 150 miliseconds is used as we dynamically generate the
- * aria-live region in the DOM and add the announcement text to it.
- * 2. If multiple `mdc-screenreaderannouncer` instances use the same `identity`, `data-aria-live`
- * for that identity is effectively determined by the first instance that creates announcements for it.
- * Changing `data-aria-live` in later instances for the same identity will not update already-created
- * live-region containers.
- * 3. If no `identity` is provided, all the screen reader components will create and use only one
- * `<div>` element with id `mdc-screenreaderannouncer-identity` in the DOM.
- *
- * Reference: https://patrickhlauke.github.io/aria/tests/live-regions/
- *
  * @tagname mdc-screenreaderannouncer
  */
 class ScreenreaderAnnouncer extends Component {

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

@@ -2,35 +2,27 @@ import { CSSResult, PropertyValueMap } from 'lit';
 import Input from '../input/input.component';
 declare const Searchfield_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/ControlTypeMixin").ControlTypeMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/KeyDownHandledMixin").KeyDownHandledMixinInterface> & typeof Input;
 /**
- * `mdc-searchfield` component is used as an input field for search functionality.
- *
- * It supports any interactable Chip component as filters. (`mdc-inputchip`, `mdc-alertchip`, `mdc-chip`)
- * Chips are rendered inline with the search input text, behaving like single characters.
- * Users can traverse the cursor between chips and text using arrow keys,
- * and remove a chip by pressing Backspace when the cursor is adjacent to it.
- *
- * This component is built by extending the `mdc-input` component.
- *
- * Searchfield supports controlled vs uncontrolled behavior for chip filters, which can be set via the `control-type` attribute:
- * - In **uncontrolled** mode (default), when a chip is removed via the UI, it is automatically removed from the DOM and a `chipRemove` event is dispatched with the removed chip in the event detail. The consumer can listen to the `chipRemove` event but does not need to do anything to remove the chip from the DOM.
- * - In **controlled** mode (`control-type="controlled"`), when a chip is removed via the UI, it is NOT removed from the DOM, but a `chipRemove` event is still dispatched with the "removed" chip in the event detail. The consumer must listen to the `chipRemove` event and handle removing the chip from the DOM themselves (e.g., by updating their state that controls which chips are rendered).
- *
- * **Accessibility:**
- *
- * NOTE: this component should not be used in combination with a Popover or Listbox component.
- * Search results should be shown permanently on the page if using this component.
- *
- * For a search field that opens a Popover, use the `mdc-searchpopover` widget instead.
- *
+ * The searchfield is a single-line text input tailored for search. It renders a leading search icon, a trailing clear button, and an inline area in front of the text caret where chip filters can be slotted. Chips behave like single characters in the input flow: they share the cursor with the text and can be focused, navigated, and removed with the keyboard.
+ * 
+ * **When to use**
+ * 
+ * - Use it whenever the user types a query to search a list, table, or other content rendered on the same page.
+ * - Use it with slotted chip filters (`mdc-inputchip`, `mdc-chip`, `mdc-alertchip`) when the search query is refined by removable filter tokens that should appear inline with the input text.
+ * 
+ * **When not to use**
+ * 
+ * - Do not use it for a search that opens a popover / listbox of suggestions or results. Use `mdc-searchpopover` instead — pairing this component with a Popover or Listbox is not supported.
+ * - Do not use it for free-form text entry that is not a search query — use `mdc-input` (or `mdc-textarea`) directly.
+ * 
  * @tagname mdc-searchfield
- *
+ * 
  * @event input - (React: onInput) This event is dispatched when the value of the input field changes (every press).
  * @event change - (React: onChange) This event is dispatched when the value of the input field changes (on blur).
  * @event focus - (React: onFocus) This event is dispatched when the input receives focus.
  * @event blur - (React: onBlur) This event is dispatched when the input loses focus.
  * @event clear - (React: onClear) This event is dispatched when the input text is cleared.
  * @event chipRemove - (React: onChipRemove) This event is dispatched when a chip filter is removed. The removed chip element is available in event.detail.chip. In `uncontrolled` mode (default) the chip is removed from the DOM automatically; in `controlled` mode only the event is fired and the consumer is responsible for removing the chip.
- *
+ * 
  * @slot filters - Slot for chip filters rendered inline with the input text
  * @slot label - Slot for the label element. If not provided, the `label` property will be used to render the label.
  * @slot toggletip - Slot for the toggletip info icon button. If not provided, the `toggletip-text` property will be used to render the info icon button and toggletip.
@@ -40,7 +32,7 @@ declare const Searchfield_base: import("../../utils/mixins/index.types").Constru
  * @slot input-leading-icon - Slot for the leading icon before the input field. If not provided, the `leadingIcon` property will be used to render the leading icon.
  * @slot input-prefix-text - Slot for the prefix text before the input field. If not provided, the `prefixText` property will be used to render the prefix text.
  * @slot trailing-button - Slot for the trailing button to clear the input field. If not provided, the clear button will be rendered when `trailingButton` property is set to true.
- *
+ * 
  * @cssproperty --mdc-label-font-size - Font size for the label text.
  * @cssproperty --mdc-label-font-weight - Font weight for the label text.
  * @cssproperty --mdc-label-line-height - Line height for the label text.
@@ -56,7 +48,7 @@ declare const Searchfield_base: import("../../utils/mixins/index.types").Constru
  * @cssproperty --mdc-input-support-text-color - Text color for the help text
  * @cssproperty --mdc-input-selection-text-color - Text color for the selected text
  * @cssproperty --mdc-input-selection-background-color - Background color for the selected text
- *
+ * 
  * @csspart label - The label element.
  * @csspart label-text - The container for the label and required indicator elements.
  * @csspart required-indicator - The required indicator element that is displayed next to the label when the `required` property is set to true.

package/dist/components/searchfield/searchfield.component.js

@@ -19,26 +19,6 @@ import { TAG_NAME as INPUT_CHIP_TAG } from '../inputchip/inputchip.constants';
 import styles from './searchfield.styles';
 import { CHIP_SELECTOR, DEFAULTS } from './searchfield.constants';
 /**
- * `mdc-searchfield` component is used as an input field for search functionality.
- *
- * It supports any interactable Chip component as filters. (`mdc-inputchip`, `mdc-alertchip`, `mdc-chip`)
- * Chips are rendered inline with the search input text, behaving like single characters.
- * Users can traverse the cursor between chips and text using arrow keys,
- * and remove a chip by pressing Backspace when the cursor is adjacent to it.
- *
- * This component is built by extending the `mdc-input` component.
- *
- * Searchfield supports controlled vs uncontrolled behavior for chip filters, which can be set via the `control-type` attribute:
- * - In **uncontrolled** mode (default), when a chip is removed via the UI, it is automatically removed from the DOM and a `chipRemove` event is dispatched with the removed chip in the event detail. The consumer can listen to the `chipRemove` event but does not need to do anything to remove the chip from the DOM.
- * - In **controlled** mode (`control-type="controlled"`), when a chip is removed via the UI, it is NOT removed from the DOM, but a `chipRemove` event is still dispatched with the "removed" chip in the event detail. The consumer must listen to the `chipRemove` event and handle removing the chip from the DOM themselves (e.g., by updating their state that controls which chips are rendered).
- *
- * **Accessibility:**
- *
- * NOTE: this component should not be used in combination with a Popover or Listbox component.
- * Search results should be shown permanently on the page if using this component.
- *
- * For a search field that opens a Popover, use the `mdc-searchpopover` widget instead.
- *
  * @tagname mdc-searchfield
  *
  * @event input - (React: onInput) This event is dispatched when the value of the input field changes (every press).

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

@@ -2,24 +2,20 @@ import { CSSResult } from 'lit';
 import Searchfield from '../searchfield/searchfield.component';
 import type { Placement } from './searchpopover.types';
 /**
- * `mdc-searchpopover` widget is a combination of the Searchfield and Popover components, connected to ensure
- * proper accessibility. This component should be used when search results or suggestions need to be displayed
- * in a popover below the search input field, where the search results hold individual actions like navigating to a
- * a different url etc.
- *
- * - Don't use this when search results are displayed inline on the page -\> use Searchfield component instead.
- * - Don't use this when a list of options is filtered based on the search input -\> use Combobox component instead.
- *
- * It supports any Chip component as filters. (`mdc-inputchip`, `mdc-alertchip`, `mdc-chip`)
- *
- * This component is built by extending the `mdc-searchfield` component & rendering the mdc-popover component inside.
- *
- * Searchpopover supports controlled vs uncontrolled behavior for chip filters, which can be set via the `control-type` attribute:
- * - In **uncontrolled** mode (default), when a chip is removed via the UI, it is automatically removed from the DOM and a `chipRemove` event is dispatched with the removed chip in the event detail. The consumer can listen to the `chipRemove` event but does not need to do anything to remove the chip from the DOM.
- * - In **controlled** mode (`control-type="controlled"`), when a chip is removed via the UI, it is NOT removed from the DOM, but a `chipRemove` event is still dispatched with the "removed" chip in the event detail. The consumer must listen to the `chipRemove` event and handle removing the chip from the DOM themselves (e.g., by updating their state that controls which chips are rendered).
- *
+ * The searchpopover is a widget built on top of `mdc-searchfield` that adds a connected `mdc-popover` below the input. The input is exposed as a combobox that owns the popover, so assistive technologies can announce when the popover is open and which content it controls. It is intended for searches whose results are individually actionable (for example navigating to a different URL).
+ * 
+ * **When to use**
+ * 
+ * - Use it when search results or suggestions appear in a popover anchored to the input and each result performs its own action.
+ * - Use it together with chip filters (`mdc-inputchip`, `mdc-chip`, `mdc-alertchip`) when the search query is refined by removable tokens.
+ * 
+ * **When not to use**
+ * 
+ * - Do not use it when search results render inline on the page — use `mdc-searchfield` instead.
+ * - Do not use it when the popover is a list of options being filtered down by the input — use `mdc-combobox` instead.
+ * 
  * @tagname mdc-searchpopover
- *
+ * 
  * @event input - (React: onInput) This event is dispatched when the value of the input field changes (every press).
  * @event change - (React: onChange) This event is dispatched when the value of the input field changes (on blur).
  * @event focus - (React: onFocus) This event is dispatched when the input receives focus.
@@ -30,7 +26,7 @@ import type { Placement } from './searchpopover.types';
  * In **uncontrolled** mode (default), the chip is removed from the DOM automatically.
  * @event shown - (React: onShown) This event is dispatched when the popover is shown
  * @event hidden - (React: onHidden) This event is dispatched when the popover is hidden
- *
+ * 
  * @slot default - Default slot (=children) for the popover content
  * @slot filters - Slot for input chips
  * @slot label - Slot for the label element. If not provided, the `label` property will be used to render the label.
@@ -41,7 +37,7 @@ import type { Placement } from './searchpopover.types';
  * @slot input-leading-icon - Slot for the leading icon before the input field. If not provided, the `leadingIcon` property will be used to render the leading icon.
  * @slot input-prefix-text - Slot for the prefix text before the input field. If not provided, the `prefixText` property will be used to render the prefix text.
  * @slot trailing-button - Slot for the trailing button to clear the input field. If not provided, the clear button will be rendered when `trailingButton` property is set to true.
- *
+ * 
  * @cssproperty --mdc-label-font-size - Font size for the label text.
  * @cssproperty --mdc-label-font-weight - Font weight for the label text.
  * @cssproperty --mdc-label-line-height - Line height for the label text.
@@ -60,7 +56,7 @@ import type { Placement } from './searchpopover.types';
  * @cssproperty --mdc-searchpopover-width - Width of the searchpopover component
  * @cssproperty --mdc-searchpopover-popover-width - Width of the popover within the searchpopover component
  * @cssproperty --mdc-searchpopover-popover-height - Height of the popover within the searchpopover component
- *
+ * 
  * @csspart label - The label element.
  * @csspart label-text - The container for the label and required indicator elements.
  * @csspart required-indicator - The required indicator element that is displayed next to the label when the `required` property is set to true.

package/dist/components/searchpopover/searchpopover.component.js

@@ -19,22 +19,6 @@ import { ROLE } from '../../utils/roles';
 import styles from './searchpopover.styles';
 import { DEFAULTS, TRIGGER_ID, POPOVER_ID } from './searchpopover.constants';
 /**
- * `mdc-searchpopover` widget is a combination of the Searchfield and Popover components, connected to ensure
- * proper accessibility. This component should be used when search results or suggestions need to be displayed
- * in a popover below the search input field, where the search results hold individual actions like navigating to a
- * a different url etc.
- *
- * - Don't use this when search results are displayed inline on the page -\> use Searchfield component instead.
- * - Don't use this when a list of options is filtered based on the search input -\> use Combobox component instead.
- *
- * It supports any Chip component as filters. (`mdc-inputchip`, `mdc-alertchip`, `mdc-chip`)
- *
- * This component is built by extending the `mdc-searchfield` component & rendering the mdc-popover component inside.
- *
- * Searchpopover supports controlled vs uncontrolled behavior for chip filters, which can be set via the `control-type` attribute:
- * - In **uncontrolled** mode (default), when a chip is removed via the UI, it is automatically removed from the DOM and a `chipRemove` event is dispatched with the removed chip in the event detail. The consumer can listen to the `chipRemove` event but does not need to do anything to remove the chip from the DOM.
- * - In **controlled** mode (`control-type="controlled"`), when a chip is removed via the UI, it is NOT removed from the DOM, but a `chipRemove` event is still dispatched with the "removed" chip in the event detail. The consumer must listen to the `chipRemove` event and handle removing the chip from the DOM themselves (e.g., by updating their state that controls which chips are rendered).
- *
  * @tagname mdc-searchpopover
  *
  * @event input - (React: onInput) This event is dispatched when the value of the input field changes (every press).

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

@@ -7,39 +7,43 @@ import type { PopoverStrategy } from '../popover/popover.types';
 import type { Placement } from './select.types';
 declare const Select_base: import("../../utils/mixins/index.types").Constructor<import("../../models").Component & import("../../utils/mixins/ListNavigationMixin").ListNavigationMixinInterface & import("../../utils/mixins/KeyToActionMixin").KeyToActionInterface & import("../../utils/mixins/KeyDownHandledMixin").KeyDownHandledMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/KeyToActionMixin").KeyToActionInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/lifecycle/CaptureDestroyEventForChildElement").CaptureDestroyEventForChildElementInterface> & import("../../utils/mixins/index.types").Constructor<import("../../models").Component & import("../../utils/mixins/AutoFocusOnMountMixin").AutoFocusOnMountMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/FormInternalsMixin").FormInternalsMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/DataAriaLabelMixin").DataAriaLabelMixinInterface> & typeof FormfieldWrapper;
 /**
- * The mdc-select component is a dropdown selection control that allows users to pick an option from a predefined list.
- * It is designed to work with `mdc-option` for individual options and `mdc-optgroup` for grouping related options.
- * Optional: Add `mdc-divider` after each option group (`mdc-optgroup`) to separate groups visually.
- *
- * Every mdc-option should have a `value` attribute set to ensure proper form submission.
- *
- * To set a default option, use the `selected` attribute on the `mdc-option` element.
- * You can also set the `value` attribute on the `mdc-select` element to match the value of the desired option. The component will select the corresponding option automatically.
- *
- * **Note:** Make sure to add `mdc-selectlistbox` as a child of `mdc-select` and wrap options/optgroup in it to ensure proper accessibility functionality. Read more about it in SelectListBox documentation.
- *
- * If you need to use `mdc-tooltip` with any options, make sure to place the tooltip component outside the `mdc-select` element.
- *
+ * The select is a form-associated dropdown control that lets the user pick a single value from a predefined list of options. It exposes the standard form field surface (label, help text, validation, required indicator, info toggletip) and renders a popover-backed listbox built from slotted `mdc-option` and `mdc-optgroup` children.
+ * 
+ * The component is form-associated and participates in native form submission, validation, and reset.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-select` when the user must pick a single value from a fixed list and typing-to-filter is not required.
+ * - Use it inside a form when you want native form submission and validation for the selected value.
+ * - Use it when options are grouped (`mdc-optgroup`) and an optional `mdc-divider` is needed between groups.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-combobox` when the user benefits from typing to filter the list.
+ * - Use `mdc-radiogroup` when there are only a handful of options and they should all be visible at once.
+ * - Use `mdc-input` when free-form text is the goal.
+ * - Use `mdc-searchfield` when the user is searching content rather than picking a single value.
+ * 
+ * @tagname mdc-select
+ * 
  * @dependency mdc-button
  * @dependency mdc-icon
  * @dependency mdc-popover
  * @dependency mdc-text
  * @dependency mdc-toggletip
- *
- * @tagname mdc-select
- *
+ * 
  * @event click - (React: onClick) This event is dispatched when the select is clicked.
  * @event change - (React: onChange) This event is dispatched when the select is changed.
  * @event input - (React: onInput) This event is dispatched when the select is changed.
  * @event keydown - (React: onKeyDown) This event is dispatched when a key is pressed down on the select.
  * @event focus - (React: onFocus) This event is dispatched when the select receives focus.
- *
+ * 
  * @slot default - This is a default/unnamed slot for Selectlistbox including options and/or option group.
  * @slot label - Slot for the label element. If not provided, the `label` property will be used to render the label.
  * @slot toggletip - Slot for the toggletip info icon button. If not provided, the `toggletip-text` property will be used to render the info icon button and toggletip.
  * @slot help-icon - Slot for the helper/validation icon. If not provided, the icon will be rendered based on the `helpTextType` property.
  * @slot help-text - Slot for the helper/validation text. If not provided, the `helpText` property will be used to render the helper/validation text.
- *
+ * 
  * @csspart label - The label element.
  * @csspart label-text - The container for the label and required indicator elements.
  * @csspart required-indicator - The required indicator element that is displayed next to the label when the `required` property is set to true.
@@ -48,7 +52,7 @@ declare const Select_base: import("../../utils/mixins/index.types").Constructor<
  * @csspart help-text - The helper/validation text element.
  * @csspart helper-icon - The helper/validation icon element that is displayed next to the helper/validation text.
  * @csspart help-text-container - The container for the helper/validation icon and text elements.
- *
+ * 
  * @cssproperty --mdc-label-font-size - Font size for the label text.
  * @cssproperty --mdc-label-font-weight - Font weight for the label text.
  * @cssproperty --mdc-label-line-height - Line height for the label text.

package/dist/components/select/select.component.js

@@ -28,18 +28,7 @@ import { ACTIONS, KeyToActionMixin, NAV_MODES } from '../../utils/mixins/KeyToAc
 import { ARROW_ICON, DEFAULTS, LISTBOX_ID, TRIGGER_ID } from './select.constants';
 import styles from './select.styles';
 /**
- * The mdc-select component is a dropdown selection control that allows users to pick an option from a predefined list.
- * It is designed to work with `mdc-option` for individual options and `mdc-optgroup` for grouping related options.
- * Optional: Add `mdc-divider` after each option group (`mdc-optgroup`) to separate groups visually.
- *
- * Every mdc-option should have a `value` attribute set to ensure proper form submission.
- *
- * To set a default option, use the `selected` attribute on the `mdc-option` element.
- * You can also set the `value` attribute on the `mdc-select` element to match the value of the desired option. The component will select the corresponding option automatically.
- *
- * **Note:** Make sure to add `mdc-selectlistbox` as a child of `mdc-select` and wrap options/optgroup in it to ensure proper accessibility functionality. Read more about it in SelectListBox documentation.
- *
- * If you need to use `mdc-tooltip` with any options, make sure to place the tooltip component outside the `mdc-select` element.
+ * @tagname mdc-select
  *
  * @dependency mdc-button
  * @dependency mdc-icon
@@ -47,8 +36,6 @@ import styles from './select.styles';
  * @dependency mdc-text
  * @dependency mdc-toggletip
  *
- * @tagname mdc-select
- *
  * @event click - (React: onClick) This event is dispatched when the select is clicked.
  * @event change - (React: onChange) This event is dispatched when the select is changed.
  * @event input - (React: onInput) This event is dispatched when the select is changed.

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

@@ -1,14 +1,18 @@
 import { Component } from '../../models';
 /**
- * Selectlistbox component as Light DOM component to act as a simple wrapper
- * for mdc-option components to ensure accessibility and proper role assignment.
- *
- * Once [ariaOwnsElements](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/ariaOwnsElements) is supported in browsers, this component can be removed
- * and mdc-option can be used directly in the select component with a listbox in a different
- * shadow root and aria-owns attribute to connect them.
- *
+ * `mdc-selectlistbox` is a light-DOM wrapper that groups `mdc-option` (and `mdc-optgroup`) children and exposes them with `role="listbox"` so screen readers announce the option list correctly. It is required as a slotted child of `mdc-select` and `mdc-combobox`.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-selectlistbox` as the direct child of `mdc-select` or `mdc-combobox`, wrapping the slotted `mdc-option` and `mdc-optgroup` elements.
+ * 
+ * **When not to use**
+ * 
+ * - Do not use it outside `mdc-select` or `mdc-combobox`. For a standalone listbox UI, use the dedicated `mdc-listbox` component instead.
+ * - Do not place `mdc-option` directly inside `mdc-select` or `mdc-combobox` without this wrapper — the listbox role and screen-reader semantics would be missing.
+ * 
  * @tagname mdc-selectlistbox
- *
+ * 
  * @slot default - This is a default/unnamed slot, which can be used to insert mdc-option components.
  */
 declare class Selectlistbox extends Component {

package/dist/components/selectlistbox/selectlistbox.component.js

@@ -1,13 +1,6 @@
 import { Component } from '../../models';
 import { ROLE } from '../../utils/roles';
 /**
- * Selectlistbox component as Light DOM component to act as a simple wrapper
- * for mdc-option components to ensure accessibility and proper role assignment.
- *
- * Once [ariaOwnsElements](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/ariaOwnsElements) is supported in browsers, this component can be removed
- * and mdc-option can be used directly in the select component with a listbox in a different
- * shadow root and aria-owns attribute to connect them.
- *
  * @tagname mdc-selectlistbox
  *
  * @slot default - This is a default/unnamed slot, which can be used to insert mdc-option components.

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

@@ -1,57 +1,38 @@
 import { CSSResult, PropertyValues } from 'lit';
-import { Provider } from '../../models';
-import type { SideNavigationVariant } from './sidenavigation.types';
+import type { SideNavigationSubmenuType, SideNavigationVariant } from './sidenavigation.types';
 import SideNavigationContext from './sidenavigation.context';
+import SideNavigationBase from './sidenavigationbase';
+declare const SideNavigation_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/KeyToActionMixin").KeyToActionInterface> & typeof SideNavigationBase;
 /**
- * The `mdc-sidenavigation` component provides a vertically stacked navigation experience,
- * typically used in layouts with persistent or collapsible sidebars.
- *
- * ## Features:
- * - Supports five layout variants: `fixed-collapsed`, `fixed-expanded`, `flexible`, `flexible-on-hover`, and `hidden`
- * - Toggleable expand/collapse behavior
- * - Displays brand logo and customer name
- * - Serves as a context provider for descendant components - `mdc-menubar` and `mdc-navmenuitem`
- *
- * ### Usage:
- * In a sidenavigation, navmenuitems can be used in the following ways:
- *
- * 1. **Simple navmenuitem** – No submenu or interaction beyond selection.
- *
- * 2. **NavMenuItem with submenu**:
- *    - Provide an `id` on the `mdc-navmenuitem`
- *    - Set the `triggerId` on the corresponding `mdc-menupopover` to match the navmenuitem's `id`
- *    - Set `parent-nav-tooltip-text` with appropriate text that will display when a child menu item
- *      inside the nested menupopover is active, conveying which submenu item is currently selected
- *
- * 3. **Actionable navmenuitem (no submenu)**:
- *    - Performs an action such as navigation or alert trigger
- *    - Set `disable-aria-current="true"` to maintain visual active state without navigation behavior
- *
- * ### Recommendations:
- * - Use `mdc-text` for section headers
- * - Use `mdc-divider` with the attribute `variant="gradient"` for section dividers
- * - For the brand logo, use an informative icon. Refer to `Momentum Informative Icons`
- *
- * #### Accessibility Notes:
- * - Always provide meaningful `aria-label` attributes for both `mdc-navmenuitem` and `mdc-menubar`
- * to ensure screen reader support
- * - Set `grabber-btn-aria-label` to provide accessible labels for the expand/collapse grabber button
- *
+ * The side navigation is a vertically stacked navigation landmark, typically used as a persistent or collapsible sidebar. It supports five layout variants, toggleable expand/collapse behaviour, an optional brand logo, an optional footer text, and acts as a context provider for nested `mdc-menubar` and `mdc-navmenuitem` elements.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-sidenavigation` for primary, persistent in-app navigation rendered alongside the main content area.
+ * - Use it when you need an expandable/collapsible sidebar with icon-only and icon-plus-label modes.
+ * - Use it as the host of nested `mdc-menubar` and `mdc-navmenuitem` content (with optional submenus via `mdc-menupopover`).
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-appheader` for top-of-page navigation.
+ * - Use `mdc-menubar` on its own when no expand/collapse, branding, or fixed footer area is needed.
+ * - Use `mdc-tablist` when navigation is scoped to switching between sibling views inside a single page.
+ * 
+ * @tagname mdc-sidenavigation
+ * 
  * @dependency mdc-text
  * @dependency mdc-button
  * @dependency mdc-divider
  * @dependency mdc-menubar
- *
+ * 
  * @event activechange - (React: onActiveChange) Dispatched when the active state of the navmenuitem changes.
- *
- * @tagname mdc-sidenavigation
- *
+ * 
  * @slot scrollable-section - Slot for the scrollable content area of the side navigation.
  * @slot scrollable-menubar - Slot for the menubar inside the scrollable section.
  * @slot fixed-section - Slot for the fixed content area of the side navigation.
  * @slot fixed-menubar - Slot for the menubar inside the fixed section.
  * @slot brand-logo - Slot for the brand logo (e.g., icon or img).
- *
+ * 
  * @csspart side-navigation-container - The main container wrapping the entire side navigation.
  * @csspart scrollable-section - The scrollable section of the side navigation.
  * @csspart scrollable-menubar - The menubar inside the scrollable section.
@@ -62,10 +43,10 @@ import SideNavigationContext from './sidenavigation.context';
  * @csspart footer-text - The footer text label in the fixed section.
  * @csspart vertical-divider - The vertical divider between the scrollable and fixed sections.
  * @csspart vertical-divider-button - The button inside the vertical divider used to toggle expand/collapse.
- *
+ * 
  * @event toggle - (React: onToggle) Dispatched when the grabber button is clicked to expand/collapse the sidenavigation.
  * @event activechange - (React: onActiveChange) Dispatched when the active state of a nested navmenuitem changes.
- *
+ * 
  * @cssproperty --mdc-sidenavigation-expanded-width - width of the sideNavigation when expanded
  * @cssproperty --mdc-sidenavigation-expanded-left-padding - padding for the left side of navmenuitems, when expanded
  * @cssproperty --mdc-sidenavigation-expanded-right-padding - padding for the right side of navmenuitems, when expanded
@@ -76,7 +57,7 @@ import SideNavigationContext from './sidenavigation.context';
  * @cssproperty --mdc-sidenavigation-bottom-padding - padding for the bottom of the scrollable section
  * @cssproperty --mdc-sidenavigation-vertical-divider-button-z-index - z-index of the vertical divider button
  */
-declare class SideNavigation extends Provider<SideNavigationContext> {
+declare class SideNavigation extends SideNavigation_base {
     /**
      * Five variants of the sideNavigation
      * - **fixed-collapsed**: Shows icons without labels and has fixed width, 4.5rem.
@@ -115,6 +96,17 @@ declare class SideNavigation extends Provider<SideNavigationContext> {
      * @default false
      */
     hideFixedSectionDivider: boolean;
+    /**
+     * Determines how sibling submenus are displayed. There are 2 types of submenus supported:
+     *
+     * - `flyout`: Submenus are shown with `mdc-menupopover`.
+     * - `dropdown`: A parent `mdc-navmenuitem` can render its submenu inside a sibling
+     *   `div[data-trigger="<navmenuitem-id>"]` while the sidenavigation is expanded. In collapsed mode,
+     *   dropdown submenus are converted to flyout menus.
+     *
+     * @default flyout
+     */
+    submenuType: SideNavigationSubmenuType;
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -174,6 +166,34 @@ declare class SideNavigation extends Provider<SideNavigationContext> {
      * @internal
      */
     private get navMenuItems();
+    /**
+     * Closes all open dropdown containers and resets their parent navmenuitems.
+     * @internal
+     */
+    private closeAllDropdowns;
+    /**
+     * Hides all div[data-trigger] elements within the sidenavigation.
+     * @internal
+     */
+    private hideAllDropdownContainers;
+    /**
+     * When collapsed with dropdown submenus, converts div[data-trigger] children into dynamically
+     * created menupopover elements for flyout behavior.
+     * @internal
+     */
+    private convertDropdownsToFlyouts;
+    /**
+     * When expanding with dropdown submenus, converts dynamically created menupopover elements
+     * back to div[data-trigger] containers.
+     * @internal
+     */
+    private convertFlyoutsToDropdowns;
+    /**
+     * Handles Escape key inside dropdown containers to close the dropdown
+     * and return focus to the parent trigger navmenuitem.
+     * @internal
+     */
+    private handleDropdownKeyDown;
     /**
      * Sets the variant attribute for the sideNavigation component.
      * If the provided variant is not included in the variant,