material 1.0.4 → 3.0.0-next.0

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

@@ -0,0 +1,157 @@
+import { PREFIX } from "../../core/config.js";
+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 { activeElementOf } from "../../core/dom/focus.js";
+import { mountRailRipple } from "../../core/navigation/ripple.js";
+import { copyDestinations, createDestination, moveDestinationFocus, updateBadge, updateSelection, } from "../../core/navigation/destinations.js";
+import { createBaseConfig } from "./config.js";
+const SCROLL_THRESHOLD = 10;
+export default function createNavigationBar(config = {}) {
+    const options = createBaseConfig(config);
+    let items = copyDestinations(options.items || [], 'NavigationBar');
+    const component = pipe(createBase, withElement(createElementConfig(options, { tag: 'nav', attributes: { 'aria-label': options.ariaLabel || 'Primary navigation' } })), withLifecycle())(options);
+    const root = component.element;
+    const getClass = component.getClass;
+    const cls = (part) => getClass(`navigation-bar${part}`);
+    const emitter = createEmitter();
+    let destroyed = false;
+    let hidden = false;
+    root.classList.add(options.itemLayout === 'vertical' ? cls('--vertical') : options.itemLayout === 'horizontal' ? cls('--horizontal') : cls('--auto'));
+    const nodes = new Map();
+    const destinations = document.createElement('div');
+    destinations.className = cls('__items');
+    root.append(destinations);
+    const render = () => {
+        const focusedId = [...nodes].find(([, element]) => element === activeElementOf(destinations))?.[0];
+        nodes.clear();
+        destinations.replaceChildren();
+        for (const item of items) {
+            const element = createDestination(item, cls);
+            nodes.set(item.id, element);
+            destinations.append(element);
+        }
+        updateSelection(items, nodes, cls);
+        root.style.setProperty(`--${PREFIX}-navigation-bar-count`, String(items.length));
+        if (focusedId) {
+            const previous = nodes.get(focusedId);
+            const target = previous && !previous.hasAttribute('aria-disabled') ? previous : [...nodes.values()].find((element) => !element.hasAttribute('aria-disabled'));
+            target?.focus();
+        }
+    };
+    const setHidden = (value) => {
+        if (destroyed || hidden === value)
+            return;
+        hidden = value;
+        root.classList.toggle(cls('--hidden'), value);
+        emitter.emit('visibility', { hidden: value });
+    };
+    const handleClick = (event) => {
+        if (destroyed || event.defaultPrevented)
+            return;
+        const element = event.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, value: item.id, index, originalEvent: event };
+        emitter.emit('select', detail);
+    };
+    const handleKeydown = (event) => {
+        const rtl = getComputedStyle(root).direction === 'rtl';
+        moveDestinationFocus(event, nodes, destinations, rtl ? { next: 'ArrowLeft', previous: 'ArrowRight' } : { next: 'ArrowRight', previous: 'ArrowLeft' });
+    };
+    const handleFocus = () => setHidden(false);
+    const scrollOption = options.hideOnScroll;
+    const scrollTarget = scrollOption
+        ? (typeof scrollOption === 'object' && scrollOption.target) || window
+        : null;
+    let lastScroll = null;
+    const scrollPosition = () => (scrollTarget === window ? window.scrollY : scrollTarget.scrollTop);
+    const handleScroll = () => {
+        const current = scrollPosition();
+        if (lastScroll === null) {
+            lastScroll = current;
+            return;
+        }
+        if (current > lastScroll + SCROLL_THRESHOLD)
+            setHidden(true);
+        else if (current < lastScroll - SCROLL_THRESHOLD)
+            setHidden(false);
+        else
+            return;
+        lastScroll = current;
+    };
+    root.addEventListener('click', handleClick);
+    destinations.addEventListener('keydown', handleKeydown);
+    root.addEventListener('focusin', handleFocus);
+    scrollTarget?.addEventListener('scroll', handleScroll, { passive: true });
+    const removeRipple = options.ripple ? mountRailRipple(root, cls) : undefined;
+    const originalDestroy = component.lifecycle.destroy.bind(component.lifecycle);
+    const destroy = () => {
+        if (destroyed)
+            return;
+        destroyed = true;
+        root.removeEventListener('click', handleClick);
+        destinations.removeEventListener('keydown', handleKeydown);
+        root.removeEventListener('focusin', handleFocus);
+        scrollTarget?.removeEventListener('scroll', handleScroll);
+        removeRipple?.();
+        nodes.clear();
+        emitter.clear();
+        originalDestroy();
+    };
+    component.lifecycle.destroy = destroy;
+    const api = {
+        element: root, getClass, lifecycle: component.lifecycle, destroy,
+        getActive: () => items.find((item) => item.active)?.id || null,
+        getValue: () => api.getActive(),
+        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(items, nodes, cls);
+            return api;
+        },
+        getItems: () => items.map((item) => ({ ...item })),
+        setItems(value) {
+            if (!destroyed) {
+                items = copyDestinations(value, 'NavigationBar');
+                render();
+            }
+            return api;
+        },
+        setBadge(id, badge, label) {
+            if (destroyed)
+                return api;
+            const item = items.find((entry) => entry.id === id);
+            if (item) {
+                item.badge = badge;
+                item.badgeLabel = label;
+                updateBadge(item, nodes.get(id), cls);
+            }
+            return api;
+        },
+        hide: () => { setHidden(true); return api; },
+        show: () => { setHidden(false); return api; },
+        isHidden: () => hidden,
+        on(event, handler) {
+            if (!destroyed)
+                emitter.on(event, handler);
+            return api;
+        },
+        off(event, handler) { emitter.off(event, handler); return api; },
+    };
+    render();
+    if (options.onSelect)
+        api.on('select', options.onSelect);
+    return api;
+}

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

