mtrl 0.8.0-next.40 → 0.8.0-next.42

package/dist/components/index.d.ts

@@ -26,6 +26,8 @@ export { default as createExtendedFab } from "./extended-fab/index.js";
 export { default as createIconButton } from "./icon-button/index.js";
 export { default as createList } from "./list/index.js";
 export { default as createMenu } from "./menu/index.js";
+export { default as createNavigationRail } from "./navigation-rail/index.js";
+export type { NavigationRailConfig, NavigationRailComponent, NavigationRailItemConfig, NavigationRailSelectEvent, NavigationRailEvents } from "./navigation-rail/types.js";
 export { default as createNavigation } from "./navigation/index.js";
 export { default as createNavigationSystem } from "./navigation/system/index.js";
 export { default as createProgress } from "./progress/index.js";

package/dist/components/index.js

@@ -17,6 +17,7 @@ export { default as createExtendedFab } from "./extended-fab/index.js";
 export { default as createIconButton } from "./icon-button/index.js";
 export { default as createList } from "./list/index.js";
 export { default as createMenu } from "./menu/index.js";
+export { default as createNavigationRail } from "./navigation-rail/index.js";
 export { default as createNavigation } from "./navigation/index.js";
 export { default as createNavigationSystem } from "./navigation/system/index.js";
 export { default as createProgress } from "./progress/index.js";

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

@@ -0,0 +1,2 @@
+import type { NavigationRailConfig } from "./types.js";
+export declare const createBaseConfig: (config: NavigationRailConfig) => NavigationRailConfig;

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

@@ -0,0 +1,14 @@
+import { createComponentConfig } from "../../core/config/component.js";
+import { NAVIGATION_RAIL_DEFAULTS as defaults } 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',
+    }, config, 'navigation-rail');
+    const width = result.expandedWidth;
+    result.expandedWidth = Number.isFinite(width)
+        ? Math.min(defaults.MAX_EXPANDED_WIDTH, Math.max(defaults.MIN_EXPANDED_WIDTH, width))
+        : defaults.EXPANDED_WIDTH;
+    return result;
+};

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

@@ -0,0 +1,9 @@
+/** M3 Expressive Android navigationrail/res/values/tokens.xml, token version 34.0.0. */
+export declare const NAVIGATION_RAIL_DEFAULTS: {
+    readonly EXPANDED: false;
+    readonly COLLAPSED_WIDTH: 96;
+    readonly EXPANDED_WIDTH: 280;
+    readonly MIN_EXPANDED_WIDTH: 220;
+    readonly MAX_EXPANDED_WIDTH: 360;
+    readonly SHOW_TOGGLE: true;
+};

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

@@ -0,0 +1,8 @@
+export const NAVIGATION_RAIL_DEFAULTS = {
+    EXPANDED: false,
+    COLLAPSED_WIDTH: 96,
+    EXPANDED_WIDTH: 280,
+    MIN_EXPANDED_WIDTH: 220,
+    MAX_EXPANDED_WIDTH: 360,
+    SHOW_TOGGLE: true,
+};

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

@@ -0,0 +1,2 @@
+export { default, default as createNavigationRail } from "./navigation-rail.js";
+export type { NavigationRailConfig, NavigationRailComponent, NavigationRailItemConfig, NavigationRailSelectEvent, NavigationRailEvents } from "./types.js";

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

@@ -0,0 +1 @@
+export { default, default as createNavigationRail } from "./navigation-rail.js";

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

@@ -0,0 +1,7 @@
+import type { NavigationRailConfig, NavigationRailComponent } from "./types.js";
+/**
+ * Creates an M3 Expressive navigation rail with stable destinations during expansion.
+ * Import its styles separately with `mtrl/styles/navigation-rail`.
+ * Links retain native browser navigation; onSelect can preventDefault for a router.
+ */
+export default function createNavigationRail(config?: NavigationRailConfig): NavigationRailComponent;

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

