material 3.2.6 → 3.3.0

package/dist/components/menu/index.d.ts

@@ -1,29 +1,4 @@
-/**
- * Menu component module
- *
- * The Menu component provides a Material Design 3 compliant dropdown menu
- * system with support for nested menus, keyboard navigation, and accessibility.
- *
- * @module components/menu
- * @category Components
- */
 export { default, default as createMenu } from "./menu.js";
 export type { MenuEvents } from "./types.js";
 export type { MenuConfig, MenuVariant, MenuComponent, MenuItem, MenuDivider, MenuGap, MenuContent, MenuEvent, MenuSelectEvent, MenuPosition } from "./types.js";
-/**
- * Constants for menu position values - use these instead of string literals
- * for better code completion and type safety.
- *
- * @example
- * import { createMenu, MENU_POSITION } from 'material';
- *
- * // Create a menu positioned at the bottom-right of its opener
- * const menu = createMenu({
- *   opener: '#dropdown-button',
- *   items: [...],
- *   position: MENU_POSITION.BOTTOM_END
- * });
- *
- * @category Components
- */
 export { MENU_POSITION, MENU_DEFAULTS, MENU_INTERACTION_TYPES, MENU_ITEM_TYPES, MENU_EVENTS, MENU_CLASSES } from "./constants.js";

package/dist/components/menu/inner.d.ts

@@ -1,9 +1,6 @@
 import type { MenuComponent } from "./types.js";
-/** @internal */
 export declare const MENU: unique symbol;
-/** What an owner of an inner menu carries. @internal */
 export interface MenuOwner {
     [MENU]?: MenuComponent;
 }
-/** The menu inside a select or a split button, if it has one. @internal */
 export declare const innerMenu: (owner: object) => MenuComponent | undefined;

package/dist/components/menu/menu.d.ts

@@ -1,29 +1,3 @@
 import { MenuConfig, MenuComponent } from "./types.js";
-/**
- * Creates a new Menu component with the specified configuration.
- *
- * The Menu component implements the Material Design 3 menu specifications,
- * providing a flexible dropdown menu system with support for nested menus,
- * keyboard navigation, and ARIA accessibility.
- *
- * Menus are built using a functional composition pattern, applying various
- * features through the pipe function for a modular architecture.
- *
- * The menu element is not added to the DOM until it's opened, and it's removed
- * from the DOM when closed, following best practices for dropdown menus.
- *
- * @param {MenuConfig} config - Configuration options for the menu
- *  This must include an opener element or selector, and an array of menu items.
- *  See {@link MenuConfig} for all available options.
- *
- * @returns {MenuComponent} A fully configured menu component instance with
- *  all requested features applied. The returned component has methods for
- *  menu manipulation, event handling, and lifecycle management.
- *
- * @throws {Error} Throws an error if menu creation fails or if required
- *  configuration (like opener) is missing.
- *
- * @category Components
- */
 declare const createMenu: (config: MenuConfig) => MenuComponent;
 export default createMenu;

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

@@ -1,511 +1,114 @@
 import type { EventCallback } from "../../core/state/emitter.js";
-/**
- * Menu position options
- * Controls where the menu will appear relative to its opener element
- *
- * @category Components
- */
 export declare const MENU_POSITION: {
-    /** Places menu below the opener, aligned to left edge */
     readonly BOTTOM_START: "bottom-start";
-    /** Places menu below the opener, centered */
     readonly BOTTOM: "bottom";
-    /** Places menu below the opener, aligned to right edge */
     readonly BOTTOM_END: "bottom-end";
-    /** Places menu above the opener, aligned to left edge */
     readonly TOP_START: "top-start";
-    /** Places menu above the opener, centered */
     readonly TOP: "top";
-    /** Places menu above the opener, aligned to right edge */
     readonly TOP_END: "top-end";
-    /** Places menu to the right of the opener, aligned to top edge */
     readonly RIGHT_START: "right-start";
-    /** Places menu to the right of the opener, centered */
     readonly RIGHT: "right";
-    /** Places menu to the right of the opener, aligned to bottom edge */
     readonly RIGHT_END: "right-end";
-    /** Places menu to the left of the opener, aligned to top edge */
     readonly LEFT_START: "left-start";
-    /** Places menu to the left of the opener, centered */
     readonly LEFT: "left";
-    /** Places menu to the left of the opener, aligned to bottom edge */
     readonly LEFT_END: "left-end";
 };
