material 3.2.6 → 3.3.0

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

@@ -1,88 +1,34 @@
 import type { EventCallback } from "../../core/state/emitter.js";
 import type { ForwardedEventPayload } from "../../core/dom/index.js";
 export type ChipType = "assist" | "filter" | "input" | "suggestion";
-/** Shared chip options. Containers default to filter chips. */
 export interface ChipConfig {
     type?: ChipType;
     label?: string;
     value?: string;
     disabled?: boolean;
-    /** In a single-select set, selecting this chip replaces the previous selection; the last selected config wins. */
     selected?: boolean;
-    /** Elevated styling is supported by assist, filter and suggestion chips. */
     elevated?: boolean;
-    /** Markup (HTML). Not sanitized by default: see Markup and sanitizing. */
     leadingIcon?: string;
-    /** Markup (HTML). Not sanitized by default: see Markup and sanitizing. Same sink as `leadingIcon`. */
     icon?: string;
-    /** Markup (HTML). Not sanitized by default: see Markup and sanitizing. */
     trailingIcon?: string;
-    /** Decorative avatar for an input chip; takes precedence over leadingIcon. Markup (HTML), not a person's name or an image URL. Not sanitized by default: see Markup and sanitizing. */
     avatar?: string;
-    /**
-     * Called when an input chip is removed, from its remove button or with Backspace or
-     * Delete. Input chips are always removable (m3.material.io chips): on its own the
-     * chip then leaves the page; in a set, the set removes it and emits `remove`. It
-     * used to be a request the owner had to act on, and without it there was no
-     * remove button. It and every `remove` listener run first, with the chip
-     * still in the set and on the page; the removal follows.
-     */
     onRemove?: ChipEvents["remove"];
     removeLabel?: string;
-    /**
-     * Filter chips: gives the trailing icon its own button, which calls this (the
-     * m3.material.io chips' trailing icon that "can be used to open a menu or remove
-     * the chip"). The chip's own action is unaffected.
-     */
     onTrailingClick?: ChipEvents["trailing"];
-    /** The trailing button's accessible name; "{label} options" for a menu, "Remove {label}" otherwise. */
     trailingLabel?: string;
-    /** The trailing button opens a menu: aria-haspopup="menu", and a drop-down arrow unless trailingIcon is set. */
     trailingMenu?: boolean;
-    /**
-     * Same payload as a `click` listener. It runs before the chip toggles, alone or
-     * in a set: `isSelected()` here is the state before the click. Read the new
-     * state in `onChange`, which follows when the selection changed.
-     */
     onClick?: ChipEvents["click"];
-    /**
-     * Same payload as a `change` listener: `{ selected, chip, value }`.
-     * On its own, a click emits `change` before `click`. In a set, the set
-     * toggles the chip during `click`, and the chip then emits `change` once.
-     * That click runs, in order: the item's `onClick`, the set's `onChange`,
-     * a set `change` listener added after `createChips`, the item's `onSelect`,
-     * a chip `click` listener added after the chip was created, the item's
-     * `onChange`, and a chip `change` listener added after the chip was created.
-     * `setSelected` does not emit `change`, and neither does the set's
-     * `selectByValue`.
-     */
     onChange?: ChipEvents["change"];
-    /**
-     * Called with the chip when the user toggles a selectable chip, not when a
-     * `selectionRequired` set refuses the click. No matching event: this is not
-     * an `on(event)` listener.
-     */
     onSelect?: (chip: ChipComponent) => void;
     class?: string;
     prefix?: string;
     componentName?: string;
     ripple?: boolean;
 }
