material 3.2.6 → 3.3.0

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

@@ -1,452 +1,105 @@
 import { BaseComponentConfig } from "../../core/config/component.js";
 import { ProgressConfig, ProgressComponent } from "../progress/types.js";
 import { ButtonSize, ButtonShape } from "./constants.js";
-/**
- * Button variant types - controls the visual style of the button
- * @category Components
- * @remarks
- * - filled: Primary action button with solid background (high emphasis)
- * - tonal: Secondary action button with medium emphasis
- * - outlined: Button with outline border and transparent background
- * - elevated: Button with slight elevation/shadow
- * - text: Button that appears as text without background or border (low emphasis)
- */
 export type ButtonVariant = "filled" | "tonal" | "outlined" | "elevated" | "text";
-/**
- * Configuration interface for the Button component
- * @category Components
- */
 export interface ButtonConfig extends BaseComponentConfig {
-    /**
-     * Button variant that determines visual styling
-     * @default 'filled'
-     */
     variant?: ButtonVariant | string;
-    /**
-     * Button size variant
-     * @default 's'
-     */
     size?: ButtonSize | string;
-    /**
-     * Button shape variant
-     * @default 'round'
-     */
     shape?: ButtonShape | string;
-    /**
-     * Whether the button is initially disabled
-     * @default false
-     */
     disabled?: boolean;
-    /**
-     * Initial button text content, or a node placed where the text goes (the
-     * web component passes a `<slot>` so the page's content is the label)
-     * @example 'Submit'
-     */
     text?: string | Node;
-    /**
-     * Initial button icon HTML content.
-     * Markup (HTML). Not sanitized by default: see Markup and sanitizing.
-     * @example '<svg>...</svg>'
-     */
     icon?: string;
-    /**
-     * Icon size in pixels or other CSS units
-     * @example '18px'
-     */
     iconSize?: string;
-    /**
-     * Additional CSS classes to add to the button
-     * @example 'form-submit header-action'
-     */
     class?: string;
-    /**
-     * Button value attribute
-     */
     value?: string;
-    /**
-     * Button type attribute
-     * @default 'button'
-     */
     type?: "button" | "submit" | "reset";
-    /**
-     * Whether to enable ripple effect
-     * @default true
-     */
     ripple?: boolean;
-    /**
-     * Component prefix for class names
-     * @default 'mtrl'
-     */
     prefix?: string;
-    /**
-     * Component name used in class generation
-     */
     componentName?: string;
-    /**
-     * Ripple effect configuration
-     */
     rippleConfig?: {
-        /** How long, in milliseconds, a released wave lingers before it is removed */
         duration?: number;
     };
-    /**
-     * Accessible name for the button (aria-label)
-     * Required for icon-only buttons without text
-     */
     ariaLabel?: string;
-    /**
-     * Progress indicator configuration
-     * When provided, integrates a progress component as the button's icon
-     */
     progress?: ProgressConfig | boolean;
-    /**
-     * Whether to show progress initially
-     * @default false
-     */
     showProgress?: boolean;
-    /**
-     * Makes the button a toggle button: a click flips its selected state,
-     * the element carries aria-pressed, and the selected state uses the M3
-     * toggle colours and swaps the resting shape (round to square, square
-     * to round). Text buttons have no toggle style.
-     * @default false
-     */
     toggle?: boolean;
-    /**
-     * Initial selected state of a toggle button
-     * @default false
-     */
     selected?: boolean;
-    /**
-     * Whether a click flips the selected state of a toggle button. Set to
-     * false when a container (button group) owns the selection.
-     * @default true
-     */
     toggleOnClick?: boolean;
 }
-/**
- * Icon API interface for managing button icons
- * @category Components
- */
 export interface IconAPI {
-    /**
-     * Sets the icon HTML content
-     * @param html - HTML string for the icon
-     * @returns The icon API for chaining
-     */
     setIcon: (html: string) => IconAPI;
-    /**
-     * Gets the current icon HTML content
-     * @returns HTML string for the icon
-     */
     getIcon: () => string;
-    /**
-     * Gets the icon DOM element
-     * @returns The icon element or null if not present
-     */
     getElement: () => HTMLElement | null;
 }