-/**
- * Position options for the menu
- *
- * @category Components
- */
 export type MenuPosition = (typeof MENU_POSITION)[keyof typeof MENU_POSITION];
-/**
- * Configuration interface for a menu item
- *
- * @category Components
- */
 export interface MenuItem<TData = unknown> {
-    /**
-     * Unique ID for the menu item
-     * Required for accessibility and event handling
-     */
     id: string;
-    /**
-     * Display text for the menu item
-     */
     text: string;
-    /**
-     * Optional icon to display before the text.
-     * Markup (HTML). Not sanitized by default: see Markup and sanitizing.
-     * Accepts an HTML string (typically SVG).
-     */
     icon?: string;
-    /**
-     * Optional keyboard shortcut hint to display
-     * Shown at the end of the menu item
-     */
     shortcut?: string;
-    /**
-     * A second line under the label, for a short explanation of the item
-     * (vertical menus only)
-     */
     supportingText?: string;
-    /**
-     * Whether the menu item is disabled
-     * Disabled items cannot be clicked but remain visible
-     */
     disabled?: boolean;
-    /**
-     * Whether this item has a submenu
-     * If true, the item will show an indicator and can open a nested menu
-     */
     hasSubmenu?: boolean;
-    /**
-     * Optional array of submenu items
-     * Only used when hasSubmenu is true
-     */
     submenu?: MenuItem<TData>[];
-    /**
-     * Additional data to associate with the menu item
-     * This can be used for custom behavior in click handlers
-     */
     data?: TData;
 }
-/**
- * Menu item type for dividers
- *
- * @category Components
- */
 export interface MenuDivider {
-    /**
-     * Type must be 'divider' to differentiate from regular menu items
-     */
     type: "divider";
-    /**
-     * Optional ID for the divider (for accessibility)
-     */
     id?: string;
 }
-/**
- * Menu item type for a gap between groups.
- *
- * The M3 expressive vertical menu separates groups two ways: a divider line,
- * or a gap. A gap splits the menu into separate surfaces, each with its own
- * rounded container, rather than drawing a line across one surface
- * (m3.material.io/components/menus, vertical menus).
- *
- * A standard menu is a single surface, so a gap there is simply space.
- *
- * @category Components
- */
 export interface MenuGap {
-    /**
-     * Type must be 'gap' to differentiate from regular menu items
-     */
     type: "gap";
-    /**
-     * Optional ID for the gap (for accessibility)
-     */
     id?: string;
 }
-/**
- * Combined type for menu content items (regular items, dividers or gaps)
- *
- * @category Components
- */
 export type MenuContent<TData = unknown> = MenuItem<TData> | MenuDivider | MenuGap;
-/**
- * Configuration interface for the Menu component
- *
- * @category Components
- */
-/** Menu variants */
 export type MenuVariant = "baseline" | "vertical";
