material 3.2.6 → 3.3.0

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

@@ -1,377 +1,109 @@
 import type { ForwardedEventPayload } from "../../core/dom/index.js";
 import type { NormalizedEvent } from "../../core/utils/mobile.js";
-/** Normalized touch-end event emitted by the interactive root on touch devices. */
 export type TimePickerTapPayload = NormalizedEvent;
-/** Horizontal swipe emitted by the interactive root on touch devices. */
 export interface TimePickerSwipePayload {
     direction: "left" | "right";
     deltaX: number;
     deltaY: number;
 }
-/**
- * The committed 24-hour value carried by `change` and `confirm`.
- */
 export interface TimePickerValueEvent {
-    /** HH:MM, or HH:MM:SS with showSeconds */
     value: string;
 }
-/** A draft edit while the committed value remains available as `value`. */
 export interface TimePickerInputEvent extends TimePickerValueEvent {
-    /** The uncommitted 24-hour value shown in the open picker. */
     draftValue: string;
 }
-/** Events emitted by the picker API and its interactive root. */
 export interface TimePickerEvents {
-    /**
-     * The committed 24-hour value (HH:MM, or HH:MM:SS with showSeconds), also
-     * submitted by the form: once when OK commits a different time. setValue is
-     * silent. Moves on the dial or in the fields are `input`.
-     */
     change: (event: TimePickerValueEvent) => void;
-    /** The committed value and draft as the dial, fields or AM/PM change. */
     input: (event: TimePickerInputEvent) => void;
-    /** The confirmed 24-hour value, matching getValue() and the submitted form value. */
     confirm: (event: TimePickerValueEvent) => void;
     open: () => void;
     close: () => void;
     cancel: () => void;
-    /** Root events; the dialog is inside the root, so its clicks and keys reach these too. */
     click: (payload: ForwardedEventPayload<MouseEvent, HTMLElement>) => void;
     keydown: (payload: ForwardedEventPayload<KeyboardEvent, HTMLElement>) => void;
     tap: (payload: TimePickerTapPayload) => void;
     swipe: (payload: TimePickerSwipePayload) => void;
 }
-/**
- * Time picker display type
- * @enum {string}
- */
 export declare enum TIME_PICKER_TYPE {
-    /** Clock dial-based time picker */
     DIAL = "dial",
-    /** Text input-based time picker */
     INPUT = "input"
 }
-/**
- * Time picker orientation
- * @enum {string}
- */
 export declare enum TIME_PICKER_ORIENTATION {
-    /** Vertical layout (default on mobile) */
     VERTICAL = "vertical",
-    /** Horizontal layout */
     HORIZONTAL = "horizontal"
 }
-/**
- * Time format (12-hour or 24-hour)
- * @enum {string}
- */
 export declare enum TIME_FORMAT {
-    /** 12-hour format with AM/PM */
     AMPM = "12h",
-    /** 24-hour format */
     MILITARY = "24h"
 }
-/** A time format as the enum or its string value, `'12h'` or `'24h'` */
 export type TimeFormat = TIME_FORMAT | `${TIME_FORMAT}`;
-/** A time picker type as the enum or its string value, `'dial'` or `'input'` */
 export type TimePickerType = TIME_PICKER_TYPE | `${TIME_PICKER_TYPE}`;
-/** An orientation as the enum or its string value, `'vertical'` or `'horizontal'` */
 export type TimePickerOrientation = TIME_PICKER_ORIENTATION | `${TIME_PICKER_ORIENTATION}`;
-/**
- * Period of day for 12-hour format
- * @enum {string}
- */
 export declare enum TIME_PERIOD {
-    /** Morning */
     AM = "AM",
-    /** Afternoon/Evening */
     PM = "PM"
 }
