material 1.0.4 → 3.0.0-next.1

package/dist/elements/styles.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Stylesheets for the shadow roots of the elements.
+ *
+ * Each element adopts the CSS of its component and the component's style
+ * dependencies, the same entries the selective stylesheets are built from
+ * (`scripts/style-manifest.ts`). One sheet per entry per page, shared by every
+ * instance.
+ *
+ * @module elements
+ */
+/** The tag prefix: `<m-switch>`. The pre-upgrade CSS is built for it. */
+export declare const DEFAULT_PREFIX = "m";
+/** Internal registry access; preserves application registrations and overrides. */
+export declare const styleText: (name: string) => string | undefined;
+/** Identifies only fallback nodes inserted by applyStyles, never authored styles. */
+export declare const isFallbackStyle: (node: Node) => boolean;
+/**
+ * Registers the CSS text of style entries, keyed as in `componentStyles`.
+ * Must run before the elements that use them are created.
+ *
+ * @experimental The element authoring API (`defineElement`, `ElementSpec`,
+ * `registerStyles`, `hasStyles`, `SHADOW_BASE_STYLES`) is outside semantic
+ * versioning in 3.x: it may change in a minor release. The elements the
+ * library defines, and their attributes, properties and events, are not.
+ */
+export declare const registerStyles: (css: Record<string, string>) => void;
+/**
+ * Whether CSS is registered under a name.
+ *
+ * @experimental The element authoring API (`defineElement`, `ElementSpec`,
+ * `registerStyles`, `hasStyles`, `SHADOW_BASE_STYLES`) is outside semantic
+ * versioning in 3.x: it may change in a minor release. The elements the
+ * library defines, and their attributes, properties and events, are not.
+ */
+export declare const hasStyles: (name: string) => boolean;
+/**
+ * On a host the server rendered with a declarative shadow root.
+ * No `data-mtrl-*` name is used anywhere else: component `data-*` names
+ * (`data-id`, `data-density`, `data-theme`) are that component's own state,
+ * and a page's `data-ssr` must not be this contract. Inert after upgrade,
+ * because the rollback rule is `:not(:defined)`.
+ */
+export declare const RENDERED_HOST_ATTRIBUTE = "data-mtrl-ssr";
+/**
+ * Last rule of every pre-upgrade sheet, inside `mtrl.preupgrade`.
+ * `:not(#\0)` is an id selector (specificity 1,0,0) that matches every element,
+ * so each selector outranks every pre-upgrade selector of the same subject
+ * (the host, its `::before` and `::after`, and a direct child), none of which
+ * has an id. The child subject is `:defined` (specificity 1,3,0). Every
+ * built-in element is defined, so a slotted `div` or `span` is rolled back.
+ * An undefined custom element is not: a carousel, a FAB menu, or a menu that
+ * opted out keeps its own pre-upgrade rule. A rendered mtrl child carries
+ * this attribute and is covered by the host selector. The deepest pre-upgrade
+ * subject is a direct child, including a following sibling of one (`> * + *`);
+ * none styles a grandchild or a child's pseudo-element. `all` does not reset
+ * custom properties; the element rules set none. Not tag-specific, so
+ * retagging for another prefix leaves it as it is.
+ */
+export declare const preupgradeRollback: () => string;
+/**
+ * Pre-upgrade CSS, built for the default prefix, for another one: every tag
+ * selector `m-*` becomes `<prefix>-*`. The rules name tags only in selectors
+ * (`m-tabs:not(:defined)>*`), and no value starts a word with `m-`.
+ */
+export declare const retagPreupgrade: (css: string, prefix: string) => string;
+/** The rules as one layered stylesheet, for each prefix. The rollback is once, after them. */
+export declare const preupgradeSheet: (css: string, prefixes?: Iterable<string>) => string;
+/**
+ * Applies the registered entries to a shadow root, in the given order.
+ * Falls back to `<style>` elements where constructable stylesheets are missing.
+ */
+export declare const applyStyles: (root: ShadowRoot, names: readonly string[]) => void;

package/dist/elements/styles.js

