material 1.0.4 → 3.0.0-next.0

package/dist/elements/datepicker.d.ts

@@ -0,0 +1,163 @@
+/**
+ * `<m-datepicker>`: the date picker as a form-associated custom element.
+ *
+ * The factory renders its own field, a text input with a calendar button:
+ * that field is the trigger. A click on the button (or on the input of a
+ * modal variant), ArrowDown in the input, the `open` attribute or `show()`
+ * opens the calendar. The modal variants (`modal`, `modal-input`,
+ * `fullscreen`) are a native `<dialog>` in the element's shadow root shown
+ * with `showModal()`: the page outside is inert and Save commits, Cancel,
+ * Escape and the backdrop do not. The docked calendar opens beside the field
+ * (`show()`, not modal) and commits each date chosen.
+ *
+ * The value is an ISO date, `YYYY-MM-DD`, as on `<input type=date>`. With
+ * `selection-mode="range"` a complete range is an ISO 8601 interval,
+ * `YYYY-MM-DD/YYYY-MM-DD`: one string for the form, with a separator no date
+ * contains. A lone date in range mode is a one-day range, `d/d`, as the
+ * factory holds it. Empty is `""`. A value that is not one of these, or
+ * that `min`, `max` or the mode rule out, empties the picker (the factory
+ * keeps no such date).
+ *
+ * The `value` attribute is the default and the `value` property the live
+ * value, as on a native input: the attribute moves the value until the user
+ * or script changes it, and a form reset returns to it. `change` is
+ * dispatched with `{ value }` when a date is committed. `open` reflects the
+ * calendar's state, as on `<dialog open>`; `open` and `close` are dispatched
+ * as it opens and closes (not when the attribute is what changed).
+ *
+ * `initial-view` is the view the calendar first opens on: `day`, `month` or
+ * `year` (the full-screen variant has the days only). `close-on-select`
+ * closes the calendar on a date chosen, committing it: a modal variant then
+ * needs no Save. The factory reads both once: a change recreates the picker.
+ *
+ * The input of a modal variant is read-only, which takes it out of constraint
+ * validation: the element reports the factory's `required` check as
+ * `valueMissing`. `readonly` is the factory's: the value stays and the
+ * calendar closed. `supporting-text` is the factory's supporting text.
+ *
+ * Parts: `datepicker`, `label`, `anchor`, `input`, `trigger`, `help`, `error`, `calendar`,
+ * `header`, `navigation`, `prev`, `next`, `weekday`, `day`, among others.
+ *
+ * @module elements
+ */
+import type { DatePickerComponent } from "../components/datepicker/types.js";
+import { type DefineOptions, type ElementHost, type ElementInstance } from "./define.js";
+/** The date picker, with what the element adds to it. */
+export interface DatepickerElementComponent extends DatePickerComponent {
+    /** Opens the calendar, unless the picker is disabled or read-only. */
+    show: () => void;
+}
+declare const datepickerSpec: {
+    name: string;
+    create: (config: import("./define.js").Config) => DatepickerElementComponent;
+    styles: string[];
+    attributes: {
+        variant: {
+            type: "string";
+            config: string;
+        };
+        "selection-mode": {
+            type: "string";
+            config: string;
+        };
+        value: {
+            type: "string";
+            config: string;
+            update: (c: DatepickerElementComponent, v: import("./define.js").AttributeValue) => void;
+        };
+        min: {
+            type: "string";
+            config: string;
+        };
+        max: {
+            type: "string";
+            config: string;
+        };
+        "date-format": {
+            type: "string";
+            config: string;
+        };
+        "initial-view": {
+            type: "string";
+            config: string;
+        };
+        "close-on-select": {
+            type: "boolean";
+            config: string;
+        };
+        label: {
+            type: "string";
+            config: string;
+        };
+        "supporting-text": {
+            type: "string";
+            config: string;
+            update: (c: DatepickerElementComponent, v: import("./define.js").AttributeValue) => undefined;
+        };
+        required: {
+            type: "boolean";
+            config: string;
+            update: (c: DatepickerElementComponent, v: import("./define.js").AttributeValue) => void;
+        };
+        disabled: {
+            type: "boolean";
+            config: string;
+            update: (c: DatepickerElementComponent, v: import("./define.js").AttributeValue) => undefined;
+        };
+        readonly: {
+            type: "boolean";
+            config: string;
+            update: (c: DatepickerElementComponent, v: import("./define.js").AttributeValue) => undefined;
+        };
+        open: {
+            type: "boolean";
+            update: (c: DatepickerElementComponent, v: import("./define.js").AttributeValue, host: HTMLElement) => void;
+        };
+    };
+    properties: {
+        value: {
+            get: (c: DatepickerElementComponent) => string;
+            set: (c: DatepickerElementComponent, value: unknown) => void;
+        };
+    };
+    model: "value";
+    methods: readonly ["show", "close"];
+    events: {
+        change: {
+            detail: (payload: unknown) => {
+                value: string;
+                date: Date | Date[] | null;
+            };
+        };
+        open: {
+            detail: () => null;
+            state: true;
+        };
+        close: {
+            detail: () => null;
+            state: true;
+        };
+    };
+    form: {
+        value: (c: DatepickerElementComponent) => string;
+        events: string[];
+        activate: (c: DatepickerElementComponent) => void;
+        state: (c: DatepickerElementComponent) => string;
+        restore: (c: DatepickerElementComponent, state: string) => void;
+        disable: (c: DatepickerElementComponent, disabled: boolean) => undefined;
+    };
+    setup: (host: ElementHost<DatepickerElementComponent>, c: DatepickerElementComponent) => () => void;
+};
+export declare const datepickerElement: import("./define.js").ElementDefinition<DatepickerElementComponent>;
+export type DatepickerSpec = typeof datepickerSpec;
+/** `<m-datepicker>` as a ref or a query returns it. */
+export type DatepickerElement = ElementInstance<DatepickerSpec, DatepickerElementComponent>;
+/** Registers `<m-datepicker>` (or `<prefix-datepicker>`). */
+export declare const defineDatepicker: (options?: DefineOptions) => string;
+declare global {
+    /** `document.querySelector("m-…")` and `createElement` return the element's type (the default prefix). */
+    interface HTMLElementTagNameMap {
+        "m-datepicker": DatepickerElement;
+    }
+}
+export {};