-/**
- * Configuration interface for the TimePicker component
- * @category Components
- */
 export interface TimePickerConfig {
-    /**
-     * Initial time value in 24-hour format (HH:MM)
-     * @example '14:30'
-     */
     value?: string;
-    /**
-     * Form field name. A time picker renders no form control of its own, so it
-     * submits nothing unless this is set; with it, a hidden input on the
-     * picker's element carries the current time as 24-hour `HH:mm` — or
-     * `HH:mm:ss` when `showSeconds` is on — whatever format the picker displays.
-     */
     name?: string;
-    /**
-     * Type of time picker to display
-     * @default TIME_PICKER_TYPE.DIAL
-     */
     type?: TimePickerType;
-    /**
-     * Time format to use (12h or 24h)
-     * @default TIME_FORMAT.AMPM
-     */
     format?: TimeFormat;
-    /**
-     * Layout orientation for the time picker
-     * @default TIME_PICKER_ORIENTATION.VERTICAL
-     */
     orientation?: TimePickerOrientation;
-    /**
-     * Title text for the time picker
-     * @example 'Select departure time'
-     */
     title?: string;
-    /**
-     * Whether to show seconds selector
-     * @default false
-     */
     showSeconds?: boolean;
-    /**
-     * Additional CSS classes to add to the time picker
-     * @example 'custom-picker dark-theme'
-     */
     class?: string;
-    /**
-     * Component prefix for class names
-     * @default 'mtrl'
-     */
     prefix?: string;
-    /**
-     * Component name used in class generation
-     */
     componentName?: string;
-    /**
-     * Earliest selectable time, 24-hour `HH:MM` or `HH:MM:SS`. Dial numbers and
-     * AM/PM that cannot reach it are disabled, and a picked or typed time before
-     * it moves up to it. `setValue` is not held to it.
-     * @example '09:00'
-     */
     minTime?: string;
-    /**
-     * Latest selectable time, 24-hour `HH:MM` or `HH:MM:SS`; as `minTime`, at the
-     * other end.
-     * @example '18:00'
-     */
     maxTime?: string;
-    /**
-     * Minute step: dial minutes off it are disabled, a pointer between them picks
-     * the nearest, and a typed minute rounds to it when committed.
-     * @default 1
-     */
     minuteStep?: number;
-    /**
-     * Second step, as `minuteStep`, when seconds are shown.
-     * @default 1
-     */
     secondStep?: number;
-    /**
-     * Custom text for cancel button
-     * @default 'Cancel'
-     */
     cancelText?: string;
-    /**
-     * Custom text for confirm button
-     * @default 'OK'
-     */
     confirmText?: string;
-    /**
-     * Whether the time picker is open when the factory returns: `isOpen()` is
-     * true and `open` has been emitted (to `onOpen`). Its surface is shown a
-     * task later, in the place the picker has been put by then, or in the body.
-     * It was `isOpen`, the name of the method that reads the state.
-     * @default false
-     */
     open?: boolean;
-    /**
-     * Whether the picker is disabled: it does not open
-     * @default false
-     */
     disabled?: boolean;
-    /**
-     * Where the dialog is appended. By default it stays in the component's own
-     * element, as the other modals' do; it was document.body.
-     * @default the component's element
-     */
     container?: string | HTMLElement;
-    /**
-     * Custom icon for the clock button
-     */
     clockIcon?: string;
-    /**
-     * Custom icon for the keyboard button
-     */
     keyboardIcon?: string;
-    /**
-     * `change` listener registered at creation. The user commits a new time on
-     * OK; setValue is silent. The argument is `{ value }` (HH:MM, or HH:MM:SS).
-     */
     onChange?: TimePickerEvents["change"];
-    /**
-     * `input` listener registered at creation, as the draft changes while the
-     * picker is open.
-     */
     onInput?: TimePickerEvents["input"];
-    /**
-     * `open` listener registered at creation.
-     */
     onOpen?: TimePickerEvents["open"];
-    /**
-     * `close` listener registered at creation.
-     */
     onClose?: TimePickerEvents["close"];
-    /**
-     * `confirm` listener registered at creation. The argument is `{ value }`,
-     * the same 24-hour string `getValue()` returns.
-     */
     onConfirm?: TimePickerEvents["confirm"];
-    /**
-     * `cancel` listener registered at creation.
-     */
     onCancel?: TimePickerEvents["cancel"];
 }