-/** Colour mappings for the vertical menu */
 export type MenuColor = "standard" | "vibrant";
 export interface MenuConfig {
-    /**
-     * Element to which the menu will be openered
-     * Can be an HTML element, a CSS selector string, or a component with an element property
-     */
     opener: HTMLElement | string | {
         element: HTMLElement;
     };
-    /**
-     * The element the menu is placed against, when it is not the opener's: a
-     * select's field, so its supporting text row never pushes the menu down
-     * The opener still opens, closes and gets focus back.
-     */
     positionTarget?: HTMLElement;
-    /**
-     * Array of menu items and dividers to display
-     */
     items: MenuContent[];
-    /**
-     * Menu variant. `'vertical'` is the M3 expressive menu: a rounded
-     * container holding items that sit apart and change shape as they are
-     * hovered, focused, pressed or selected.
-     * @default 'baseline'
-     */
     variant?: MenuVariant;
-    /**
-     * Colour mapping for the vertical variant. `'vibrant'` is tertiary-based
-     * and more prominent, so it should be used sparingly.
-     */
     color?: MenuColor;
-    /**
-     * Position of the menu relative to the opener
-     * @default 'bottom-start'
-     */
     position?: MenuPosition;
-    /**
-     * Whether the menu should close when an item is clicked
-     * @default true
-     */
     closeOnSelect?: boolean;
-    /**
-     * Whether the menu should close when the user clicks outside
-     * @default true
-     */
     closeOnClickOutside?: boolean;
-    /**
-     * Whether the menu should close when the escape key is pressed
-     * @default true
-     */
     closeOnEscape?: boolean;
-    /**
-     * Whether the menu should close when the window is resized
-     * @default false
-     */
     closeOnResize?: boolean;
-    /**
-     * Whether submenus should open on hover
-     * @default true
-     */
     openSubmenuOnHover?: boolean;
-    /**
-     * Optional width for the menu (in CSS units)
-     * If not provided, menu will size to its content
-     */
     width?: string;
-    /**
-     * Optional maximum height for the menu (in CSS units)
-     * If content exceeds this height, the menu will scroll
-     */
     maxHeight?: string;
-    /**
-     * Optional offset from the opener (in pixels)
-     * @default 0
-     */
     offset?: number;
-    /**
-     * Whether the menu should automatically flip position to stay in viewport
-     * @default true
-     */
     autoFlip?: boolean;
-    /**
-     * Whether the menu is initially visible
-     * @default false
-     */
     visible?: boolean;
-    /**
-     * Container element to append the menu to
-     * If not provided, menu will be appended to document.body
-     * Use this when the menu needs to stay within a specific container (e.g., inside a dialog)
-     */
     container?: HTMLElement | null;
-    /**
-     * `"top"` renders the menu in place, next to its opener, and shows it in the
-     * browser's top layer as a `popover="manual"` element: above every z-index,
-     * outside any clipping ancestor, and still inside the opener's shadow root,
-     * so it keeps that root's styles. `container` is then not used. The menu
-     * positions itself in viewport coordinates and keeps its own dismissal.
-     * Submenus open in the top layer too.
-     *
-     * Where the browser has no popover support, the menu behaves as without it.
-     * Unset, the menu is appended to `container` or `document.body`.
-     */
     layer?: "top";
-    /**
-     * When true, the opener is used only for positioning.
-     * No click, blur, or keyboard handlers are attached to the opener element.
-     * The consumer is responsible for calling open() / close() manually.
-     * @default false
-     */
     manualOpen?: boolean;
-    /**
-     * Renders the menu as the listbox popup of a combobox (WAI-ARIA select-only
-     * combobox): the list is `role="listbox"` and each item `role="option"` with
-     * its own id, focus stays with the combobox, which owns the keyboard and
-     * points at the active option with `aria-activedescendant`, and the opener
-     * gets no ARIA from the menu. Pair it with `manualOpen`.
-     * @default false
-     */
     listbox?: boolean;
-    /**
-     * When true, renders a compact menu with smaller items and tighter spacing.
-     * Useful in dense UIs like toolbars and action bars where the standard
-     * 48px item height is too large.
-     * @default false
-     */
     dense?: boolean;
-    /**
-     * Additional CSS classes to add to the menu
-     */
     class?: string;
-    /**
-     * Component prefix for CSS class names
-     * @default 'mtrl'
-     */
     prefix?: string;
-    /**
-     * Component name used in CSS class generation
-     * @default 'menu'
-     */
     componentName?: string;
-    /**
-     * Event handlers for the menu
-     */
     on?: {
-        /**
-         * Called when the menu is opened
-         */
         open?: (event: MenuEvent) => void;
-        /**
-         * Called when the menu is closed
-         */
         close?: (event: MenuEvent) => void;
-        /**
-         * Called when a menu item is selected
-         */
         select?: (event: MenuSelectEvent) => void;
     };
 }
