material 1.0.3 → 3.0.0-next.0

package/dist/elements/bottom-sheet.d.ts

@@ -0,0 +1,130 @@
+/**
+ * `<m-bottom-sheet>`: the bottom sheet as a custom element. Its regions are
+ * slots: `headline` (the `headline` attribute is its fallback text), which
+ * names the sheet, and the default slot, the content. The drag handle is the
+ * factory's; `no-drag-handle` drops it, and dragging with it.
+ *
+ * Standard by default, in the page beside what it covers. `modal` makes it
+ * the modal sheet in the factory's top layer (`layer: "top"`): a native
+ * `<dialog>` in the element's shadow root, shown with `showModal()`, above
+ * every z-index, the page outside inert, the scrim its `::backdrop`; Escape
+ * and a click on the backdrop close it.
+ *
+ * `open` shows it and reflects its state, as on `<dialog open>`. `show()`,
+ * `close()`, `expand()` and `collapse()` are its methods, and `open` and
+ * `close` are dispatched as it opens and closes (not when the attribute is
+ * what changed).
+ *
+ * An open sheet is partially expanded, `peek-height` pixels tall (by
+ * default its content up to half the screen), or with `expanded` at its full
+ * height. `max-width` is the widest it grows, in pixels (640 by default),
+ * past which it centres itself; a change recreates it. `expanded` reflects that state as `open` does: set while the sheet
+ * is closed, it opens expanded. `expand` and `collapse` are dispatched as the
+ * user or a method moves it to its full height and away from it, closing
+ * included, so an app keeping `expanded` in its state follows them.
+ * `no-close-on-scrim-click` and `no-close-on-escape` keep a modal sheet open
+ * on a click on the scrim and on Escape.
+ *
+ * Parts: `bottom-sheet`, `container`, `handle`, `header`, `title`, `content`.
+ *
+ * @module elements
+ */
+import type { BottomSheetComponent, BottomSheetEventHandlers } from "../components/bottom-sheet/types.js";
+import { type DefineOptions, type ElementInstance } from "./define.js";
+/** The sheet's events, and `expand` and `collapse`, which the element tells apart from its state changes. */
+export interface BottomSheetElementEvents extends BottomSheetEventHandlers {
+    expand?: () => void;
+    collapse?: () => void;
+}
+/** The sheet with the `show()` the element names after `<dialog>`'s, and its `expand` and `collapse` events. */
+export interface BottomSheetElementComponent extends Omit<BottomSheetComponent, "on" | "off"> {
+    show: () => BottomSheetComponent;
+    on: <T extends keyof BottomSheetElementEvents>(event: T, handler: NonNullable<BottomSheetElementEvents[T]>) => unknown;
+    off: <T extends keyof BottomSheetElementEvents>(event: T, handler: NonNullable<BottomSheetElementEvents[T]>) => unknown;
+}
+declare const bottomSheetSpec: {
+    name: string;
+    slots: readonly ["headline"];
+    create: (config: import("./define.js").Config) => BottomSheetElementComponent;
+    styles: string[];
+    hostStyles: string;
+    attributes: {
+        open: {
+            type: "boolean";
+            update: (c: BottomSheetElementComponent, v: import("./define.js").AttributeValue, host: HTMLElement) => void;
+        };
+        expanded: {
+            type: "boolean";
+            update: (c: BottomSheetElementComponent, v: import("./define.js").AttributeValue) => void;
+        };
+        modal: {
+            type: "boolean";
+            config: string;
+        };
+        headline: {
+            type: "string";
+            config: string;
+            update: (c: BottomSheetElementComponent, v: import("./define.js").AttributeValue, host: HTMLElement) => void;
+        };
+        "peek-height": {
+            type: "number";
+            config: string;
+        };
+        "max-width": {
+            type: "number";
+            config: string;
+        };
+        "no-drag-handle": {
+            type: "boolean";
+            config: string;
+        };
+        "no-close-on-scrim-click": {
+            type: "boolean";
+            config: string;
+        };
+        "no-close-on-escape": {
+            type: "boolean";
+            config: string;
+        };
+        "aria-label": {
+            type: "string";
+            update: (c: BottomSheetElementComponent, _v: import("./define.js").AttributeValue, host: HTMLElement) => void;
+        };
+    };
+    methods: readonly ["show", "close", "expand", "collapse"];
+    events: {
+        open: {
+            detail: () => null;
+            state: true;
+        };
+        close: {
+            detail: () => null;
+            state: true;
+        };
+        expand: {
+            detail: () => null;
+            state: true;
+        };
+        collapse: {
+            detail: () => null;
+            state: true;
+        };
+    };
+    config: (host: HTMLElement) => {
+        host: HTMLElement;
+    };
+    setup: (host: import("./define.js").ElementHost<BottomSheetElementComponent>, component: BottomSheetElementComponent) => () => void;
+};
+export declare const bottomSheetElement: import("./define.js").ElementDefinition<BottomSheetElementComponent>;
+export type BottomSheetSpec = typeof bottomSheetSpec;
+/** `<m-bottom-sheet>` as a ref or a query returns it. */
+export type BottomSheetElement = ElementInstance<BottomSheetSpec, BottomSheetElementComponent>;
+/** Registers `<m-bottom-sheet>` (or `<prefix-bottom-sheet>`). */
+export declare const defineBottomSheet: (options?: DefineOptions) => string;
+declare global {
+    /** `document.querySelector("m-…")` and `createElement` return the element's type (the default prefix). */
+    interface HTMLElementTagNameMap {
+        "m-bottom-sheet": BottomSheetElement;
+    }
+}
+export {};