@@ -0,0 +1,323 @@
+import { pipe } from "../../core/compose/pipe.js";
+import { createBase, withElement } from "../../core/compose/component.js";
+import { withLifecycle } from "../../core/compose/features/lifecycle.js";
+import { createElementConfig } from "../../core/config/component.js";
+import { createEmitter } from "../../core/state/emitter.js";
+import { mountRailRipple } from "./ripple.js";
+import { createBaseConfig } from "./config.js";
+const copyItems = (items) => {
+    const ids = new Set();
+    let selected = false;
+    return items.map(item => {
+        if (!item.id || !item.label || !item.icon || ids.has(item.id))
+            throw new Error('NavigationRail destinations require unique IDs, labels, and icons');
+        ids.add(item.id);
+        const active = !!item.active && !item.disabled && !selected;
+        selected || (selected = active);
+        return { ...item, active };
+    });
+};
+export default function createNavigationRail(config = {}) {
+    const options = createBaseConfig(config);
+    let items = copyItems(options.items || []);
+    const component = pipe(createBase, withElement(createElementConfig(options, { tag: options.layout === 'modal' ? 'dialog' : 'nav', attributes: { 'aria-label': options.ariaLabel || 'Primary navigation' } })), withLifecycle())(options);
+    const root = component.element;
+    const getClass = component.getClass;
+    const cls = (part) => getClass(`navigation-rail${part}`);
+    const emitter = createEmitter();
+    let expanded = !!options.expanded;
+    let destroyed = false;
+    let connectionObserver = null;
+    const dialog = options.layout === 'modal' ? root : null;
+    if (dialog)
+        root.classList.add(cls('--modal'));
+    if (options.hideWhenCollapsed)
+        root.classList.add(cls('--hide-collapsed'));
+    const nodes = new Map();
+    const destinations = document.createElement('div');
+    destinations.className = cls('__items');
+    const header = document.createElement('div');
+    header.className = cls('__header');
+    let toggle = null;
+    if (options.showToggle) {
+        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)
+        header.append(options.header);
+    if (header.childElementCount)
+        root.append(header);
+    root.append(destinations);
+    root.style.setProperty(`--${options.prefix}-navigation-rail-expanded-width`, `${options.expandedWidth}px`);
+    const updateBadge = (item, element) => {
+        let badge = element.querySelector(`.${cls('__badge')}`);
+        const visible = item.badge !== undefined && item.badge !== false && item.badge !== '';
+        if (!visible) {
+            badge?.remove();
+            element.setAttribute('aria-label', item.label);
+            return;
+        }
+        if (!badge) {
+            badge = document.createElement('span');
+            badge.className = cls('__badge');
+            badge.setAttribute('aria-hidden', 'true');
+            element.querySelector(`.${cls("__content")}`).append(badge);
+        }
+        badge.classList.toggle(cls('__badge--dot'), item.badge === true);
+        badge.textContent = item.badge === true ? '' : String(item.badge);
+        element.setAttribute('aria-label', `${item.label}, ${item.badgeLabel || (item.badge === true ? 'New activity' : String(item.badge))}`);
+    };
+    const updateSelection = () => {
+        for (const item of items) {
+            const element = nodes.get(item.id);
+            element.classList.toggle(cls('__item--active'), !!item.active);
+            if (item.active)
+                element.setAttribute('aria-current', 'page');
+            else
+                element.removeAttribute('aria-current');
+            const icon = element.querySelector(`.${cls('__icon')}`);
+            icon.innerHTML = item.active && item.activeIcon ? item.activeIcon : item.icon;
+        }
+    };
+    const render = () => {
+        const focusedId = [...nodes].find(([, element]) => element === document.activeElement)?.[0];
+        nodes.clear();
+        destinations.replaceChildren();
+        for (const item of items) {
+            const element = document.createElement(item.href ? 'a' : 'button');
+            if (item.href) {
+                if (!item.disabled)
+                    element.setAttribute("href", item.href);
+                else {
+                    element.setAttribute('role', 'link');
+                    element.tabIndex = -1;
+                }
+            }
+            else {
+                element.setAttribute('type', 'button');
+                if (item.disabled)
+                    element.setAttribute('disabled', '');
+            }
+            if (item.disabled)
+                element.setAttribute('aria-disabled', 'true');
+            element.className = cls('__item');
+            element.dataset.id = item.id;
+            const indicator = document.createElement('span');
+            indicator.className = cls('__indicator');
+            indicator.setAttribute('aria-hidden', 'true');
+            const icon = document.createElement('span');
+            icon.className = cls('__icon');
+            icon.setAttribute('aria-hidden', 'true');
+            const label = document.createElement('span');
+            label.className = cls('__label');
+            label.textContent = item.label;
+            const content = document.createElement('span');
+            content.className = cls('__content');
+            content.append(indicator, icon, label);
+            element.append(content);
+            updateBadge(item, element);
+            nodes.set(item.id, element);
+            destinations.append(element);
+        }
+        updateSelection();
+        if (focusedId) {
+            const previous = nodes.get(focusedId);
+            const target = previous && !previous.hasAttribute('aria-disabled') ? previous : [...nodes.values()].find(element => !element.hasAttribute('aria-disabled')) || toggle;
+            target?.focus();
+        }
+    };
+    const showModal = () => {
+        if (!dialog || destroyed || !expanded)
+            return;
+        if (root.isConnected) {
+            connectionObserver?.disconnect();
+            connectionObserver = null;
+            if (!dialog.open)
+                dialog.showModal();
+        }
+        else if (!connectionObserver) {
+            connectionObserver = new MutationObserver(showModal);
+            connectionObserver.observe(root.ownerDocument, { childList: true, subtree: true });
+        }
+    };
+    const synchronize = () => {
+        root.classList.toggle(cls('--expanded'), expanded);
+        toggle?.setAttribute('aria-expanded', String(expanded));
+        toggle?.setAttribute('aria-label', (expanded ? options.collapseLabel : options.expandLabel));
+        if (dialog) {
+            if (expanded)
+                showModal();
+            else {
+                connectionObserver?.disconnect();
+                connectionObserver = null;
+                if (dialog.open)
+                    dialog.close();
+            }
+        }
+        else if (options.hideWhenCollapsed) {
+            root.toggleAttribute('inert', !expanded);
+            root.setAttribute('aria-hidden', String(!expanded));
+        }
+    };
+    const setExpanded = (value) => {
+        if (destroyed || expanded === value)
+            return api;
+        expanded = value;
+        synchronize();
+        emitter.emit(value ? 'expand' : 'collapse', { expanded: value });
+        if (!destroyed) {
+            if (value)
+                options.onExpand?.();
+            else
+                options.onCollapse?.();
+        }
+        return api;
+    };
+    const handleClick = (event) => {
+        if (destroyed || event.defaultPrevented)
+            return;
+        const target = event.target;
+        if (dialog && target === root) {
+            const rect = root.getBoundingClientRect();
+            if (event.clientX < rect.left || event.clientX > rect.right || event.clientY < rect.top || event.clientY > rect.bottom)
+                api.collapse();
+            return;
+        }
+        if (toggle?.contains(target)) {
+            api.toggle();
+            return;
+        }
+        const element = target.closest(`.${cls('__item')}`);
+        if (!element || !destinations.contains(element))
+            return;
+        const index = items.findIndex(item => nodes.get(item.id) === element), item = items[index];
+        if (!item || item.disabled) {
+            event.preventDefault();
+            return;
+        }
+        if (item.href && (event.ctrlKey || event.metaKey || event.shiftKey || event.altKey || event.button !== 0))
+            return;
+        api.setActive(item.id);
+        const detail = { id: item.id, index, originalEvent: event };
+        emitter.emit('select', detail);
+        if (!destroyed)
+            options.onSelect?.(detail);
+    };
+    const handleKeydown = (event) => {
+        const enabled = [...nodes.values()].filter(element => !element.hasAttribute('aria-disabled'));
+        const index = enabled.indexOf(document.activeElement);
+        if (index < 0 || event.altKey || event.ctrlKey || event.metaKey)
+            return;
+        let next;
+        switch (event.key) {
+            case 'ArrowDown':
+                next = (index + 1) % enabled.length;
+                break;
+            case 'ArrowUp':
+                next = (index + enabled.length - 1) % enabled.length;
+                break;
+            case 'Home':
+                next = 0;
+                break;
+            case 'End':
+                next = enabled.length - 1;
+                break;
+            default: return;
+        }
+        event.preventDefault();
+        enabled[next].focus();
+    };
+    const modalTab = (event) => {
+        if (event.key !== 'Tab' || event.defaultPrevented)
+            return;
+        const focusable = [...root.querySelectorAll('button, a[href], input, select, textarea, [tabindex]')].filter(element => element.tabIndex >= 0 && !element.matches(':disabled, [aria-disabled="true"]') && element.getClientRects().length > 0);
+        const first = focusable[0], last = focusable.at(-1), focused = root.ownerDocument.activeElement;
+        if (!first) {
+            event.preventDefault();
+            root.focus();
+        }
+        else if (event.shiftKey && (focused === first || focused === root)) {
+            event.preventDefault();
+            last.focus();
+        }
+        else if (!event.shiftKey && (focused === last || focused === root)) {
+            event.preventDefault();
+            first.focus();
+        }
+    };
+    dialog?.addEventListener('keydown', modalTab);
+    const dismiss = (event) => { event.preventDefault(); api.collapse(); };
+    dialog?.addEventListener('cancel', dismiss);
+    const closed = () => {
+        if (!dialog?.open)
+            api.collapse();
+    };
+    dialog?.addEventListener('close', closed);
+    root.addEventListener('click', handleClick);
+    destinations.addEventListener('keydown', handleKeydown);
+    const removeRipple = options.ripple ? mountRailRipple(root, cls) : undefined;
+    const originalDestroy = component.lifecycle.destroy.bind(component.lifecycle);
+    const destroy = () => {
+        if (destroyed)
+            return;
+        destroyed = true;
+        connectionObserver?.disconnect();
+        connectionObserver = null;
+        dialog?.removeEventListener('keydown', modalTab);
+        dialog?.removeEventListener('cancel', dismiss);
+        dialog?.removeEventListener('close', closed);
+        if (dialog?.open)
+            dialog.close();
+        root.removeEventListener('click', handleClick);
+        destinations.removeEventListener('keydown', handleKeydown);
+        removeRipple?.();
+        nodes.clear();
+        emitter.clear();
+        originalDestroy();
+    };
+    component.lifecycle.destroy = destroy;
+    const api = {
+        element: root, getClass, lifecycle: component.lifecycle, destroy,
+        expand: () => setExpanded(true), collapse: () => setExpanded(false), toggle: () => setExpanded(!expanded), isExpanded: () => expanded,
+        getActive: () => items.find(item => item.active)?.id || null,
+        setActive(id) {
+            if (destroyed || (id !== null && !items.some(item => item.id === id && !item.disabled)))
+                return api;
+            items = items.map(item => ({ ...item, active: item.id === id }));
+            updateSelection();
+            return api;
+        },
+        getItems: () => items.map(item => ({ ...item })),
+        setItems(value) {
+            if (!destroyed) {
+                const next = copyItems(value);
+                items = next;
+                render();
+            }
+            return api;
+        },
+        setBadge(id, badge, label) {
+            if (destroyed)
+                return api;
+            const item = items.find(item => item.id === id);
+            if (item) {
+                item.badge = badge;
+                item.badgeLabel = label;
+                updateBadge(item, nodes.get(id));
+            }
+            return api;
+        },
+        on(event, handler) {
+            if (!destroyed)
+                emitter.on(event, handler);
+            return api;
+        },
+        off(event, handler) { emitter.off(event, handler); return api; },
+    };
+    render();
+    synchronize();
+    return api;
+}

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