-/**
- * What `open` and `close` carry. Neither can be cancelled: the menu is
- * already open, or closed, when its listener runs.
- *
- * @category Components
- */
 export interface MenuEvent {
-    /** The menu component that triggered the event */
     menu: MenuComponent;
-    /** Original DOM event if available */
     originalEvent?: Event;
 }
-/**
- * Menu selection event interface
- *
- * @category Components
- */
 export interface MenuSelectEvent<TData = unknown> extends MenuEvent {
-    /** The selected menu item */
     item: MenuItem<TData>;
-    /** ID of the selected menu item */
     itemId: string;
-    /** The item's id again, as the `value` of the `<m-menu>` element's `select` */
     value: string;
-    /** Data associated with the menu item (if any) */
     itemData?: TData;
-    /** Keeps the menu open: a `closeOnSelect` menu does not close for this selection */
     preventDefault: () => void;
-    /** Whether a listener has called `preventDefault()` */
     defaultPrevented: boolean;
 }
-/**
- * Menu component interface
- *
- * @category Components
- */
 export interface MenuComponent {
-    /** The menu's root DOM element */
     element: HTMLElement;
-    /**
-     * Opens the menu.
-     *
-     * When it returns, `isOpen()` is true and `open` has been emitted. The
-     * surface is placed and shown, and focus moves in, after that. On an open
-     * menu it does nothing and emits nothing.
-     *
-     * From then on a click outside and Escape close it (`closeOnClickOutside`,
-     * `closeOnEscape`). The event that opened it never does: the click or the
-     * key press whose dispatch had begun when `open()` ran is ignored, and only
-     * that one.
-     * @param event - Optional event that triggered the open
-     * @param interactionType - The type of interaction that triggered the open ('mouse' or 'keyboard')
-     * @returns The menu component for chaining
-     */
     open: (event?: Event, interactionType?: "mouse" | "keyboard") => MenuComponent;
-    /**
-     * Closes the menu.
-     *
-     * When it returns, `isOpen()` is false and `close` has been emitted. The
-     * surface fades after that and then leaves the document. On a closed menu
-     * it does nothing and emits nothing.
-     *
-     * `close()` then `open()` at once ends open, and `open()` then `close()`
-     * ends closed: the later call wins, and what the earlier one still had to
-     * do (showing the surface, or removing it) is dropped.
-     * @param event - Optional event that triggered the close
-     * @param restoreFocus - Whether focus returns to the opener (default true)
-     * @param skipAnimation - Whether to close without the exit animation
-     * @returns The menu component for chaining
-     */
     close: (event?: Event, restoreFocus?: boolean, skipAnimation?: boolean) => MenuComponent;
-    /**
-     * Toggles the menu's open state
-     * @param event - Optional event that triggered the toggle
-     * @returns The menu component for chaining
-     */
     toggle: (event?: Event) => MenuComponent;
-    /**
-     * Checks if the menu is currently open. It changes inside `open()` and
-     * `close()`, before their events, and does not wait for the animation.
-     * @returns True if the menu is open
-     */
     isOpen: () => boolean;
-    /**
-     * Updates the menu items
-     * @param items - New array of menu items and dividers
-     * @returns The menu component for chaining
-     */
     setItems: (items: MenuContent[]) => MenuComponent;
-    /**
-     * Gets the current menu items
-     * @returns Array of current menu items and dividers
-     */
     getItems: () => MenuContent[];
-    /**
-     * Updates the menu's opener element
-     * @param opener - New opener element or selector
-     * @returns The menu component for chaining
-     */
     setOpener: (opener: HTMLElement | string) => MenuComponent;
-    /**
-     * Gets the current opener element
-     * @returns Current opener element
-     */
     getOpener: () => HTMLElement;
-    /**
-     * Updates the menu's position
-     * @param position - New position value
-     * @returns The menu component for chaining
-     */
     setPosition: (position: MenuPosition) => MenuComponent;
-    /**
-     * Gets the current menu position
-     * @returns Current position
-     */
     getPosition: () => MenuPosition;
-    /**
-     * Sets the selected menu item
-     * @param itemId - ID of the menu item to mark as selected
-     * @returns The menu component for chaining
-     */
     setSelected: (itemId: string | null) => MenuComponent;
-    /**
-     * Gets the currently selected menu item's ID
-     * @returns ID of the selected menu item or null if none is selected
-     */
     getSelected: () => string | null;
-    /**
-     * Adds an event listener to the menu
-     * @param event - Event name ('open', 'close', 'select')
-     * @param handler - Event handler function
-     * @returns The menu component for chaining
-     */
     on<T extends keyof MenuEvents>(event: T, handler: MenuEvents[T]): MenuComponent;
-    /**
-     * Adds an event listener for any event the menu emits, such as
-     * 'submenu-opened', 'submenu-closed', 'all-submenus-closed' or 'menu-closing'
-     * @param event - Event name
-     * @param handler - Event handler function
-     * @returns The menu component for chaining
-     */
     on(event: string, handler: EventCallback): MenuComponent;
-    /**
-     * Removes an event listener from the menu
-     * @param event - Event name
-     * @param handler - Event handler function
-     * @returns The menu component for chaining
-     */
     off<T extends keyof MenuEvents>(event: T, handler: MenuEvents[T]): MenuComponent;
-    /**
-     * Removes an event listener for any event the menu emits
-     * @param event - Event name
-     * @param handler - Event handler function
-     * @returns The menu component for chaining
-     */
     off(event: string, handler: EventCallback): MenuComponent;
-    /**
-     * Destroys the menu component and cleans up resources
-     */
     destroy: () => void;
 }