@@ -0,0 +1,47 @@
+export const DEFAULT_PREFIX = "m";
+const sources = new Map();
+const fallbackStyles = new WeakSet();
+export const styleText = (name) => sources.get(name);
+export const isFallbackStyle = (node) => fallbackStyles.has(node);
+const sheets = new Map();
+export const registerStyles = (css) => {
+    for (const [name, text] of Object.entries(css)) {
+        sources.set(name, text);
+        sheets.delete(name);
+    }
+};
+export const hasStyles = (name) => sources.has(name);
+const canAdopt = () => typeof CSSStyleSheet === "function" &&
+    "replaceSync" in CSSStyleSheet.prototype &&
+    typeof ShadowRoot === "function" &&
+    "adoptedStyleSheets" in ShadowRoot.prototype;
+const sheetFor = (name, text) => {
+    let sheet = sheets.get(name);
+    if (!sheet) {
+        sheet = new CSSStyleSheet();
+        sheet.replaceSync(text);
+        sheets.set(name, sheet);
+    }
+    return sheet;
+};
+const PREUPGRADE_LAYER = "mtrl.preupgrade";
+export const RENDERED_HOST_ATTRIBUTE = "data-mtrl-ssr";
+export const preupgradeRollback = () => {
+    const selector = `[${RENDERED_HOST_ATTRIBUTE}]:not(:defined):not(#\\0)`;
+    return `${selector},${selector}::before,${selector}::after,${selector} > :defined{all:revert-layer}`;
+};
+export const retagPreupgrade = (css, prefix) => prefix === DEFAULT_PREFIX ? css : css.replace(/(^|[\s,>+~({}])m-(?=[a-z])/g, `$1${prefix}-`);
+export const preupgradeSheet = (css, prefixes = [DEFAULT_PREFIX]) => `@layer ${PREUPGRADE_LAYER}{${Array.from(prefixes, (prefix) => retagPreupgrade(css, prefix)).join("")}${preupgradeRollback()}}`;
+export const applyStyles = (root, names) => {
+    const known = names.filter((name) => sources.has(name));
+    if (canAdopt()) {
+        root.adoptedStyleSheets = known.map((name) => sheetFor(name, sources.get(name)));
+        return;
+    }
+    for (const name of known) {
+        const style = document.createElement("style");
+        style.textContent = sources.get(name);
+        fallbackStyles.add(style);
+        root.append(style);
+    }
+};

package/dist/elements/switch.d.ts

@@ -0,0 +1,101 @@
+/**
+ * `<m-switch>`: the switch as a form-associated custom element.
+ *
+ * The `checked` attribute is the default state and the `checked` property the
+ * live one, as on a native checkbox: the attribute moves the state until the
+ * user or script changes it. Children are the label.
+ *
+ * Parts: `switch`, `container`, `content`, `label`, `helper`, `input`, `track`, `thumb`,
+ * `thumb-icon`.
+ *
+ * @module elements
+ */
+import type { SwitchComponent } from "../components/switch/types.js";
+import { type DefineOptions, type ElementInstance } from "./define.js";
+declare const switchSpec: {
+    name: string;
+    create: (config: import("./define.js").Config) => SwitchComponent;
+    styles: string[];
+    hostStyles: string;
+    attributes: {
+        checked: {
+            type: "boolean";
+            config: string;
+            update: (c: SwitchComponent, v: import("./define.js").AttributeValue) => undefined;
+        };
+        disabled: {
+            type: "boolean";
+            config: string;
+            update: (c: SwitchComponent, v: import("./define.js").AttributeValue) => undefined;
+        };
+        required: {
+            type: "boolean";
+            config: string;
+        };
+        value: {
+            type: "string";
+            config: string;
+            update: (c: SwitchComponent, v: import("./define.js").AttributeValue) => undefined;
+        };
+        /** Markup (HTML). Not sanitized by default: see Markup and sanitizing. */
+        icon: {
+            type: "string";
+            config: string;
+        };
+        error: {
+            type: "boolean";
+            config: string;
+            update: (c: SwitchComponent, v: import("./define.js").AttributeValue) => undefined;
+        };
+        "supporting-text": {
+            type: "string";
+            config: string;
+            update: (c: SwitchComponent, v: import("./define.js").AttributeValue) => undefined;
+        };
+    };
+    properties: {
+        checked: {
+            get: (c: SwitchComponent) => boolean;
+            set: (c: SwitchComponent, v: unknown) => undefined;
+            config: string;
+        };
+    };
+    methods: readonly ["toggle", "check", "uncheck"];
+    model: "checked";
+    events: {
+        change: {
+            detail: (payload: unknown) => {
+                checked: boolean;
+                value: boolean;
+                valueAttribute: string;
+                nativeEvent: Event | undefined;
+            };
+        };
+    };
+    slot: {
+        attribute: "label";
+        config: string;
+    };
+    form: {
+        value: (c: SwitchComponent) => string | null;
+        control: (c: SwitchComponent) => HTMLInputElement;
+        events: string[];
+        activate: (c: SwitchComponent) => void;
+        state: (c: SwitchComponent) => "checked" | "unchecked";
+        restore: (c: SwitchComponent, state: string) => undefined;
+        disable: (c: SwitchComponent, disabled: boolean) => undefined;
+    };
+};
+export declare const switchElement: import("./define.js").ElementDefinition<SwitchComponent>;
+export type SwitchSpec = typeof switchSpec;
+/** `<m-switch>` as a ref or a query returns it. */
+export type SwitchElement = ElementInstance<SwitchSpec, SwitchComponent>;
+/** Registers `<m-switch>` (or `<prefix-switch>`). */
+export declare const defineSwitch: (options?: DefineOptions) => string;
+declare global {
+    /** `document.querySelector("m-…")` and `createElement` return the element's type (the default prefix). */
+    interface HTMLElementTagNameMap {
+        "m-switch": SwitchElement;
+    }
+}
+export {};

package/dist/elements/switch.js

@@ -0,0 +1,49 @@
+import createSwitch from "../components/switch/index.js";
+import { defineElement } from "./define.js";
+const switchSpec = {
+    name: "switch",
+    create: (config) => createSwitch(config),
+    styles: ["switch"],
+    hostStyles: ":host{display:inline-flex}",
+    attributes: {
+        checked: { type: "boolean", config: "checked", update: (c, v) => void c.setValue(!!v) },
+        disabled: { type: "boolean", config: "disabled", update: (c, v) => void (v ? c.disable() : c.enable()) },
+        required: { type: "boolean", config: "required" },
+        value: { type: "string", config: "value", update: (c, v) => void c.setValueAttribute(String(v ?? "")) },
+        icon: { type: "string", config: "icon" },
+        error: { type: "boolean", config: "error", update: (c, v) => void c.setError(!!v) },
+        "supporting-text": {
+            type: "string",
+            config: "supportingText",
+            update: (c, v) => void (v ? c.setSupportingText(String(v), c.isError()) : c.removeSupportingText()),
+        },
+    },
+    properties: {
+        checked: { get: (c) => c.isChecked(), set: (c, v) => void c.setValue(!!v), config: "checked" },
+    },
+    methods: ["toggle", "check", "uncheck"],
+    model: "checked",
+    events: {
+        change: {
+            detail: (payload) => {
+                const { checked, value, valueAttribute, nativeEvent } = payload;
+                return { checked, value, valueAttribute, nativeEvent };
+            },
+        },
+    },
+    slot: {
+        attribute: "label",
+        config: "label",
+    },
+    form: {
+        value: (c) => (c.isChecked() ? c.getValueAttribute() || "on" : null),
+        control: (c) => c.input,
+        events: ["change"],
+        activate: (c) => c.input.click(),
+        state: (c) => (c.isChecked() ? "checked" : "unchecked"),
+        restore: (c, state) => void c.setValue(state === "checked"),
+        disable: (c, disabled) => void (disabled ? c.disable() : c.enable()),
+    },
+};
+export const switchElement = defineElement(switchSpec);
+export const defineSwitch = (options) => switchElement.define(options);

package/dist/elements/tabs.d.ts

@@ -0,0 +1,87 @@
+/**
+ * `<m-tabs>` with `<m-tab>` children.
+ *
+ * Each `<m-tab>` declares one tab (`value`, `icon`, `badge`, `disabled`, and its
+ * text as content). The tabs element reads them into the factory's config and
+ * rebuilds when they change; the children stay where the framework put them.
+ * `value` on `<m-tabs>` is the default selection, which moves the live one
+ * until the user or script changes it; the `value` property is the live
+ * selection.
+ *
+ * Parts: `tabs`, `scroll`, `tab`, `button`, `icon`, `text`, `ripple`, `indicator`, `divider`.
+ *
+ * @module elements
+ */
+import type { TabsComponent } from "../components/tabs/types.js";
+import { type Config, type DefineOptions, type ElementAttributes, type ElementInstance } from "./define.js";
+declare const tabsSpec: {
+    name: string;
+    create: (config: Config) => TabsComponent;
+    styles: string[];
+    hostStyles: string;
+    attributes: {
+        variant: {
+            type: "string";
+            config: string;
+        };
+        value: {
+            type: "string";
+        };
+    };
+    properties: {
+        value: {
+            get: (c: TabsComponent) => string | null;
+            set: (c: TabsComponent, v: unknown) => undefined;
+        };
+    };
+    model: "value";
+    events: {
+        change: {
+            detail: (payload: unknown) => {
+                value: string | null;
+            };
+        };
+    };
+    config: (host: HTMLElement) => Config;
+    observeChildren: (host: HTMLElement, component: TabsComponent) => boolean;
+};
+export declare const tabsElement: import("./define.js").ElementDefinition<TabsComponent>;
+export type TabsSpec = typeof tabsSpec;
+/** `<m-tabs>` as a ref or a query returns it. */
+export type TabsElement = ElementInstance<TabsSpec, TabsComponent>;
+/**
+ * `<m-tab>` declares one tab and renders nothing. Its text content is the
+ * label unless `label` is set.
+ */
+export declare const tabDeclaration: {
+    readonly name: "tab";
+    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 badge: {
+            readonly type: "string";
+        };
+        readonly disabled: {
+            readonly type: "boolean";
+        };
+    };
+};
+export type TabAttributes = ElementAttributes<typeof tabDeclaration>;
+/** Registers `<m-tabs>` and `<m-tab>` (or with another prefix). */
+export declare const defineTabs: (options?: DefineOptions) => string;
+declare global {
+    /** `document.querySelector("m-…")` and `createElement` return the element's type (the default prefix). */
+    interface HTMLElementTagNameMap {
+        "m-tabs": TabsElement;
+        "m-tab": HTMLElement & TabAttributes;
+    }
+}
+export {};