-/**
- * Configuration as it leaves `createBaseConfig`.
- *
- * `TimePickerConfig` marks these optional because a caller may omit them.
- * Once the defaults have been merged they are all present, and everything
- * downstream — the renderer, the clock dial, the API — reads them as such.
- * Saying so here is what lets that hold without each reader guessing.
- * @category Components
- * @internal
- */
 export type ResolvedTimePickerConfig = TimePickerConfig & Required<Pick<TimePickerConfig, "type" | "format" | "orientation" | "showSeconds" | "minuteStep" | "secondStep" | "cancelText" | "confirmText" | "open" | "clockIcon" | "keyboardIcon" | "prefix">> & {
-    /** The dialog title's id, unique per picker. */
     titleId?: string;
 };
-/**
- * Time value object
- * @category Components
- */
 export interface TimeValue {
-    /** Hours (0-23) */
     hours: number;
-    /** Minutes (0-59) */
     minutes: number;
-    /** Seconds (0-59), optional */
     seconds?: number;
-    /** AM/PM for 12-hour format */
     period?: TIME_PERIOD;
 }
-/**
- * TimePicker component interface
- * @category Components
- */
 export interface TimePickerComponent {
-    /** The time picker's container DOM element */
     element: HTMLElement;
-    /** Modal container element */
     modalElement: HTMLElement;
-    /** Dialog container element */
     dialogElement: HTMLElement;
-    /** Whether the time picker is currently open */
     isOpen: () => boolean;
-    /**
-     * Opens the time picker. When it returns, `isOpen()` is true and `open` has
-     * been emitted; the surface may be painted after `open()` returns. On an
-     * open or disabled picker it does nothing.
-     * @returns The time picker component for chaining
-     */
     open: () => TimePickerComponent;
-    /**
-     * Closes the time picker
-     * @returns The time picker component for chaining
-     */
     close: () => TimePickerComponent;
-    /**
-     * Toggles the time picker open/closed state
-     * @returns The time picker component for chaining
-     */
     toggle: () => TimePickerComponent;
-    /**
-     * Gets the current time value
-     * @returns Current time string in 24-hour format (HH:MM, or HH:MM:SS when showSeconds is true)
-     */
     getValue: () => string;
-    /**
-     * Gets the current time as a TimeValue object
-     * @returns Current time object with hours, minutes, seconds, and period
-     */
     getTimeObject: () => TimeValue;
-    /**
-     * Sets the time value. Silent: neither `change` nor onChange
-     * @param time - Time string in 24-hour format (HH:MM or HH:MM:SS)
-     * @returns The time picker component for chaining
-     */
     setValue: (time: string) => TimePickerComponent;
-    /**
-     * Sets the time picker type (dial or input)
-     * @param type - Time picker type
-     * @returns The time picker component for chaining
-     */
     setType: (type: TimePickerType) => TimePickerComponent;
-    /**
-     * Gets the current time picker type
-     * @returns Current time picker type
-     */
     getType: () => TIME_PICKER_TYPE;
-    /**
-     * Sets the time format (12h or 24h)
-     * @param format - Time format
-     * @returns The time picker component for chaining
-     */
     setFormat: (format: TimeFormat) => TimePickerComponent;
-    /**
-     * Gets the current time format
-     * @returns Current time format
-     */
     getFormat: () => TIME_FORMAT;
-    /**
-     * Sets the time picker orientation
-     * @param orientation - Time picker orientation
-     * @returns The time picker component for chaining
-     */
     setOrientation: (orientation: TimePickerOrientation) => TimePickerComponent;
-    /**
-     * Gets the current time picker orientation
-     * @returns Current time picker orientation
-     */
     getOrientation: () => TIME_PICKER_ORIENTATION;
-    /**
-     * Sets the time picker title
-     * @param title - Title text
-     * @returns The time picker component for chaining
-     */
     setTitle: (title: string) => TimePickerComponent;
-    /**
-     * Gets the current time picker title
-     * @returns Current title text
-     */
     getTitle: () => string;
-    /** Enables the picker */
     enable: () => TimePickerComponent;
-    /** Disables the picker: it does not open, and an open one is cancelled */
     disable: () => TimePickerComponent;
-    /** Whether the picker is disabled */
     isDisabled: () => boolean;
-    /**
-     * Destroys the time picker component and cleans up resources
-     */
     destroy: () => void;
-    /**
-     * Adds an event listener to the time picker
-     * @param event - Event name ('change', 'open', 'close', etc.)
-     * @param handler - Event handler function
-     * @returns The time picker component for chaining
-     */
     on: <K extends keyof TimePickerEvents>(event: K, handler: TimePickerEvents[K]) => TimePickerComponent;
-    /**
-     * Removes an event listener from the time picker
-     * @param event - Event name
-     * @param handler - Event handler function
-     * @returns The time picker component for chaining
-     */
     off: <K extends keyof TimePickerEvents>(event: K, handler: TimePickerEvents[K]) => TimePickerComponent;
 }

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

