material 3.2.6 → 3.2.7

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

@@ -1,301 +1,102 @@
 import type { TouchEvents } from "../../core/utils/mobile.js";
 import type { ButtonConfig as BaseButtonConfig } from "../button/types.js";
 import type { ForwardedEventPayload } from "../../core/dom/index.js";
-/**
- * Card variant types 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
- *
- * @category Components
- */
 export type CardVariant = 'elevated' | 'filled' | 'outlined';
-/**
- * Card elevation levels in Material Design 3.
- * Specifies the shadow height in density-independent pixels (dp).
- * These values match the CARD_ELEVATION_LEVELS constants.
- *
- * @category Components
- */
 export type CardElevationLevel = 0 | 1 | 2 | 4;
-/**
- * Button configuration interface for buttons shorthand.
- * Used in the card's `buttons` configuration property for simple button creation.
- *
- * @interface ButtonConfig
- * @category Components
- */
 export interface ButtonConfig extends Omit<BaseButtonConfig, "variant"> {
-    /** Button text content */
     text?: string;
-    /** Button variant (text, outlined, filled, etc.) */
     variant?: string;
-    /** Button icon HTML content */
     icon?: string;
 }
-/**
- * Card configuration interface defining all possible card options.
- * This is the primary configuration interface for creating card components.
- *
- * @interface CardConfig
- * @category Components
- * @example
- * ```typescript
- * const cardConfig: CardConfig = {
- *   variant: 'elevated',
- *   interactive: true,
- *   header: {
- *     title: 'Card Title',
- *     subtitle: 'Secondary text'
- *   },
- *   content: {
- *     text: 'Card content text'
- *   },
- *   buttons: [
- *     { text: 'Action', variant: 'text' }
- *   ]
- * };
- * ```
- */
 export interface CardConfig {
-    /** Card variant type (elevated, filled, outlined) */
     variant?: CardVariant | string;
-    /**
-     * The hover and press states and their elevation, for a card the app
-     * makes interactive itself. Not a control: no role of button and no tab
-     * stop; `clickable` is.
-     */
     interactive?: boolean;
-    /** Whether the card should take full width */
     fullWidth?: boolean;
-    /**
-     * A card that acts on activation: a button (role, tab stop, Enter and
-     * Space click it) with the ripple
-     */
     clickable?: boolean;
-    /** Whether the card is draggable */
     draggable?: boolean;
-    /** Additional CSS class(es) */
     class?: string;
-    /** Header configuration */
     headerConfig?: CardHeaderConfig;
-    /** Content configuration */
     contentConfig?: CardContentConfig;
-    /** Actions configuration */
     actionsConfig?: CardActionsConfig;
-    /** Media configuration */
     mediaConfig?: CardMediaConfig;
-    /** ARIA attributes for accessibility */
     aria?: CardAriaAttributes;
-    /** Inline header configuration (alternative to headerConfig) */
     header?: CardHeaderConfig;
-    /** Inline content configuration (alternative to contentConfig) */
     content?: CardContentConfig;
-    /** Inline media configuration (alternative to mediaConfig) */
     media?: CardMediaConfig;
-    /** Inline actions configuration (alternative to actionsConfig) */
     actions?: CardActionsConfig;
-    /** Simple buttons array for actions (will be converted to actionsConfig) */
     buttons?: ButtonConfig[];
-    /** Internal component name */
     componentName?: string;
-    /** CSS class prefix */
     prefix?: string;
-    /** Callback executed after component creation */
     afterCreation?: (component: BaseComponent) => void;
 }
-/**
- * ARIA attributes for card accessibility.
- * These attributes enhance the card's accessibility for assistive technologies.
- *
- * @interface CardAriaAttributes
- * @category Components
- */
 export interface CardAriaAttributes {
-    /** ARIA label */
     label?: string;
-    /** ARIA labelledby */
     labelledby?: string;
-    /** ARIA describedby */
     describedby?: string;
-    /** ARIA role (default: 'button' for a clickable card, 'article' for any other) */
     role?: string;
-    /** Additional ARIA attributes as key-value pairs */
     [key: string]: string | undefined;
 }
-/**
- * Card header configuration.
- * Options for configuring the card's header section with title, subtitle, and actions.
- *
- * @interface CardHeaderConfig
- * @category Components
- */
 export interface CardHeaderConfig {
-    /** Header title text */
     title?: string;
-    /** Header subtitle text */
     subtitle?: string;
-    /** Avatar element or HTML string */
     avatar?: HTMLElement | string;
-    /** Action element or HTML string */
     action?: HTMLElement | string;
-    /** Additional CSS class(es) */
     class?: string;
 }
