material 3.2.6 → 3.3.0

package/dist/components/button-group/types.d.ts

@@ -1,130 +1,38 @@
 import type { ButtonConfig, ButtonComponent } from "../button/types.js";
-/**
- * Button group orientation
- * @category Components
- */
 export type ButtonGroupOrientation = "horizontal" | "vertical";
-/**
- * Button group variant - applies to all buttons in the group
- * @category Components
- */
 export type ButtonGroupVariant = "filled" | "tonal" | "outlined" | "elevated" | "text";
-/**
- * Button group density options
- * Controls the overall sizing and spacing of buttons in the group
- * @category Components
- */
 export type ButtonGroupDensity = "default" | "comfortable" | "compact";
-/**
- * Event types for button group
- */
 export type ButtonGroupEventType = "click" | "focus" | "blur" | "change";
-/**
- * Material 3 button group kinds.
- * - "standard": padding between buttons; a selected button morphs from round
- *   to square and its neighbours adjust.
- * - "connected": 2dp between buttons, round outer corners, square inner
- *   corners; selection changes only the selected button. Replaces the
- *   segmented button for single- and multi-select.
- */
 export type ButtonGroupKind = "standard" | "connected";
 export type ButtonGroupSelection = "none" | "single" | "multi";
 export type ButtonGroupShape = "round" | "square";
 export type ButtonGroupSize = "xs" | "s" | "m" | "l" | "xl";
-/** Label display: always, or only on the selected button (icon-only otherwise) */
 export type ButtonGroupLabels = "always" | "selected";
-/** Payload of the "change" event: the selection after the change. */
 export interface ButtonGroupChangeEvent {
     buttonGroup: ButtonGroupComponent;
-    /** Values of the selected buttons, in button order */
     values: string[];
-    /**
-     * The selection in the `value` shape of the `<m-button-group>` element's
-     * `change`: an array for a multi-select group, a string or null otherwise.
-     */
     value: string | string[] | null;
     selected: ButtonComponent[];
-    /** The button whose click caused the change, if any */
     button?: ButtonComponent;
     originalEvent?: Event;
 }
-/**
- * Event data for button group events
- */
 export interface ButtonGroupEvent {
-    /** The button group component that contains the clicked button */
     buttonGroup: ButtonGroupComponent;
-    /** The button component that was clicked */
     button: ButtonComponent;
-    /** Index of the button in the group */
     index: number;
-    /** Original DOM event */
     originalEvent: Event;
 }
-/**
- * Configuration for a single button within a button group
- * Extends ButtonConfig but omits properties controlled by the group
- * @category Components
- */
 interface ButtonGroupItemBase extends Omit<ButtonConfig, "variant"> {
-    /**
-     * Unique identifier for the button
-     * If not provided, index will be used
-     */
     id?: string;
-    /**
-     * Button text content
-     * @example 'Bold'
-     */
     text?: string;
-    /**
-     * Button icon HTML content.
-     * Markup (HTML). Not sanitized by default: see Markup and sanitizing.
-     * @example '<svg>...</svg>'
-     */
     icon?: string;
-    /**
-     * Accessible label. See {@link ButtonGroupItemConfig}: optional on an item
-     * that has text, required on an icon-only one.
-     *
-     * @example 'Toggle bold'
-     */
     ariaLabel?: string;
-    /**
-     * Whether this button is disabled
-     * @default false
-     */
     disabled?: boolean;
-    /**
-     * Value associated with this button
-     */
     value?: string;
-    /** Icon shown while selected (toggle buttons). Markup (HTML). Not sanitized by default: see Markup and sanitizing. */
     selectedIcon?: string;
-    /** Initially selected (selection groups only) */
     selected?: boolean;
-    /**
-     * Additional CSS class for this button
-     */
     class?: string;
 }