-/**
- * @internal What the chip set passes a chip on top of its config; not part of
- * ChipConfig, so apps cannot set it.
- */
 export interface ChipOptions extends ChipConfig {
-    /** Selection belongs to the chips container. */
     managedSelection?: boolean;
-    /** Notify the owning set when a chip becomes selected. */
     onSelected?: (chip: ChipComponent) => void;
-    /** The owning set removes the chip, once its `remove` listeners have run. */
     onRemoved?: (chip: ChipComponent) => void;
-    /**
-     * The chip is a cell of a chip set's grid: the root is a
-     * `gridcell`, and a one-action chip's cell is its focus target.
-     */
     cell?: boolean;
 }
 type NamedChipConfig = Omit<ChipConfig, "type" | "text" | "selected" | "avatar" | "onRemove" | "removeLabel" | "onChange" | "onSelect" | "onTrailingClick" | "trailingLabel" | "trailingMenu"> & {
@@ -95,7 +41,6 @@ export type InputChipConfig = Omit<FilterChipConfig, "elevated" | "onTrailingCli
 export interface ChipChangePayload {
     selected: boolean;
     chip: ChipComponent;
-    /** The chip's value, as `getValue()` returns it; every model event carries it */
     value: string | null;
 }
 export interface ChipEvents {
@@ -105,18 +50,11 @@ export interface ChipEvents {
     blur: (payload: ForwardedEventPayload<FocusEvent, HTMLElement>) => void;
     change: (payload: ChipChangePayload) => void;
     remove: (chip: ChipComponent) => void;
-    /** A filter chip's trailing button was activated. */
     trailing: (chip: ChipComponent) => void;
 }
-/** Shared API. Selection setters are inert on assist and suggestion chips. */
 export interface ChipComponent {
     element: HTMLElement;
-    /** Native primary action. Removal is a sibling button, never nested inside it. */
     action: HTMLButtonElement;
-    /**
-     * A filter chip's trailing button, when it has one (`onTrailingClick`): anchor a
-     * menu to it and keep its aria-expanded in step.
-     */
     trailingAction?: HTMLButtonElement;
     getType: () => ChipType;
     getValue: () => string | null;
@@ -126,7 +64,6 @@ export interface ChipComponent {
     isDisabled: () => boolean;
     setLabel: (label: string) => ChipComponent;
     getLabel: () => string;
-    /** Alias of setLabel for chips-container consumers. */
     setText: (text: string) => ChipComponent;
     getText: () => string;
     setIcon: (icon: string) => ChipComponent;
@@ -134,7 +71,6 @@ export interface ChipComponent {
     setLeadingIcon: (icon: string) => ChipComponent;
     setTrailingIcon: (icon: string) => ChipComponent;
     isSelected: () => boolean;
-    /** Selects or deselects this chip silently. In a single-select set, selecting it deselects the previous chip. */
     setSelected: (selected: boolean) => ChipComponent;
     toggleSelected: () => ChipComponent;
     focus: () => ChipComponent;
@@ -143,107 +79,27 @@ export interface ChipComponent {
     off: <K extends keyof ChipEvents>(event: K, handler: ChipEvents[K]) => ChipComponent;
     addClass: (...classes: string[]) => ChipComponent;
 }
-/**
- * Configuration interface for the Chips component
- * @category Components
- */
 export interface ChipsConfig {
-    /**
-     * Array of chip configurations to initialize
-     * @default []
-     */
     chips?: ChipConfig[];
-    /**
-     * Whether the chip set is horizontally scrollable
-     * @default false
-     */
     scrollable?: boolean;
-    /**
-     * Whether the chip set is vertically stacked
-     * @default false
-     */
     vertical?: boolean;
-    /**
-     * Additional CSS classes
-     */
     class?: string;
-    /**
-     * CSS selector for filtering behavior
-     */
     selector?: string | null;
-    /**
-     * Whether several chips can be selected at once. Multi-select is the default, as
-     * Material's chip groups are (single-select is opt-in).
-     * @default true
-     */
     multiSelect?: boolean;
-    /**
-     * Whether the set keeps at least one chip selected: deselecting the last selected
-     * chip is refused, and a refused click emits no `change`, on the chip or on the set.
-     * Off by default, as in Material; single-select sets used to
-     * enforce it without a way to opt out.
-     * @default false
-     */
     selectionRequired?: boolean;
-    /**
-     * Same payload as an `on("change")` listener. Registered before the `on`
-     * map and before a listener added after `createChips`.
-     * `selectByValue(values, true)` reaches it, with `changed: null`.
-     * `selectByValue(values)` and `clearSelection()` stay silent.
-     */
     onChange?: ChipsEvents["change"];
-    /**
-     * Component prefix for class names
-     * @default 'mtrl'
-     */
     prefix?: string;
-    /**
-     * Label text for the chips container
-     */
     label?: string;
-    /**
-     * Position of the label (start or end)
-     * @default 'start'
-     */
     labelPosition?: "start" | "end";
-    /**
-     * Schema definition for the component structure
-     * @internal
-     */
     schema?: unknown;
-    /**
-     * Event handlers for component events
-     */
     on?: Partial<ChipsEvents>;
 }
-/**
- * Chips component interface
- * @category Components
- */
-/**
- * What a chips feature needs from the component it is handed.
- *
- * The chips pipe is createBase, withEvents, withElement, withContainer,
- * withChipItems, withDom, then the controller -- so the element and the
- * emitter are installed before it runs, and `chipContainer` and
- * `chipInstances` come from the two features just above it.
- *
- * @category Components
- * @internal
- */
 export interface ChipsFeatureComponent {
     element: HTMLElement;
     getClass: (name: string) => string;
     emit?: (event: string, data: unknown) => unknown;
-    /** withDom builds this; the controller appends chips to it */
     chipContainer?: HTMLElement;
-    /**
-     * withChipItems keeps the live chips here. Required, because it runs before
-     * the controller in the only pipe that builds one, and the controller reads
-     * it on every path.
-     */
     chipInstances: ChipComponent[];
-    /** withContainer installs this whole, so the members are not optional in it */
     layout?: {
         isVertical: () => boolean;
         isScrollable: () => boolean;
@@ -253,186 +109,52 @@ export interface ChipsFeatureComponent {
         destroy: () => void;
     };
 }
-/**
- * The handlers the chips controller keeps per event name.
- *
- * @category Components
- * @internal
- */
 export type ChipsEventListeners = Record<string, EventCallback[]>;
-/**
- * The payload of the chips set's `change`.
- *
- * Read `value` for the set's current value, `selected` for selected chip
- * values, and `changed` for the chip toggled by the user.
- */
 export interface ChipsChangeEvent {
-    /** The selection in the `value` property's shape: a string or null for a single-select set, an array for a multi-select one. */
     value: string | string[] | null;
-    /** The values of the selected chips, in chip order (a chip without a value gives null) */
     selected: (string | null)[];
-    /** The value of the chip the user toggled; null for a change made by a method */
     changed: string | null;
 }
-/** A chip joined the set; `value` is the selection after insertion. */
 export interface ChipsAddEvent {
     value: string | string[] | null;
     chip: ChipComponent;
 }
-/** A chip left the set; `value` is the remaining selection. */
 export interface ChipsRemoveEvent extends ChipsAddEvent {
-    /** The selection after removal, in the same shape as the set's `getValue()`. */
     value: string | string[] | null;
-    /** The removed chip's value, captured before destruction. */
     chipValue: string | null;
 }
-/** Events emitted by the chips container's controller. */
 export interface ChipsEvents {
-    /**
-     * The selection after the change. Read `event.value`, the same field the
-     * `<m-chips>` element's `change` carries.
-     */
     change: (event: ChipsChangeEvent) => void;
-    /** The newly created chip and the selection after insertion. */
     add: (event: ChipsAddEvent) => void;
-    /** The removed chip and the selection after removal. */
     remove: (event: ChipsRemoveEvent) => void;
 }
 export interface ChipsComponent {
-    /** The chips container's DOM element */
     element: HTMLElement;
-    /**
-     * Adds a new chip to the chips container. In a single-select set, a selected
-     * chip replaces the previous selection before `add` fires; `add.value`
-     * reads the new selection. Programmatic additions do not emit `change`.
-     * @param chipConfig - Configuration for the chip
-     * @returns The chips instance for chaining
-     */
     addChip: (chipConfig: ChipConfig) => ChipsComponent;
-    /**
-     * Removes a chip from the chips container
-     * @param chipOrIndex - Chip instance or index to remove
-     * @returns The chips instance for chaining
-     */
     removeChip: (chipOrIndex: ChipComponent | number) => ChipsComponent;
-    /**
-     * Gets all chip instances in the set
-     * @returns Array of chip instances
-     */
     getChips: () => ChipComponent[];
-    /**
-     * Gets currently selected chips
-     * @returns Array of selected chip instances
-     */
     getSelectedChips: () => ChipComponent[];
-    /**
-     * Gets the values of selected chips
-     * @returns Array of selected chip values
-     */
     getSelectedValues: () => (string | null)[];
-    /**
-     * Gets the current value - form field compatibility
-     * @returns The first selected value (or null) in single-select mode, the selected values in multi-select mode
-     */
     getValue: () => string | string[] | null;
-    /**
-     * Sets the value by selecting chips by value, without a change event - form field compatibility
-     * @param values - Value or array of values to select; null, undefined or empty clears the selection
-     * @returns The chips instance for chaining
-     */
     setValue: (values: string | string[] | null | undefined) => ChipsComponent;
-    /**
-     * Selects chips by their values
-     * @param values - Value or array of values to select
-     * @param triggerEvent - Emits `change` when true; silent by default
-     * @returns The chips instance for chaining
-     */
     selectByValue: (values: string | string[], triggerEvent?: boolean) => ChipsComponent;
-    /**
-     * Clears all selections. Silent: only the user's change emits `change`
-     * @returns The chips instance for chaining
-     */
     clearSelection: () => ChipsComponent;
-    /**
-     * Sets the scrollable state of the chips container
-     * @param isScrollable - Whether the chips container should be scrollable
-     * @returns The chips instance for chaining
-     */
     setScrollable: (isScrollable: boolean) => ChipsComponent;
-    /**
-     * Sets the vertical layout state
-     * @param isVertical - Whether the chips container should be vertically stacked
-     * @returns The chips instance for chaining
-     */
     setVertical: (isVertical: boolean) => ChipsComponent;
-    /**
-     * Sets the label text
-     * @param text - Label text
-     * @returns The chips instance for chaining
-     */
     setLabel: (text: string) => ChipsComponent;
-    /**
-     * Gets the label text
-     * @returns Label text
-     */
     getLabel: () => string;
-    /**
-     * Sets the label position
-     * @param position - Label position ('start' or 'end')
-     * @returns The chips instance for chaining
-     */
     setLabelPosition: (position: "start" | "end") => ChipsComponent;
-    /**
-     * Gets the label position
-     * @returns Label position
-     */
     getLabelPosition: () => string;
-    /**
-     * Scrolls to a specific chip. A scrollable set scrolls smoothly, from its
-     * stylesheet, and at once under reduced motion.
-     * @param chipOrIndex - Chip instance or index to scroll to
-     * @returns The chips instance for chaining
-     */
     scrollToChip: (chipOrIndex: ChipComponent | number) => ChipsComponent;
-    /**
-     * Enables keyboard navigation between chips in the set
-     * @returns The chips instance for chaining
-     */
     enableKeyboardNavigation: () => ChipsComponent;
-    /**
-     * Turns keyboard navigation between the chips on and off: while disabled,
-     * the arrows, Home and End no longer move focus in the set
-     */
     keyboard: {
-        /** Moves focus with the arrows, Home and End again */
         enable: () => void;
-        /** Stops moving focus with the arrows, Home and End */
         disable: () => void;
     };
-    /**
-     * Destroys the chips container and all contained chips
-     */
     destroy: () => void;
-    /**
-     * Adds an event listener to the chips container
-     * @param event - Event name ('change', etc.)
-     * @param handler - Event handler function
-     * @returns The chips instance for chaining
-     */
     on: <K extends keyof ChipsEvents>(event: K, handler: ChipsEvents[K]) => ChipsComponent;
-    /**
-     * Removes an event listener from the chips container
-     * @param event - Event name
-     * @param handler - Event handler function
-     * @returns The chips instance for chaining
-     */
     off: <K extends keyof ChipsEvents>(event: K, handler: ChipsEvents[K]) => ChipsComponent;
 }
-/**
- * Registers ChipConfig with the global defaults map, so
- * `setComponentDefaults("chip", ...)` is typed without core
- * importing anything from this component.
- */
 declare module "../../core/config/global" {
     interface ComponentConfigMap {
         chip?: Partial<ChipConfig>;

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

@@ -1,101 +1,45 @@
-/**
- * DatePicker variants
- */
 export declare const DATEPICKER_VARIANTS: {
-    /** Docked datepicker appears inline on the page */
     readonly DOCKED: "docked";
-    /** Modal datepicker appears in a dialog overlay */
     readonly MODAL: "modal";
-    /** Modal with input field for entering dates */
     readonly MODAL_INPUT: "modal-input";
 };
-/**
- * DatePicker views
- */
 export declare const DATEPICKER_VIEWS: {
-    /** Daily calendar grid view */
     readonly DAY: "day";
-    /** Month selection view */
     readonly MONTH: "month";
-    /** Year selection view */
     readonly YEAR: "year";
 };
-/**
- * DatePicker selection modes
- */
 export declare const DATEPICKER_SELECTION_MODES: {
-    /** Select a single date */
     readonly SINGLE: "single";
-    /** Select a date range */
     readonly RANGE: "range";
 };
-/**
- * Day names for the calendar
- */
 export declare const DAY_NAMES: string[];
-/**
- * Month names for the calendar
- */
 export declare const MONTH_NAMES: string[];
-/**
- * Month names abbreviated
- */
 export declare const MONTH_NAMES_SHORT: string[];
-/**
- * Default format for displaying dates
- */
 export declare const DEFAULT_DATE_FORMAT = "MM/DD/YYYY";
-/**
- * DatePicker CSS class names
- */
 export declare const DATEPICKER_CLASSES: {
-    /** Root container class */
     readonly ROOT: "datepicker";
-    /** Class for the input field */
     readonly INPUT: "datepicker__input";
-    /** Class for the calendar container */
     readonly CALENDAR: "datepicker__calendar";
-    /** Class for the header section */
     readonly HEADER: "datepicker__header";
-    /** Class for the month/year navigation */
     readonly NAVIGATION: "datepicker__navigation";
-    /** Class for the day names row */
     readonly WEEKDAYS: "datepicker__weekdays";
-    /** Class for the days grid */
     readonly DAYS: "datepicker__days";
-    /** Class for individual day cells */
     readonly DAY: "datepicker__day";
-    /** Class for today's date */
     readonly TODAY: "datepicker__day--today";
-    /** Class for selected date */
     readonly SELECTED: "datepicker__day--selected";
-    /** Class for disabled dates */
     readonly DISABLED: "datepicker__day--disabled";
-    /** Class for dates outside the current month */
     readonly OUTSIDE_MONTH: "datepicker__day--outside";
-    /** Class for first date in a range */
     readonly RANGE_START: "datepicker__cell--range-start";
-    /** Class for last date in a range */
     readonly RANGE_END: "datepicker__cell--range-end";
-    /** Class for dates between start and end in a range */
     readonly RANGE_MIDDLE: "datepicker__cell--range";
 };
-/**
- * DatePicker events
- */
 export declare const DATEPICKER_EVENTS: {
-    /** Fired when the selected date changes */
     readonly CHANGE: "change";
-    /** Fired when the datepicker opens */
     readonly OPEN: "open";
-    /** Fired when the datepicker closes */
     readonly CLOSE: "close";
-    /** Fired when a day is clicked/focused */
     readonly SELECT: "select";
-    /** Fired when the view changes (day/month/year) */
     readonly VIEW_CHANGE: "viewChange";
 };
-/** Internal SVG assets; accessible names are on their buttons. */
 export declare const DATEPICKER_ICONS: {
     readonly calendar: "<svg viewBox=\"0 0 24 24\" width=\"24\" height=\"24\" fill=\"currentColor\" aria-hidden=\"true\"><path d=\"M19 4h-1V2h-2v2H8V2H6v2H5a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2V6a2 2 0 0 0-2-2ZM5 10h14v10H5V10Zm0-4h14v2H5V6Zm2 6h4v4H7v-4Z\"/></svg>";
     readonly edit: "<svg viewBox=\"0 0 24 24\" width=\"24\" height=\"24\" fill=\"currentColor\" aria-hidden=\"true\"><path d=\"m3 17.25 11.06-11.06 3.75 3.75L6.75 21H3v-3.75ZM20.71 7.04l-1.83 1.83-3.75-3.75 1.83-1.83a1 1 0 0 1 1.41 0l2.34 2.34a1 1 0 0 1 0 1.41Z\"/></svg>";

package/dist/components/datepicker/datepicker.d.ts

@@ -1,9 +1,4 @@
 import type { DatePickerComponent, DatePickerConfig, DatePickerValueOf } from "./types.js";
-/** M3 calendar/input modes share a draft; modal acceptance is the commit boundary. */
-/**
- * The value's type follows a literal selectionMode: `'range'` makes
- * it a pair, the default a date.
- */
 declare const createDatePicker: <M extends string = "single">(config?: DatePickerConfig & {
     selectionMode?: M;
 }) => DatePickerComponent<DatePickerValueOf<M>>;