@momentum-design/components 0.134.20 → 0.134.22

package/dist/components/sidenavigation/sidenavigation.component.js

@@ -9,49 +9,19 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
-import { Component, Provider } from '../../models';
+import { Component } from '../../models';
 import { TYPE, VALID_TEXT_TAGS } from '../text/text.constants';
 import { TAG_NAME as NAVMENUITEM_TAGNAME } from '../navmenuitem/navmenuitem.constants';
+import { TAG_NAME as MENUPOPOVER_TAGNAME } from '../menupopover/menupopover.constants';
 import { DIRECTIONS, DIVIDER_VARIANT, DIVIDER_ORIENTATION } from '../divider/divider.constants';
 import { ROLE } from '../../utils/roles';
-import { KEYS } from '../../utils/keys';
-import { DEFAULTS, VARIANTS } from './sidenavigation.constants';
+import { ACTIONS, KeyToActionMixin } from '../../utils/mixins/KeyToActionMixin';
+import { DEFAULTS, SUBMENU_TYPES, VARIANTS } from './sidenavigation.constants';
 import SideNavigationContext from './sidenavigation.context';
 import styles from './sidenavigation.styles';
+import SideNavigationBase from './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
+ * @tagname mdc-sidenavigation
  *
  * @dependency mdc-text
  * @dependency mdc-button
@@ -60,8 +30,6 @@ import styles from './sidenavigation.styles';
  *
  * @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.
@@ -92,11 +60,11 @@ import styles from './sidenavigation.styles';
  * @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
  */