-/**
- * Configuration interface for the Button Group component
- * @category Components
- */
-/**
- * A button in a group.
- *
- * Whether an item renders as an icon button is decided at render time from
- * this config -- an item with an icon and no text becomes one -- so whether
- * its accessible label is optional depends on the same config. A text item
- * takes its name from the text; an icon-only item has nothing else to take it
- * from, and without a label announces as "button" (WCAG 4.1.2).
- *
- * Expressed as a union rather than a flat required field, because requiring
- * it on text items too is over-broad -- it would make 67 call sites in this
- * component's own tests pass a label that duplicates the text.
- */
 export type ButtonGroupItemConfig = (ButtonGroupItemBase & {
     text: string;
 }) | (ButtonGroupItemBase & {
@@ -132,90 +40,27 @@ export type ButtonGroupItemConfig = (ButtonGroupItemBase & {
     ariaLabel: string;
 });
 export interface ButtonGroupConfig {
-    /**
-     * Array of button configurations
-     */
     buttons?: ButtonGroupItemConfig[];
-    /** "standard" (default) or "connected" */
     kind?: ButtonGroupKind;
-    /** "none" (default): plain actions. "single" or "multi": toggle buttons. */
     selection?: ButtonGroupSelection;
-    /** With single or multi selection: the last selected button cannot be deselected */
     required?: boolean;
-    /** Corner style: round (default) or square */
     shape?: ButtonGroupShape;
-    /**
-     * Standard groups: share of its width a pressed button gains while its
-     * neighbours give up the difference (M3: 0.15). 0 disables the motion.
-     * @default 0.15
-     */
     expandedRatio?: number;
-    /** Material size token: xs, s (default), m, l, xl */
     size?: ButtonGroupSize;
-    /**
-     * "always" (default): buttons show icon and text. "selected": buttons with
-     * an icon and a text show the text only while selected; the selected button
-     * widens to reveal it (M3 Expressive connected groups).
-     */
     labels?: ButtonGroupLabels;
-    /**
-     * Visual variant applied to all buttons in the group
-     * @default 'outlined'
-     */
     variant?: ButtonGroupVariant;
-    /**
-     * Orientation of the button group
-     * @default 'horizontal'
-     */
     orientation?: ButtonGroupOrientation;
-    /**
-     * Density setting that controls button sizing
-     * @default 'default'
-     */
     density?: ButtonGroupDensity;
-    /**
-     * Whether the entire button group is disabled
-     * @default false
-     */
     disabled?: boolean;
-    /**
-     * Whether buttons should have equal width
-     * @default false
-     */
     equalWidth?: boolean;
-    /**
-     * Component prefix for class names
-     * @default 'mtrl'
-     */
     prefix?: string;
-    /**
-     * Component name used in class generation
-     */
     componentName?: string;
-    /**
-     * Additional CSS class for the button group container
-     */
     class?: string;
-    /**
-     * Whether to enable ripple effect on buttons
-     * @default true
-     */
     ripple?: boolean;
-    /**
-     * Ripple effect configuration
-     */
     rippleConfig?: {
-        /** How long, in milliseconds, a released wave lingers before it is removed */
         duration?: number;
     };
-    /**
-     * Accessible label for the button group
-     * @example 'Text formatting options'
-     */
     ariaLabel?: string;
-    /**
-     * Listeners registered at creation, ahead of any listener added afterwards.
-     */
     on?: {
         click?: (event: ButtonGroupEvent) => void;
         focus?: (event: ButtonGroupEvent) => void;
@@ -223,87 +68,23 @@ export interface ButtonGroupConfig {
         change?: (event: ButtonGroupChangeEvent) => void;
     };
 }
-/**
- * Button Group component interface
- * @category Components
- */
 export interface ButtonGroupComponent {
-    /** The component's container DOM element */
     element: HTMLElement;
-    /** Array of button component instances */
     buttons: ButtonComponent[];
-    /**
-     * Gets a button by its index
-     * @param index - Button index
-     * @returns The button component or undefined
-     */
     getButton: (index: number) => ButtonComponent | undefined;
-    /**
-     * Gets a button by its id or value
-     * @param id - Button id or value
-     * @returns The button component or undefined
-     */
     getButtonById: (id: string) => ButtonComponent | undefined;
-    /**
-     * Gets the current variant
-     * @returns Current variant name
-     */
     getVariant: () => ButtonGroupVariant;
-    /**
-     * Sets the variant for all buttons in the group
-     * @param variant - New variant to apply
-     * @returns The ButtonGroupComponent for chaining
-     */
     setVariant: (variant: ButtonGroupVariant) => ButtonGroupComponent;
-    /**
-     * Gets the current orientation
-     * @returns Current orientation
-     */
     getOrientation: () => ButtonGroupOrientation;
-    /**
-     * Sets the orientation of the button group
-     * @param orientation - New orientation
-     * @returns The ButtonGroupComponent for chaining
-     */
     setOrientation: (orientation: ButtonGroupOrientation) => ButtonGroupComponent;
-    /**
-     * Gets the current density
-     * @returns Current density
-     */
     getDensity: () => ButtonGroupDensity;
-    /**
-     * Sets the density of the button group
-     * @param density - New density level
-     * @returns The ButtonGroupComponent for chaining
-     */
     setDensity: (density: ButtonGroupDensity) => ButtonGroupComponent;
-    /**
-     * Enables the entire button group
-     * @returns The ButtonGroupComponent for chaining
-     */
     enable: () => ButtonGroupComponent;
-    /**
-     * Disables the entire button group
-     * @returns The ButtonGroupComponent for chaining
-     */
     disable: () => ButtonGroupComponent;
-    /** Whether the whole group is disabled */
     isDisabled: () => boolean;
-    /**
-     * Enables a specific button by index
-     * @param index - Button index
-     * @returns The ButtonGroupComponent for chaining
-     */
     enableButton: (index: number) => ButtonGroupComponent;
-    /**
-     * Disables a specific button by index
-     * @param index - Button index
-     * @returns The ButtonGroupComponent for chaining
-     */
     disableButton: (index: number) => ButtonGroupComponent;
-    /** Selection (groups with selection "single" or "multi") */
     getSelected: () => string[];
-    /** Reads the current model value without changing selection. */
     getValue: () => string | string[] | null;
     isSelected: (value: string) => boolean;
     select: (value: string) => ButtonGroupComponent;
@@ -311,26 +92,11 @@ export interface ButtonGroupComponent {
     toggle: (value: string) => ButtonGroupComponent;
     getKind: () => ButtonGroupKind;
     getSelection: () => ButtonGroupSelection;
-    /**
-     * Adds an event listener to the button group
-     * @param event - Event name
-     * @param handler - Event handler function
-     * @returns The ButtonGroupComponent for chaining
-     */
     on: {
         (event: "change", handler: (event: ButtonGroupChangeEvent) => void): ButtonGroupComponent;
         (event: "click" | "focus" | "blur", handler: (event: ButtonGroupEvent) => void): ButtonGroupComponent;
     };
-    /**
-     * Removes an event listener from the button group
-     * @param event - Event name
-     * @param handler - Event handler function
-     * @returns The ButtonGroupComponent for chaining
-     */
     off: (event: ButtonGroupEventType, handler: (event: ButtonGroupEvent | ButtonGroupChangeEvent) => void) => ButtonGroupComponent;
-    /**
-     * Destroys the component and cleans up resources
-     */
     destroy: () => void;
 }
 export {};

package/dist/components/card/card.d.ts

@@ -1,67 +1,3 @@
 import { CardComponent, CardConfig } from "./types.js";
-/**
- * Creates a new Card component following Material Design 3 principles.
- *
- * Material Design 3 Cards are surfaces that display content and actions about a single topic.
- * Cards can contain text, media, and UI controls. They provide entry points to more
- * detailed information and can include interactive elements.
- *
- * @param {CardConfig} config - Card configuration object
- * @returns {CardComponent} Card component instance with the following API methods:
- * - `addContent(contentElement)`: Adds content to the card
- * - `setHeader(headerElement)`: Sets the card header
- * - `addMedia(mediaElement, position)`: Adds media to the card
- * - `setActions(actionsElement)`: Sets the card actions section
- * - `makeDraggable(dragStartCallback)`: Makes the card draggable
- * - `focus()`: Sets focus to the card
- * - `destroy()`: Destroys the card component and removes event listeners
- *
- * @throws {Error} Throws an error if card creation fails
- * @category Components
- * @example
- * ```typescript
- * // Create a basic card
- * const card = createCard({
- *   variant: 'elevated',
- *   header: {
- *     title: 'Card Title',
- *     subtitle: 'Secondary text'
- *   },
- *   content: {
- *     text: 'Card content goes here.'
- *   }
- * });
- *
- * // Create an interactive card with actions
- * const cardWithActions = createCard({
- *   variant: 'filled',
- *   interactive: true,
- *   header: { title: 'Interactive Card' },
- *   content: { text: 'Click the buttons below.' },
- *   buttons: [
- *     { text: 'Action 1', variant: 'text' },
- *     { text: 'Action 2', variant: 'filled' }
- *   ]
- * });
- *
- * // Card with media
- * const mediaCard = createCard({
- *   media: {
- *     src: '/path/to/image.jpg',
- *     alt: 'Descriptive alt text',
- *     aspectRatio: '16:9'
- *   },
- *   header: { title: 'Media Card' }
- * });
- *
- * // Using API methods
- * const card = createCard();
- * const content = document.createElement('div');
- * content.className = 'mtrl-card__content';
- * content.textContent = 'Added programmatically';
- * card.addContent(content);
- * card.makeDraggable();
- * ```
- */
 declare const createCard: (config?: CardConfig) => CardComponent;
 export default createCard;

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

@@ -1,70 +1,40 @@
-/**
- * Card variants following Material Design 3 guidelines
- * - ELEVATED: Card with shadow elevation (default)
- * - FILLED: Card with filled background color and no elevation
- * - OUTLINED: Card with outline border and no elevation
- */
 export declare const CARD_VARIANTS: {
     readonly ELEVATED: "elevated";
     readonly FILLED: "filled";
     readonly OUTLINED: "outlined";
 };
-/**
- * Card elevation levels in Material Design 3
- * Specifies the shadow height in density-independent pixels (dp)
- */
 export declare const CARD_ELEVATIONS: {
     readonly LEVEL0: 0;
     readonly LEVEL1: 1;
     readonly LEVEL2: 2;
     readonly LEVEL4: 4;
 };
-/**
- * Card width constants
- * Provides standardized card widths based on Material Design
- */
 export declare const CARD_WIDTHS: {
     readonly SMALL: "344px";
     readonly MEDIUM: "480px";
     readonly LARGE: "624px";
     readonly FULL: "100%";
 };
-/**
- * Card corner radius options
- * Provides standardized corner radius values
- */
 export declare const CARD_CORNER_RADIUS: {
     readonly SMALL: "8px";
     readonly MEDIUM: "12px";
     readonly LARGE: "16px";
 };
-/**
- * Card media aspect ratio options
- */
 export declare const CARD_ASPECT_RATIOS: {
     readonly SQUARE: "1:1";
     readonly STANDARD: "4:3";
     readonly WIDESCREEN: "16:9";
 };
-/**
- * Card action alignment options
- */
 export declare const CARD_ACTION_ALIGNMENT: {
     readonly START: "start";
     readonly CENTER: "center";
     readonly END: "end";
     readonly SPACE_BETWEEN: "space-between";
 };
-/**
- * Card media position options
- */
 export declare const CARD_MEDIA_POSITION: {
     readonly TOP: "top";
     readonly BOTTOM: "bottom";
 };
-/**
- * CSS class names used in the card component
- */
 export declare const CARD_CLASSES: {
     readonly ROOT: "card";
     readonly HEADER: "card__header";
@@ -75,14 +45,11 @@ export declare const CARD_CLASSES: {
     readonly CONTENT: "card__content";
     readonly MEDIA: "card__media";
     readonly ACTIONS: "card__actions";
-    /** Reserved modifier; draggable currently uses the native attribute. */
     readonly DRAGGABLE: "card--draggable";
     readonly INTERACTIVE: "card--interactive";
     readonly FULL_WIDTH: "card--full-width";
-    /** Reserved modifier; clickable currently uses INTERACTIVE. */
     readonly CLICKABLE: "card--clickable";
     readonly LOADING: "card--state-loading";
     readonly EXPANDED: "card--expanded";
-    /** Reserved modifier prefix; elevation currently uses styles. */
     readonly ELEVATION_PREFIX: "card--elevation-";
 };

package/dist/components/card/content.d.ts

@@ -1,92 +1,6 @@
 import { CardContentConfig, CardHeaderConfig, CardMediaConfig, CardActionsConfig } from "./types.js";
 export declare const CARD_CONTENT_PADDING = true;
-/**
- * Creates a card content component
- *
- * @param {CardContentConfig} config - Content configuration
- * @returns {HTMLElement} Card content element
- *
- * @example
- * ```typescript
- * // Create text content
- * const textContent = createCardContent({ text: 'Simple text content' });
- *
- * // Create HTML content with no padding
- * const htmlContent = createCardContent({
- *   html: '<p>Formatted <strong>HTML</strong> content</p>',
- *   padding: false
- * });
- * ```
- */
 export declare const createCardContent: (config?: CardContentConfig) => HTMLElement;
-/**
- * Creates a card header component
- *
- * @param {CardHeaderConfig} config - Header configuration
- * @returns {HTMLElement} Card header element
- *
- * @example
- * ```typescript
- * // Create a header with title and subtitle
- * const header = createCardHeader({
- *   title: 'Card Title',
- *   subtitle: 'Supporting text'
- * });
- *
- * // Create a header with an avatar and action
- * const avatarHeader = createCardHeader({
- *   title: 'User Profile',
- *   avatar: '<img src="user.jpg" alt="User avatar">',
- *   action: createIconButton({ icon: 'more_vert' })
- * });
- * ```
- */
 export declare const createCardHeader: (config?: CardHeaderConfig) => HTMLElement;
-/**
- * Creates a card actions component
- *
- * @param {CardActionsConfig} config - Actions configuration
- * @returns {HTMLElement} Card actions element
- *
- * @example
- * ```typescript
- * // Create simple actions container with buttons
- * const actions = createCardActions({
- *   actions: [
- *     createButton({ text: 'Cancel' }),
- *     createButton({ text: 'OK', variant: 'filled' })
- *   ],
- *   align: 'end'
- * });
- *
- * // Create full-bleed actions
- * const fullBleedActions = createCardActions({
- *   actions: [createButton({ text: 'View Details', fullWidth: true })],
- *   fullBleed: true
- * });
- * ```
- */
 export declare const createCardActions: (config?: CardActionsConfig) => HTMLElement;
-/**
- * Creates a card media component
- *
- * @param {CardMediaConfig} config - Media configuration
- * @returns {HTMLElement} Card media element
- *
- * @example
- * ```typescript
- * // Create a media component with an image
- * const media = createCardMedia({
- *   src: 'image.jpg',
- *   alt: 'Descriptive alt text',
- *   aspectRatio: '16:9'
- * });
- *
- * // Create a media component with a custom element
- * const customMedia = createCardMedia({
- *   element: videoElement,
- *   aspectRatio: '4:3'
- * });
- * ```
- */
 export declare const createCardMedia: (config?: CardMediaConfig) => HTMLElement;

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

@@ -1,69 +1,3 @@
-/**
- * @module Card
- *
- * Card component following Material Design 3 guidelines.
- * Cards are surfaces that display content and actions about a single topic.
- * They should be easy to scan for relevant and actionable information.
- *
- * The main export is the {@link default | createCard} factory function that creates
- * a {@link CardComponent} instance with the provided configuration.
- *
- * Features:
- * - Multiple variants: elevated, filled, and outlined
- * - Support for header, content, media, and actions sections
- * - Interactive behavior with elevation changes on hover
- * - Draggable capability
- * - Expandable content support
- * - Loading state indication
- * - Swipe gestures with custom actions
- *
- * The API includes methods for:
- * - {@link CardComponent.addContent | Adding content}
- * - {@link CardComponent.setHeader | Setting header}
- * - {@link CardComponent.addMedia | Adding media}
- * - {@link CardComponent.setActions | Setting actions}
- * - {@link CardComponent.makeDraggable | Making cards draggable}
- * - {@link CardComponent.focus | Managing focus}
- *
- * @example
- * ```typescript
- * // Create a basic card
- * const card = createCard({
- *   variant: 'elevated',
- *   header: {
- *     title: 'Card Title',
- *     subtitle: 'Secondary text'
- *   },
- *   content: {
- *     text: 'Card content goes here.'
- *   },
- *   buttons: [
- *     { text: 'Action', variant: 'text' }
- *   ]
- * });
- *
- * // Modify card programmatically using API methods
- * const image = document.createElement('div');
- * image.className = 'mtrl-card__media';
- * image.style.backgroundImage = 'url(path/to/image.jpg)';
- *
- * card.addMedia(image, 'top')
- *     .makeDraggable((event) => {
- *       console.log('Card drag started');
- *     });
- * ```
- *
- * @category Components
- */
-/**
- * Factory function to create a new Card component.
- * @see CardComponent for the full API reference
- */
 export { default, default as createCard } from "./card.js";
-/**
- * Card component types and interfaces
- *
- * These types define the structure and behavior of the Card component.
- */
 export type { CardVariant, CardElevationLevel, CardConfig, CardHeaderConfig, CardContentConfig, CardActionsConfig, CardMediaConfig, CardAriaAttributes, CardComponent, CardEvents, } from "./types.js";
 export { createCardContent, createCardHeader, createCardActions, createCardMedia, } from "./content.js";