package/dist/elements/datepicker.js

@@ -0,0 +1,120 @@
+import createDatePicker from "../components/datepicker/index.js";
+import { toIsoValue } from "../components/datepicker/utils.js";
+import { defineElement } from "./define.js";
+const toValue = toIsoValue;
+const hosts = new WeakMap();
+let missing = null;
+const valueMissingMessage = () => (missing ?? (missing = Object.assign(document.createElement("input"), { type: "date", required: true }).validationMessage ||
+    "Please fill out this field."));
+const validate = (c) => {
+    const internals = hosts.get(c)?.internals;
+    if (!internals)
+        return;
+    if (!c.checkValidity())
+        internals.setValidity({ valueMissing: true }, valueMissingMessage(), c.input);
+    else
+        internals.setValidity({});
+};
+const setValue = (c, value) => {
+    const text = value === null || value === undefined ? "" : String(value);
+    const [start, end] = text.split("/");
+    if (start)
+        c.setValue(end === undefined ? start : [start, end]);
+    const held = c.getValue();
+    const expected = Array.isArray(held) && end === undefined ? `${text}/${text}` : text;
+    if (held !== null && toValue(held) !== expected)
+        c.clear();
+    validate(c);
+};
+const create = (config) => {
+    const { value, ...rest } = config;
+    const picker = createDatePicker(rest);
+    const component = Object.assign(picker, {
+        show: () => void picker.open(),
+    });
+    if (value)
+        setValue(component, value);
+    return component;
+};
+const isOpen = (c) => !!c.element.querySelector("dialog")?.open;
+const setOpen = (c, open, host) => {
+    if (open)
+        c.show();
+    else
+        c.close();
+    host.toggleAttribute("open", isOpen(c));
+};
+const datepickerSpec = {
+    name: "datepicker",
+    create: (config) => create(config),
+    styles: ["datepicker"],
+    attributes: {
+        variant: { type: "string", config: "variant" },
+        "selection-mode": { type: "string", config: "selectionMode" },
+        value: { type: "string", config: "value", update: (c, v) => setValue(c, v) },
+        min: { type: "string", config: "minDate" },
+        max: { type: "string", config: "maxDate" },
+        "date-format": { type: "string", config: "dateFormat" },
+        "initial-view": { type: "string", config: "initialView" },
+        "close-on-select": { type: "boolean", config: "closeOnSelect" },
+        label: { type: "string", config: "label" },
+        "supporting-text": {
+            type: "string",
+            config: "supportingText",
+            update: (c, v) => void c.setSupportingText(v === null ? null : String(v)),
+        },
+        required: {
+            type: "boolean",
+            config: "required",
+            update: (c, v) => {
+                c.setRequired(!!v);
+                validate(c);
+            },
+        },
+        disabled: { type: "boolean", config: "disabled", update: (c, v) => void (v ? c.disable() : c.enable()) },
+        readonly: { type: "boolean", config: "readOnly", update: (c, v) => void c.setReadOnly(!!v) },
+        open: { type: "boolean", update: (c, v, host) => setOpen(c, !!v, host) },
+    },
+    properties: {
+        value: { get: (c) => toValue(c.getValue()), set: setValue },
+    },
+    model: "value",
+    methods: ["show", "close"],
+    events: {
+        change: {
+            detail: (payload) => {
+                const { value, rangeEndDate } = payload;
+                const date = Array.isArray(value) ? value : value && rangeEndDate ? [value, rangeEndDate] : (value ?? null);
+                return { value: toValue(value, rangeEndDate), date };
+            },
+        },
+        open: { detail: () => null, state: true },
+        close: { detail: () => null, state: true },
+    },
+    form: {
+        value: (c) => toValue(c.getValue()),
+        events: ["change"],
+        activate: (c) => c.input.focus(),
+        state: (c) => toValue(c.getValue()),
+        restore: (c, state) => setValue(c, state),
+        disable: (c, disabled) => void (disabled ? c.disable() : c.enable()),
+    },
+    setup: (host, c) => {
+        hosts.set(c, host);
+        validate(c);
+        const reflect = () => void host.toggleAttribute("open", isOpen(c));
+        const onChange = () => validate(c);
+        c.on("open", reflect);
+        c.on("close", reflect);
+        c.on("change", onChange);
+        if (host.hasAttribute("open"))
+            setOpen(c, true, host);
+        return () => {
+            c.off("open", reflect);
+            c.off("close", reflect);
+            c.off("change", onChange);
+        };
+    },
+};
+export const datepickerElement = defineElement(datepickerSpec);
+export const defineDatepicker = (options) => datepickerElement.define(options);