@@ -0,0 +1,2 @@
+/** A CSS-animated state layer with no document listeners, timers, or animation frames. */
+export declare function mountRailRipple(root: HTMLElement, className: (part: string) => string): () => void;

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

@@ -0,0 +1,41 @@
+export function mountRailRipple(root, className) {
+    const waveClass = className('__ripple');
+    const press = (event) => {
+        const target = event.target.closest(`.${className('__item')}, .${className('__toggle')}`);
+        if (!target || !root.contains(target) || target.hasAttribute('aria-disabled'))
+            return;
+        if (event instanceof KeyboardEvent && (event.repeat || !['Enter', ' '].includes(event.key)))
+            return;
+        if (event.type === 'pointerdown' && event.button !== 0)
+            return;
+        if (root.ownerDocument.defaultView?.matchMedia?.('(prefers-reduced-motion: reduce)').matches)
+            return;
+        const host = target.querySelector(`.${className('__indicator')}`) || target;
+        const bounds = host.getBoundingClientRect();
+        const wave = document.createElement('span');
+        wave.className = waveClass;
+        wave.setAttribute('aria-hidden', 'true');
+        const size = Math.max(bounds.width, bounds.height) * 2;
+        const pointer = event instanceof MouseEvent;
+        wave.style.width = wave.style.height = `${size}px`;
+        wave.style.left = `${(pointer ? event.clientX - bounds.left : bounds.width / 2) - size / 2}px`;
+        wave.style.top = `${(pointer ? event.clientY - bounds.top : bounds.height / 2) - size / 2}px`;
+        host.append(wave);
+    };
+    const finish = (event) => {
+        const target = event.target;
+        if (target.classList.contains(waveClass))
+            target.remove();
+    };
+    root.addEventListener('pointerdown', press);
+    root.addEventListener('keydown', press);
+    root.addEventListener('animationend', finish);
+    root.addEventListener('animationcancel', finish);
+    return () => {
+        root.removeEventListener('pointerdown', press);
+        root.removeEventListener('keydown', press);
+        root.removeEventListener('animationend', finish);
+        root.removeEventListener('animationcancel', finish);
+        root.querySelectorAll(`.${waveClass}`).forEach(wave => wave.remove());
+    };
+}

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

