material 1.0.4 → 3.0.0-next.0

package/dist/elements/list.d.ts

@@ -0,0 +1,147 @@
+/**
+ * `<m-list>` with `<m-list-item>` children.
+ *
+ * Each `<m-list-item>` declares one row: its text (or `headline`) is the
+ * headline, with `overline`, `supporting-text`, a leading icon, avatar or
+ * image, a trailing icon or text, `value`, `disabled` and `selected`. An item
+ * with `kind="divider"` or `kind="subheader"` declares the list's structure
+ * instead. The list reads them into the factory's config and updates in place
+ * when they change; the children stay where the framework put them.
+ *
+ * `selection` is the factory's mode: `single` (the default), `multiple`, or
+ * `none` (rows are not interactive). `value` on `<m-list>` and the items'
+ * `selected` are the default selection, which moves the live one until the
+ * user or script changes it; the `value` property is the live selection (the
+ * first selected value, as on a native `<select multiple>`) and `values` all
+ * of it. A click or Enter on a row dispatches `activate` with its value, then
+ * `change` when the selection moved.
+ *
+ * Parts: `list`, `content`, `item`, `action`, `text`, `headline`, `supporting`.
+ *
+ * @module elements
+ */
+import type { ListComponent, ListItem } from "../components/list/types.js";
+import { type Config, type DefineOptions, type ElementAttributes, type ElementHost, type ElementInstance } from "./define.js";
+declare const listSpec: {
+    name: string;
+    create: (config: Config) => ListComponent<ListItem>;
+    styles: string[];
+    hostStyles: string;
+    attributes: {
+        selection: {
+            type: "string";
+            config: string;
+        };
+        value: {
+            type: "string";
+            config: string;
+            update: (c: ListComponent<ListItem>, v: import("./define.js").AttributeValue) => void;
+        };
+        disabled: {
+            type: "boolean";
+            update: (c: ListComponent<ListItem>, _v: import("./define.js").AttributeValue, host: HTMLElement) => undefined;
+        };
+        "aria-label": {
+            type: "string";
+            config: string;
+            update: (c: ListComponent<ListItem>, v: import("./define.js").AttributeValue) => void;
+        };
+    };
+    properties: {
+        value: {
+            get: (c: ListComponent<ListItem>) => string | null;
+            set: (c: ListComponent<ListItem>, v: unknown) => void;
+            config: string;
+        };
+        values: {
+            get: (c: ListComponent<ListItem>) => string[];
+            set: (c: ListComponent<ListItem>, v: unknown) => void;
+            config: string;
+        };
+    };
+    model: "value";
+    defaults: string[];
+    events: {
+        activate: {
+            detail: (payload: unknown) => {
+                value: string;
+            };
+            state: true;
+        };
+        change: {
+            detail: (payload: unknown) => {
+                value: string | null;
+                values: string[];
+            };
+        };
+    };
+    config: (host: HTMLElement) => Config;
+    setup: (host: ElementHost<ListComponent<ListItem>>, component: ListComponent<ListItem>) => (() => void);
+    observeChildren: (host: HTMLElement, component: ListComponent<ListItem>) => boolean;
+};
+export declare const listElement: import("./define.js").ElementDefinition<ListComponent<ListItem>>;
+export type ListSpec = typeof listSpec;
+/** `<m-list>` as a ref or a query returns it. */
+export type ListElement = ElementInstance<ListSpec, ListComponent<ListItem>>;
+/**
+ * `<m-list-item>` declares one row and renders nothing. Its text content is
+ * the headline unless `headline` is set.
+ */
+export declare const listItemDeclaration: {
+    readonly name: "list-item";
+    readonly attributes: {
+        readonly value: {
+            readonly type: "string";
+        };
+        readonly headline: {
+            readonly type: "string";
+        };
+        readonly overline: {
+            readonly type: "string";
+        };
+        readonly "supporting-text": {
+            readonly type: "string";
+        };
+        /** Markup (HTML). Not sanitized by default: see Markup and sanitizing. */
+        readonly "leading-icon": {
+            readonly type: "string";
+        };
+        /** Markup (HTML), not a person's name or an image URL. Not sanitized by default: see Markup and sanitizing. */
+        readonly "leading-avatar": {
+            readonly type: "string";
+        };
+        readonly "leading-image": {
+            readonly type: "string";
+        };
+        /** Markup (HTML). Not sanitized by default: see Markup and sanitizing. */
+        readonly "trailing-icon": {
+            readonly type: "string";
+        };
+        readonly "trailing-text": {
+            readonly type: "string";
+        };
+        readonly kind: {
+            readonly type: "string";
+        };
+        readonly inset: {
+            readonly type: "boolean";
+        };
+        readonly disabled: {
+            readonly type: "boolean";
+        };
+        readonly selected: {
+            readonly type: "boolean";
+        };
+    };
+};
+export type ListItemAttributes = ElementAttributes<typeof listItemDeclaration>;
+/** Registers `<m-list>` and `<m-list-item>` (or with another prefix). */
+export declare const defineList: (options?: DefineOptions) => string;
+declare global {
+    /** `document.querySelector("m-…")` and `createElement` return the element's type (the default prefix). */
+    interface HTMLElementTagNameMap {
+        "m-list": ListElement;
+        "m-list-item": HTMLElement & ListItemAttributes;
+    }
+}
+export {};