-/**
- * Text API interface for managing button text
- * @category Components
- */
 export interface TextAPI {
-    /**
-     * Sets the text content
-     * @param content - Text content
-     * @returns The text API for chaining
-     */
     setText: (content: string) => TextAPI;
-    /**
-     * Gets the current text content
-     * @returns Button text content
-     */
     getText: () => string;
-    /**
-     * Gets the text DOM element
-     * @returns The text element or null if not present
-     */
     getElement: () => HTMLElement | null;
 }
-/**
- * Button component interface
- * @category Components
- */
-/**
- * What a forwarded DOM event hands a button listener.
- *
- * The button does not emit events of its own: `click`, `focus` and `blur` are
- * native events forwarded from its element by `forwardEvents` in config.ts,
- * and the forwarder wraps each one in this shape.
- */
 export interface ButtonEventPayload<E extends Event = Event> {
-    /** The DOM event that triggered the forward. */
     event: E;
-    /** The button's root element, which is the element listened on. */
     element: HTMLElement;
-    /** The same DOM event as `event`; both names have always been provided. */
     originalEvent: E;
 }
-/** A toggle button's `change`. */
 export interface ButtonChangePayload {
-    /** Whether the button is now selected */
     selected: boolean;
-    /** The button's value, as `getValue()` returns it */
     value: string;
 }