@@ -0,0 +1,72 @@
+import type { DestinationConfig } from "../../core/navigation/destinations.js";
+/** One destination of the bar: a link (`href`) or a button. */
+export type NavigationBarItemConfig = DestinationConfig;
+/** What `select` and `onSelect` carry: the destination chosen by click or keyboard. */
+export interface NavigationBarSelectEvent {
+    id: string;
+    /** The id, as `<m-navigation-bar>`'s `change` carries it */
+    value: string;
+    index: number;
+    originalEvent: MouseEvent;
+}
+export interface NavigationBarEvents {
+    select: NavigationBarSelectEvent;
+    /** The bar was hidden (`hidden: true`) or shown again, by scroll or by `hide()`/`show()` */
+    visibility: {
+        hidden: boolean;
+    };
+}
+/**
+ * Where an item puts its icon. `'vertical'`: above the label, the compact bar.
+ * `'horizontal'`: beside it, M3 Expressive's medium-width bar, with the items
+ * centred. `'auto'` (the default) is vertical, and horizontal while the bar
+ * itself is at least 600px wide: a CSS container query on the bar, so a bar in
+ * a narrow pane stays vertical in a wide window. Compose leaves the choice to
+ * the caller; MDC-Android puts the threshold at 600dp.
+ */
+export type NavigationBarItemLayout = 'auto' | 'vertical' | 'horizontal';
+export interface NavigationBarConfig {
+    /** Three to five destinations (M3) */
+    items?: NavigationBarItemConfig[];
+    itemLayout?: NavigationBarItemLayout;
+    /**
+     * Hides the bar while the page scrolls down and shows it when it scrolls
+     * up, as the bottom app bar's `autoHide`. `true` follows the window; pass an
+     * element to follow its scroll instead. Off by default: M3's guidelines
+     * advise against hiding navigation while a screen reader is in use, which a
+     * page can't detect. Focus inside the bar always shows it.
+     */
+    hideOnScroll?: boolean | {
+        target?: HTMLElement | Window;
+    };
+    /** The landmark's name; default "Primary navigation" */
+    ariaLabel?: string;
+    ripple?: boolean;
+    /** `select` listener registered at creation. */
+    onSelect?: (event: NavigationBarEvents["select"]) => void;
+    class?: string;
+    prefix?: string;
+    componentName?: string;
+}
+export interface NavigationBarComponent {
+    element: HTMLElement;
+    getClass: (name: string) => string;
+    lifecycle: {
+        destroy: () => void;
+    };
+    getActive: () => string | null;
+    /** The active destination's id, as getActive(): the value getter every component has (FLO-380) */
+    getValue: () => string | null;
+    /** Marks a destination active, silently (no `select`); `null` clears it */
+    setActive: (id: string | null) => NavigationBarComponent;
+    getItems: () => NavigationBarItemConfig[];
+    setItems: (items: NavigationBarItemConfig[]) => NavigationBarComponent;
+    setBadge: (id: string, badge: NavigationBarItemConfig['badge'], label?: string) => NavigationBarComponent;
+    /** Slides the bar out of view (without the slide under reduced motion) */
+    hide: () => NavigationBarComponent;
+    show: () => NavigationBarComponent;
+    isHidden: () => boolean;
+    on: <K extends keyof NavigationBarEvents>(event: K, handler: (payload: NavigationBarEvents[K]) => void) => NavigationBarComponent;
+    off: <K extends keyof NavigationBarEvents>(event: K, handler: (payload: NavigationBarEvents[K]) => void) => NavigationBarComponent;
+    destroy: () => void;
+}

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

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

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,15 @@
+import { createComponentConfig } from "../../core/config/component.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)
+        ? 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,14 @@
+/** 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;
+};
+/** 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

@@ -0,0 +1,12 @@
+export const NAVIGATION_RAIL_DEFAULTS = {
+    EXPANDED: false,
+    COLLAPSED_WIDTH: 96,
+    EXPANDED_WIDTH: 280,
+    MIN_EXPANDED_WIDTH: 220,
+    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/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 `material/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,251 @@
+import { PREFIX } from "../../core/config.js";
+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 "../../core/navigation/ripple.js";
+import { createBaseConfig } from "./config.js";
+import { setHTML } from "../../core/dom/html.js";
+import { activeElementOf } from "../../core/dom/focus.js";
+import { copyDestinations, createDestination, moveDestinationFocus, updateBadge as updateDestinationBadge, updateSelection as updateDestinations } from "../../core/navigation/destinations.js";
+const copyItems = (items) => copyDestinations(items, 'NavigationRail');
+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 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)
+        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');
+        header.append(toggle);
+    }
+    if (options.header)
+        header.append(options.header);
+    if (header.childElementCount)
+        root.append(header);
+    root.append(destinations);
+    root.style.setProperty(`--${PREFIX}-navigation-rail-expanded-width`, `${options.expandedWidth}px`);
+    const updateBadge = (item, element) => updateDestinationBadge(item, element, cls);
+    const updateSelection = () => updateDestinations(items, nodes, cls);
+    const render = () => {
+        const focusedId = [...nodes].find(([, element]) => element === activeElementOf(destinations))?.[0];
+        nodes.clear();
+        destinations.replaceChildren();
+        for (const item of items) {
+            const element = createDestination(item, cls);
+            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 (toggle)
+            setHTML(toggle, (expanded ? options.collapseIcon : options.expandIcon));
+        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;
+        startSwitch();
+        synchronize();
+        emitter.emit(value ? 'expand' : 'collapse', { expanded: value });
+        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, value: item.id, index, originalEvent: event };
+        emitter.emit('select', detail);
+    };
+    const handleKeydown = (event) => {
+        moveDestinationFocus(event, nodes, destinations, { next: 'ArrowDown', previous: 'ArrowUp' });
+    };
+    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 = activeElementOf(root);
+        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;
+        endSwitch();
+        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,
+        getValue: () => api.getActive(),
+        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();
+    if (options.onSelect)
+        api.on('select', options.onSelect);
+    if (options.onExpand)
+        api.on('expand', options.onExpand);
+    if (options.onCollapse)
+        api.on('collapse', options.onCollapse);
+    return api;
+}

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

@@ -0,0 +1,91 @@
+import type { BaseComponentConfig } from "../../core/config/component.js";
+/** A primary destination. Icons are markup supplied by the application. */
+export interface NavigationRailItemConfig {
+    id: string;
+    label: string;
+    /** Markup (HTML). Not sanitized by default: see Markup and sanitizing. */
+    icon: string;
+    /** Markup (HTML). Not sanitized by default: see Markup and sanitizing. Shown while this destination is active. */
+    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;
+    /** The id again, as the `value` of the `<m-navigation-rail>` element's `change` (FLO-320) */
+    value: 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;
+    /** Menu button icon while collapsed. Default: Material Symbols `menu`. Markup (HTML). Not sanitized by default: see Markup and sanitizing. */
+    expandIcon?: string;
+    /** Menu button icon while expanded. Default: Material Symbols `menu_open`. Markup (HTML). Not sanitized by default: see Markup and sanitizing. */
+    collapseIcon?: string;
+    /** Optional application-owned header, such as a FAB. Its lifecycle stays with its owner. */
+    header?: HTMLElement;
+    ripple?: boolean;
+    /** `select` listener registered at creation. */
+    onSelect?: (event: NavigationRailEvents["select"]) => void;
+    /** `expand` listener registered at creation. The argument is `{ expanded: true }`. */
+    onExpand?: (event: NavigationRailEvents["expand"]) => void;
+    /** `collapse` listener registered at creation. The argument is `{ expanded: false }`. */
+    onCollapse?: (event: NavigationRailEvents["collapse"]) => 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;
+    /** Reads the current model value without changing selection. */
+    getValue: () => 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;
+    };
+}
+/**
+ * Registers NavigationRailConfig with the global defaults map, so
+ * `setComponentDefaults("navigation-rail", ...)` is typed without core
+ * importing anything from this component. FLO-115.
+ */
+declare module "../../core/config/global" {
+    interface ComponentConfigMap {
+        "navigation-rail"?: Partial<NavigationRailConfig>;
+    }
+}

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

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