package/dist/elements/list.js

@@ -0,0 +1,191 @@
+import createList from "../components/list/index.js";
+import { safeUrl } from "../core/utils/url.js";
+import { createDeclarationClass, defineElement, DEFAULT_PREFIX, } from "./define.js";
+const defaultSelected = new WeakMap();
+const modes = new WeakMap();
+const itemSlot = (child, position) => {
+    const icon = child.getAttribute(`${position}-icon`);
+    if (icon !== null)
+        return { type: "icon", content: icon };
+    if (position === "trailing") {
+        const text = child.getAttribute("trailing-text");
+        return text === null ? undefined : { type: "text", content: text };
+    }
+    const avatar = child.getAttribute("leading-avatar");
+    if (avatar !== null)
+        return { type: "avatar", content: avatar };
+    const src = child.getAttribute("leading-image");
+    if (src === null)
+        return undefined;
+    const image = document.createElement("img");
+    image.src = safeUrl(src);
+    image.alt = "";
+    return { type: "image", content: image };
+};
+const declaredItems = (host) => {
+    const itemTag = `${host.localName}-item`;
+    const disabled = host.hasAttribute("disabled");
+    const items = [];
+    const values = new Set();
+    for (const child of Array.from(host.children)) {
+        if (child.localName !== itemTag)
+            continue;
+        const headline = child.getAttribute("headline") ?? (child.textContent ?? "").trim();
+        const kind = child.getAttribute("kind");
+        if (kind === "divider" || kind === "subheader") {
+            items.push({ kind, headline, inset: child.hasAttribute("inset") });
+            continue;
+        }
+        const value = child.getAttribute("value") ?? headline;
+        if (values.has(value)) {
+            console.warn(`<${host.localName}>: more than one item has the value "${value}"; keeping the first.`);
+            continue;
+        }
+        values.add(value);
+        items.push({
+            id: value,
+            headline,
+            overline: child.getAttribute("overline") ?? undefined,
+            supportingText: child.getAttribute("supporting-text") ?? undefined,
+            leading: itemSlot(child, "leading"),
+            trailing: itemSlot(child, "trailing"),
+            disabled: disabled || child.hasAttribute("disabled"),
+            selected: child.hasAttribute("selected"),
+        });
+    }
+    return items;
+};
+const selectedKey = (items) => items.filter((item) => item.selected).map((item) => String(item.id)).join("\u0000");
+const readList = (host) => ({ items: declaredItems(host) });
+const create = (config) => {
+    const { selection, selectedValue, selectedValues, ...rest } = config;
+    const items = rest.items ?? [];
+    const mode = selection === "none" || selection === "multiple" ? selection : "single";
+    let initial;
+    if (selectedValues)
+        initial = selectedValues;
+    else {
+        initial = items.filter((item) => item.selected).map((item) => String(item.id));
+        if (selectedValue !== undefined)
+            initial = mode === "multiple" ? [...initial, selectedValue] : [selectedValue];
+    }
+    const component = createList({
+        ...rest,
+        items: items.map((item) => ({ ...item, selected: undefined })),
+        trackSelection: mode !== "none",
+        multiSelect: mode === "multiple",
+        initialSelection: mode === "multiple" ? initial : initial.slice(0, 1),
+    });
+    defaultSelected.set(component, selectedKey(items));
+    modes.set(component, mode);
+    return component;
+};
+const selectedValues = (component) => component.getSelectedItems().map((item) => String(item.id));
+const select = (component, values) => {
+    component.setSelection(modes.get(component) === "multiple" ? values : values.slice(0, 1));
+};
+const toValues = (value) => value === null || value === undefined || value === "" ? [] : Array.isArray(value) ? value.map(String) : [String(value)];
+const updateList = (host, component) => {
+    const declared = declaredItems(host);
+    if (selectedKey(declared) !== defaultSelected.get(component))
+        return false;
+    const items = component.getAllItems();
+    items.splice(0, items.length, ...declared.map((item) => ({ ...item, selected: undefined })));
+    void component.refresh();
+    return true;
+};
+const detail = (component) => {
+    const values = selectedValues(component);
+    return { value: values[0] ?? null, values };
+};
+const dispatchActivation = (host, component) => {
+    let before = "";
+    let activated = null;
+    const onSelect = (event) => {
+        activated = String(event.item.id);
+    };
+    const capture = () => {
+        activated = null;
+        before = selectedValues(component).join("\u0000");
+    };
+    const after = () => {
+        const value = activated;
+        activated = null;
+        if (value === null)
+            return;
+        const dispatch = (type, detail) => host.dispatchEvent(new CustomEvent(type, { detail, bubbles: true, composed: true }));
+        dispatch("activate", { value });
+        if (selectedValues(component).join("\u0000") !== before)
+            dispatch("change", detail(component));
+    };
+    component.on("select", onSelect);
+    component.element.addEventListener("click", capture, true);
+    component.element.addEventListener("click", after);
+    return () => {
+        component.off("select", onSelect);
+        component.element.removeEventListener("click", capture, true);
+        component.element.removeEventListener("click", after);
+    };
+};
+const listSpec = {
+    name: "list",
+    create: (config) => create(config),
+    styles: ["list"],
+    hostStyles: ":host{display:block}",
+    attributes: {
+        selection: { type: "string", config: "selection" },
+        value: { type: "string", config: "selectedValue", update: (c, v) => select(c, toValues(v)) },
+        disabled: { type: "boolean", update: (c, _v, host) => void updateList(host, c) },
+        "aria-label": {
+            type: "string",
+            config: "ariaLabel",
+            update: (c, v) => (v === null ? c.element.removeAttribute("aria-label") : c.element.setAttribute("aria-label", String(v))),
+        },
+    },
+    properties: {
+        value: {
+            get: (c) => selectedValues(c)[0] ?? null,
+            set: (c, v) => select(c, toValues(v)),
+            config: "selectedValue",
+        },
+        values: {
+            get: (c) => selectedValues(c),
+            set: (c, v) => select(c, toValues(v)),
+            config: "selectedValues",
+        },
+    },
+    model: "value",
+    defaults: ["values"],
+    events: {
+        activate: { detail: (payload) => payload, state: true },
+        change: { detail: (payload) => payload },
+    },
+    config: readList,
+    setup: dispatchActivation,
+    observeChildren: updateList,
+};
+export const listElement = defineElement(listSpec);
+export const listItemDeclaration = {
+    name: "list-item",
+    attributes: {
+        value: { type: "string" },
+        headline: { type: "string" },
+        overline: { type: "string" },
+        "supporting-text": { type: "string" },
+        "leading-icon": { type: "string" },
+        "leading-avatar": { type: "string" },
+        "leading-image": { type: "string" },
+        "trailing-icon": { type: "string" },
+        "trailing-text": { type: "string" },
+        kind: { type: "string" },
+        inset: { type: "boolean" },
+        disabled: { type: "boolean" },
+        selected: { type: "boolean" },
+    },
+};
+export const defineList = (options) => {
+    const itemTag = `${options?.prefix ?? DEFAULT_PREFIX}-${listItemDeclaration.name}`;
+    if (!customElements.get(itemTag))
+        customElements.define(itemTag, createDeclarationClass(listItemDeclaration.attributes));
+    return listElement.define(options);
+};