-/**
- * The events a button reports, and what each hands its handler.
- *
- * `on` and `off` are generic over these keys, so a misspelled event name is a
- * compile error rather than a listener that never fires, and a handler's
- * payload is typed rather than `any`.
- *
- * Native forwarding and toggle selection are reported here. `mount` and `unmount` are *not* here: the lifecycle
- * feature keeps its own emitter and exposes them as `lifecycle.onMount` and
- * `lifecycle.onUnmount`, so they never reach `component.on`.
- */
 export interface ButtonEvents {
-    /**
-     * A toggle button's selected state changed on a click. `value` is the
-     * button's value (`getValue()`), as every model event carries;
-     * `selected` is the toggled state.
-     */
     change: (payload: ButtonChangePayload) => void;
-    /** The button was clicked. Not forwarded while the button is disabled. */
     click: (payload: ButtonEventPayload<MouseEvent>) => void;
-    /** The button took focus. */
     focus: (payload: ButtonEventPayload<FocusEvent>) => void;
-    /** The button lost focus. */
     blur: (payload: ButtonEventPayload<FocusEvent>) => void;
 }
 export interface ButtonComponent {
-    /** The button's DOM element */
     element: HTMLButtonElement;
-    /** API for managing button text */
     text: TextAPI;
-    /** API for managing button icons */
     icon: IconAPI;
-    /** API for managing disabled state */
     disabled: {
-        /** Enables the button */
         enable: () => void;
-        /** Disables the button */
         disable: () => void;
-        /** Checks if the button is disabled */
         isDisabled: () => boolean;
     };
-    /** API for managing component lifecycle */
     lifecycle: {
-        /** Destroys the component and cleans up resources */
         destroy: () => void;
     };
-    /**
-     * Gets a class name with the component's prefix
-     * @param name - Base class name
-     * @returns Prefixed class name
-     */
     getClass: (name: string) => string;
-    /**
-     * Gets the button's value attribute
-     * @returns Button value
-     */
     getValue: () => string;
-    /**
-     * Sets the button's value attribute
-     * @param value - New value
-     * @returns The button component for chaining
-     */
     setValue: (value: string) => ButtonComponent;
-    /**
-     * Gets the button's current variant
-     * @returns Current variant name ('filled', 'outlined', etc.)
-     */
     getVariant: () => ButtonVariant | string;
-    /**
-     * Sets the button's variant (visual style)
-     * @param variant - New variant to apply ('filled', 'outlined', 'text', etc.)
-     * @returns The button component for chaining
-     */
     setVariant: (variant: ButtonVariant | string) => ButtonComponent;
-    /**
-     * Gets the button's current size
-     * @returns Current size name ('xs', 's', 'm', 'l', 'xl')
-     */
     getSize: () => ButtonSize | string;
-    /**
-     * Sets the button's size
-     * @param size - New size to apply ('xs', 's', 'm', 'l', 'xl')
-     * @returns The button component for chaining
-     */
     setSize: (size: ButtonSize | string) => ButtonComponent;
-    /**
-     * Gets the button's current shape
-     * @returns Current shape name ('round', 'square')
-     */
     getShape: () => ButtonShape | string;
-    /**
-     * Sets the button's shape
-     * @param shape - New shape to apply ('round', 'square')
-     * @returns The button component for chaining
-     */
     setShape: (shape: ButtonShape | string) => ButtonComponent;
-    /**
-     * Enables the button (removes disabled attribute)
-     * @returns The button component for chaining
-     */
     enable: () => ButtonComponent;
-    /**
-     * Disables the button (adds disabled attribute)
-     * @returns The button component for chaining
-     */
     disable: () => ButtonComponent;
-    /** Whether the button is disabled */
     isDisabled: () => boolean;
-    /**
-     * Sets the button's text content
-     * @param content - Text content
-     * @returns The button component for chaining
-     */
     setText: (content: string) => ButtonComponent;
-    /**
-     * Gets the button's text content
-     * @returns Button text content
-     */
     getText: () => string;
-    /**
-     * Checks if the button has an icon
-     * @returns True if the button has an icon, false otherwise
-     */
     hasIcon: () => boolean;
-    /**
-     * Sets the button's icon
-     * If empty string is provided, removes the icon completely
-     * @param icon - Icon HTML content, or empty string to remove
-     * @returns The button component for chaining
-     */
     setIcon: (icon: string) => ButtonComponent;
-    /**
-     * Gets the button's icon HTML content
-     * @returns Icon HTML
-     */
     getIcon: () => string;
-    /**
-     * Destroys the button component and cleans up resources
-     */
     destroy: () => void;
-    /**
-     * Sets the active state of the button
-     * Used to visually indicate the button's active state, such as when it has a menu open
-     *
-     * @param active - Whether the button should appear active
-     * @returns The button component for chaining
-     */
     setActive: (active: boolean) => ButtonComponent;
-    /**
-     * Sets the selected state of a toggle button (no-op unless `toggle` is set)
-     * @param selected - Whether the button is selected
-     * @returns The button component for chaining
-     */
     setSelected: (selected: boolean) => ButtonComponent;
-    /**
-     * Whether a toggle button is selected
-     * @returns true when selected, false otherwise or when not a toggle button
-     */
     isSelected: () => boolean;
-    /**
-     * Adds an event listener to the button
-     * @param event - One of the events in {@link ButtonEvents}
-     * @param handler - Receives the payload declared for that event
-     * @returns The button component for chaining
-     */
     on: <K extends keyof ButtonEvents>(event: K, handler: ButtonEvents[K]) => ButtonComponent;
-    /**
-     * Removes an event listener from the button
-     * @param event - One of the events in {@link ButtonEvents}
-     * @param handler - The same handler that was passed to `on`
-     * @returns The button component for chaining
-     */
     off: <K extends keyof ButtonEvents>(event: K, handler: ButtonEvents[K]) => ButtonComponent;
-    /**
-     * Adds CSS classes to the button element
-     * @param classes - One or more class names to add
-     * @returns The button component for chaining
-     */
     addClass: (...classes: string[]) => ButtonComponent;
-    /**
-     * Sets the aria-label attribute for accessibility
-     * @param label - Aria label text
-     * @returns The button component for chaining
-     */
     setAriaLabel: (label: string) => ButtonComponent;
-    /**
-     * Progress component instance (if progress is enabled)
-     */
     progress?: ProgressComponent;
-    /**
-     * Shows the progress indicator (if progress is enabled)
-     * @returns The button component for chaining
-     */
     showProgress?: () => Promise<ButtonComponent>;
-    /**
-     * Shows the progress indicator synchronously (if progress is enabled)
-     * @returns The button component for chaining
-     */
     showProgressSync?: () => ButtonComponent;
-    /**
-     * Hides the progress indicator (if progress is enabled)
-     * @returns The button component for chaining
-     */
     hideProgress?: () => Promise<ButtonComponent>;
-    /**
-     * Hides the progress indicator synchronously (if progress is enabled)
-     * @returns The button component for chaining
-     */
     hideProgressSync?: () => ButtonComponent;
-    /**
-     * Sets the progress value (0-100) (if progress is enabled)
-     * @param value - Progress value
-     * @returns The button component for chaining
-     */
     setProgress?: (value: number) => Promise<ButtonComponent>;
-    /**
-     * Sets the progress value synchronously (0-100) (if progress is enabled)
-     * @param value - Progress value
-     * @returns The button component for chaining
-     */
     setProgressSync?: (value: number) => ButtonComponent;
-    /**
-     * Sets the progress to indeterminate mode (if progress is enabled)
-     * @param indeterminate - Whether progress should be indeterminate
-     * @returns The button component for chaining
-     */
     setIndeterminate?: (indeterminate: boolean) => Promise<ButtonComponent>;
-    /**
-     * Sets the progress to indeterminate mode synchronously (if progress is enabled)
-     * @param indeterminate - Whether progress should be indeterminate
-     * @returns The button component for chaining
-     */
     setIndeterminateSync?: (indeterminate: boolean) => ButtonComponent;
-    /**
-     * Updates both button text and progress for loading states (if progress is enabled)
-     * @param loading - Whether to show loading state
-     * @param text - Optional text to display while loading
-     * @returns The button component for chaining
-     */
     setLoading?: (loading: boolean, text?: string) => Promise<ButtonComponent>;
-    /**
-     * Updates both button text and progress for loading states synchronously (if progress is enabled)
-     * @param loading - Whether to show loading state
-     * @param text - Optional text to display while loading
-     * @returns The button component for chaining
-     */
     setLoadingSync?: (loading: boolean, text?: string) => ButtonComponent;
 }