-/**
- * Card content configuration.
- * Options for configuring the card's main content area.
- *
- * @interface CardContentConfig
- * @category Components
- */
 export interface CardContentConfig {
-    /** Text content */
     text?: string;
-    /** HTML content */
     html?: string;
-    /** Child elements */
     children?: HTMLElement[];
-    /** Whether to add padding (true by default) */
     padding?: boolean;
-    /** Additional CSS class(es) */
     class?: string;
 }
-/**
- * Card actions configuration.
- * Options for configuring the card's action buttons area at the bottom.
- *
- * @interface CardActionsConfig
- * @category Components
- */
 export interface CardActionsConfig {
-    /** Action elements */
     actions?: HTMLElement[];
-    /** Whether actions should be full-bleed */
     fullBleed?: boolean;
-    /** Whether actions should be stacked vertically */
     vertical?: boolean;
-    /** Horizontal alignment */
     align?: 'start' | 'center' | 'end' | 'space-between';
-    /** Additional CSS class(es) */
     class?: string;
 }
-/**
- * Card media configuration.
- * Options for configuring the card's media section (images or other media content).
- *
- * @interface CardMediaConfig
- * @category Components
- */
 export interface CardMediaConfig {
-    /** Image source URL */
     src?: string;
-    /** Image alt text (required for accessibility) */
     alt?: string;
-    /** Custom element instead of image */
     element?: HTMLElement;
-    /** Aspect ratio */
     aspectRatio?: '16:9' | '4:3' | '1:1' | string;
-    /** Whether media should use object-fit: contain */
     contain?: boolean;
-    /** Additional CSS class(es) */
     class?: string;
-    /**
-     * Position of the media in the card
-     * - 'top': Media appears at the top of the card (default)
-     * - 'bottom': Media appears after the content
-     */
     position?: 'top' | 'bottom';
 }
-/**
- * Base component interface.
- * Core interface that all components extend with basic functionality.
- *
- * @interface BaseComponent
- * @category Components
- */
 export interface BaseComponent {
-    /** The DOM element */
     element: HTMLElement;
-    /** Get class name with prefix */
     getClass: (name: string) => string;
-    /** Get modifier class */
     getModifierClass: (base: string, modifier: string) => string;
-    /** Get element class */
     getElementClass: (base: string, element: string) => string;
-    /** Add CSS class(es) */
     addClass: (...classes: string[]) => BaseComponent;
-    /**
-     * Emit one of the card's own events ({@link CardEvents}), with its payload:
-     * the names and payloads `on` and `off` accept.
-     */
     emit?: <K extends keyof CardEvents>(event: K, payload: Parameters<CardEvents[K]>[0]) => void;
-    /** Component configuration */
     config: CardComponentConfig;
-    /** Touch state for touch interactions */
     touchState?: TouchState;
-    /** Update touch state */
     updateTouchState?: (event: TouchEvent | MouseEvent, status: 'start' | 'end') => void;
-    /** Component lifecycle methods */
     lifecycle?: ComponentLifecycle;
 }
-/**
- * Touch state interface for touch interactions.
- * Used to track touch events for interactive components.
- *
- * @interface TouchState
- * @category Components
- */
 export interface TouchState {
-    /** Timestamp when touch started */
     startTime: number;
-    /** Starting position */
     startPosition: {
         x: number;
         y: number;
     };
-    /** Whether touch is active */
     isTouching: boolean;
-    /** Current touch target */
     activeTarget: EventTarget | null;
 }
-/**
- * Component lifecycle interface.
- * Defines the lifecycle hooks for component creation, updates, and destruction.
- *
- * @interface ComponentLifecycle
- * @category Components
- */
 export interface ComponentLifecycle {
-    /** Called when component is mounted to DOM */
     mount?: () => void;
-    /** Called when component is updated */
     update?: () => void;
-    /** Called when component is destroyed */
     destroy: () => void;
 }
-/**
- * Card component configuration.
- * Internal configuration object that extends the user-provided schema
- * with additional required properties.
- *
- * @interface CardComponentConfig
- * @extends CardConfig
- * @category Components
- */
 export interface CardComponentConfig extends CardConfig {
-    /** Component name */
     componentName: string;
-    /** CSS class prefix */
     prefix: string;
 }
-/**
- * The card's events. A clickable card forwards `click`; an
- * interactive one `mouseenter`, `mouseleave`, `keydown`, `focus` and `blur`;
- * a draggable one emits `dragstart` and `dragend`.
- */
 export interface CardEvents extends TouchEvents {
-    /** Presentation state after expanding or collapsing. */
     expandedChanged: (payload: {
         expanded: boolean;
     }) => void;
@@ -312,202 +113,35 @@ export interface CardEvents extends TouchEvents {
         event: DragEvent;
     }) => void;
 }