@@ -0,0 +1,68 @@
+import type { BaseComponentConfig } from "../../core/config/component.js";
+/** A primary destination. Icons are trusted SVG/HTML supplied by the application. */
+export interface NavigationRailItemConfig {
+    id: string;
+    label: string;
+    icon: string;
+    activeIcon?: string;
+    href?: string;
+    badge?: string | number | boolean;
+    /** Accessible description for a dot badge or count, e.g. "3 unread messages". */
+    badgeLabel?: string;
+    active?: boolean;
+    disabled?: boolean;
+}
+export interface NavigationRailSelectEvent {
+    id: string;
+    index: number;
+    originalEvent: MouseEvent;
+}
+export interface NavigationRailEvents {
+    select: NavigationRailSelectEvent;
+    expand: {
+        expanded: true;
+    };
+    collapse: {
+        expanded: false;
+    };
+}
+/** Standalone, non-modal M3 Expressive navigation rail. */
+export interface NavigationRailConfig extends BaseComponentConfig {
+    items?: NavigationRailItemConfig[];
+    expanded?: boolean;
+    /** Standard rail occupies layout space; modal expansion uses a native modal dialog. */
+    layout?: 'standard' | 'modal';
+    /** Hide the standard rail when collapsed. Modal rails always hide when collapsed. */
+    hideWhenCollapsed?: boolean;
+    /** Expanded width in CSS pixels, clamped to the Android token range 220–360. Default 280. */
+    expandedWidth?: number;
+    /** Show the accessible expand/collapse menu button. Default true. */
+    showToggle?: boolean;
+    expandLabel?: string;
+    collapseLabel?: string;
+    /** Optional application-owned header, such as a FAB. Its lifecycle stays with its owner. */
+    header?: HTMLElement;
+    ripple?: boolean;
+    onSelect?: (event: NavigationRailSelectEvent) => void;
+    onExpand?: () => void;
+    onCollapse?: () => void;
+}
+export interface NavigationRailComponent {
+    element: HTMLElement;
+    getClass: (name: string) => string;
+    expand: () => NavigationRailComponent;
+    collapse: () => NavigationRailComponent;
+    toggle: () => NavigationRailComponent;
+    isExpanded: () => boolean;
+    setActive: (id: string | null) => NavigationRailComponent;
+    getActive: () => string | null;
+    setItems: (items: NavigationRailItemConfig[]) => NavigationRailComponent;
+    getItems: () => NavigationRailItemConfig[];
+    setBadge: (id: string, badge: NavigationRailItemConfig['badge'], label?: string) => NavigationRailComponent;
+    on: <K extends keyof NavigationRailEvents>(event: K, handler: (detail: NavigationRailEvents[K]) => void) => NavigationRailComponent;
+    off: <K extends keyof NavigationRailEvents>(event: K, handler: (detail: NavigationRailEvents[K]) => void) => NavigationRailComponent;
+    destroy: () => void;
+    lifecycle: {
+        destroy: () => void;
+    };
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -5,6 +5,12 @@ export const withTextLabel = (config = {}) => (component) => {
     const position = config.labelPosition || "start";
     labelElement.className = `${config.prefix}-${config.componentName}-label ${config.prefix}-${config.componentName}-label--${position}`;
     labelElement.textContent = config.label;
+    const input = component.input;
+    if (input instanceof HTMLElement) {
+        if (!input.id)
+            input.id = `${config.prefix}-${config.componentName}-${Math.random().toString(36).slice(2, 9)}`;
+        labelElement.htmlFor = input.id;
+    }
     if (position === "start") {
         if (component.element.firstChild) {
             component.element.insertBefore(labelElement, component.element.firstChild);

package/dist/core/config/global.d.ts

@@ -5,6 +5,7 @@
  * without adding complexity or performance overhead.
  */
 import { ButtonConfig } from "../../components/button/types.js";
+import type { NavigationRailConfig } from "../../components/navigation-rail/types.js";
 import { TextfieldConfig } from "../../components/textfield/types.js";
 /**
  * Component configuration map
@@ -13,6 +14,7 @@ import { TextfieldConfig } from "../../components/textfield/types.js";
  * For components not yet integrated, use Partial<any> as a placeholder
  */
 export interface ComponentConfigMap {
+    "navigation-rail"?: Partial<NavigationRailConfig>;
     button?: Partial<ButtonConfig>;
     textfield?: Partial<TextfieldConfig>;
     checkbox?: Partial<any>;

package/dist/core/utils/theme.js

@@ -68,7 +68,7 @@ export function getThemeColor(varName, options) {
     return value;
 }
 if (typeof window !== 'undefined') {
-    window.addEventListener('unload', () => {
+    window.addEventListener('pagehide', () => {
         if (themeObserver) {
             themeObserver.disconnect();
             themeObserver = null;