package/dist/elements/loading-indicator.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `<m-loading-indicator>`: the expressive loading indicator as a custom
+ * element. It animates from connection; a `value` from 0 to 1 makes it
+ * determinate. `aria-label` names what is loading.
+ *
+ * Parts: `loading-indicator`, `canvas`.
+ *
+ * @module elements
+ */
+import type { LoadingIndicatorComponent } from "../components/loading-indicator/types.js";
+import { type DefineOptions, type ElementInstance } from "./define.js";
+declare const loadingIndicatorSpec: {
+    name: string;
+    create: (config: import("./define.js").Config) => LoadingIndicatorComponent;
+    styles: string[];
+    hostStyles: string;
+    attributes: {
+        size: {
+            type: "number";
+            config: string;
+            update: (c: LoadingIndicatorComponent, v: import("./define.js").AttributeValue) => undefined;
+        };
+        contained: {
+            type: "boolean";
+            config: string;
+        };
+        value: {
+            type: "number";
+            config: string;
+            update: (c: LoadingIndicatorComponent, v: import("./define.js").AttributeValue) => undefined;
+        };
+        "aria-label": {
+            type: "string";
+            config: string;
+            update: (c: LoadingIndicatorComponent, v: import("./define.js").AttributeValue) => undefined;
+        };
+    };
+    methods: readonly ["start", "stop"];
+};
+export declare const loadingIndicatorElement: import("./define.js").ElementDefinition<LoadingIndicatorComponent>;
+export type LoadingIndicatorSpec = typeof loadingIndicatorSpec;
+/** `<m-loading-indicator>` as a ref or a query returns it. */
+export type LoadingIndicatorElement = ElementInstance<LoadingIndicatorSpec, LoadingIndicatorComponent>;
+/** Registers `<m-loading-indicator>` (or `<prefix-loading-indicator>`). */
+export declare const defineLoadingIndicator: (options?: DefineOptions) => string;
+declare global {
+    /** `document.querySelector("m-…")` and `createElement` return the element's type (the default prefix). */
+    interface HTMLElementTagNameMap {
+        "m-loading-indicator": LoadingIndicatorElement;
+    }
+}
+export {};