-/**
- * Card component interface with methods.
- * This is the public API of the card component that users interact with.
- *
- * @interface CardComponent
- * @extends BaseComponent
- * @category Components
- */
 export interface CardComponent extends BaseComponent {
-    /** Subscribes to one of the card's events */
     on: <K extends keyof CardEvents>(event: K, handler: CardEvents[K]) => CardComponent;
-    /** Removes a handler added with `on` */
     off: <K extends keyof CardEvents>(event: K, handler: CardEvents[K]) => CardComponent;
-    /**
-     * Adds content to the card.
-     * This method appends content to the card component.
-     *
-     * @param contentElement - The content element to add
-     * @returns The card instance for chaining
-     * @example
-     * ```typescript
-     * const content = document.createElement('div');
-     * content.className = 'mtrl-card__content';
-     * content.textContent = 'Card content goes here';
-     * card.addContent(content);
-     * ```
-     */
     addContent: (contentElement: HTMLElement) => CardComponent;
-    /**
-     * Sets the card header.
-     * Places the header element in the card. When media elements exist,
-     * the header is placed after the last media element to ensure proper
-     * visual hierarchy following Material Design guidelines.
-     *
-     * @param headerElement - The header element to add
-     * @returns The card instance for chaining
-     * @example
-     * ```typescript
-     * // Add a header after media
-     * card.setHeader(headerElement);
-     * ```
-     */
     setHeader: (headerElement: HTMLElement) => CardComponent;
-    /**
-     * Adds media to the card.
-     * Places media elements at the specified position in the card.
-     *
-     * @param mediaElement - The media element to add
-     * @param position - Position to place media ('top', 'bottom')
-     * @returns The card instance for chaining
-     * @example
-     * ```typescript
-     * // Creating media element
-     * const media = document.createElement('div');
-     * media.className = 'mtrl-card__media';
-     *
-     * // Adding at the top (default)
-     * card.addMedia(media);
-     *
-     * // Or adding at the bottom
-     * card.addMedia(media, 'bottom');
-     * ```
-     */
     addMedia: (mediaElement: HTMLElement, position?: 'top' | 'bottom') => CardComponent;
-    /**
-     * Sets the card actions section.
-     * Replaces any existing actions with the provided actions element.
-     * Actions typically contain buttons or other interactive controls,
-     * and are placed at the bottom of the card.
-     *
-     * @param actionsElement - The actions element to add
-     * @returns The card instance for chaining
-     * @example
-     * ```typescript
-     * // Create actions container
-     * const actions = document.createElement('div');
-     * actions.className = 'mtrl-card__actions';
-     *
-     * // Add buttons to actions
-     * const button = document.createElement('button');
-     * button.textContent = 'Action';
-     * actions.appendChild(button);
-     *
-     * // Set actions on card
-     * card.setActions(actions);
-     * ```
-     */
     setActions: (actionsElement: HTMLElement) => CardComponent;
-    /**
-     * Makes the card draggable.
-     * Sets up native HTML5 drag and drop functionality and adds appropriate
-     * accessibility attributes. Automatically updates ARIA attributes during drag.
-     *
-     * @param dragStartCallback - Callback for drag start event
-     * @returns The card instance for chaining
-     * @example
-     * ```typescript
-     * // Basic draggable card
-     * card.makeDraggable();
-     *
-     * // With custom drag start handler
-     * card.makeDraggable((event) => {
-     *   // Set custom data or perform other actions on drag start
-     *   event.dataTransfer.setData('text/plain', 'Card data');
-     * });
-     * ```
-     */
     makeDraggable: (dragStartCallback?: (event: DragEvent) => void) => CardComponent;
-    /**
-     * Sets focus to the card.
-     * Useful for programmatic focus management, especially in keyboard navigation
-     * scenarios or after dynamic content changes.
-     *
-     * @returns The card instance for chaining
-     * @example
-     * ```typescript
-     * // Focus the card
-     * card.focus();
-     *
-     * // Can be chained with other methods
-     * card.setHeader(headerElement).focus();
-     * ```
-     */
     focus: () => CardComponent;
-    /**
-     * Destroys the card component and removes event listeners.
-     * Call this method when the card is no longer needed to prevent memory leaks.
-     *
-     * @example
-     * ```typescript
-     * // Clean up resources when done with the card
-     * card.destroy();
-     * ```
-     */
     destroy: () => void;
 }