-/**
- * Menu events interface for type-checking
- *
- * @category Components
- * @internal
- */
 export interface MenuEvents {
     open: (event: MenuEvent) => void;
     close: (event: MenuEvent) => void;
     select: (event: MenuSelectEvent) => void;
 }
-/**
- * The menu as its own features see it, part-way through the pipe.
- *
- * One shared shape rather than five near-identical ones, because the features
- * enhance the same object in sequence. `element`, `getClass` and `lifecycle`
- * are required: withElement and withLifecycle run before any of them. The
- * rest are optional because they are installed by siblings, and which have
- * run depends on where in the pipe you are.
- *
- * @category Components
- * @internal
- */
-/**
- * What withController installs at `component.menu`.
- *
- * The commands return the component they were handed, which is the
- * pre-controller one; nothing reads it and the API layer discards it. Declared
- * void for the same reason as MenuOpenerApi -- so the feature's generic does
- * not appear in its own return type, which is what stopped the pipe binding C
- * at that stage.
- *
- * @category Components
- * @internal
- */
-/**
- * Menu state the keyboard handlers read.
- *
- * Declared here rather than in features/keyboard.ts so the host below can
- * name it: a host that types its manager methods needs their parameter types
- * in scope.
- */
 export interface KeyboardMenuState {
     items: MenuContent[];
 }
