material 3.2.6 → 3.2.7

package/dist/core/theme/tokens.d.ts

@@ -1,44 +1,60 @@
-/**
- * M3 colour roles to mtrl's colour tokens.
- *
- * One function turns a scheme's role colours into the `--mtrl-sys-color-*`
- * declarations a theme sets, light and dark. The theme generator
- * (`scripts/generate-themes.ts`) calls it with material-color-utilities'
- * output, and md3.io's theme builder calls it the same way, so a theme made on
- * the site and a theme shipped in the package cannot drift. It has no
- * dependency: the colour science stays in the caller.
- *
- * @module core/theme
- */
-/**
- * The colour roles a theme sets: the baseline theme's, in its order. Every
- * generated theme declares exactly these (a test holds the list to baseline).
- */
-export declare const THEME_ROLES: readonly ["error", "on-error", "error-container", "on-error-container", "primary", "on-primary", "primary-container", "on-primary-container", "secondary", "on-secondary", "secondary-container", "on-secondary-container", "tertiary", "on-tertiary", "tertiary-container", "on-tertiary-container", "primary-fixed", "primary-fixed-dim", "on-primary-fixed", "on-primary-fixed-variant", "secondary-fixed", "secondary-fixed-dim", "on-secondary-fixed", "on-secondary-fixed-variant", "tertiary-fixed", "tertiary-fixed-dim", "on-tertiary-fixed", "on-tertiary-fixed-variant", "surface", "surface-dim", "surface-bright", "surface-variant", "surface-container-lowest", "surface-container-low", "surface-container", "surface-container-high", "surface-container-highest", "on-surface", "on-surface-variant", "outline", "outline-variant", "shadow", "scrim", "inverse-surface", "inverse-on-surface", "inverse-primary"];
+export declare const THEME_ROLES: readonly [
+    "error",
+    "on-error",
+    "error-container",
+    "on-error-container",
+    "primary",
+    "on-primary",
+    "primary-container",
+    "on-primary-container",
+    "secondary",
+    "on-secondary",
+    "secondary-container",
+    "on-secondary-container",
+    "tertiary",
+    "on-tertiary",
+    "tertiary-container",
+    "on-tertiary-container",
+    "primary-fixed",
+    "primary-fixed-dim",
+    "on-primary-fixed",
+    "on-primary-fixed-variant",
+    "secondary-fixed",
+    "secondary-fixed-dim",
+    "on-secondary-fixed",
+    "on-secondary-fixed-variant",
+    "tertiary-fixed",
+    "tertiary-fixed-dim",
+    "on-tertiary-fixed",
+    "on-tertiary-fixed-variant",
+    "surface",
+    "surface-dim",
+    "surface-bright",
+    "surface-variant",
+    "surface-container-lowest",
+    "surface-container-low",
+    "surface-container",
+    "surface-container-high",
+    "surface-container-highest",
+    "on-surface",
+    "on-surface-variant",
+    "outline",
+    "outline-variant",
+    "shadow",
+    "scrim",
+    "inverse-surface",
+    "inverse-on-surface",
+    "inverse-primary"
+];
 export type ThemeRole = (typeof THEME_ROLES)[number];
-/**
- * A scheme's colours by role. Keys are the M3 role names, kebab-case
- * (`primary-container`) or camelCase as material-color-utilities spells them
- * (`primaryContainer`); values are `#rrggbb` hex strings.
- */
 export type SchemeRoles = Record<string, string>;
 export interface SchemeToTokensOptions {
-    /** The token prefix, as `--{prefix}-sys-color-*`. Default `mtrl`. */
     prefix?: string;
 }
-/** A theme's declarations: custom property to value, light and dark. */
 export interface ThemeTokens {
     light: Record<string, string>;
     dark: Record<string, string>;
 }