package/dist/elements/bottom-sheet.js

@@ -0,0 +1,96 @@
+import createBottomSheet from "../components/bottom-sheet/index.js";
+import { defineElement } from "./define.js";
+import { headlineSlot, setHeadline, setSheetOpen, sheetSetup, syncSheet } from "./sheet.js";
+const PARTS = {
+    container: "bottom-sheet__container",
+    header: "bottom-sheet__header",
+    title: "bottom-sheet__title",
+};
+const create = (config) => {
+    const { host, headline, modal, noDragHandle, noCloseOnScrimClick, noCloseOnEscape, ...rest } = config;
+    const content = document.createElement("slot");
+    const sheet = createBottomSheet({
+        ...rest,
+        title: " ",
+        content,
+        dragHandle: !noDragHandle,
+        closeOnScrimClick: !noCloseOnScrimClick,
+        closeOnEscape: !noCloseOnEscape,
+        variant: modal ? "modal" : "standard",
+        layer: modal ? "top" : undefined,
+    });
+    headlineSlot(sheet, PARTS, headline);
+    const handlers = { expand: new Set(), collapse: new Set() };
+    sheet.on("stateChange", ({ state, previous }) => {
+        const event = state === "expanded" ? "expand" : previous === "expanded" ? "collapse" : null;
+        if (!event)
+            return;
+        host.toggleAttribute("expanded", state === "expanded");
+        handlers[event].forEach((handler) => handler());
+    });
+    const own = (event) => event === "expand" || event === "collapse";
+    const { on, off } = sheet;
+    return Object.assign(sheet, {
+        show: () => sheet.open(),
+        on: (event, handler) => own(event) ? handlers[event].add(handler) : on.call(sheet, event, handler),
+        off: (event, handler) => own(event) ? handlers[event].delete(handler) : off.call(sheet, event, handler),
+    });
+};
+const setOpen = (component, open, host) => {
+    if (open && !component.isOpen() && host.hasAttribute("expanded"))
+        component.expand();
+    else
+        setSheetOpen(component, open);
+};
+const setExpanded = (component, expanded) => {
+    if (!component.isOpen() || expanded === (component.getState() === "expanded"))
+        return;
+    if (expanded)
+        component.expand();
+    else
+        component.collapse();
+};
+const bottomSheetSpec = {
+    name: "bottom-sheet",
+    slots: ["headline"],
+    create: (config) => create(config),
+    styles: ["bottom-sheet"],
+    hostStyles: ":host{display:contents}",
+    attributes: {
+        open: { type: "boolean", update: (c, v, host) => setOpen(c, !!v, host) },
+        expanded: { type: "boolean", update: (c, v) => setExpanded(c, !!v) },
+        modal: { type: "boolean", config: "modal" },
+        headline: {
+            type: "string",
+            config: "headline",
+            update: (c, v, host) => {
+                setHeadline(c, v);
+                syncSheet(host, c, PARTS);
+            },
+        },
+        "peek-height": { type: "number", config: "peekHeight" },
+        "max-width": { type: "number", config: "maxWidth" },
+        "no-drag-handle": { type: "boolean", config: "noDragHandle" },
+        "no-close-on-scrim-click": { type: "boolean", config: "noCloseOnScrimClick" },
+        "no-close-on-escape": { type: "boolean", config: "noCloseOnEscape" },
+        "aria-label": { type: "string", update: (c, _v, host) => syncSheet(host, c, PARTS) },
+    },
+    methods: ["show", "close", "expand", "collapse"],
+    events: {
+        open: { detail: () => null, state: true },
+        close: { detail: () => null, state: true },
+        expand: { detail: () => null, state: true },
+        collapse: { detail: () => null, state: true },
+    },
+    config: (host) => ({ host }),
+    setup: (host, component) => sheetSetup(host, component, PARTS, (handler) => {
+        component.on("open", handler);
+        component.on("close", handler);
+        return () => {
+            component.off("open", handler);
+            component.off("close", handler);
+        };
+    }, () => setOpen(component, true, host)),
+};
+export const bottomSheetElement = defineElement(bottomSheetSpec);
+export const defineBottomSheet = (options) => bottomSheetElement.define(options);