@@ -1,35 +1,18 @@
-/**
- * Toolbar variants (m3.material.io toolbars)
- * - docked: full width at the bottom of the window, for global actions
- * - floating: a pill above the content, for contextual actions
- */
 export declare const TOOLBAR_VARIANTS: {
     readonly DOCKED: "docked";
     readonly FLOATING: "floating";
 };
 export type ToolbarVariant = (typeof TOOLBAR_VARIANTS)[keyof typeof TOOLBAR_VARIANTS];
-/**
- * Toolbar colours
- * - standard: surface container, low emphasis
- * - vibrant: primary container, high emphasis (e.g. an edit mode)
- */
 export declare const TOOLBAR_COLORS: {
     readonly STANDARD: "standard";
     readonly VIBRANT: "vibrant";
 };
 export type ToolbarColor = (typeof TOOLBAR_COLORS)[keyof typeof TOOLBAR_COLORS];
-/** Floating toolbar layouts. A docked toolbar is always horizontal. */
 export declare const TOOLBAR_ORIENTATIONS: {
     readonly HORIZONTAL: "horizontal";
     readonly VERTICAL: "vertical";
 };
 export type ToolbarOrientation = (typeof TOOLBAR_ORIENTATIONS)[keyof typeof TOOLBAR_ORIENTATIONS];
