mtrl 0.8.0-next.42 → 0.8.0-next.44

package/dist/components/navigation-rail/config.js

@@ -1,10 +1,11 @@
 import { createComponentConfig } from "../../core/config/component.js";
-import { NAVIGATION_RAIL_DEFAULTS as defaults } from "./constants.js";
+import { NAVIGATION_RAIL_DEFAULTS as defaults, NAVIGATION_RAIL_ICONS as icons } from "./constants.js";
 export const createBaseConfig = (config) => {
     const result = createComponentConfig({
         expanded: defaults.EXPANDED, expandedWidth: defaults.EXPANDED_WIDTH,
         showToggle: defaults.SHOW_TOGGLE, ripple: true, items: [],
         expandLabel: 'Expand navigation', collapseLabel: 'Collapse navigation',
+        expandIcon: icons.EXPAND, collapseIcon: icons.COLLAPSE,
     }, config, 'navigation-rail');
     const width = result.expandedWidth;
     result.expandedWidth = Number.isFinite(width)

package/dist/components/navigation-rail/constants.d.ts

@@ -7,3 +7,8 @@ export declare const NAVIGATION_RAIL_DEFAULTS: {
     readonly MAX_EXPANDED_WIDTH: 360;
     readonly SHOW_TOGGLE: true;
 };
+/** Material Symbols `menu` and `menu_open`, the M3 rail menu button in each state. */
+export declare const NAVIGATION_RAIL_ICONS: {
+    readonly EXPAND: "<svg viewBox=\"0 -960 960 960\" aria-hidden=\"true\" focusable=\"false\"><path d=\"M120-240v-80h720v80H120Zm0-200v-80h720v80H120Zm0-200v-80h720v80H120Z\"/></svg>";
+    readonly COLLAPSE: "<svg viewBox=\"0 -960 960 960\" aria-hidden=\"true\" focusable=\"false\"><path d=\"M120-240v-80h520v80H120Zm664-40L584-480l200-200 56 56-144 144 144 144-56 56ZM120-440v-80h400v80H120Zm0-200v-80h520v80H120Z\"/></svg>";
+};

package/dist/components/navigation-rail/constants.js

@@ -6,3 +6,7 @@ export const NAVIGATION_RAIL_DEFAULTS = {
     MAX_EXPANDED_WIDTH: 360,
     SHOW_TOGGLE: true,
 };
+export const NAVIGATION_RAIL_ICONS = {
+    EXPAND: '<svg viewBox="0 -960 960 960" aria-hidden="true" focusable="false"><path d="M120-240v-80h720v80H120Zm0-200v-80h720v80H120Zm0-200v-80h720v80H120Z"/></svg>',
+    COLLAPSE: '<svg viewBox="0 -960 960 960" aria-hidden="true" focusable="false"><path d="M120-240v-80h520v80H120Zm664-40L584-480l200-200 56 56-144 144 144 144-56 56ZM120-440v-80h400v80H120Zm0-200v-80h520v80H120Z"/></svg>',
+};

package/dist/components/navigation-rail/navigation-rail.js

@@ -27,6 +27,19 @@ export default function createNavigationRail(config = {}) {
     const emitter = createEmitter();
     let expanded = !!options.expanded;
     let destroyed = false;
+    let switching = null;
+    const SWITCH_DURATION = 450;
+    const endSwitch = () => {
+        if (switching !== null)
+            clearTimeout(switching);
+        switching = null;
+        root.classList.remove(cls('--switching'));
+    };
+    const startSwitch = () => {
+        endSwitch();
+        root.classList.add(cls('--switching'));
+        switching = setTimeout(endSwitch, SWITCH_DURATION);
+    };
     let connectionObserver = null;
     const dialog = options.layout === 'modal' ? root : null;
     if (dialog)
@@ -43,7 +56,6 @@ export default function createNavigationRail(config = {}) {
         toggle = document.createElement('button');
         toggle.type = 'button';
         toggle.className = cls('__toggle');
-        toggle.innerHTML = '<svg viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg>';
         header.append(toggle);
     }
     if (options.header)
@@ -57,6 +69,7 @@ export default function createNavigationRail(config = {}) {
         const visible = item.badge !== undefined && item.badge !== false && item.badge !== '';
         if (!visible) {
             badge?.remove();
+            element.classList.remove(cls('__item--badged'));
             element.setAttribute('aria-label', item.label);
             return;
         }
@@ -68,6 +81,7 @@ export default function createNavigationRail(config = {}) {
         }
         badge.classList.toggle(cls('__badge--dot'), item.badge === true);
         badge.textContent = item.badge === true ? '' : String(item.badge);
+        element.classList.toggle(cls('__item--badged'), item.badge !== true);
         element.setAttribute('aria-label', `${item.label}, ${item.badgeLabel || (item.badge === true ? 'New activity' : String(item.badge))}`);
     };
     const updateSelection = () => {
@@ -147,6 +161,8 @@ export default function createNavigationRail(config = {}) {
         root.classList.toggle(cls('--expanded'), expanded);
         toggle?.setAttribute('aria-expanded', String(expanded));
         toggle?.setAttribute('aria-label', (expanded ? options.collapseLabel : options.expandLabel));
+        if (toggle)
+            toggle.innerHTML = (expanded ? options.collapseIcon : options.expandIcon);
         if (dialog) {
             if (expanded)
                 showModal();
@@ -166,6 +182,7 @@ export default function createNavigationRail(config = {}) {
         if (destroyed || expanded === value)
             return api;
         expanded = value;
+        startSwitch();
         synchronize();
         emitter.emit(value ? 'expand' : 'collapse', { expanded: value });
         if (!destroyed) {
@@ -264,6 +281,7 @@ export default function createNavigationRail(config = {}) {
         if (destroyed)
             return;
         destroyed = true;
+        endSwitch();
         connectionObserver?.disconnect();
         connectionObserver = null;
         dialog?.removeEventListener('keydown', modalTab);

package/dist/components/navigation-rail/types.d.ts

@@ -40,6 +40,10 @@ export interface NavigationRailConfig extends BaseComponentConfig {
     showToggle?: boolean;
     expandLabel?: string;
     collapseLabel?: string;
+    /** Menu button icon while collapsed. Default: Material Symbols `menu`. */
+    expandIcon?: string;
+    /** Menu button icon while expanded. Default: Material Symbols `menu_open`. */
+    collapseIcon?: string;
     /** Optional application-owned header, such as a FAB. Its lifecycle stays with its owner. */
     header?: HTMLElement;
     ripple?: boolean;

package/dist/components/select/features.js

@@ -99,6 +99,7 @@ export const withMenu = (config) => (component) => {
         closeOnResize: true,
         offset: 0,
         container: component.element,
+        ...(config.menu ?? {}),
     });
     menu.on("select", (event) => {
         if (!event.item || event.item.hasSubmenu) {

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

@@ -1,3 +1,4 @@
+import type { MenuColor, MenuVariant } from "../menu/types.js";
 /**
  * Available Select variants
  */
@@ -75,6 +76,26 @@ export interface SelectConfig {
      * Whether select is required
      */
     required?: boolean;
+    /**
+     * Options handed to the select's menu. By default the menu lives inside
+     * the select's own element with no height of its own, which suits a short
+     * list in a still surface; a long list, or a select inside a scrolling or
+     * clipping container (a drawer, a sheet), wants the menu in the body with a
+     * max height, so it is neither cropped nor taller than the screen.
+     * @example { container: document.body, maxHeight: "320px" }
+     */
+    menu?: {
+        /** Where the menu is mounted and positioned against; document.body for a menu that escapes a clipping container */
+        container?: HTMLElement | null;
+        /** The menu's max height (a CSS length); the list scrolls inside it */
+        maxHeight?: string;
+        /** Whether the menu flips above the field when there is no room below */
+        autoFlip?: boolean;
+        /** The menu's variant: 'vertical' is the M3 expressive menu, items apart in a rounded container */
+        variant?: MenuVariant;
+        /** The vertical variant's colour mapping */
+        color?: MenuColor;
+    };
     /**
      * Whether select is disabled
      */

package/dist/core/compose/cleanup.d.ts

@@ -0,0 +1,14 @@
+/** A resource scope shared by every stage of a component's composition. */
+export interface CleanupScope {
+    readonly destroyed: boolean;
+    add(cleanup: () => void): void;
+    destroy(): void;
+}
+export declare const createCleanup: () => CleanupScope;
+/** Also support custom component bases that already provide a lifecycle. */
+export declare const getCleanup: (component: {
+    resources?: CleanupScope;
+    lifecycle?: {
+        destroy(): void;
+    };
+}) => CleanupScope;

package/dist/core/compose/cleanup.js

@@ -0,0 +1,51 @@
+export const createCleanup = () => {
+    let callbacks;
+    let destroyed = false;
+    return {
+        get destroyed() { return destroyed; },
+        add(cleanup) {
+            if (destroyed)
+                cleanup();
+            else
+                (callbacks ?? (callbacks = [])).push(cleanup);
+        },
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            const pending = callbacks;
+            callbacks = undefined;
+            let failure;
+            let failed = false;
+            for (const cleanup of pending ?? []) {
+                try {
+                    cleanup();
+                }
+                catch (error) {
+                    if (!failed)
+                        failure = error;
+                    failed = true;
+                }
+            }
+            if (failed)
+                throw failure;
+        },
+    };
+};
+export const getCleanup = (component) => {
+    if (component.resources)
+        return component.resources;
+    const resources = component.resources = createCleanup();
+    if (component.lifecycle) {
+        const destroy = component.lifecycle.destroy.bind(component.lifecycle);
+        component.lifecycle.destroy = () => {
+            try {
+                resources.destroy();
+            }
+            finally {
+                destroy();
+            }
+        };
+    }
+    return resources;
+};

package/dist/core/compose/component.d.ts

@@ -2,6 +2,7 @@
  * @module core/compose/component
  * @description Core utilities for component composition and creation with built-in mobile support
  */
+import { type CleanupScope } from "./cleanup.js";
 /**
  * Touch state interface to track touch interactions
  */
@@ -18,6 +19,7 @@ export interface TouchState {
  * Base component interface with prefix utilities
  */
 export interface BaseComponent {
+    resources?: CleanupScope;
     config: Record<string, any>;
     componentName?: string;
     getClass: (name: string) => string;

package/dist/core/compose/component.js

@@ -1,9 +1,12 @@
+import { getCleanup } from "./cleanup.js";
 import { createElement, removeEventHandlers, } from "../dom/create.js";
 import { normalizeEvent, hasTouchSupport, TOUCH_CONFIG, PASSIVE_EVENTS, } from "../utils/mobile.js";
+const getModifierClass = (base, modifier) => `${base}--${modifier}`;
+const getElementClass = (base, element) => `${base}-${element}`;
 const withPrefix = (prefix) => ({
     getClass: (name) => `${prefix}-${name}`,
-    getModifierClass: (base, modifier) => `${base}--${modifier}`,
-    getElementClass: (base, element) => `${base}-${element}`,
+    getModifierClass,
+    getElementClass,
 });
 export const createBase = (config = {}) => ({
     config,
@@ -34,12 +37,12 @@ export const createBase = (config = {}) => ({
         }
     },
 });
-export const withElement = (options = {}) => (component) => {
+const setupTouch = (element, base, options) => {
     const handleTouchStart = (event) => {
         base.updateTouchState(event, "start");
         element.classList.add(`${base.getClass("touch-active")}`);
-        if (options.forwardEvents?.touchstart && "emit" in component) {
-            component.emit("touchstart", normalizeEvent(event));
+        if (options.forwardEvents?.touchstart && "emit" in base && typeof base.emit === "function") {
+            base.emit("touchstart", normalizeEvent(event));
         }
     };
     const handleTouchEnd = (event) => {
@@ -48,11 +51,11 @@ export const withElement = (options = {}) => (component) => {
         const touchDuration = Date.now() - base.touchState.startTime;
         element.classList.remove(`${base.getClass("touch-active")}`);
         base.updateTouchState(event, "end");
-        if (touchDuration < TOUCH_CONFIG.TAP_THRESHOLD && "emit" in component) {
-            component.emit("tap", normalizeEvent(event));
+        if (touchDuration < TOUCH_CONFIG.TAP_THRESHOLD && "emit" in base && typeof base.emit === "function") {
+            base.emit("tap", normalizeEvent(event));
         }
-        if (options.forwardEvents?.touchend && "emit" in component) {
-            component.emit("touchend", normalizeEvent(event));
+        if (options.forwardEvents?.touchend && "emit" in base && typeof base.emit === "function") {
+            base.emit("touchend", normalizeEvent(event));
         }
     };
     const handleTouchMove = (event) => {
@@ -62,17 +65,28 @@ export const withElement = (options = {}) => (component) => {
         const deltaX = normalized.clientX - base.touchState.startPosition.x;
         const deltaY = normalized.clientY - base.touchState.startPosition.y;
         if (Math.abs(deltaX) > TOUCH_CONFIG.SWIPE_THRESHOLD &&
-            "emit" in component) {
-            component.emit("swipe", {
+            "emit" in base && typeof base.emit === "function") {
+            base.emit("swipe", {
                 direction: deltaX > 0 ? "right" : "left",
                 deltaX,
                 deltaY,
             });
         }
-        if (options.forwardEvents?.touchmove && "emit" in component) {
-            component.emit("touchmove", { ...normalized, deltaX, deltaY });
+        if (options.forwardEvents?.touchmove && "emit" in base && typeof base.emit === "function") {
+            base.emit("touchmove", { ...normalized, deltaX, deltaY });
         }
     };
+    element.addEventListener("touchstart", handleTouchStart, PASSIVE_EVENTS);
+    element.addEventListener("touchend", handleTouchEnd);
+    element.addEventListener("touchmove", handleTouchMove, PASSIVE_EVENTS);
+    return () => {
+        element.removeEventListener("touchstart", handleTouchStart);
+        element.removeEventListener("touchend", handleTouchEnd);
+        element.removeEventListener("touchmove", handleTouchMove);
+    };
+};
+export const withElement = (options = {}) => (component) => {
+    const resources = getCleanup(component);
     const base = component;
     let parent = component.config.parent || options.parent;
     if (typeof parent === "string") {
@@ -106,11 +120,16 @@ export const withElement = (options = {}) => (component) => {
         container: parent,
     };
     const element = createElement(elementOptions);
-    if (hasTouchSupport() && options.interactive) {
-        element.addEventListener("touchstart", handleTouchStart, PASSIVE_EVENTS);
-        element.addEventListener("touchend", handleTouchEnd);
-        element.addEventListener("touchmove", handleTouchMove, PASSIVE_EVENTS);
-    }
+    const cleanupTouch = hasTouchSupport() && options.interactive
+        ? setupTouch(element, base, options)
+        : undefined;
+    resources.add(() => {
+        cleanupTouch?.();
+        base.touchState.activeTarget = null;
+        base.touchState.isTouching = false;
+        removeEventHandlers(element);
+        element.remove();
+    });
     return {
         ...component,
         element,
@@ -119,13 +138,7 @@ export const withElement = (options = {}) => (component) => {
             return this;
         },
         destroy() {
-            if (hasTouchSupport() && options.interactive) {
-                element.removeEventListener("touchstart", handleTouchStart);
-                element.removeEventListener("touchend", handleTouchEnd);
-                element.removeEventListener("touchmove", handleTouchMove);
-            }
-            removeEventHandlers(element);
-            element.remove();
+            resources.destroy();
         },
     };
 };

package/dist/core/compose/features/debounce.js

@@ -1,14 +1,10 @@
+import { getCleanup } from "../cleanup.js";
 import { debounce } from "../../utils/performance.js";
-function hasLifecycle(component) {
-    return 'lifecycle' in component &&
-        component.lifecycle &&
-        typeof component.lifecycle === 'object' &&
-        'destroy' in component.lifecycle &&
-        typeof component.lifecycle.destroy === 'function';
-}
 export const withDebounce = (config = {}) => (component) => {
     const debouncedHandlers = {};
     const addDebouncedEvent = (event, handler, wait, options = {}) => {
+        if (resources.destroyed)
+            return enhancedComponent;
         if (debouncedHandlers[event]) {
             removeDebouncedEvent(event);
         }
@@ -23,31 +19,26 @@ export const withDebounce = (config = {}) => (component) => {
     const removeDebouncedEvent = (event) => {
         const handler = debouncedHandlers[event];
         if (handler) {
+            handler.debounced.cancel();
             component.element.removeEventListener(event, handler.debounced);
             delete debouncedHandlers[event];
         }
         return enhancedComponent;
     };
-    if (hasLifecycle(component)) {
-        const originalDestroy = component.lifecycle.destroy;
-        component.lifecycle.destroy = () => {
-            Object.keys(debouncedHandlers).forEach(event => {
-                const handler = debouncedHandlers[event];
-                component.element.removeEventListener(event, handler.debounced);
-            });
-            originalDestroy.call(component.lifecycle);
-        };
-    }
-    if (config.debouncedEvents) {
-        Object.entries(config.debouncedEvents).forEach(([event, settings]) => {
-            addDebouncedEvent(event, settings.handler, settings.wait, settings.options);
-        });
-    }
+    const resources = getCleanup(component);
+    resources.add(() => {
+        Object.keys(debouncedHandlers).forEach(event => removeDebouncedEvent(event));
+    });
     const enhancedComponent = {
         ...component,
         addDebouncedEvent,
         removeDebouncedEvent
     };
+    if (config.debouncedEvents) {
+        Object.entries(config.debouncedEvents).forEach(([event, settings]) => {
+            addDebouncedEvent(event, settings.handler, settings.wait, settings.options);
+        });
+    }
     return enhancedComponent;
 };
 export default withDebounce;

package/dist/core/compose/features/disabled.js

@@ -54,9 +54,7 @@ export const withDisabled = (config) => (component) => {
         }
     };
     if (config.disabled) {
-        requestAnimationFrame(() => {
-            disabled.disable();
-        });
+        disabled.disable();
     }
     return {
         ...component,

package/dist/core/compose/features/events.js

@@ -1,10 +1,14 @@
+import { getCleanup } from "../cleanup.js";
 import { createEmitter } from "../../state/emitter.js";
 export const withEvents = () => (component) => {
     const emitter = createEmitter();
+    const resources = getCleanup(component);
+    resources.add(() => emitter.clear());
     return {
         ...component,
         on(event, handler) {
-            emitter.on(event, handler);
+            if (!resources.destroyed)
+                emitter.on(event, handler);
             return this;
         },
         off(event, handler) {

package/dist/core/compose/features/lifecycle.js

@@ -1,3 +1,4 @@
+import { getCleanup } from "../cleanup.js";
 import { createEmitter } from "../../state/emitter.js";
 function hasEvents(component) {
     return 'events' in component &&
@@ -21,13 +22,17 @@ function hasIcon(component) {
         typeof component.icon.getElement === 'function';
 }
 export const withLifecycle = () => (component) => {
+    const resources = getCleanup(component);
     let mounted = false;
+    let destroyed = false;
+    const destroyElement = component.destroy?.bind(component);
     const emitter = createEmitter();
+    resources.add(() => emitter.clear());
     const lifecycle = {
         onMount: (handler) => emitter.on('mount', handler),
         onUnmount: (handler) => emitter.on('unmount', handler),
         mount: () => {
-            if (!mounted) {
+            if (!mounted && !destroyed) {
                 mounted = true;
                 emitter.emit('mount');
             }
@@ -41,9 +46,14 @@ export const withLifecycle = () => (component) => {
         },
         isMounted: () => mounted,
         destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
             if (mounted) {
                 this.unmount();
             }
+            emitter.clear();
+            resources.destroy();
             if (hasEvents(component)) {
                 component.events.destroy();
             }
@@ -59,9 +69,10 @@ export const withLifecycle = () => (component) => {
                     iconElement.remove();
                 }
             }
-            if (component.element) {
-                component.element.remove();
-            }
+            if (destroyElement)
+                destroyElement();
+            else
+                component.element?.remove();
         }
     };
     return {

package/dist/core/compose/features/ripple.d.ts

@@ -52,12 +52,6 @@ export interface RippleComponent extends BaseComponent {
  * @returns Ripple controller
  */
 export declare const createRipple: (config?: RippleConfig) => RippleController;
-declare global {
-    interface HTMLElement {
-        __rippleHandlers?: Array<(e: MouseEvent) => void>;
-        __rippleContainer?: HTMLElement;
-    }
-}
 /**
  * Adds ripple effect functionality to a component
  *