package/dist/elements/button-group.d.ts

@@ -0,0 +1,164 @@
+/**
+ * `<m-button-group>` with `<m-button-group-item>` children.
+ *
+ * Each `<m-button-group-item>` declares one button (`value`, `icon`,
+ * `selected-icon`, `aria-label`, `disabled`, `selected`, and its text as the
+ * label). The group reads them into the factory's config and updates in place
+ * when they change; the children stay where the framework put them.
+ *
+ * With `selection="single"` or `"multi"` the buttons toggle. `value` on the
+ * group is the default selection (comma-separated in a multi group), which
+ * moves the live one until the user or script changes it; without it, the
+ * items' `selected` is the default. The `value` property is the live
+ * selection: a string or null in a single group, an array in a multi group,
+ * null without selection. Every press dispatches `action` with the button's
+ * value; the factory calls it `click`, which the host already receives from
+ * the browser.
+ *
+ * Parts: `button-group`, `button`, `text`, `ripple`.
+ *
+ * @module elements
+ */
+import type { ButtonGroupComponent } from "../components/button-group/types.js";
+import { type Config, type DefineOptions, type ElementAttributes, type ElementHost, type ElementInstance } from "./define.js";
+/** The live selection: one value, several, or none. */
+export type ButtonGroupValue = string | string[] | null;
+declare const buttonGroupSpec: {
+    name: string;
+    create: (config: Config) => ButtonGroupComponent;
+    styles: string[];
+    attributes: {
+        variant: {
+            type: "string";
+            config: string;
+            update: (c: ButtonGroupComponent, v: import("./define.js").AttributeValue) => undefined;
+        };
+        kind: {
+            type: "string";
+            config: string;
+        };
+        selection: {
+            type: "string";
+            config: string;
+        };
+        required: {
+            type: "boolean";
+            config: string;
+        };
+        size: {
+            type: "string";
+            config: string;
+        };
+        shape: {
+            type: "string";
+            config: string;
+        };
+        labels: {
+            type: "string";
+            config: string;
+        };
+        orientation: {
+            type: "string";
+            config: string;
+            update: (c: ButtonGroupComponent, v: import("./define.js").AttributeValue) => undefined;
+        };
+        density: {
+            type: "string";
+            config: string;
+            update: (c: ButtonGroupComponent, v: import("./define.js").AttributeValue) => undefined;
+        };
+        "equal-width": {
+            type: "boolean";
+            config: string;
+        };
+        "expanded-ratio": {
+            type: "number";
+            config: string;
+        };
+        disabled: {
+            type: "boolean";
+            config: string;
+            update: (c: ButtonGroupComponent, v: import("./define.js").AttributeValue, host: HTMLElement) => void;
+        };
+        "aria-label": {
+            type: "string";
+            config: string;
+            update: (c: ButtonGroupComponent, v: import("./define.js").AttributeValue) => void;
+        };
+        value: {
+            type: "string";
+            update: (c: ButtonGroupComponent, v: import("./define.js").AttributeValue) => void;
+        };
+    };
+    properties: {
+        value: {
+            get: (c: ButtonGroupComponent) => ButtonGroupValue;
+            set: (c: ButtonGroupComponent, v: unknown) => void;
+        };
+    };
+    model: "value";
+    events: {
+        change: {
+            detail: (payload: unknown) => {
+                value: ButtonGroupValue;
+            };
+        };
+        action: {
+            detail: (payload: unknown) => {
+                value: string;
+                index: number;
+            };
+            state: true;
+        };
+    };
+    config: (host: HTMLElement) => Config;
+    setup: (host: ElementHost<ButtonGroupComponent>, component: ButtonGroupComponent) => () => undefined;
+    observeChildren: (host: ElementHost<ButtonGroupComponent>, component: ButtonGroupComponent) => boolean;
+};
+export declare const buttonGroupElement: import("./define.js").ElementDefinition<ButtonGroupComponent>;
+export type ButtonGroupSpec = typeof buttonGroupSpec;
+/** `<m-button-group>` as a ref or a query returns it. */
+export type ButtonGroupElement = ElementInstance<ButtonGroupSpec, ButtonGroupComponent>;
+/**
+ * `<m-button-group-item>` declares one button and renders nothing. Its text
+ * content is the label unless `label` is set.
+ */
+export declare const buttonGroupItemDeclaration: {
+    readonly name: "button-group-item";
+    readonly attributes: {
+        readonly value: {
+            readonly type: "string";
+        };
+        readonly label: {
+            readonly type: "string";
+        };
+        /** Markup (HTML). Not sanitized by default: see Markup and sanitizing. */
+        readonly icon: {
+            readonly type: "string";
+        };
+        /** Markup (HTML). Not sanitized by default: see Markup and sanitizing. Shown on an icon-only item while it is selected. */
+        readonly "selected-icon": {
+            readonly type: "string";
+        };
+        readonly "aria-label": {
+            readonly type: "string";
+        };
+        readonly disabled: {
+            readonly type: "boolean";
+        };
+        readonly selected: {
+            readonly type: "boolean";
+        };
+    };
+};
+export type ButtonGroupItemAttributes = ElementAttributes<typeof buttonGroupItemDeclaration>;
+/** Registers `<m-button-group>` and `<m-button-group-item>` (or with another prefix). */
+export declare const defineButtonGroup: (options?: DefineOptions) => string;
+declare global {
+    /** `document.querySelector("m-…")` and `createElement` return the element's type (the default prefix). */
+    interface HTMLElementTagNameMap {
+        "m-button-group": ButtonGroupElement;
+        "m-button-group-item": HTMLElement & ButtonGroupItemAttributes;
+    }
+}
+export {};