-/**
- * Where the toolbar sits in its positioned container.
- * - none: in the flow, placed by the page
- * - bottom, top: a horizontal toolbar (docked: bottom only)
- * - start, end: a vertical toolbar, on the reading-direction side
- */
 export declare const TOOLBAR_PLACEMENTS: {
     readonly NONE: "none";
     readonly BOTTOM: "bottom";
@@ -38,27 +21,17 @@ export declare const TOOLBAR_PLACEMENTS: {
     readonly END: "end";
 };
 export type ToolbarPlacement = (typeof TOOLBAR_PLACEMENTS)[keyof typeof TOOLBAR_PLACEMENTS];
-/**
- * How a docked toolbar lays out its items: spread evenly across the width
- * (compact windows), or centred 32dp apart (medium windows and up).
- */
 export declare const TOOLBAR_ARRANGEMENTS: {
     readonly SPREAD: "spread";
     readonly CENTER: "center";
 };
 export type ToolbarArrangement = (typeof TOOLBAR_ARRANGEMENTS)[keyof typeof TOOLBAR_ARRANGEMENTS];
-/** Scroll behaviours: stay on screen, or leave it while scrolling forward. */
 export declare const TOOLBAR_SCROLL_BEHAVIORS: {
     readonly NONE: "none";
     readonly EXIT: "exit";
 };
 export type ToolbarScrollBehavior = (typeof TOOLBAR_SCROLL_BEHAVIORS)[keyof typeof TOOLBAR_SCROLL_BEHAVIORS];
-/** Which side of a floating toolbar its FAB sits on, along the toolbar. */
 export type ToolbarFabPosition = "start" | "end";
-/**
- * The scroll distance, in px, that hides or shows the toolbar
- * (Compose FloatingToolbarDefaults.ScrollDistanceThreshold, 40dp).
- */
 export declare const TOOLBAR_SCROLL_THRESHOLD = 40;
 export declare const TOOLBAR_EVENTS: {
     readonly SHOW: "show";

package/dist/components/toolbar/toolbar.d.ts

@@ -1,29 +1,4 @@
 import type { ToolbarConfig, ToolbarComponent } from "./types.js";
-/**
- * Creates a toolbar: M3 Expressive's docked and floating toolbars.
- *
- * The element with the `toolbar` role holds the items and is one tab stop,
- * walked with the arrow keys, Home and End. A paired FAB sits beside it,
- * outside that tab stop.
- *
- * @param config - Toolbar configuration
- * @returns A toolbar component
- * @category Components
- * @see https://m3.material.io/components/toolbars/overview
- *
- * @example
- * ```ts
- * const toolbar = createToolbar({
- *   variant: 'floating',
- *   placement: 'bottom',
- *   items: [
- *     { icon: boldIcon, ariaLabel: 'Bold', toggle: true },
- *     { icon: italicIcon, ariaLabel: 'Italic', toggle: true },
- *   ],
- *   overflow: (opener) => createMenu({ opener, items: moreItems }),
- * });
- * ```
- */
 declare const createToolbar: (config?: ToolbarConfig) => ToolbarComponent;
 export default createToolbar;
 export { createToolbar };

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

@@ -3,150 +3,48 @@ import type { BaseComponentConfig } from "../../core/config/component.js";
 import type { ButtonConfig } from "../button/types.js";
 import type { IconButtonConfig } from "../icon-button/types.js";
 import type { ToolbarVariant, ToolbarColor, ToolbarOrientation, ToolbarPlacement, ToolbarArrangement, ToolbarScrollBehavior, ToolbarFabPosition } from "./constants.js";
-/** Anything the toolbar can hold that already exists: an element, or a component carrying one. */
 export type ToolbarElementItem = HTMLElement | {
     element: HTMLElement;
 };
-/** A button the toolbar creates from its config: a label is what makes it a button. */
 export type ToolbarButtonItem = ButtonConfig & {
     text: string;
 };
-/**
- * An item of the toolbar:
- * - an icon button config (`icon`, `ariaLabel`, and `toggle`, `selected`,
- *   `variant`, `width` as on createIconButton), created by the toolbar;
- * - a button config with `text`, created by the toolbar;
- * - an element or a component, such as a text field or a divider, added as it is.
- */
 export type ToolbarItem = ToolbarElementItem | ToolbarButtonItem | IconButtonConfig;
-/**
- * Configuration of a toolbar
- * @category Components
- * @see https://m3.material.io/components/toolbars/overview
- */
 export interface ToolbarConfig extends BaseComponentConfig {
-    /**
-     * Docked (full width, global actions) or floating (a pill, contextual actions)
-     * @default 'docked'
-     */
     variant?: ToolbarVariant | string;
-    /**
-     * Standard (surface container) or vibrant (primary container)
-     * @default 'standard'
-     */
     color?: ToolbarColor | string;
-    /**
-     * Layout of a floating toolbar. A docked toolbar is always horizontal.
-     * @default 'horizontal'
-     */
     orientation?: ToolbarOrientation | string;
-    /**
-     * Where the toolbar sits in its positioned container: `'none'` leaves it in
-     * the flow. A horizontal toolbar takes `'bottom'` or `'top'` (docked: bottom
-     * only), a vertical one `'start'` or `'end'`.
-     * @default 'none'
-     */
     placement?: ToolbarPlacement | string;
-    /**
-     * How a docked toolbar lays out its items: spread across the width, or centred 32dp apart
-     * @default 'spread'
-     */
     arrangement?: ToolbarArrangement | string;
-    /**
-     * Whether a floating toolbar casts a shadow (elevation level 1). Remove it
-     * when the content beneath is visually distinct. A docked toolbar has none.
-     * @default true for floating
-     */
     elevated?: boolean;
-    /** The items, in order */
     items?: ToolbarItem[];
-    /**
-     * A FAB paired with a floating toolbar, outside its tab stop. Create it with
-     * createFab; a vibrant toolbar pairs with a `tertiary-container` FAB.
-     */
     fab?: ToolbarElementItem;
-    /**
-     * Which end of the toolbar the FAB sits at, along its layout
-     * @default 'end'
-     */
     fabPosition?: ToolbarFabPosition | string;
-    /**
-     * Adds a trailing "more" icon button and calls this with it, to build the
-     * overflow menu the button opens: `(opener) => createMenu({ opener, items })`.
-     * The toolbar itself does not import the menu.
-     */
     overflow?: (opener: HTMLElement) => unknown;
-    /**
-     * Icon of the overflow button
-     * @default a "more vertical" icon
-     */
     overflowIcon?: string;
-    /**
-     * Accessible name of the overflow button
-     * @default 'More options'
-     */
     overflowLabel?: string;
-    /**
-     * `'exit'` hides the toolbar while the content scrolls forward and shows it
-     * when it scrolls back
-     * @default 'none'
-     */
     scrollBehavior?: ToolbarScrollBehavior | string;
-    /**
-     * What scrolls, for `scrollBehavior: 'exit'`
-     * @default window
-     */
     scrollTarget?: HTMLElement | Window;
-    /**
-     * The scroll distance, in px, that hides or shows the toolbar
-     * @default 40
-     */
     scrollThreshold?: number;
-    /**
-     * Accessible name of the toolbar
-     * @default 'Toolbar'
-     */
     ariaLabel?: string;
-    /** Additional CSS classes */
     class?: string;
 }
-/** Events of a toolbar */
 export interface ToolbarEvents {
-    /** The toolbar came back on screen */
     show: () => void;
-    /** The toolbar left the screen */
     hide: () => void;
 }
-/**
- * A toolbar
- * @category Components
- */
 export interface ToolbarComponent extends ElementComponent {
-    /** The element with the `toolbar` role, which holds the items */
     bar: HTMLElement;
-    /** The overflow button, when `overflow` is set */
     overflowButton: HTMLElement | null;
-    /**
-     * Adds an item at the end, before the overflow button
-     * @returns The item's element
-     */
     add(item: ToolbarItem): HTMLElement;
-    /** Removes an item; one the toolbar created is destroyed */
     remove(item: ToolbarElementItem): this;
-    /** The item elements, in order, without the overflow button */
     getItems(): HTMLElement[];
-    /** Brings the toolbar back on screen */
     show(): this;
-    /** Moves the toolbar off screen and out of the focus order */
     hide(): this;
-    /** Whether the toolbar is on screen */
     isVisible(): boolean;
-    /** Changes the colour */
     setColor(color: ToolbarColor | string): this;
-    /** The current colour */
     getColor(): ToolbarColor;
     on<K extends keyof ToolbarEvents>(event: K, handler: ToolbarEvents[K]): this;
     off<K extends keyof ToolbarEvents>(event: K, handler: ToolbarEvents[K]): this;
-    /** Removes the toolbar, its listeners and the items it created */
     destroy(): void;
 }