-/**
- * Turns a light and a dark scheme's role colours into a theme's colour
- * tokens. Every role in {@link THEME_ROLES} must be present in both.
- *
- * @example
- * const tokens = schemeToTokens({ light, dark });
- * tokens.light["--mtrl-sys-color-primary"]; // "#6750a4"
- */
 export declare const schemeToTokens: (schemes: {
     light: SchemeRoles;
     dark: SchemeRoles;

package/dist/core/utils/background.d.ts

@@ -1,35 +1,6 @@
-/**
- * Result interface for background color lookup
- */
 export interface BackgroundResult {
-    /** The computed background color value */
     color: string;
-    /** The element from which the color was obtained */
     element: HTMLElement | null;
 }
-/**
- * Gets the computed background color of an element or its ancestors.
- * Recursively traverses the DOM tree upward until it finds a non-transparent background.
- * Resolves CSS variables if used in background color.
- *
- * @param {HTMLElement} element - The starting element to check
- * @param {number} [maxDepth=20] - Maximum number of parent levels to check
- * @returns {BackgroundResult} Object containing the color and source element
- *
- * @example
- * // Get the inherited background color and its source element
- * const { color, element: sourceElement } = getInheritedBackground(myElement);
- * console.log(color); // 'rgb(255, 255, 255)' or '#1c2526' for dark mode
- *
- * // Observe the source element for changes
- * if (sourceElement) {
- *   const observer = new MutationObserver(() => {
- *     const { color } = getInheritedBackground(myElement);
- *     myElement.style.backgroundColor = color;
- *   });
- *
- *   observer.observe(sourceElement, { attributes: true, attributeFilter: ['style', 'class'] });
- * }
- */
 export declare const getInheritedBackground: (element: HTMLElement, maxDepth?: number) => BackgroundResult;
 export default getInheritedBackground;

package/dist/core/utils/color.d.ts

@@ -1,14 +1 @@
-/**
- * Converts a color to RGBA format with specified opacity
- * Handles hex, rgb, rgba, and named colors
- *
- * @param color - The color string to convert (hex, rgb, rgba, or named color)
- * @param opacity - The opacity value (0-1)
- * @returns RGBA color string
- *
- * @example
- * colorToRGBA('#ff0000', 0.5) // 'rgba(255, 0, 0, 0.5)'
- * colorToRGBA('rgb(255, 0, 0)', 0.5) // 'rgba(255, 0, 0, 0.5)'
- * colorToRGBA('red', 0.5) // 'rgba(255, 0, 0, 0.5)'
- */
 export declare const colorToRGBA: (color: string, opacity: number) => string;

package/dist/core/utils/index.d.ts

@@ -5,16 +5,5 @@ export { throttle, debounce, once } from "./performance.js";
 export { getThemeColor } from "./theme.js";
 export { colorToRGBA } from "./color.js";
 export { isSafeUrl, safeUrl, URL_ATTRIBUTES } from "./url.js";
-/**
- * Creates a transformer that only runs if a condition is met
- * @param {Function} predicate - Condition to check
- * @param {Function} transformer - Transformer to run if condition is true
- * @returns {Function} Conditional transformer
- */
 export declare const when: <T, C>(predicate: (obj: T, context: C) => boolean, transformer: (obj: T, context: C) => T) => (obj: T, context: C) => T;
-/**
- * Joins class names, filtering out falsy values
- * @param {...(string | undefined | null | false)} classes - Class names to join
- * @returns {string} Joined class names
- */
 export declare const classNames: (...classes: (string | undefined | null | false)[]) => string;

package/dist/core/utils/mobile.d.ts

@@ -1,10 +1,3 @@
-/**
- * Mobile device detection and capability checks
- * This provides a centralized way to handle mobile-specific features and behaviors
- */
-/**
- * Interface for normalized event properties
- */
 export interface NormalizedEvent {
     clientX: number;
     clientY: number;
@@ -15,51 +8,27 @@ export interface NormalizedEvent {
     stopPropagation: () => void;
     type: string;
 }
-/** Horizontal gesture emitted by an interactive root. */
 export interface SwipePayload {
     direction: "left" | "right";
     deltaX: number;
     deltaY: number;
 }
-/** Touch gestures emitted by touch-enabled interactive roots. */
 export interface TouchEvents {
     tap: (payload: NormalizedEvent) => void;
     swipe: (payload: SwipePayload) => void;
 }
-/**
- * Detects if the current device is likely a mobile device
- * Uses a combination of user agent and screen size checks for reliability
- */
 export declare const isMobileDevice: () => boolean;
-/**
- * Options for passive event listeners
- */
 export declare const PASSIVE_EVENTS: AddEventListenerOptions;
-/**
- * Configuration constants for mobile interactions
- * Following WCAG guidelines and touch interaction best practices
- */
 export declare const TOUCH_CONFIG: {
     TARGET_SIZE: number;
     FEEDBACK_DURATION: number;
     TAP_THRESHOLD: number;
     SWIPE_THRESHOLD: number;
 };
-/**
- * Accessibility-minded touch target sizes
- * Based on WCAG guidelines for touch targets
- */
 export declare const TOUCH_TARGETS: {
     MINIMUM: number;
     COMFORTABLE: number;
     LARGE: number;
 };
-/**
- * Detects if the current device supports touch events
- */
 export declare const hasTouchSupport: () => boolean;
-/**
- * Normalizes both mouse and touch events into a consistent format
- * This allows components to handle interactions uniformly
- */
 export declare const normalizeEvent: (event: Event) => NormalizedEvent;

package/dist/core/utils/object.d.ts

@@ -1,13 +1,2 @@
-/**
- * Checks if a value is a plain object
- * @param value - The value to check
- * @returns true if the value is a plain object
- */
 export declare const isObject: (value: unknown) => value is Record<string, unknown>;
-/**
- * Accesses a nested property of an object using a string path
- * @param obj - The object to traverse
- * @param path - The property path (e.g. 'user.address.street')
- * @returns The value at the specified path or undefined if not found
- */
 export declare const byString: <T extends object, R = unknown>(obj: T, path: string) => R | undefined;

package/dist/core/utils/performance.d.ts

@@ -1,82 +1,12 @@
 export type Cancellable<F> = F & {
     cancel(): void;
 };
-/**
- * @module core/utils/performance
- * @description Performance utilities for optimizing high-frequency event handlers
- */
-/**
- * Creates a throttled function that only invokes the provided function
- * at most once per every specified wait milliseconds.
- *
- * Throttling ensures that the function executes at a regular interval,
- * which is useful for limiting the rate of execution for expensive operations.
- *
- * @param {Function} fn - The function to throttle
- * @param {number} wait - The number of milliseconds to throttle invocations to
- * @param {Object} options - Configuration options
- * @param {boolean} options.leading - Specify invoking on the leading edge of the timeout (default: true)
- * @param {boolean} options.trailing - Specify invoking on the trailing edge of the timeout (default: true)
- * @returns {Function} The throttled function
- *
- * @example
- * // Throttle scroll handler to execute at most once every 100ms
- * const throttledScroll = throttle((e) => {
- *   updateScrollPosition(window.scrollY);
- * }, 100);
- *
- * window.addEventListener('scroll', throttledScroll);
- */
 export declare const throttle: <T extends (...args: never[]) => unknown>(fn: T, wait: number, options?: {
     leading?: boolean;
     trailing?: boolean;
 }) => Cancellable<(...args: Parameters<T>) => void>;
-/**
- * Creates a debounced function that delays invoking the provided function
- * until after the specified wait milliseconds have elapsed since the last time
- * it was invoked.
- *
- * Debouncing groups multiple sequential calls into a single execution at the end,
- * which is useful for handling rapid-fire events like resize or input.
- *
- * @param {Function} fn - The function to debounce
- * @param {number} wait - The number of milliseconds to delay
- * @param {Object} options - Configuration options
- * @param {boolean} options.leading - Specify invoking on the leading edge of the timeout (default: false)
- * @param {boolean} options.maxWait - Maximum time function can be delayed before execution in milliseconds
- * @returns {Function} The debounced function
- *
- * @example
- * // Debounced search that executes 300ms after the user stops typing
- * const debouncedSearch = debounce((query) => {
- *   performSearch(query);
- * }, 300);
- *
- * searchInput.addEventListener('input', (e) => {
- *   debouncedSearch(e.target.value);
- * });
- */
 export declare const debounce: <T extends (...args: never[]) => unknown>(fn: T, wait: number, options?: {
     leading?: boolean;
     maxWait?: number;
 }) => Cancellable<(...args: Parameters<T>) => void>;
-/**
- * Creates a function that is restricted to invoking the provided function once.
- * Repeat calls to the function return the value of the first invocation.
- *
- * @param {Function} fn - The function to restrict
- * @returns {Function} The restricted function
- *
- * @example
- * // Initialize app only once
- * const initApp = once(() => {
- *   console.log('App initialized');
- *   setupEventListeners();
- *   loadInitialData();
- * });
- *
- * // Can be called multiple times, but executes only once
- * button1.addEventListener('click', initApp);
- * button2.addEventListener('click', initApp);
- */
 export declare const once: <T extends (...args: never[]) => unknown>(fn: T) => ((...args: Parameters<T>) => ReturnType<T>);

package/dist/core/utils/theme.d.ts

@@ -1,41 +1,5 @@
 type ThemeChangeCallback = () => void;
-/**
- * Register a callback to be notified of theme changes
- * @param callback Function to call when theme changes
- * @returns Function to unregister the callback
- */
 export declare const onThemeChange: (callback: ThemeChangeCallback) => (() => void);
-/**
- * Gets a theme color from CSS variables, with optional alpha/opacity support.
- * The prefix is automatically added to the variable name.
- * With `element`, colors are read where that element sits, so a theme set on
- * any ancestor (or a shadow host) applies. Otherwise they are retrieved from
- * the active theme (defined on body element) if available, falling back to
- * the default theme (defined on :root) if not found.
- *
- * @param {string} varName - The CSS variable name without prefix (e.g. 'sys-color-primary')
- * @param {object} [options] - Options for color retrieval
- * @param {number} [options.alpha] - Alpha value (0-1): a hex colour is returned as rgba()
- * @param {string} [options.fallback] - Fallback color if variable is not found
- * @param {Element} [options.element] - Element whose theme to read; used when it is in a document
- * @param {ThemeChangeCallback} [options.onThemeChange] - Optional callback for theme changes
- * @returns {string} The color value (hex, rgb, or rgba)
- *
- * The themes declare no `--<prefix>-sys-color-*-rgb` twins, and material 3.0.0
- * no longer derives them: read `sys-color-X`, with `alpha` for rgba().
- *
- * @example
- * // Basic usage
- * getThemeColor('sys-color-primary') // '#006493' (from active theme)
- *
- * // With theme change notification
- * getThemeColor('sys-color-primary', {
- *   onThemeChange: () => {
- *     // Re-render or update component
- *     component.update();
- *   }
- * });
- */
 export declare function getThemeColor(varName: string, options?: {
     alpha?: number;
     fallback?: string;

package/dist/core/utils/url.d.ts

@@ -1,20 +1,3 @@
-/**
- * Attributes whose value is a URL, and so must be checked before assignment.
- */
 export declare const URL_ATTRIBUTES: Set<string>;
-/**
- * Whether a URL is safe to assign to a navigable attribute.
- *
- * Relative URLs, fragments and query-only URLs have no scheme and are safe:
- * they cannot execute. A value with a scheme is safe only if the scheme is
- * in the allowlist. Leading whitespace and control characters are stripped
- * first, because browsers ignore them when resolving `java\nscript:alert(1)`.
- */
 export declare const isSafeUrl: (url: string) => boolean;
-/**
- * Returns the URL if its scheme is allowed, otherwise an empty string.
- *
- * Empty rather than throwing: a refused URL should leave an inert control, not
- * break the page that rendered it.
- */
 export declare const safeUrl: (url: string) => string;

package/dist/elements/adapter.d.ts

@@ -1,27 +1,7 @@
-/**
- * What every framework adapter shares: how a spec's attributes, live
- * properties and events become a framework's props, how values are written as
- * attributes, and the tag prefix. Framework-free; each adapter
- * (`src/react`, `src/vue`, …) builds on it.
- *
- * @module elements
- */
 import { type AttributeType, type DefineOptions, type ElementAttributes, type ElementProperties } from "./define.js";
-/** The runtime parts of an element spec an adapter reads. */
 export interface ComponentSpec {
     name: string;
-    /** `false`: the server never marks the host. A function still can. Absent means it does. */
     ssr?: boolean | ((host: HTMLElement) => boolean);
-    /**
-     * The prefix-independent attribute the element's host carries once connected
-     * (`data-mtrl-icon-button`). The renderer, the element class and every
-     * adapter read it from this spec, so a future element with a marker needs no
-     * adapter change. The server writes it beside `data-mtrl-ssr`; styles match
-     * slotted hosts with it where the sheet cannot spell their tag.
-     *
-     * @internal A host attribute an element carries so another element's sheet
-     * can match it; not part of the public API and may change without notice.
-     */
     marker?: string;
     attributes?: Record<string, {
         type: AttributeType;
@@ -35,7 +15,6 @@ export interface ComponentSpec {
     form?: unknown;
     model?: string;
 }
-/** A declaration child (`<m-tab>`): attributes and children only, no behaviour. */
 export interface DeclarationSpec {
     name: string;
     attributes: Record<string, {
@@ -43,79 +22,51 @@ export interface DeclarationSpec {
     }>;
 }
 export type Pascal<S extends string> = S extends `${infer H}-${infer T}` ? `${Capitalize<H>}${Pascal<T>}` : Capitalize<S>;
-/** An attribute a live property shadows is set through `default<Name>`. */
 export type DefaultProps<S> = {
     [K in keyof ElementProperties<S> & keyof ElementAttributes<S> & string as `default${Capitalize<K>}`]?: ElementAttributes<S>[K];
 };
-/**
- * Events a component had in 0.10 and material 3.0.0 removed: the icon button's `toggle`.
- * The adapters refuse the matching handler prop (`onToggle`, `ontoggle`): its
- * type is a sentence, so the compiler's error says what to do. It would
- * otherwise fall through to the host's native handler of that name, compile,
- * and never fire when the button toggles. A 3.x migration guard, with no
- * run-time code: drop it in 4.0.
- */
-export type RetiredEvents<S> = [S] extends [import("./icon-button.js").IconButtonSpec] ? [import("./icon-button.js").IconButtonSpec] extends [S] ? "toggle" : never : never;
-/** A form-associated element takes `name`. */
+export type RetiredEvents<S> = [
+    S
+] extends [
+    import("./icon-button.js").IconButtonSpec
+] ? [
+    import("./icon-button.js").IconButtonSpec
+] extends [
+    S
+] ? "toggle" : never : never;
 export type FormProps<S> = S extends {
     form: unknown;
 } ? {
     name?: string;
 } : Record<never, never>;
-/** The live property a framework's two-way binding (`v-model`, `bind:`) drives. */
 export type ModelOf<S> = S extends {
     model: infer M extends keyof ElementProperties<S> & string;
 } ? M : never;
 export declare const camel: (name: string) => string;
 export declare const pascal: (name: string) => string;
-/**
- * An attribute value as a framework should render it. A present boolean is
- * `""`, which the element reads as true whether it arrives as an attribute or
- * as a property.
- */
 export declare const toAttribute: (type: AttributeType, value: unknown) => string | undefined;
 export interface AttributeProp {
-    /** The attribute's name on the element. */
     name: string;
     type: AttributeType;
-    /** A live property of the same name exists; this prop is its `default*`. */
     shadowed: boolean;
 }
-/** A spec, read once into the maps an adapter needs. */
 export interface Described {
-    /** Prop name (camelCase, or `default<Name>` when shadowed) to attribute. */
     attributes: Map<string, AttributeProp>;
-    /** Live-state property names. */
     properties: string[];
-    /** Event names, as the element dispatches them. */
     events: string[];
-    /** The property two-way binding drives, if any. */
     model: string | undefined;
     form: boolean;
-    /** Live property name to the attribute it shadows (`checked` → the `checked` attribute). */
     shadowedBy: Map<string, AttributeProp>;
-    /** The named slots, as `slot="…"` names them. */
     slots: readonly string[];
 }
 export declare const describe: (spec: ComponentSpec) => Described;
-/**
- * Writes the attributes live properties shadow (`defaultChecked` → the
- * `checked` attribute) on the element. Frameworks would assign a same-named
- * prop to the live property, so every adapter writes these itself in the
- * browser. A prop that is not given leaves the attribute alone.
- */
 export declare const writeDefaults: (element: HTMLElement, described: Described, read: (prop: string) => unknown) => void;
-/** Writes live-state props to the element. A prop that is not given leaves the element's own state. */
 export declare const writeLive: (element: HTMLElement, described: Described, read: (property: string) => unknown) => void;
-/**
- * On the server a live value is the markup's default, so the page renders in
- * that state before it hydrates: the attribute each given live property
- * shadows, with its value.
- */
-export declare const serverDefaults: (described: Described, read: (property: string) => unknown) => Array<[string, string]>;
+export declare const serverDefaults: (described: Described, read: (property: string) => unknown) => Array<[
+    string,
+    string
+]>;
 export declare const describeDeclaration: (spec: DeclarationSpec) => Map<string, AttributeProp>;
-/** The tag prefix adapters render. */
 export declare const getPrefix: () => string;
-/** Sets the tag prefix every adapter renders. Call before the first render. */
 export declare const configure: (options: DefineOptions) => void;
 export declare const isBrowser: boolean;

package/dist/elements/badge.d.ts

@@ -1,17 +1,3 @@
-/**
- * `<m-badge>`: a standalone badge. The factory attaches a badge to a target
- * it wraps; the element is the badge alone, placed by the page like any
- * inline element.
- *
- * The label is the `label` attribute, or the element's text when there is
- * none. The factory writes a formatted string (`999+`), not a node, so the
- * text is read rather than slotted. The `visible` property is the live
- * visibility; an empty or zero label hides the badge, as in the factory.
- *
- * Parts: `badge`.
- *
- * @module elements
- */
 import type { BadgeComponent } from "../components/badge/types.js";
 import { type DefineOptions, type ElementInstance } from "./define.js";
 declare const badgeSpec: {
@@ -57,12 +43,9 @@ declare const badgeSpec: {
 };
 export declare const badgeElement: import("./define.js").ElementDefinition<BadgeComponent>;
 export type BadgeSpec = typeof badgeSpec;
-/** `<m-badge>` as a ref or a query returns it. */
 export type BadgeElement = ElementInstance<BadgeSpec, BadgeComponent>;
-/** Registers `<m-badge>` (or `<prefix-badge>`). */
 export declare const defineBadge: (options?: DefineOptions) => string;
 declare global {
-    /** `document.querySelector("m-…")` and `createElement` return the element's type (the default prefix). */
     interface HTMLElementTagNameMap {
         "m-badge": BadgeElement;
     }

package/dist/elements/bottom-app-bar.d.ts

@@ -1,20 +1,10 @@
-/**
- * `<m-bottom-app-bar>`: the bottom app bar as a container with slots.
- *
- * Children are the actions (icon buttons); `slot="fab"` takes the FAB, placed
- * at the end or, with `fab-position="center"`, in the middle. `auto-hide`
- * hides the bar while the window scrolls down and shows it again on the way
- * up; `show()` and `hide()` do the same from script.
- *
- * Parts: `bottom-app-bar`, `actions`, `fab-container`.
- *
- * @module elements
- */
 import type { BottomAppBarComponent } from "../components/bottom-app-bar/types.js";
 import { type Config, type DefineOptions, type ElementInstance } from "./define.js";
 declare const bottomAppBarSpec: {
     name: string;
-    slots: readonly ["fab"];
+    slots: readonly [
+        "fab"
+    ];
     create: (config: Config) => BottomAppBarComponent;
     styles: string[];
     hostStyles: string;
@@ -36,18 +26,18 @@ declare const bottomAppBarSpec: {
             update: (c: BottomAppBarComponent, v: import("./define.js").AttributeValue) => void;
         };
     };
-    methods: readonly ["show", "hide"];
+    methods: readonly [
+        "show",
+        "hide"
+    ];
     config: (host: HTMLElement) => Config;
     setup: (host: import("./define.js").ElementHost<BottomAppBarComponent>, component: BottomAppBarComponent) => () => void | undefined;
 };
 export declare const bottomAppBarElement: import("./define.js").ElementDefinition<BottomAppBarComponent>;
 export type BottomAppBarSpec = typeof bottomAppBarSpec;
-/** `<m-bottom-app-bar>` as a ref or a query returns it. */
 export type BottomAppBarElement = ElementInstance<BottomAppBarSpec, BottomAppBarComponent>;
-/** Registers `<m-bottom-app-bar>` (or `<prefix-bottom-app-bar>`). */
 export declare const defineBottomAppBar: (options?: DefineOptions) => string;
 declare global {
-    /** `document.querySelector("m-…")` and `createElement` return the element's type (the default prefix). */
     interface HTMLElementTagNameMap {
         "m-bottom-app-bar": BottomAppBarElement;
     }