package/dist/elements/button-group.js

@@ -0,0 +1,174 @@
+import createButtonGroup from "../components/button-group/index.js";
+import { createDeclarationClass, defineElement, DEFAULT_PREFIX, } from "./define.js";
+const parse = (value, multi) => {
+    if (value === null || value === undefined || value === "")
+        return [];
+    const all = Array.isArray(value)
+        ? value.map(String)
+        : multi
+            ? String(value).split(",").map((part) => part.trim()).filter(Boolean)
+            : [String(value)];
+    return multi ? all : all.slice(0, 1);
+};
+const declaredItems = (host) => {
+    const itemTag = `${host.localName}-item`;
+    const items = [];
+    for (const child of Array.from(host.children)) {
+        if (child.localName !== itemTag)
+            continue;
+        const text = child.getAttribute("label") ?? (child.textContent ?? "").trim();
+        const icon = child.getAttribute("icon") ?? undefined;
+        const ariaLabel = child.getAttribute("aria-label") ?? undefined;
+        const value = child.getAttribute("value") ?? (text || ariaLabel || String(items.length));
+        const base = {
+            value,
+            icon,
+            selectedIcon: child.getAttribute("selected-icon") ?? undefined,
+            disabled: child.hasAttribute("disabled"),
+            selected: child.hasAttribute("selected"),
+        };
+        items.push(text || !icon ? { ...base, text, ariaLabel } : { ...base, ariaLabel: ariaLabel ?? value });
+    }
+    return items;
+};
+const applied = new WeakMap();
+const readGroup = (host) => {
+    const items = declaredItems(host);
+    const multi = host.getAttribute("selection") === "multi";
+    const chosen = host.hasAttribute("value")
+        ? parse(host.getAttribute("value"), multi)
+        : parse(items.filter((item) => item.selected).map((item) => item.value), multi);
+    applied.set(host, items);
+    return { buttons: items.map((item) => ({ ...item, selected: chosen.includes(item.value) })) };
+};
+const model = (c) => {
+    const selection = c.getSelection();
+    if (selection === "none")
+        return null;
+    const selected = c.getSelected();
+    return selection === "multi" ? selected : (selected[0] ?? null);
+};
+const select = (c, value) => {
+    const selection = c.getSelection();
+    if (selection === "none")
+        return;
+    const wanted = parse(value, selection === "multi");
+    for (const next of wanted)
+        c.select(next);
+    for (const current of c.getSelected())
+        if (!wanted.includes(current))
+            c.deselect(current);
+};
+const applyDisabled = (host, c, items) => {
+    const group = host.hasAttribute("disabled");
+    items.forEach((item, index) => void (group || item.disabled ? c.disableButton(index) : c.enableButton(index)));
+};
+const updateGroup = (host, component) => {
+    const items = declaredItems(host);
+    const previous = applied.get(host) ?? [];
+    if (items.length !== previous.length || items.length !== component.buttons.length)
+        return false;
+    for (const [index, item] of items.entries()) {
+        const before = previous[index];
+        if (item.value !== before.value || !item.text !== !before.text || item.selectedIcon !== before.selectedIcon)
+            return false;
+        if (item.selected !== before.selected && !host.hasAttribute("value"))
+            return false;
+        if (item.ariaLabel === undefined && before.ariaLabel !== undefined)
+            return false;
+    }
+    for (const [index, item] of items.entries()) {
+        const before = previous[index];
+        const button = component.buttons[index];
+        if (item.text && item.text !== before.text)
+            button.setText(item.text);
+        if (item.icon !== before.icon)
+            button.setIcon(item.icon ?? "");
+        if (item.ariaLabel !== undefined && item.ariaLabel !== before.ariaLabel)
+            button.setAriaLabel(item.ariaLabel);
+    }
+    applied.set(host, items);
+    applyDisabled(host, component, items);
+    return true;
+};
+const buttonGroupSpec = {
+    name: "button-group",
+    create: (config) => createButtonGroup(config),
+    styles: ["progress", "button", "icon-button", "button-group"],
+    attributes: {
+        variant: { type: "string", config: "variant", update: (c, v) => void c.setVariant(String(v ?? "outlined")) },
+        kind: { type: "string", config: "kind" },
+        selection: { type: "string", config: "selection" },
+        required: { type: "boolean", config: "required" },
+        size: { type: "string", config: "size" },
+        shape: { type: "string", config: "shape" },
+        labels: { type: "string", config: "labels" },
+        orientation: {
+            type: "string",
+            config: "orientation",
+            update: (c, v) => void c.setOrientation(v === "vertical" ? "vertical" : "horizontal"),
+        },
+        density: { type: "string", config: "density", update: (c, v) => void c.setDensity(String(v ?? "default")) },
+        "equal-width": { type: "boolean", config: "equalWidth" },
+        "expanded-ratio": { type: "number", config: "expandedRatio" },
+        disabled: {
+            type: "boolean",
+            config: "disabled",
+            update: (c, v, host) => {
+                if (v)
+                    c.disable();
+                else
+                    c.enable();
+                applyDisabled(host, c, applied.get(host) ?? []);
+            },
+        },
+        "aria-label": {
+            type: "string",
+            config: "ariaLabel",
+            update: (c, v) => c.element.setAttribute("aria-label", v === null ? "Button group" : String(v)),
+        },
+        value: { type: "string", update: (c, v) => select(c, v) },
+    },
+    properties: {
+        value: { get: (c) => model(c), set: (c, v) => select(c, v) },
+    },
+    model: "value",
+    events: {
+        change: {
+            detail: (payload) => ({ value: model(payload.buttonGroup) }),
+        },
+        action: {
+            detail: (payload) => payload,
+            state: true,
+        },
+    },
+    config: readGroup,
+    setup: (host, component) => {
+        const onClick = (event) => {
+            const value = applied.get(host)?.[event.index]?.value ?? String(event.index);
+            host.dispatchEvent(new CustomEvent("action", { detail: { value, index: event.index }, bubbles: true, composed: true }));
+        };
+        component.on("click", onClick);
+        return () => void component.off("click", onClick);
+    },
+    observeChildren: updateGroup,
+};
+export const buttonGroupElement = defineElement(buttonGroupSpec);
+export const buttonGroupItemDeclaration = {
+    name: "button-group-item",
+    attributes: {
+        value: { type: "string" },
+        label: { type: "string" },
+        icon: { type: "string" },
+        "selected-icon": { type: "string" },
+        "aria-label": { type: "string" },
+        disabled: { type: "boolean" },
+        selected: { type: "boolean" },
+    },
+};
+export const defineButtonGroup = (options) => {
+    const itemTag = `${options?.prefix ?? DEFAULT_PREFIX}-${buttonGroupItemDeclaration.name}`;
+    if (!customElements.get(itemTag))
+        customElements.define(itemTag, createDeclarationClass(buttonGroupItemDeclaration.attributes));
+    return buttonGroupElement.define(options);
+};