-/**
- * Registers ButtonConfig with the global defaults map, so
- * `setComponentDefaults("button", ...)` is typed without core
- * importing anything from this component.
- */
 declare module "../../core/config/global" {
     interface ComponentConfigMap {
         button?: Partial<ButtonConfig>;

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

@@ -1,54 +1,3 @@
 import { ButtonGroupConfig, ButtonGroupComponent } from "./types.js";
-/**
- * Creates a new Button Group component
- *
- * The Button Group component provides a container for grouping related action buttons.
- * A standard group holds related actions, each button acting on its own; a
- * connected group (`kind: "connected"`, with `selection`) is M3's replacement for
- * the segmented button, which material 3.0.0 removed.
- *
- * Per Material Design 3 specifications:
- * - Standard groups space their buttons (18/12/8/8/8dp by size) and a
- *   pressed button briefly widens while its neighbours narrow
- * - Connected groups space their buttons 2dp apart with square inner
- *   corners and round outer corners; a selected button becomes a pill
- * - All buttons share the same variant, size and shape
- * - Supports horizontal and vertical orientations
- * - Supports density scaling (4dp per step)
- *
- * @param {ButtonGroupConfig} config - Button Group configuration
- * @returns {ButtonGroupComponent} Button Group component instance
- *
- * @example
- * // Create a horizontal button group for text formatting
- * const formattingTools = createButtonGroup({
- *   buttons: [
- *     { icon: boldIcon, ariaLabel: 'Bold' },
- *     { icon: italicIcon, ariaLabel: 'Italic' },
- *     { icon: underlineIcon, ariaLabel: 'Underline' }
- *   ],
- *   variant: 'outlined',
- *   ariaLabel: 'Text formatting options'
- * });
- *
- * // Listen for button clicks
- * formattingTools.on('click', (event) => {
- *   console.log('Button clicked:', event.index);
- * });
- *
- * @example
- * // Create a vertical button group with text labels
- * const navigationGroup = createButtonGroup({
- *   buttons: [
- *     { text: 'Previous', icon: prevIcon },
- *     { text: 'Play', icon: playIcon },
- *     { text: 'Next', icon: nextIcon }
- *   ],
- *   orientation: 'vertical',
- *   variant: 'tonal'
- * });
- *
- * @category Components
- */
 declare const createButtonGroup: (config?: ButtonGroupConfig) => ButtonGroupComponent;
 export default createButtonGroup;

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

@@ -1,59 +1,29 @@
-/**
- * Button group variants
- * All buttons in the group share the same variant for visual consistency
- */
 export declare const BUTTON_GROUP_VARIANTS: {
-    /** Primary action buttons with solid background */
     readonly FILLED: "filled";
-    /** Secondary action buttons with medium emphasis */
     readonly TONAL: "tonal";
-    /** Buttons with outline border (default for button groups per MD3) */
     readonly OUTLINED: "outlined";
-    /** Buttons with slight elevation/shadow */
     readonly ELEVATED: "elevated";
-    /** Text-only buttons without background or border */
     readonly TEXT: "text";
 };
-/**
- * Button group orientations
- */
 export declare const BUTTON_GROUP_ORIENTATIONS: {
-    /** Buttons arranged horizontally (default) */
     readonly HORIZONTAL: "horizontal";
-    /** Buttons arranged vertically */
     readonly VERTICAL: "vertical";
 };
-/**
- * Density levels for button groups
- * Controls sizing and spacing per MD3 density specifications
- */
 export declare const BUTTON_GROUP_DENSITY: {
-    /** Default size with standard spacing (40px height) */
     readonly DEFAULT: "default";
-    /** Reduced size and spacing (36px height) */
     readonly COMFORTABLE: "comfortable";
-    /** Minimal size and spacing (32px height) */
     readonly COMPACT: "compact";
 };
-/**
- * Button group events
- */
 export declare const BUTTON_GROUP_EVENTS: {
-    /** Fired when any button in the group is clicked */
     readonly CLICK: "click";
-    /** Fired when a button receives focus */
     readonly FOCUS: "focus";
-    /** Fired when a button loses focus */
     readonly BLUR: "blur";
-    /** Fired when the selection changes (selection groups) */
     readonly CHANGE: "change";
 };
-/** Material 3 button group kinds */
 export declare const BUTTON_GROUP_KINDS: {
     readonly STANDARD: "standard";
     readonly CONNECTED: "connected";
 };
-/** Selection behaviour of the group */
 export declare const BUTTON_GROUP_SELECTION: {
     readonly NONE: "none";
     readonly SINGLE: "single";
@@ -70,12 +40,6 @@ export declare const BUTTON_GROUP_SIZES: {
     readonly L: "l";
     readonly XL: "xl";
 };
-/**
- * Material 3 button group tokens per size (dp): container height, button
- * icon size, standard between-space, connected inner corner and its shape
- * scale step (m3.material.io button group specs; ButtonGroupSmallTokens.kt and
- * ConnectedButtonGroupSmallTokens.kt for the s size)
- */
 export declare const BUTTON_GROUP_SIZE_TOKENS: {
     readonly xs: {
         readonly height: 32;
@@ -113,31 +77,12 @@ export declare const BUTTON_GROUP_SIZE_TOKENS: {
         readonly connectedStep: "large-increased";
     };
 };
-/** Connected groups use 2dp between buttons at every size */
 export declare const BUTTON_GROUP_CONNECTED_GAP = 2;
-/** Connected pressed inner corner: extra-small (ConnectedButtonGroupSmallTokens.PressedInnerCornerCornerSize) */
 export declare const BUTTON_GROUP_CONNECTED_PRESSED_CORNER = 4;
-/** Connected xs and s groups keep a 48dp minimum width per button */
 export declare const BUTTON_GROUP_CONNECTED_MIN_WIDTH = 48;
-/**
- * Standard groups: a pressed button widens by this share of its width and
- * its neighbours give up the difference (ButtonGroupDefaults.ExpandedRatio)
- */
 export declare const BUTTON_GROUP_EXPANDED_RATIO = 0.15;
-/**
- * The most a neighbour gives up when a button in a standard group is pressed:
- * the trailing content padding of a button (Compose ButtonGroup compression
- * limit, ButtonDefaults.ContentPadding end, BaselineButtonTokens.TrailingSpace).
- * It applies to every neighbour, so an icon button with no padding still makes
- * room for the pressed button.
- */
 export declare const BUTTON_GROUP_COMPRESSION_LIMIT = 24;
-/** Density reduces the container height by 4dp per step */
 export declare const BUTTON_GROUP_DENSITY_STEP = 4;
-/**
- * Default configuration values
- */
-/** Label display in selection groups */
 export declare const BUTTON_GROUP_LABELS: {
     readonly ALWAYS: "always";
     readonly SELECTED: "selected";
@@ -148,58 +93,30 @@ export declare const BUTTON_GROUP_DEFAULTS: {
     readonly SHAPE: "round";
     readonly SIZE: "s";
     readonly LABELS: "always";
-    /** Default variant (outlined per MD3 button group specs) */
     readonly VARIANT: "outlined";
-    /** Default orientation */
     readonly ORIENTATION: "horizontal";
-    /** Default density level */
     readonly DENSITY: "default";
-    /** Whether ripple effect is enabled by default */
     readonly RIPPLE: true;
-    /** Whether buttons have equal width by default */
     readonly EQUAL_WIDTH: false;
-    /** Default ripple animation duration in milliseconds */
     readonly RIPPLE_DURATION: 300;
 };
-/**
- * CSS classes for button group elements
- * Following BEM naming convention
- */
 export declare const BUTTON_GROUP_CLASSES: {
-    /** Container element */
     readonly ROOT: "button-group";
-    /** Individual button within group */
     readonly BUTTON: "button-group__button";
-    /** First button in group */
     readonly FIRST: "button-group__button--first";
-    /** Last button in group */
     readonly LAST: "button-group__button--last";
-    /** Middle buttons (neither first nor last) */
     readonly MIDDLE: "button-group__button--middle";
-    /** Single button (only one in group) */
     readonly SINGLE: "button-group__button--single";
-    /** Disabled state */
     readonly DISABLED: "button-group--disabled";
-    /** Horizontal orientation */
     readonly HORIZONTAL: "button-group--horizontal";
-    /** Vertical orientation */
     readonly VERTICAL: "button-group--vertical";
-    /** Equal width buttons */
     readonly EQUAL_WIDTH: "button-group--equal-width";
-    /** Filled variant */
     readonly FILLED: "button-group--filled";
-    /** Tonal variant */
     readonly TONAL: "button-group--tonal";
-    /** Outlined variant */
     readonly OUTLINED: "button-group--outlined";
-    /** Elevated variant */
     readonly ELEVATED: "button-group--elevated";
-    /** Text variant */
     readonly TEXT: "button-group--text";
-    /** Default density */
     readonly DENSITY_DEFAULT: "button-group--density-default";
-    /** Comfortable density */
     readonly DENSITY_COMFORTABLE: "button-group--density-comfortable";
-    /** Compact density */
     readonly DENSITY_COMPACT: "button-group--density-compact";
 };

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

@@ -1,13 +1,3 @@
-/**
- * Button Group component exports
- *
- * The Button Group component provides a container for grouping related action buttons.
- * A standard group holds related actions, each button acting on its own; a
- * connected group (`kind: "connected"`, with `selection`) is M3's replacement for
- * the segmented button, which material 3.0.0 removed.
- *
- * @packageDocumentation
- */
 export { default as createButtonGroup } from "./button-group.js";
 export { default } from "./button-group.js";
 export type { ButtonGroupConfig, ButtonGroupComponent, ButtonGroupItemConfig, ButtonGroupEvent, ButtonGroupEventType, ButtonGroupVariant, ButtonGroupOrientation, ButtonGroupDensity } from "./types.js";