-class SideNavigation extends Provider {
+class SideNavigation extends KeyToActionMixin(SideNavigationBase) {
     constructor() {
         super({
             context: SideNavigationContext.context,
-            initialValue: new SideNavigationContext(DEFAULTS.VARIANT, true),
+            initialValue: new SideNavigationContext(DEFAULTS.VARIANT, true, DEFAULTS.SUBMENU_TYPE),
         });
         /**
          * Five variants of the sideNavigation
@@ -120,6 +88,17 @@ class SideNavigation extends Provider {
          * @default false
          */
         this.hideFixedSectionDivider = false;
+        /**
+         * 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
+         */
+        this.submenuType = DEFAULTS.SUBMENU_TYPE;
         this.isHovered = false;
         this.isFocused = false;
         /** @internal */
@@ -201,6 +180,7 @@ class SideNavigation extends Provider {
          */
         this.findNav = (navs, navId) => navs.find(nav => nav.navId === navId);
         this.addEventListener('activechange', this.handleNestedNavMenuItemActiveChange.bind(this));
+        this.addEventListener('keydown', this.handleDropdownKeyDown.bind(this));
     }
     connectedCallback() {
         super.connectedCallback();
@@ -240,9 +220,28 @@ class SideNavigation extends Provider {
                 default:
             }
         }
-        if (changedProperties.has('variant') || changedProperties.has('expanded')) {
+        if (changedProperties.has('variant') || changedProperties.has('expanded') || changedProperties.has('submenuType')) {
             this.updateContext();
         }
+        // When collapsing or when dropdown submenus are turned off, close all dropdown containers
+        if (changedProperties.has('expanded') || changedProperties.has('submenuType')) {
+            if (!this.expanded || this.submenuType !== SUBMENU_TYPES.DROPDOWN) {
+                this.closeAllDropdowns();
+            }
+            // Handle dropdown-to-flyout conversion
+            if (this.submenuType === SUBMENU_TYPES.DROPDOWN) {
+                if (!this.expanded) {
+                    this.convertDropdownsToFlyouts();
+                }
+                else {
+                    this.convertFlyoutsToDropdowns();
+                }
+            }
+            else {
+                // If dropdown submenus are turned off, clean up any dynamic menupopover elements
+                this.convertFlyoutsToDropdowns();
+            }
+        }
     }
     firstUpdated(changedProperties) {
         super.firstUpdated(changedProperties);
@@ -251,6 +250,12 @@ class SideNavigation extends Provider {
             this.expanded = true;
             this.updateContext();
         }
+        // Hide all dropdown containers by default
+        this.hideAllDropdownContainers();
+        // If initially collapsed with dropdown submenus, convert to flyouts
+        if (this.submenuType === SUBMENU_TYPES.DROPDOWN && !this.expanded) {
+            this.convertDropdownsToFlyouts();
+        }
     }
     /**
      * Update all observing components of this
@@ -259,9 +264,12 @@ class SideNavigation extends Provider {
      * Is called on every re-render, see Provider class
      */
     updateContext() {
-        if (this.context.value.variant !== this.variant || this.context.value.expanded !== this.expanded) {
+        if (this.context.value.variant !== this.variant ||
+            this.context.value.expanded !== this.expanded ||
+            this.context.value.submenuType !== this.submenuType) {
             this.context.value.variant = this.variant;
             this.context.value.expanded = this.expanded;
+            this.context.value.submenuType = this.submenuType;
             this.context.updateObservers();
         }
     }
@@ -272,6 +280,192 @@ class SideNavigation extends Provider {
     get navMenuItems() {
         return Array.from(this.querySelectorAll(`${NAVMENUITEM_TAGNAME}:not([disabled])`));
     }
+    /**
+     * Closes all open dropdown containers and resets their parent navmenuitems.
+     * @internal
+     */
+    closeAllDropdowns() {
+        this.navMenuItems.filter(item => this.context.value.isDropDownParent(item)).forEach(item => item.closeDropdown());
+        // Also hide all dropdown containers
+        this.hideAllDropdownContainers();
+    }
+    /**
+     * Hides all div[data-trigger] elements within the sidenavigation.
+     * @internal
+     */
+    hideAllDropdownContainers() {
+        const containers = this.querySelectorAll('div[data-trigger]');
+        containers.forEach(container => {
+            Object.assign(container.style, {
+                display: 'none',
+                flexDirection: 'column',
+                gap: '0.25rem',
+            });
+        });
+    }
+    /**
+     * When collapsed with dropdown submenus, converts div[data-trigger] children into dynamically
+     * created menupopover elements for flyout behavior.
+     * @internal
+     */
+    convertDropdownsToFlyouts() {
+        const containers = this.querySelectorAll('div[data-trigger]');
+        containers.forEach(container => {
+            var _a;
+            const triggerId = container.getAttribute('data-trigger');
+            if (!triggerId)
+                return;
+            // Check if a dynamic menupopover already exists for this trigger
+            const existingPopover = (_a = container.parentElement) === null || _a === void 0 ? void 0 : _a.querySelector(`${MENUPOPOVER_TAGNAME}[triggerid="${CSS.escape(triggerId)}"][data-dynamic-popover]`);
+            if (existingPopover)
+                return;
+            // Create menupopover
+            const popover = document.createElement(MENUPOPOVER_TAGNAME);
+            popover.setAttribute('triggerid', triggerId);
+            popover.setAttribute('data-dynamic-popover', '');
+            popover.setAttribute('placement', 'right-start');
+            // Move children from div to menupopover
+            while (container.firstChild) {
+                popover.appendChild(container.firstChild);
+            }
+            // Insert menupopover after the div
+            container.after(popover);
+            // Hide the empty div
+            Object.assign(container.style, { display: 'none' });
+        });
+    }
+    /**
+     * When expanding with dropdown submenus, converts dynamically created menupopover elements
+     * back to div[data-trigger] containers.
+     * @internal
+     */
+    convertFlyoutsToDropdowns() {
+        const dynamicPopovers = this.querySelectorAll(`${MENUPOPOVER_TAGNAME}[data-dynamic-popover]`);
+        dynamicPopovers.forEach(popover => {
+            const triggerId = popover.getAttribute('triggerid');
+            if (!triggerId)
+                return;
+            // Find the corresponding div[data-trigger]
+            const container = this.querySelector(`div[data-trigger="${CSS.escape(triggerId)}"]`);
+            if (!container)
+                return;
+            // Move children back from menupopover to div
+            while (popover.firstChild) {
+                container.appendChild(popover.firstChild);
+            }
+            // Remove the dynamic menupopover
+            popover.remove();
+        });
+    }
+    /**
+     * Handles Escape key inside dropdown containers to close the dropdown
+     * and return focus to the parent trigger navmenuitem.
+     * @internal
+     */
+    handleDropdownKeyDown(event) {
+        var _a, _b;
+        if (this.submenuType !== SUBMENU_TYPES.DROPDOWN || !this.expanded)
+            return;
+        const target = event.target;
+        const isNavMenuItem = target.tagName.toLowerCase() === NAVMENUITEM_TAGNAME;
+        if (!isNavMenuItem)
+            return;
+        const targetItem = target;
+        const action = this.getActionForKeyEvent(event);
+        if (action === ACTIONS.ESCAPE) {
+            const dropdownContainer = target.closest('div[data-trigger]');
+            if (!dropdownContainer)
+                return;
+            const triggerId = dropdownContainer.getAttribute('data-trigger');
+            if (!triggerId)
+                return;
+            const triggerItem = this.querySelector(`${NAVMENUITEM_TAGNAME}#${CSS.escape(triggerId)}`);
+            if (triggerItem) {
+                triggerItem.closeDropdown();
+                triggerItem.focus();
+                event.stopPropagation();
+            }
+            return;
+        }
+        const context = this.context.value;
+        const isInsideDropdown = targetItem.hasAttribute('in-dropdown-container');
+        const isOpen = targetItem.getAttribute('aria-expanded') === 'true';
+        const getDropdownContainer = (item) => { var _a, _b; return (_b = (_a = item.parentElement) === null || _a === void 0 ? void 0 : _a.querySelector(`div[data-trigger="${item.id}"]`)) !== null && _b !== void 0 ? _b : null; };
+        const getFirstDropdownItem = (container) => container === null || container === void 0 ? void 0 : container.querySelector(`${NAVMENUITEM_TAGNAME}:not([disabled])`);
+        if (isInsideDropdown) {
+            const dropdownContainer = target.closest('div[data-trigger]');
+            if (!dropdownContainer)
+                return;
+            const children = Array.from(dropdownContainer.querySelectorAll(`${NAVMENUITEM_TAGNAME}:not([disabled])`));
+            const currentIndex = children.indexOf(targetItem);
+            if (currentIndex === -1)
+                return;
+            switch (action) {
+                case ACTIONS.DOWN: {
+                    // Arrow Down: move focus to the next child navmenuitem in the dropdown container, if exists. If on the last child, move focus back to the first child.
+                    const idx = currentIndex + 1 < children.length ? currentIndex + 1 : 0;
+                    children[idx].focus();
+                    event.preventDefault();
+                    break;
+                }
+                case ACTIONS.UP: {
+                    // Arrow Up: move focus to the previous child navmenuitem in the dropdown container, if exists. If on the first child, move focus to the last child.
+                    const idx = currentIndex > 0 ? currentIndex - 1 : children.length - 1;
+                    children[idx].focus();
+                    event.preventDefault();
+                    break;
+                }
+                case ACTIONS.RIGHT: {
+                    // Arrow Right: move focus to the next parent-level navmenuitem in the main list (if exists). If this parent-level navmenuitem has a dropdown, then open the dropdown and move focus to the first child navmenuitem in the dropdown container.
+                    const outerItems = this.navMenuItems.filter(item => !item.hasAttribute('in-dropdown-container'));
+                    const triggerId = dropdownContainer.getAttribute('data-trigger');
+                    const triggerIndex = outerItems.findIndex(item => item.id === triggerId);
+                    if (triggerIndex !== -1 && triggerIndex + 1 < outerItems.length) {
+                        const nextItem = outerItems[triggerIndex + 1];
+                        nextItem.focus();
+                        if (context.isDropDownParent(nextItem)) {
+                            nextItem.openDropdown();
+                            const nextDropdownContainer = getDropdownContainer(nextItem);
+                            (_a = getFirstDropdownItem(nextDropdownContainer)) === null || _a === void 0 ? void 0 : _a.focus();
+                        }
+                    }
+                    break;
+                }
+                case ACTIONS.LEFT: {
+                    // Arrow Left: move focus to the previous parent-level navmenuitem in the main list (if exists). If this parent-level navmenuitem has a dropdown, then open the dropdown and move focus to the first child navmenuitem in the dropdown container.
+                    const outerItems = this.navMenuItems.filter(item => !item.hasAttribute('in-dropdown-container'));
+                    const triggerId = dropdownContainer.getAttribute('data-trigger');
+                    const triggerIndex = outerItems.findIndex(item => item.id === triggerId);
+                    if (triggerIndex > 0) {
+                        const previousItem = outerItems[triggerIndex - 1];
+                        previousItem.focus();
+                        if (context.isDropDownParent(previousItem)) {
+                            previousItem.openDropdown();
+                            const previousDropdownContainer = getDropdownContainer(previousItem);
+                            (_b = getFirstDropdownItem(previousDropdownContainer)) === null || _b === void 0 ? void 0 : _b.focus();
+                        }
+                    }
+                    break;
+                }
+                default:
+                    event.preventDefault();
+            }
+        }
+        // if the dropdown is closed and ArrowRight is pressed on the parent navmenuitem, open the dropdown and move focus to the first child navmenuitem in the dropdown container
+        if (action === ACTIONS.RIGHT) {
+            const dropdownContainer = getDropdownContainer(targetItem);
+            if (dropdownContainer) {
+                if (!isOpen) {
+                    targetItem.openDropdown();
+                }
+                const firstChild = getFirstDropdownItem(dropdownContainer);
+                if (firstChild) {
+                    firstChild.focus();
+                    event.preventDefault();
+                }
+            }
+        }
+    }
     /**
      * Sets the variant attribute for the sideNavigation component.
      * If the provided variant is not included in the variant,
@@ -301,7 +495,7 @@ class SideNavigation extends Provider {
     }
     preventScrollOnSpace(event) {
         // Prevent default space key behavior to avoid scrolling the page
-        if (event.key === KEYS.SPACE) {
+        if (this.getActionForKeyEvent(event) === ACTIONS.SPACE) {
             event.preventDefault();
         }
     }
@@ -386,4 +580,8 @@ __decorate([
     property({ type: Boolean, reflect: true, attribute: 'hide-fixed-section-divider' }),
     __metadata("design:type", Boolean)
 ], SideNavigation.prototype, "hideFixedSectionDivider", void 0);
+__decorate([
+    property({ type: String, reflect: true, attribute: 'submenu-type' }),
+    __metadata("design:type", String)
+], SideNavigation.prototype, "submenuType", void 0);
 export default SideNavigation;

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

@@ -6,7 +6,12 @@ declare const VARIANTS: {
     FLEXIBLE_ON_HOVER: string;
     HIDDEN: string;
 };
+declare const SUBMENU_TYPES: {
+    FLYOUT: string;
+    DROPDOWN: string;
+};
 declare const DEFAULTS: {
     readonly VARIANT: string;
+    readonly SUBMENU_TYPE: string;
 };
-export { DEFAULTS, VARIANTS, TAG_NAME };
+export { DEFAULTS, VARIANTS, SUBMENU_TYPES, TAG_NAME };

package/dist/components/sidenavigation/sidenavigation.constants.js

@@ -7,7 +7,12 @@ const VARIANTS = {
     FLEXIBLE_ON_HOVER: 'flexible-on-hover',
     HIDDEN: 'hidden',
 };
+const SUBMENU_TYPES = {
+    FLYOUT: 'flyout',
+    DROPDOWN: 'dropdown',
+};
 const DEFAULTS = {
     VARIANT: VARIANTS.FLEXIBLE,
+    SUBMENU_TYPE: SUBMENU_TYPES.FLYOUT,
 };
-export { DEFAULTS, VARIANTS, TAG_NAME };
+export { DEFAULTS, VARIANTS, SUBMENU_TYPES, TAG_NAME };

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

@@ -1,14 +1,19 @@
 import type NavMenuItem from '../navmenuitem/navmenuitem.component';
+import type { SideNavigationSubmenuType } from './sidenavigation.types';
 declare class SideNavigationContext {
     variant?: string;
     expanded?: boolean;
+    submenuType?: SideNavigationSubmenuType;
     private currentActiveNavMenuItem?;
     static context: {
         __context__: SideNavigationContext;
     };
-    constructor(defaultVariant?: string, defaultExpanded?: boolean);
+    constructor(defaultVariant?: string, defaultExpanded?: boolean, defaultSubmenuType?: SideNavigationSubmenuType);
+    get isDropdownSubmenuType(): boolean;
     hasSiblingWithTriggerId(navMenuItem: NavMenuItem | undefined): boolean;
+    isDropDownParent(navMenuItem: NavMenuItem | undefined): boolean;
     private getParentNavMenuItems;
+    private getTriggerElement;
     setCurrentActiveNavMenuItem(navMenuItem: NavMenuItem | undefined): void;
 }
 export default SideNavigationContext;

package/dist/components/sidenavigation/sidenavigation.context.js

@@ -2,11 +2,15 @@
 import { createContext } from '@lit/context';
 import { TAG_NAME as MENUPOPOVER_TAGNAME } from '../menupopover/menupopover.constants';
 import { TAG_NAME as NAVMENUITEM_TAGNAME } from '../navmenuitem/navmenuitem.constants';
-import { TAG_NAME } from './sidenavigation.constants';
+import { SUBMENU_TYPES, TAG_NAME } from './sidenavigation.constants';
 class SideNavigationContext {
-    constructor(defaultVariant, defaultExpanded) {
+    constructor(defaultVariant, defaultExpanded, defaultSubmenuType) {
         this.variant = defaultVariant;
         this.expanded = defaultExpanded;
+        this.submenuType = defaultSubmenuType;
+    }
+    get isDropdownSubmenuType() {
+        return this.submenuType === SUBMENU_TYPES.DROPDOWN;
     }
     hasSiblingWithTriggerId(navMenuItem) {
         var _a, _b;
@@ -18,21 +22,33 @@ class SideNavigationContext {
             sibling.tagName.toLowerCase() === MENUPOPOVER_TAGNAME &&
             sibling.getAttribute('triggerid') === id);
     }
+    isDropDownParent(navMenuItem) {
+        var _a, _b;
+        const id = navMenuItem === null || navMenuItem === void 0 ? void 0 : navMenuItem.getAttribute('id');
+        if (!id)
+            return false;
+        const siblings = Array.from((_b = (_a = navMenuItem === null || navMenuItem === void 0 ? void 0 : navMenuItem.parentElement) === null || _a === void 0 ? void 0 : _a.children) !== null && _b !== void 0 ? _b : []);
+        return siblings.some(sibling => sibling !== navMenuItem && sibling.matches(`div[data-trigger="${id}"]`));
+    }
     getParentNavMenuItems(navMenuItem) {
+        var _a;
         if (!navMenuItem)
             return [];
         const parents = [];
         let current = navMenuItem;
         while (current) {
-            // Walk up to find the menupopover
+            let triggeringNavMenuItem = null;
+            // A navmenuitem is either inside a menupopover (flyout) or a div[data-trigger] (dropdown), never both.
             const popover = current === null || current === void 0 ? void 0 : current.closest(MENUPOPOVER_TAGNAME);
-            if (!popover)
-                break;
-            const triggerId = popover.getAttribute('triggerid');
-            if (!triggerId)
-                break;
-            // Find the NavMenuItem that triggered this menupopover
-            const triggeringNavMenuItem = document.getElementById(triggerId);
+            if (popover) {
+                triggeringNavMenuItem = this.getTriggerElement(popover, 'triggerid');
+            }
+            else {
+                const dropdownContainer = (_a = current === null || current === void 0 ? void 0 : current.parentElement) === null || _a === void 0 ? void 0 : _a.closest('div[data-trigger]');
+                if (dropdownContainer) {
+                    triggeringNavMenuItem = this.getTriggerElement(dropdownContainer, 'data-trigger');
+                }
+            }
             if (triggeringNavMenuItem && triggeringNavMenuItem.tagName.toLowerCase() === NAVMENUITEM_TAGNAME) {
                 parents.push(triggeringNavMenuItem);
                 current = triggeringNavMenuItem;
@@ -43,10 +59,19 @@ class SideNavigationContext {
         }
         return parents;
     }
+    getTriggerElement(container, attribute) {
+        const triggerId = container.getAttribute(attribute);
+        if (!triggerId)
+            return null;
+        return document.getElementById(triggerId);
+    }
     setCurrentActiveNavMenuItem(navMenuItem) {
         var _a;
         const isSameItem = ((_a = this.currentActiveNavMenuItem) === null || _a === void 0 ? void 0 : _a.navId) === (navMenuItem === null || navMenuItem === void 0 ? void 0 : navMenuItem.navId);
-        const shouldSkip = (navMenuItem === null || navMenuItem === void 0 ? void 0 : navMenuItem.cannotActivate) || this.hasSiblingWithTriggerId(navMenuItem) || (navMenuItem === null || navMenuItem === void 0 ? void 0 : navMenuItem.softDisabled);
+        const shouldSkip = (navMenuItem === null || navMenuItem === void 0 ? void 0 : navMenuItem.cannotActivate) ||
+            this.hasSiblingWithTriggerId(navMenuItem) ||
+            (this.isDropdownSubmenuType && this.expanded && this.isDropDownParent(navMenuItem)) ||
+            (navMenuItem === null || navMenuItem === void 0 ? void 0 : navMenuItem.softDisabled);
         if (isSameItem || shouldSkip)
             return;
         // Clean up previous active item

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

@@ -1,7 +1,8 @@
 import type { TypedCustomEvent, ValueOf } from '../../utils/types';
 import type SideNavigation from './sidenavigation.component';
-import { VARIANTS } from './sidenavigation.constants';
+import { SUBMENU_TYPES, VARIANTS } from './sidenavigation.constants';
 type SideNavigationVariant = ValueOf<typeof VARIANTS>;
+type SideNavigationSubmenuType = ValueOf<typeof SUBMENU_TYPES>;
 type SideNavigationActiveChangeEvent = TypedCustomEvent<SideNavigation, {
     navId: string;
     active: boolean;
@@ -13,4 +14,4 @@ interface Events {
     onActiveChangeEvent: SideNavigationActiveChangeEvent;
     onToggleEvent: SideNavigationToggleEvent;
 }
-export type { SideNavigationVariant, Events };
+export type { SideNavigationVariant, SideNavigationSubmenuType, Events };

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

@@ -0,0 +1,8 @@
+import { Provider } from '../../models';
+import SideNavigationContext from './sidenavigation.context';
+/**
+ * The `SideNavigationBase` class serves as a foundational component for the side navigation feature. It extends the `Provider` class, which allows it to manage and provide the `SideNavigationContext` to its child components. Since `KeyToActionMixin` cannot be directly applied to a `Provider` with context, this base class is created as an intermediate layer. The `SideNavigation` component then extends this class and wraps it with `KeyToActionMixin` to gain mixin functionality while maintaining context management.
+ */
+declare class SideNavigationBase extends Provider<SideNavigationContext> {
+}
+export default SideNavigationBase;

package/dist/components/sidenavigation/sidenavigationbase.js

@@ -0,0 +1,7 @@
+import { Provider } from '../../models';
+/**
+ * The `SideNavigationBase` class serves as a foundational component for the side navigation feature. It extends the `Provider` class, which allows it to manage and provide the `SideNavigationContext` to its child components. Since `KeyToActionMixin` cannot be directly applied to a `Provider` with context, this base class is created as an intermediate layer. The `SideNavigation` component then extends this class and wraps it with `KeyToActionMixin` to gain mixin functionality while maintaining context management.
+ */
+class SideNavigationBase extends Provider {
+}
+export default SideNavigationBase;

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

@@ -3,23 +3,22 @@ import { CSSResult } from 'lit';
 import { Component } from '../../models';
 import type { SkeletonVariant } from './skeleton.types';
 /**
- * `mdc-skeleton` is a component that shows a grey placeholder area.
- * It provides visual feedback to users that content is being loaded.
- *
- * **Skeleton Variants:**
- * - **rectangular**: Default variant with 0.25rem border radius
- * - **rounded**: Has 0.5rem border radius
- * - **circular**: Has 50% border radius for circular shapes
- * - **button**: Optimized for button placeholders with 1.25rem border radius
- *
- * **Sizing Behavior:**
- * 1. If wrapping content, takes dimensions of wrapped content
- * 2. Otherwise grows to fill parent container
- *
+ * The skeleton is a grey placeholder block that signals to users that real content is being loaded. It can wrap a child element to take that element's dimensions, or stretch to fill its parent when used standalone.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-skeleton` to indicate that content is loading, in place of the real content while it is being fetched or rendered.
+ * - Use it to wrap a known-shape child (button, avatar, paragraph) so the placeholder matches the eventual layout.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-spinner` when the loading duration is short or you only need a single inline indicator rather than a layout-matching placeholder.
+ * - Use `mdc-progressbar` when there is a known, measurable progress value to communicate.
+ * 
  * @tagname mdc-skeleton
- *
+ * 
  * @slot - Content to wrap (optional). When provided, skeleton takes dimensions of this content.
- *
+ * 
  * @cssproperty --mdc-skeleton-background-color - background color of the skeleton
  * @cssproperty --mdc-skeleton-height - height of the skeleton
  * @cssproperty --mdc-skeleton-width - width of the skeleton

package/dist/components/skeleton/skeleton.component.js

@@ -13,19 +13,6 @@ import { Component } from '../../models';
 import { DEFAULTS } from './skeleton.constants';
 import styles from './skeleton.styles';
 /**
- * `mdc-skeleton` is a component that shows a grey placeholder area.
- * It provides visual feedback to users that content is being loaded.
- *
- * **Skeleton Variants:**
- * - **rectangular**: Default variant with 0.25rem border radius
- * - **rounded**: Has 0.5rem border radius
- * - **circular**: Has 50% border radius for circular shapes
- * - **button**: Optimized for button placeholders with 1.25rem border radius
- *
- * **Sizing Behavior:**
- * 1. If wrapping content, takes dimensions of wrapped content
- * 2. Otherwise grows to fill parent container
- *
  * @tagname mdc-skeleton
  *
  * @slot - Content to wrap (optional). When provided, skeleton takes dimensions of this content.

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

@@ -2,21 +2,23 @@ import type { CSSResult, PropertyValueMap } from 'lit';
 import { Component } from '../../models';
 declare const Slider_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/KeyDownHandledMixin").KeyDownHandledMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/KeyToActionMixin").KeyToActionInterface> & typeof Component;
 /**
- * Slider component is used to select a value or range of values from within a defined range.
- * It provides a visual representation of the current value(s) and allows users to adjust the value(s) by dragging the thumb(s) along the track.
- * It can be used as a single slider or a range slider. This is set by the boolean attribute `range`
- * If the step value is more than 1, tick marks are shown to represent the steps between the min and max values. The slider thumb will snap to the nearest tick mark.
- *
- * ## Spatial navigation
- *
- * In spatial navigation mode, the user has to step into edit mode to adjust the slider value using left and right navigation keys.
- * To enter edit mode, the user can press the Enter when one of the slider's handler is focused. User can leave edit mode by press
- * Enter or Escape.
- *
+ * The slider lets users pick a value, or a range of values, from a defined numeric range by dragging one or two thumbs along a track. When the step is greater than 1, the slider also renders tick marks and snaps to the nearest tick.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-slider` when the user needs to pick a numeric value from a continuous (or stepped) range, and the relative position matters (volume, brightness, zoom, etc.).
+ * - Use `range` when the user needs to pick both ends of a numeric interval (price range, time window).
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-stepper` when only discrete numeric increments are meaningful and precise typing is important.
+ * - Use `mdc-input type="number"` when the user needs to type an exact value.
+ * - Use `mdc-toggle` for binary on/off choices.
+ * 
  * @tagname mdc-slider
- *
+ * 
  * @dependency mdc-icon
- *
+ * 
  * @csspart slider-tooltip - The tooltip of the slider
  * @csspart slider-track - The track of the slider
  * @csspart slider-wrapper - The wrapper around the slider input(s)
@@ -24,10 +26,10 @@ declare const Slider_base: import("../../utils/mixins/index.types").Constructor<
  * @csspart slider-tick - The individual tick marks
  * @csspart slider-input - The input element of the slider
  * @csspart slider-label - The label of the slider
- *
+ * 
  * @event input - Fired when the slider value changes
  * @event change - Fired when the slider value is committed
- *
+ * 
  * @cssproperty --mdc-slider-thumb-color - The color of the slider thumb
  * @cssproperty --mdc-slider-thumb-border-color - The color of the slider thumb border
  * @cssproperty --mdc-slider-thumb-size - The size of the slider thumb