package/dist/elements/loading-indicator.js

@@ -0,0 +1,26 @@
+import createLoadingIndicator from "../components/loading-indicator/index.js";
+import { LOADING_INDICATOR_DEFAULTS } from "../components/loading-indicator/constants.js";
+import { defineElement } from "./define.js";
+const loadingIndicatorSpec = {
+    name: "loading-indicator",
+    create: (config) => createLoadingIndicator(config),
+    styles: ["loading-indicator"],
+    hostStyles: ":host{display:inline-flex;vertical-align:middle}",
+    attributes: {
+        size: {
+            type: "number",
+            config: "size",
+            update: (c, v) => void c.setSize(v === null ? LOADING_INDICATOR_DEFAULTS.SIZE : Number(v)),
+        },
+        contained: { type: "boolean", config: "contained" },
+        value: { type: "number", config: "value", update: (c, v) => void c.setValue(v === null ? null : Number(v)) },
+        "aria-label": {
+            type: "string",
+            config: "ariaLabel",
+            update: (c, v) => void c.setLabel(v === null ? LOADING_INDICATOR_DEFAULTS.LABEL : String(v)),
+        },
+    },
+    methods: ["start", "stop"],
+};
+export const loadingIndicatorElement = defineElement(loadingIndicatorSpec);
+export const defineLoadingIndicator = (options) => loadingIndicatorElement.define(options);

package/dist/elements/menu.d.ts