-/**
- * Loading feature interface.
- * Provides methods to control loading state on the card.
- *
- * @interface LoadingFeature
- * @category Components
- */
 export interface LoadingFeature {
-    /** Check if loading state is active */
     isLoading: () => boolean;
-    /** Set loading state */
     setLoading: (loading: boolean) => void;
 }
-/**
- * Expandable feature interface.
- * Provides methods to control the expanded/collapsed state of a card.
- *
- * @interface ExpandableFeature
- * @category Components
- */
 export interface ExpandableFeature {
-    /** Check if expanded state is active */
     isExpanded: () => boolean;
-    /** Set expanded state */
     setExpanded: (expanded: boolean) => void;
-    /** Toggle expanded state */
     toggleExpanded: () => void;
 }
-/**
- * Swipeable feature interface.
- * Provides methods to control the swipe behavior of a card.
- *
- * @interface SwipeableFeature
- * @category Components
- */
 export interface SwipeableFeature {
-    /** Reset swipe position */
     reset: () => void;
 }
-/**
- * API options interface.
- * Configuration object for the card's API methods.
- *
- * @interface ApiOptions
- * @category Components
- */
 export interface ApiOptions {
-    /** Lifecycle methods */
     lifecycle: {
-        /** Destroy callback */
         destroy: () => void;
     };
-    /** The resolved configuration the card was created from */
     config: CardComponentConfig;
 }