package/dist/elements/define.d.ts

@@ -0,0 +1,246 @@
+/**
+ * `defineElement` turns a component factory into a custom element.
+ *
+ * The element owns one factory instance, built inside its shadow root on first
+ * connection. Attributes are the component's defaults, as on native controls;
+ * properties carry its live state. The model's attribute (`checked`, `value`)
+ * moves the live state until the state is dirty: changed by the user or set by
+ * script, as a native input's dirty value and checkedness flags. Factory
+ * events are re-dispatched from the host under the same names.
+ *
+ * Every piece of the component is a CSS part named after its BEM class
+ * without the prefix: the block by its name (`mtrl-button` is
+ * `::part(button)`), an element by its element name (`mtrl-switch__track` is
+ * `::part(track)`). The piece holding the slot also takes the slot
+ * attribute's name, so `m-button::part(label)` is the button's label.
+ *
+ * Nothing here touches the DOM at import time: the element class is built on
+ * first use, so every element module can be imported on a server.
+ *
+ * @module elements
+ */
+import { DEFAULT_PREFIX } from "./styles.js";
+/** The part of a component the element relies on. */
+export interface ElementComponent {
+    element: HTMLElement;
+    destroy: () => void;
+}
+export type AttributeType = "string" | "boolean" | "number";
+export type AttributeValue = string | boolean | number | null;
+export type Config = Record<string, unknown>;
+export interface AttributeSpec<C> {
+    type: AttributeType;
+    /** Config key the attribute feeds at creation. Omitted: the attribute is not passed to the factory. */
+    config?: string;
+    /** Applies a change after creation. Omitted: the component is recreated. */
+    update?: (component: C, value: AttributeValue, host: HTMLElement) => void;
+}
+export interface PropertySpec<C> {
+    get: (component: C) => unknown;
+    set: (component: C, value: unknown) => void;
+    /** Config key a value set before creation feeds. */
+    config?: string;
+}
+export interface EventSpec {
+    /** Maps the factory payload to the event's `detail`. Default: the payload. */
+    detail?: (payload: unknown) => unknown;
+    /**
+     * The event reports a change of state beside the model (`open`,
+     * `expanded`), not of the model: dispatching it leaves the element clean.
+     */
+    state?: boolean;
+}
+export interface SlotSpec {
+    /** Attribute whose text is the slot's fallback content. */
+    attribute: string;
+    /**
+     * The config key that takes the text or a node (`text`, `label`): the
+     * element passes its `<slot>` there and the factory places it.
+     */
+    config: string;
+}
+export interface FormSpec<C> {
+    /**
+     * The value submitted with the form under the host's `name`; FormData
+     * submits its own entries instead (several values); null submits nothing.
+     */
+    value: (component: C, host: HTMLElement) => string | FormData | null;
+    /** The inner control whose validity the element reports. */
+    control?: (component: C) => HTMLInputElement | HTMLTextAreaElement | null;
+    /** Events after which the form value is read again. */
+    events?: readonly string[];
+    /** Called when a `<label for>` or the host itself is clicked. */
+    activate?: (component: C) => void;
+    /**
+     * The state the browser keeps for the control, to hand back through
+     * `restore` when it restores the form (history navigation, autofill).
+     */
+    state?: (component: C) => string;
+    restore?: (component: C, state: string) => void;
+    disable?: (component: C, disabled: boolean) => void;
+}
+/** What a spec's `setup` sees of the element. */
+export interface ElementHost<C extends ElementComponent> extends HTMLElement {
+    /** The factory instance, while connected. */
+    readonly component: C | null;
+    readonly internals: ElementInternals | null;
+    /** The model was changed by the user or by script: its attributes no longer move it. */
+    readonly dirty: boolean;
+}
+export interface ElementSpec<C extends ElementComponent> {
+    /** Name after the prefix: "switch" registers `<m-switch>`. */
+    name: string;
+    create: (config: Config) => C;
+    /**
+     * Whether renderElement may build this element's shadow root. Defaults to
+     * true. False emits only the host and light DOM; a synchronous predicate
+     * can opt out based on the authored host. Browser upgrade is unchanged.
+     */
+    ssr?: boolean | ((host: HTMLElement) => boolean);
+    /** Style entries, in cascade order. */
+    styles: readonly string[];
+    /** CSS for the host, after the shared host rules. */
+    hostStyles?: string;
+    attributes?: Record<string, AttributeSpec<C>>;
+    properties?: Record<string, PropertySpec<C>>;
+    methods?: readonly string[];
+    /**
+     * The live property two-way binding drives (`v-model`, Svelte's `bind:`).
+     * Its attribute (the kebab-cased name) is its default: see `defaults`.
+     */
+    model?: string;
+    /**
+     * Live properties beyond `model` whose attribute is their default the same
+     * way (the slider's `secondValue` and `second-value`). A change of such an
+     * attribute moves the live state until the element is dirty, and a form
+     * reset returns to it.
+     */
+    defaults?: readonly string[];
+    events?: Record<string, EventSpec>;
+    slot?: SlotSpec;
+    /**
+     * The named slots the element reads: a child with `slot="<name>"` goes
+     * there. Declared `as const`, so the adapters type them (a Svelte snippet,
+     * a Vue slot) and describe() lists them. check-elements proves each is
+     * read and none other is (FLO-325).
+     */
+    slots?: readonly string[];
+    form?: FormSpec<C>;
+    /** Extra config read from the host, such as children. */
+    config?: (host: HTMLElement) => Config;
+    /** Wiring that lives as long as one component; returns its cleanup. */
+    setup?: (host: ElementHost<C>, component: C) => (() => void) | void;
+    /**
+     * React to the host's children changing. `true` recreates the component; a
+     * function updates it in place and returns false when it cannot, which
+     * falls back to recreating.
+     */
+    observeChildren?: boolean | ((host: ElementHost<C>, component: C) => boolean);
+}
+export interface DefineOptions {
+    /** Tag prefix, without the dash. Default "m". */
+    prefix?: string;
+}
+export { DEFAULT_PREFIX };
+/**
+ * Global base styles components rely on, which a shadow root does not inherit.
+ * Registered under these names like the component entries.
+ */
+export declare const SHADOW_BASE_STYLES: readonly ["ripple"];
+/**
+ * The sheet every shadow root adopts first. The reduced-motion rule is the
+ * document reset's (styles/base/_reset.scss), which does not match inside a
+ * shadow tree: transitions are limited to the fades, animations end at once
+ * (FLO-549). test/styles/reduced-motion.test.ts keeps the two copies equal.
+ * @internal
+ */
+export declare const BASE_HOST_STYLES: string;
+/** Internal shared host CSS, in browser cascade order. */
+export declare const hostStyleText: (spec: {
+    hostStyles?: string;
+}) => string;
+type Camel<S extends string> = S extends `${infer H}-${infer T}` ? `${H}${Capitalize<Camel<T>>}` : S;
+type ValueOf<T> = T extends "boolean" ? boolean : T extends "number" ? number : string;
+type Get<S, K extends string> = S extends {
+    [P in K]: infer V;
+} ? V : Record<never, never>;
+/** Attributes as properties, camelCased: `supporting-text` is `supportingText`. */
+export type ElementAttributes<S> = {
+    [K in keyof Get<S, "attributes"> & string as Camel<K>]?: Get<S, "attributes">[K] extends {
+        type: infer T;
+    } ? ValueOf<T> : never;
+};
+/**
+ * Attributes as markup writes them (`supporting-text`), for a bare `m-*` tag
+ * in JSX (`material/react/jsx`, `material/solid/jsx`, FLO-333).
+ */
+export type ElementMarkup<S> = {
+    [K in keyof Get<S, "attributes"> & string]?: Get<S, "attributes">[K] extends {
+        type: infer T;
+    } ? ValueOf<T> : never;
+} & ElementSlotText<S>;
+/** Live-state properties, typed by their getter. */
+export type ElementProperties<S> = {
+    [K in keyof Get<S, "properties"> & string]?: Get<S, "properties">[K] extends {
+        get: (c: never) => infer R;
+    } ? R : unknown;
+};
+/** The slot's fallback-text attribute, when the spec has one. */
+export type ElementSlotText<S> = S extends {
+    slot: {
+        attribute: infer A extends string;
+    };
+} ? string extends A ? Record<never, never> : {
+    [K in A]?: string;
+} : Record<never, never>;
+/** Event names to their `CustomEvent`, typed by the spec's `detail` mapper. */
+export type ElementEvents<S> = {
+    [K in keyof Get<S, "events"> & string]: CustomEvent<Get<S, "events">[K] extends {
+        detail: (p: never) => infer D;
+    } ? D : unknown>;
+};
+/** Methods the element forwards to its component. */
+export type ElementMethods<S, C> = S extends {
+    methods: readonly (infer M)[];
+} ? string extends M ? Record<never, never> : {
+    [K in M & keyof C & string]: C[K] extends (...args: infer A) => unknown ? (...args: A) => unknown : never;
+} : Record<never, never>;
+/**
+ * Every property an element instance has, beyond HTMLElement's. A live-state
+ * property replaces the attribute of the same name: the `checked` property is
+ * the switch's current state, the `checked` attribute only its default.
+ */
+export type ElementProps<S> = Omit<ElementAttributes<S>, keyof ElementProperties<S>> & ElementProperties<S> & ElementSlotText<S>;
+/** The names of the element's named slots, from its spec's `slots` (FLO-325). */
+export type ElementSlots<S> = S extends {
+    slots: readonly (infer N extends string)[];
+} ? N : never;
+/** A named slot as a prop name (`header-action` → `headerAction`), for adapters whose slots are props. */
+export type ElementSlotProp<S> = Camel<ElementSlots<S>>;
+/** An element instance, as a ref or `document.querySelector` returns it. */
+export type ElementInstance<S, C extends ElementComponent> = ElementHost<C> & ElementProps<S> & ElementMethods<S, C>;
+/** The element class for a spec. Called on first use, never at import. */
+export declare const createElementClass: <C extends ElementComponent>(spec: ElementSpec<C>) => CustomElementConstructor;
+/**
+ * The class of a declaration element (`<m-tab>`): it renders nothing, and each
+ * declared attribute has a property that reads and writes it. Frameworks that set
+ * a custom element's props as properties (Solid always does) then reach the
+ * attributes its parent reads, as frameworks that set attributes already did.
+ * Called on first use, never at import.
+ */
+export declare const createDeclarationClass: (attributes: Record<string, {
+    type: AttributeType;
+}>) => CustomElementConstructor;
+/** A spec with its element class and registration. */
+export interface ElementDefinition<C extends ElementComponent> {
+    spec: ElementSpec<C>;
+    /** The element class, built on first access. Browser only. */
+    readonly element: CustomElementConstructor;
+    /** Registers the element; a repeated call is a no-op. Returns the tag. Browser only. */
+    define: (options?: DefineOptions) => string;
+}
+/**
+ * Creates the definition for a spec. Nothing is built or registered until
+ * `element` or `define()` is used, so the module can be imported on a server.
+ */
+export declare const defineElement: <C extends ElementComponent>(spec: ElementSpec<C>) => ElementDefinition<C>;