@@ -0,0 +1,178 @@
+/**
+ * `<m-menu>` with `<m-menu-item>` children.
+ *
+ * Each `<m-menu-item>` declares one item: its text (or `label`), `value`,
+ * `icon`, `shortcut`, `supporting-text` and `disabled`; `divider` makes it a
+ * divider instead and `gap` a gap between groups (separate surfaces in the
+ * vertical menu), and `<m-menu-item>` children inside it are its submenu.
+ * The menu reads them into the factory's items and updates in place when they
+ * change; the children stay where the framework put them.
+ *
+ * The menu opens against an anchor: `anchor` is the id of an element in the
+ * menu's own root, then the document's, and the `anchor` property an element
+ * (or an id). The anchor opens and closes the menu by pointer and key, as the
+ * factory's opener does. The surface stays in the element's shadow root and
+ * is shown in the top layer (the factory's `layer: "top"`), so it keeps its
+ * styles and is above everything on the page.
+ *
+ * `open` is state, not a value, as on `<details>`: the attribute reflects
+ * whether the menu is open, setting or removing it opens or closes it, and
+ * the user closing the menu removes it. `show()`, `hide()` and `toggle()` do
+ * the same. `open` and `close` are dispatched as it opens and closes, by
+ * those methods, the anchor or the user (not when the attribute or the
+ * property is what changed: that is applied at once, and quietly, as on the
+ * other elements), and `select` with the item's value when one is chosen.
+ * There is no two-way binding: an app that keeps `open` in its state follows
+ * the `close` event. `no-close-on-select` keeps the menu open when an item is
+ * chosen, and `color="vibrant"` is the vertical menu's vibrant colours.
+ *
+ * Parts: `menu`, `list`, `item`, `item-content`, `item-text`.
+ *
+ * @module elements
+ */
+import type { MenuComponent, MenuContent } from "../components/menu/types.js";
+import { type Config, type DefineOptions, type ElementAttributes, type ElementInstance } from "./define.js";
+/** The menu, with the methods the element adds to it. */
+export type MenuElementComponent = MenuComponent & {
+    /** Opens the menu. */
+    show: () => void;
+    /** Closes the menu. */
+    hide: () => void;
+};
+/** An anchor as a property takes it: an element, or an id. */
+export type MenuAnchor = HTMLElement | string | null;
+/**
+ * The items `<tag>` children declare, with their own `<tag>` children as a
+ * submenu. Shared by the elements whose menu takes items (`<m-split-button>`).
+ */
+export declare const declaredMenuItems: (parent: Element, tag: string) => MenuContent[];
+declare const menuSpec: {
+    name: string;
+    ssr: (host: HTMLElement) => boolean;
+    create: (config: Config) => MenuElementComponent;
+    styles: string[];
+    hostStyles: string;
+    attributes: {
+        open: {
+            type: "boolean";
+            update: (c: MenuElementComponent, v: import("./define.js").AttributeValue) => void;
+        };
+        anchor: {
+            type: "string";
+            config: string;
+            update: (c: MenuElementComponent, v: import("./define.js").AttributeValue) => void;
+        };
+        position: {
+            type: "string";
+            config: string;
+            update: (c: MenuElementComponent, v: import("./define.js").AttributeValue) => undefined;
+        };
+        offset: {
+            type: "number";
+            config: string;
+        };
+        variant: {
+            type: "string";
+            config: string;
+        };
+        color: {
+            type: "string";
+            config: string;
+        };
+        "no-close-on-select": {
+            type: "boolean";
+            config: string;
+        };
+        dense: {
+            type: "boolean";
+            config: string;
+        };
+        "max-height": {
+            type: "string";
+            config: string;
+            update: (c: MenuElementComponent, v: import("./define.js").AttributeValue) => undefined;
+        };
+        "aria-label": {
+            type: "string";
+            update: (c: MenuElementComponent, v: import("./define.js").AttributeValue) => void;
+        };
+    };
+    properties: {
+        anchor: {
+            get: (c: MenuElementComponent) => HTMLElement | null;
+            set: (c: MenuElementComponent, v: unknown) => void;
+            config: string;
+        };
+    };
+    methods: readonly ["show", "hide", "toggle"];
+    events: {
+        open: {
+            detail: () => {};
+            state: true;
+        };
+        close: {
+            detail: () => {};
+            state: true;
+        };
+        select: {
+            detail: (payload: unknown) => {
+                value: string;
+            };
+        };
+    };
+    config: (host: HTMLElement) => Config;
+    setup: (host: import("./define.js").ElementHost<MenuElementComponent>, c: MenuElementComponent) => () => void;
+    observeChildren: (host: HTMLElement, c: MenuComponent) => boolean;
+};
+export declare const menuElement: import("./define.js").ElementDefinition<MenuElementComponent>;
+export type MenuSpec = typeof menuSpec;
+/** `<m-menu>` as a ref or a query returns it. */
+export type MenuElement = ElementInstance<MenuSpec, MenuElementComponent>;
+/**
+ * `<m-menu-item>` declares one item and renders nothing. Its text is the
+ * label unless `label` is set; `<m-menu-item>` children are its submenu.
+ * Shared with `<m-split-button>`.
+ */
+export declare const menuItemDeclaration: {
+    readonly name: "menu-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";
+        };
+        readonly shortcut: {
+            readonly type: "string";
+        };
+        readonly "supporting-text": {
+            readonly type: "string";
+        };
+        readonly disabled: {
+            readonly type: "boolean";
+        };
+        readonly divider: {
+            readonly type: "boolean";
+        };
+        readonly gap: {
+            readonly type: "boolean";
+        };
+    };
+};
+export type MenuItemAttributes = ElementAttributes<typeof menuItemDeclaration>;
+/** Registers `<m-menu-item>`, before the elements that read it. */
+export declare const defineMenuItem: (options?: DefineOptions) => void;
+/** Registers `<m-menu>` and `<m-menu-item>` (or with another prefix). */
+export declare const defineMenu: (options?: DefineOptions) => string;
+declare global {
+    /** `document.querySelector("m-…")` and `createElement` return the element's type (the default prefix). */
+    interface HTMLElementTagNameMap {
+        "m-menu": MenuElement;
+        "m-menu-item": HTMLElement & MenuItemAttributes;
+    }
+}
+export {};