package/dist/elements/tabs.js

@@ -0,0 +1,108 @@
+import createTabs from "../components/tabs/index.js";
+import { createDeclarationClass, defineElement, DEFAULT_PREFIX, } from "./define.js";
+const declaredTabs = (host) => {
+    const tabTag = host.localName.replace(/tabs$/, "tab");
+    const active = host.getAttribute("value");
+    const tabs = [];
+    for (const child of Array.from(host.children)) {
+        if (child.localName !== tabTag)
+            continue;
+        const text = child.getAttribute("label") ?? (child.textContent ?? "").trim();
+        const value = child.getAttribute("value") ?? text;
+        const badge = child.getAttribute("badge");
+        tabs.push({
+            text,
+            value,
+            icon: child.getAttribute("icon") ?? undefined,
+            badge: badge ?? undefined,
+            disabled: child.hasAttribute("disabled"),
+            state: value === active ? "active" : undefined,
+        });
+    }
+    return tabs;
+};
+const readTabs = (host) => ({ tabs: declaredTabs(host) });
+const updateTabs = (host, component) => {
+    const declared = declaredTabs(host);
+    const values = declared.map((tab) => tab.value ?? "");
+    if (new Set(values).size !== values.length)
+        return false;
+    const current = component.getTabs();
+    const existing = new Set(current.map((tab) => tab.getValue()));
+    const kept = current.map((tab) => tab.getValue()).filter((value) => values.includes(value));
+    const firstNew = values.findIndex((value) => !existing.has(value));
+    const declaredKept = (firstNew === -1 ? values : values.slice(0, firstNew)).filter((value) => existing.has(value));
+    if (kept.join("\u0000") !== declaredKept.join("\u0000"))
+        return false;
+    if (firstNew !== -1 && values.slice(firstNew).some((value) => existing.has(value)))
+        return false;
+    for (const tab of current)
+        if (!values.includes(tab.getValue()))
+            component.removeTab(tab);
+    for (const config of declared) {
+        const tab = component.getTabs().find((candidate) => candidate.getValue() === config.value);
+        if (!tab) {
+            component.addTab({ ...config, state: undefined });
+            continue;
+        }
+        if (tab.getText() !== (config.text ?? ""))
+            tab.setText(config.text ?? "");
+        if (tab.getIcon() !== (config.icon ?? ""))
+            tab.setIcon(config.icon ?? "");
+        if (config.badge !== undefined) {
+            if (tab.getBadge() !== String(config.badge))
+                tab.setBadge(config.badge);
+            else
+                tab.showBadge();
+        }
+        else {
+            tab.hideBadge();
+        }
+        if (config.disabled)
+            tab.disable();
+        else
+            tab.enable();
+    }
+    return true;
+};
+const tabsSpec = {
+    name: "tabs",
+    create: (config) => createTabs(config),
+    styles: ["badge", "progress", "button", "tabs"],
+    hostStyles: ":host{display:block}",
+    attributes: {
+        variant: { type: "string", config: "variant" },
+        value: { type: "string" },
+    },
+    properties: {
+        value: {
+            get: (c) => c.getActiveTab()?.getValue() ?? null,
+            set: (c, v) => void (v === null || v === undefined ? undefined : c.setActiveTab(String(v))),
+        },
+    },
+    model: "value",
+    events: {
+        change: {
+            detail: (payload) => ({ value: payload.value }),
+        },
+    },
+    config: readTabs,
+    observeChildren: updateTabs,
+};
+export const tabsElement = defineElement(tabsSpec);
+export const tabDeclaration = {
+    name: "tab",
+    attributes: {
+        value: { type: "string" },
+        label: { type: "string" },
+        icon: { type: "string" },
+        badge: { type: "string" },
+        disabled: { type: "boolean" },
+    },
+};
+export const defineTabs = (options) => {
+    const tabTag = `${options?.prefix ?? DEFAULT_PREFIX}-${tabDeclaration.name}`;
+    if (!customElements.get(tabTag))
+        customElements.define(tabTag, createDeclarationClass(tabDeclaration.attributes));
+    return tabsElement.define(options);
+};