-/** Menu actions the keyboard handlers call. */
 export interface KeyboardActions {
     closeMenu: (event: Event, restoreFocus?: boolean) => void;
     findItemById: (id: string) => MenuItem | null;
@@ -525,14 +128,6 @@ export interface MenuControllerApi {
     getPosition: () => MenuPosition;
     setPosition: (position: MenuPosition) => void;
 }
-/**
- * A component that can act as a menu's opener: anything that exposes an
- * element through `element`, `getElement()` or `input`, and follows the menu's
- * open state when it can.
- *
- * @category Components
- * @internal
- */
 export interface OpenerComponent {
     element?: HTMLElement;
     getElement?: () => HTMLElement;
@@ -542,25 +137,7 @@ export interface OpenerComponent {
     focus?: () => void;
     blur?: () => void;
 }
-/**
- * What a menu opener can be given as: a selector, an element or a component
- *
- * @category Components
- * @internal
- */
 export type OpenerTarget = string | HTMLElement | OpenerComponent;
-/**
- * What withOpener installs at `component.opener`.
- *
- * The three setters return the component they were handed, which is the
- * pre-opener one and so not useful for chaining; nothing reads it, and the API
- * layer discards it. Declared `void` so the value is not promised, and so the
- * feature's generic does not appear in its own return type -- which is what
- * stopped the pipe binding C at that stage.
- *
- * @category Components
- * @internal
- */
 export interface MenuOpenerApi {
     setOpener: (opener: OpenerTarget) => void;
     getOpener: () => HTMLElement | null;

package/dist/components/navigation-bar/navigation-bar.d.ts

@@ -1,9 +1,2 @@
 import type { NavigationBarComponent, NavigationBarConfig } from "./types.js";
-/**
- * Creates an M3 Expressive navigation bar: three to five destinations along
- * the bottom of a compact or medium window (Compose `ShortNavigationBar`).
- * Import its styles separately with `material/styles/navigation-bar`. Links keep
- * native browser navigation; `onSelect` can `preventDefault()` for a router.
- * Don't show it together with a toolbar (m3.material.io).
- */
 export default function createNavigationBar(config?: NavigationBarConfig): NavigationBarComponent;

package/dist/components/navigation-bar/types.d.ts

@@ -1,48 +1,26 @@
 import type { DestinationConfig } from "../../core/navigation/destinations.js";
-/** One destination of the bar: a link (`href`) or a button. */
 export type NavigationBarItemConfig = DestinationConfig;
-/** What `select` and `onSelect` carry: the destination chosen by click or keyboard. */
 export interface NavigationBarSelectEvent {
     id: string;
-    /** The id, as `<m-navigation-bar>`'s `change` carries it */
     value: string;
     index: number;
     originalEvent: MouseEvent;
 }
 export interface NavigationBarEvents {
     select: NavigationBarSelectEvent;
-    /** The bar was hidden (`hidden: true`) or shown again, by scroll or by `hide()`/`show()` */
     visibility: {
         hidden: boolean;
     };
 }
-/**
- * Where an item puts its icon. `'vertical'`: above the label, the compact bar.
- * `'horizontal'`: beside it, M3 Expressive's medium-width bar, with the items
- * centred. `'auto'` (the default) is vertical, and horizontal while the bar
- * itself is at least 600px wide: a CSS container query on the bar, so a bar in
- * a narrow pane stays vertical in a wide window. Compose leaves the choice to
- * the caller; MDC-Android puts the threshold at 600dp.
- */
 export type NavigationBarItemLayout = 'auto' | 'vertical' | 'horizontal';
 export interface NavigationBarConfig {
-    /** Three to five destinations (M3) */
     items?: NavigationBarItemConfig[];
     itemLayout?: NavigationBarItemLayout;
-    /**
-     * Hides the bar while the page scrolls down and shows it when it scrolls
-     * up, as the bottom app bar's `autoHide`. `true` follows the window; pass an
-     * element to follow its scroll instead. Off by default: M3's guidelines
-     * advise against hiding navigation while a screen reader is in use, which a
-     * page can't detect. Focus inside the bar always shows it.
-     */
     hideOnScroll?: boolean | {
         target?: HTMLElement | Window;
     };
-    /** The landmark's name; default "Primary navigation" */
     ariaLabel?: string;
     ripple?: boolean;
-    /** `select` listener registered at creation. */
     onSelect?: (event: NavigationBarEvents["select"]) => void;
     class?: string;
     prefix?: string;
@@ -55,14 +33,11 @@ export interface NavigationBarComponent {
         destroy: () => void;
     };
     getActive: () => string | null;
-    /** The active destination's id, as getActive(): the value getter every component has */
     getValue: () => string | null;
-    /** Marks a destination active, silently (no `select`); `null` clears it */
     setActive: (id: string | null) => NavigationBarComponent;
     getItems: () => NavigationBarItemConfig[];
     setItems: (items: NavigationBarItemConfig[]) => NavigationBarComponent;
     setBadge: (id: string, badge: NavigationBarItemConfig['badge'], label?: string) => NavigationBarComponent;
-    /** Slides the bar out of view (without the slide under reduced motion) */
     hide: () => NavigationBarComponent;
     show: () => NavigationBarComponent;
     isHidden: () => boolean;