package/dist/elements/button.d.ts

@@ -0,0 +1,90 @@
+/**
+ * `<m-button>`: the button as a custom element. Children are the label.
+ *
+ * `type="submit"` and `type="reset"` act on the host's form, which a button
+ * inside a shadow root cannot reach by itself (see `form-button`).
+ *
+ * A toggle button (for now from the button's global defaults: the element has
+ * no toggle attribute) dispatches `change` with `{ selected, value }` from the
+ * host on each click (FLO-380).
+ *
+ * Parts: `button`, `icon`, `label` (also `text`), `ripple`.
+ *
+ * @module elements
+ */
+import type { ButtonComponent } from "../components/button/types.js";
+import { type DefineOptions, type ElementInstance } from "./define.js";
+declare const buttonSpec: {
+    name: string;
+    create: (config: import("./define.js").Config) => ButtonComponent;
+    styles: string[];
+    hostStyles: string;
+    attributes: {
+        variant: {
+            type: "string";
+            config: string;
+            update: (c: ButtonComponent, v: import("./define.js").AttributeValue) => undefined;
+        };
+        size: {
+            type: "string";
+            config: string;
+            update: (c: ButtonComponent, v: import("./define.js").AttributeValue) => undefined;
+        };
+        shape: {
+            type: "string";
+            config: string;
+            update: (c: ButtonComponent, v: import("./define.js").AttributeValue) => undefined;
+        };
+        disabled: {
+            type: "boolean";
+            config: string;
+            update: (c: ButtonComponent, v: import("./define.js").AttributeValue) => undefined;
+        };
+        /** Markup (HTML). Not sanitized by default: see Markup and sanitizing. */
+        icon: {
+            type: "string";
+            config: string;
+        };
+        value: {
+            type: "string";
+            config: string;
+            update: (c: ButtonComponent, v: import("./define.js").AttributeValue) => undefined;
+        };
+        type: {
+            readonly type: "string";
+            readonly update: () => undefined;
+        };
+        "aria-label": {
+            type: "string";
+            config: string;
+            update: (c: ButtonComponent, v: import("./define.js").AttributeValue) => undefined;
+        };
+    };
+    slot: {
+        attribute: "label";
+        config: string;
+    };
+    events: {
+        change: {
+            detail: (payload: unknown) => {
+                selected: boolean;
+                value: string;
+            };
+        };
+    };
+    form: import("./define.js").FormSpec<ButtonComponent>;
+    setup: <C extends import("./define.js").ElementComponent>(host: import("./define.js").ElementHost<C>) => (() => void);
+};
+export declare const buttonElement: import("./define.js").ElementDefinition<ButtonComponent>;
+export type ButtonSpec = typeof buttonSpec;
+/** `<m-button>` as a ref or a query returns it. */
+export type ButtonElement = ElementInstance<ButtonSpec, ButtonComponent>;
+/** Registers `<m-button>` (or `<prefix-button>`). */
+export declare const defineButton: (options?: DefineOptions) => string;
+declare global {
+    /** `document.querySelector("m-…")` and `createElement` return the element's type (the default prefix). */
+    interface HTMLElementTagNameMap {
+        "m-button": ButtonElement;
+    }
+}
+export {};