package/dist/elements/text-field.d.ts

@@ -0,0 +1,172 @@
+/**
+ * `<m-text-field>`: the text field as a form-associated custom element.
+ *
+ * The `value` attribute is the default value and the `value` property the
+ * live one, as on a native input: the attribute moves the value until the
+ * user or script changes it. The `label` attribute is the floating
+ * label, which the factory renders; there is no slot.
+ *
+ * `label` and `type` have no setter on the text field: changing one
+ * recreates it, keeping the value. A field created without a label has no
+ * label element to update, and `type="multiline"` swaps the input for a
+ * textarea.
+ *
+ * Parts: `text-field`, `field`, `label`, `input`, `leading-icon`, `trailing-icon`, `prefix`,
+ * `suffix`, `supporting`, `helper`, `counter`, `outline`, `outline-leading`, `outline-notch`,
+ * `outline-trailing`.
+ *
+ * @module elements
+ */
+import type { TextFieldComponent } from "../components/text-field/types.js";
+import { type AttributeValue, type DefineOptions, type ElementInstance } from "./define.js";
+/** The text field, with the methods the element adds to it. */
+export type TextFieldElementComponent = TextFieldComponent & {
+    /** Selects the field's text. */
+    select: () => void;
+};
+declare const textFieldSpec: {
+    name: string;
+    create: (config: import("./define.js").Config) => TextFieldElementComponent;
+    styles: string[];
+    hostStyles: string;
+    attributes: {
+        variant: {
+            type: "string";
+            config: string;
+            update: (c: TextFieldElementComponent, v: AttributeValue) => undefined;
+        };
+        density: {
+            type: "string";
+            config: string;
+            update: (c: TextFieldElementComponent, v: AttributeValue) => undefined;
+        };
+        label: {
+            type: "string";
+            config: string;
+        };
+        type: {
+            type: "string";
+            config: string;
+        };
+        value: {
+            type: "string";
+            config: string;
+            update: (c: TextFieldElementComponent, v: AttributeValue) => void;
+        };
+        placeholder: {
+            type: "string";
+            config: string;
+            update: (c: TextFieldElementComponent, v: AttributeValue) => undefined;
+        };
+        "supporting-text": {
+            type: "string";
+            config: string;
+            update: (c: TextFieldElementComponent, v: AttributeValue) => undefined;
+        };
+        "prefix-text": {
+            type: "string";
+            config: string;
+            update: (c: TextFieldElementComponent, v: AttributeValue) => undefined;
+        };
+        "suffix-text": {
+            type: "string";
+            config: string;
+            update: (c: TextFieldElementComponent, v: AttributeValue) => undefined;
+        };
+        /** Markup (HTML). Not sanitized by default: see Markup and sanitizing. */
+        "leading-icon": {
+            type: "string";
+            config: string;
+            update: (c: TextFieldElementComponent, v: AttributeValue) => undefined;
+        };
+        /** Markup (HTML). Not sanitized by default: see Markup and sanitizing. */
+        "trailing-icon": {
+            type: "string";
+            config: string;
+            update: (c: TextFieldElementComponent, v: AttributeValue) => undefined;
+        };
+        maxlength: {
+            type: "number";
+            config: string;
+            update: (c: TextFieldElementComponent, v: AttributeValue) => void;
+        };
+        pattern: {
+            type: "string";
+            config: string;
+            update: (c: TextFieldElementComponent, v: AttributeValue) => void;
+        };
+        required: {
+            type: "boolean";
+            config: string;
+            update: (c: TextFieldElementComponent, v: AttributeValue) => undefined;
+        };
+        readonly: {
+            type: "boolean";
+            config: string;
+            update: (c: TextFieldElementComponent, v: AttributeValue) => void;
+        };
+        disabled: {
+            type: "boolean";
+            config: string;
+            update: (c: TextFieldElementComponent, v: AttributeValue) => undefined;
+        };
+        error: {
+            type: "boolean";
+            config: string;
+            update: (c: TextFieldElementComponent, v: AttributeValue) => undefined;
+        };
+        autocomplete: {
+            type: "string";
+            config: string;
+            update: (c: TextFieldElementComponent, v: AttributeValue) => void;
+        };
+        "aria-label": {
+            type: "string";
+            config: string;
+            update: (c: TextFieldElementComponent, v: AttributeValue) => void;
+        };
+    };
+    properties: {
+        value: {
+            get: (c: TextFieldElementComponent) => string;
+            set: (c: TextFieldElementComponent, v: unknown) => undefined;
+        };
+    };
+    methods: readonly ["select", "setError"];
+    model: "value";
+    events: {
+        input: {
+            detail: (payload: unknown) => {
+                value: string;
+            };
+        };
+        change: {
+            detail: (payload: unknown) => {
+                value: string;
+            };
+        };
+    };
+    form: {
+        value: (c: TextFieldElementComponent) => string;
+        control: (c: TextFieldElementComponent) => HTMLInputElement | HTMLTextAreaElement;
+        events: string[];
+        activate: (c: TextFieldElementComponent) => void;
+        state: (c: TextFieldElementComponent) => string;
+        restore: (c: TextFieldElementComponent, state: string) => undefined;
+        disable: (c: TextFieldElementComponent, disabled: boolean) => undefined;
+    };
+    setup: (_host: import("./define.js").ElementHost<TextFieldElementComponent>, c: TextFieldElementComponent) => () => void;
+};
+export declare const textFieldElement: import("./define.js").ElementDefinition<TextFieldElementComponent>;
+export type TextFieldSpec = typeof textFieldSpec;
+/** `<m-text-field>` as a ref or a query returns it. */
+export type TextFieldElement = ElementInstance<TextFieldSpec, TextFieldElementComponent>;
+/** Registers `<m-text-field>` (or `<prefix-text-field>`). */
+export declare const defineTextField: (options?: DefineOptions) => string;
+declare global {
+    /** `document.querySelector("m-…")` and `createElement` return the element's type (the default prefix). */
+    interface HTMLElementTagNameMap {
+        "m-text-field": TextFieldElement;
+    }
+}
+export {};