-/**
- * Registers CardConfig with the global defaults map, so
- * `setComponentDefaults("card", ...)` is typed without core
- * importing anything from this component.
- */
 declare module "../../core/config/global" {
     interface ComponentConfigMap {
         card?: Partial<CardConfig>;

package/dist/components/carousel/carousel.d.ts

@@ -1,25 +1,3 @@
 import { CarouselConfig, CarouselComponent } from "./types.js";
-/**
- * Creates a Material 3 carousel.
- *
- * Items are laid out by a keyline strategy per layout (multi-browse,
- * uncontained, hero, centred hero, full-screen) and scrolled natively;
- * they change size as they move through the layout and snap into place.
- *
- * @example
- * ```ts
- * const carousel = createCarousel({
- *   variant: 'hero',
- *   itemWidth: 360,
- *   slides: [
- *     { image: 'a.jpg', title: 'Alpha' },
- *     { image: 'b.jpg', title: 'Beta' },
- *   ],
- * });
- * carousel.on('change', ({ index }) => console.log(index));
- * ```
- *
- * @category Components
- */
 export declare const createCarousel: (config?: CarouselConfig) => CarouselComponent;
 export default createCarousel;

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

@@ -1,33 +1,17 @@
-/**
- * Material 3 carousel layouts (m3.material.io carousel specs)
- */
 export declare const CAROUSEL_VARIANTS: {
-    /** At least one large, one medium and one small item; the default */
     readonly MULTI_BROWSE: "multi-browse";
-    /** Items keep one size and run off the trailing edge */
     readonly UNCONTAINED: "uncontained";
-    /** One large item and a small preview of the next */
     readonly HERO: "hero";
-    /** One large item centred between two small ones */
     readonly HERO_CENTER: "hero-center";
-    /** One edge-to-edge item at a time, scrolling vertically */
     readonly FULL_SCREEN: "full-screen";
 };
 export declare const CAROUSEL_EVENTS: {
-    /** The snapped item changed; detail carries the index */
     readonly CHANGE: "change";
 };
-/**
- * Defaults from the Compose Material 3 carousel (CarouselDefaults) and the
- * carousel specs: 8dp between items, 16dp container padding, 28dp corners,
- * small items between 40 and 56dp, 10dp anchors just outside the container.
- */
 export declare const CAROUSEL_DEFAULTS: {
     readonly VARIANT: "multi-browse";
-    /** Preferred width of a large item; hero layouts use it as a maximum */
     readonly ITEM_WIDTH: 280;
     readonly GAP: 8;
-    /** Full-screen layouts space items 16dp apart */
     readonly GAP_FULL_SCREEN: 16;
     readonly PADDING: 16;
     readonly CORNER_RADIUS: 28;

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

@@ -1,61 +1,34 @@
 import type { ForwardedEventPayload } from "../../core/dom/index.js";
-/** Current item reported by programmatic navigation or native scrolling. */
 export interface CarouselChangePayload {
-    /** The current item's index, as `getValue()` returns it; every model event carries it */
     value: number;
 }
-/** Events emitted by the scroll feature and forwarded from the root. */
 export interface CarouselEvents {
     change: (payload: CarouselChangePayload) => void;
     focus: (payload: ForwardedEventPayload<FocusEvent, HTMLElement>) => void;
     blur: (payload: ForwardedEventPayload<FocusEvent, HTMLElement>) => void;
 }
 export type CarouselVariant = "multi-browse" | "uncontained" | "hero" | "hero-center" | "full-screen";
-/**
- * Content of one carousel item. Either an image with optional text and a
- * call to action, or arbitrary content.
- */
 export interface CarouselSlide {
     image?: string;
-    /** Alternative text for the image; empty when the image is decorative */
     alt?: string;
     title?: string;
     description?: string;
     buttonText?: string;
     buttonUrl?: string;
-    /** Custom content, replaces the image and text */
     content?: HTMLElement | string;
 }
 export interface CarouselConfig {
-    /** Layout, "multi-browse" by default */
     variant?: CarouselVariant;
     slides?: CarouselSlide[];
-    /**
-     * Width of a large item in px. Multi-browse and uncontained layouts
-     * treat it as the preferred width, hero layouts as a maximum (the
-     * container width by default).
-     */
     itemWidth?: number;
-    /** Space between items, 8 by default (16 for full-screen) */
     gap?: number;
-    /** Space between the container edges and the items, 16 by default (0 for full-screen) */
     padding?: number;
-    /** Corner radius of the items, 28 by default */
     cornerRadius?: number;
-    /** Snap to items after scrolling; on by default except for uncontained layouts */
     snap?: boolean;
-    /**
-     * Scroll horizontal carousels with a vertical mouse wheel; false by default.
-     * Normalized deltas accumulate per gesture and glide to directional snap points.
-     * One notch advances at least one item; momentum can pass several whole items.
-     * At either edge the page scrolls.
-     * Horizontal trackpad gestures, zoom and vertical layouts stay native.
-     */
     wheel?: boolean;
     initialSlide?: number;
     minSmallItemWidth?: number;
     maxSmallItemWidth?: number;
-    /** Accessible name of the carousel */
     ariaLabel?: string;
     prefix?: string;
     componentName?: string;
@@ -72,10 +45,8 @@ export interface CarouselComponent {
     prev: () => CarouselComponent;
     goTo: (index: number) => CarouselComponent;
     getCurrentSlide: () => number;
-    /** Reads the current model value without changing selection. */
     getValue: () => number;
     getVariant: () => CarouselVariant;
-    /** Enable or disable vertical mouse wheel scrolling in place. */
     setWheel: (on: boolean) => CarouselComponent;
     addSlide: (slide: CarouselSlide, index?: number) => CarouselComponent;
     removeSlide: (index: number) => CarouselComponent;

package/dist/components/checkbox/checkbox.d.ts

@@ -1,64 +1,3 @@
-/**
- * Checkbox Component Implementation
- *
- * This module implements a Material Design 3 checkbox component
- * with support for different visual variants, indeterminate state,
- * and configurable label positioning.
- *
- * @module components/checkbox
- * @category Components
- */
 import { CheckboxConfig, CheckboxComponent } from "./types.js";
-/**
- * Creates a new Checkbox component with the specified configuration.
- *
- * Checkboxes allow users to select one or more items from a set,
- * or to toggle a single option on or off. This implementation follows
- * Material Design 3 guidelines for accessible, customizable checkboxes.
- *
- * @param {CheckboxConfig} config - Configuration options for the checkbox
- * @returns {CheckboxComponent} A fully configured checkbox component instance
- * @throws {Error} Throws an error if checkbox creation fails
- *
- * @category Components
- *
- * @example
- * // Create a basic checkbox
- * const checkbox = createCheckbox({
- *   label: 'Accept terms and conditions',
- *   name: 'accept-terms'
- * });
- *
- * document.querySelector('.form').appendChild(checkbox.element);
- *
- * @example
- * // Create a pre-checked checkbox with custom styling
- * const checkbox = createCheckbox({
- *   label: 'Remember me',
- *   checked: true,
- *   labelPosition: 'start'
- * });
- *
- * // Add event listener
- * checkbox.on('change', (e) => {
- *   console.log('Checkbox changed:', e.checked);
- * });
- *
- * @example
- * // Create an indeterminate checkbox for "select all" functionality
- * const selectAll = createCheckbox({
- *   label: 'Select All',
- *   indeterminate: true
- * });
- *
- * // Later, based on selections:
- * if (allSelected) {
- *   selectAll.check();
- * } else if (noneSelected) {
- *   selectAll.uncheck();
- * } else {
- *   selectAll.setIndeterminate(true);
- * }
- */
 declare const createCheckbox: (config?: CheckboxConfig) => CheckboxComponent;
 export default createCheckbox;