@ui-sdk/web 0.0.0-stage → 0.1.0-beta.1

package/dist/date-picker.js

@@ -0,0 +1,174 @@
+// src/date-picker.ts
+import { datePicker } from "@ui-sdk/core/date-picker";
+import { partState } from "@ui-sdk/core/renderer";
+import {
+  defineCalendarParts,
+  renderCalendarParts,
+  renderDefaultCalendar
+} from "./calendar.js";
+import {
+  createParts,
+  findOwner,
+  ownButton,
+  parseAttribute
+} from "./define-element.js";
+import { showDefaultText } from "./default-text.js";
+import { element } from "./list.js";
+import { popupKinds, popupState, sheetPortal } from "./popup.js";
+var owner = "ui-date-picker";
+function defineDatePickerElements() {
+  createParts(datePicker, {
+    root: {
+      tag: owner,
+      defaults: {
+        showOutsideDays: true,
+        closeOnSelect: true,
+        dismissible: true
+      },
+      display: "block",
+      formAssociated: true,
+      kinds: popupKinds,
+      // `unavailable` as a property takes any matcher, like `{ weekday: [0, 6] }`.
+      properties: ["unavailable"],
+      // container="#id" is found in the page by the portal, never passed on as a
+      // selector. A disabled <ui-field> around it disables all of it, as a
+      // disabled Field does in the other frameworks.
+      options: (el) => ({
+        container: void 0,
+        ...el.closest("ui-field")?.hasAttribute("disabled") && {
+          disabled: true
+        }
+      }),
+      // The live `value` and `month` properties, as on a calendar.
+      state: {
+        value: {
+          get: (api) => api.getValue(),
+          set: (api, value) => api.setValue(value)
+        },
+        month: {
+          get: (api) => api.getMonth(),
+          set: (api, month) => api.setMonth(month)
+        },
+        ...popupState
+      },
+      api: [
+        "getValue",
+        "setValue",
+        "clear",
+        "getMonth",
+        "setMonth",
+        "previous",
+        "next",
+        "focus",
+        "isOpen",
+        "setOpen",
+        "open",
+        "close",
+        "toggle"
+      ],
+      // container="#id" renders the popup there, and a sheet's viewport with it.
+      portal: sheetPortal("ui-date-picker-viewport"),
+      render(picker, instance) {
+        if (!checkedForContent.has(picker)) {
+          checkedForContent.add(picker);
+          if (!picker.firstElementChild) {
+            renderDefaultContent(picker);
+          }
+        }
+        const cleanups = [
+          renderCalendarParts(picker, instance),
+          showDefaultText(
+            picker,
+            instance,
+            "ui-date-picker-hint",
+            () => partState(instance.part("hint", {})).placeholder
+          )
+        ];
+        if (hasDefaultContent.has(picker)) {
+          const update = () => matchInputs(picker, instance);
+          update();
+          cleanups.push(instance.subscribe(update));
+        }
+        return () => cleanups.forEach((cleanup) => cleanup?.());
+      }
+    },
+    input: {
+      tag: "ui-date-picker-input",
+      display: "contents",
+      target: textInput,
+      context: (el) => ({
+        id: parseAttribute("boolean", el.getAttribute("end")) ? "end" : "start"
+      }),
+      // The input's binding reads which end it holds once.
+      rebind: ["end"]
+    },
+    trigger: {
+      tag: "ui-date-picker-trigger",
+      display: "contents",
+      target: ownButton((button) => button.innerHTML = calendarIcon)
+    },
+    content: {
+      tag: "ui-date-picker-content",
+      display: "block",
+      kinds: popupKinds,
+      render(el) {
+        const picker = findOwner(el, owner);
+        if (picker && !el.firstElementChild) {
+          renderDefaultCalendar(el, picker);
+        }
+      }
+    },
+    hint: "ui-date-picker-hint",
+    clear: {
+      tag: "ui-date-picker-clear",
+      display: "contents",
+      target: ownButton()
+    },
+    // `value` is a date, or a range's two dates separated by a comma.
+    preset: {
+      tag: "ui-date-picker-preset",
+      display: "contents",
+      target: ownButton(),
+      context: (el) => ({ id: el.getAttribute("value") ?? "" })
+    }
+  });
+  defineCalendarParts(datePicker, "ui-calendar");
+}
+var calendarIcon = '<svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" aria-hidden="true"><rect x="2" y="3" width="12" height="11" rx="1.5" /><path d="M2 6.5h12M5.5 1.5v3M10.5 1.5v3" /></svg>';
+var checkedForContent = /* @__PURE__ */ new WeakSet();
+var hasDefaultContent = /* @__PURE__ */ new WeakSet();
+var renderedModes = /* @__PURE__ */ new WeakMap();
+function renderDefaultContent(picker) {
+  hasDefaultContent.add(picker);
+  picker.append(
+    element("ui-date-picker-input"),
+    element("ui-date-picker-trigger"),
+    element("ui-date-picker-content")
+  );
+}
+function matchInputs(picker, instance) {
+  const { mode } = instance.get();
+  if (renderedModes.get(picker) === mode) {
+    return;
+  }
+  renderedModes.set(picker, mode);
+  const end = picker.querySelector(":scope > ui-date-picker-input[end]");
+  if (mode !== "range") {
+    return end?.remove();
+  }
+  if (!end) {
+    picker.querySelector(":scope > ui-date-picker-input")?.after(element("ui-date-picker-input", { end: true }));
+  }
+}
+function textInput(el) {
+  const written = el.querySelector("input");
+  if (written) {
+    return written;
+  }
+  const input = element("input");
+  el.append(input);
+  return input;
+}
+export {
+  defineDatePickerElements
+};

package/dist/default-text.d.ts

@@ -0,0 +1,3 @@
+import type { PrimitiveInstance } from "@ui-sdk/core";
+declare function showDefaultText(owner: HTMLElement, instance: PrimitiveInstance, selector: string, text: (el: HTMLElement, instance: PrimitiveInstance, index: number) => string): () => void;
+export { showDefaultText };

package/dist/default-text.js

@@ -0,0 +1,24 @@
+// src/default-text.ts
+function showDefaultText(owner, instance, selector, text) {
+  const update = () => {
+    const parts = Array.from(
+      owner.querySelectorAll(selector)
+    ).filter((el) => el.closest(owner.localName) === owner);
+    parts.forEach((el, index) => {
+      if (!("text" in el.dataset) && el.childNodes.length) {
+        return;
+      }
+      el.dataset.text = "";
+      const next = text(el, instance, index);
+      if (el.textContent !== next) {
+        el.textContent = next;
+      }
+    });
+  };
+  const unsubscribe = instance.subscribe(update);
+  queueMicrotask(update);
+  return unsubscribe;
+}
+export {
+  showDefaultText
+};

package/dist/define-element.d.ts

@@ -0,0 +1,404 @@
+import type { OptionsOf, Part as InstancePart, Primitive, PrimitiveInstance, PropSpec, SlotName, TypesOf } from "@ui-sdk/core";
+import { type Feature } from "@ui-sdk/core/renderer";
+/**
+ * Whether to define a tag now. Never on the server, where importing a component
+ * does nothing, and once per tag. A tag that another library or another copy
+ * of ui-sdk defined first keeps that definition, with a warning.
+ */
+declare function claimTag(tagName: string): boolean;
+/** A stable id for any element, for parts that need a key and have none. */
+declare function autoId(el: Element): string;
+/**
+ * The button or link a wrapper part holds, like the <button> in <ui-tabs-tab>,
+ * so the part binds to it and native button behavior stays.
+ * @stable
+ */
+declare function wrappedButton(el: HTMLElement): HTMLElement | null;
+/**
+ * A `target` for a wrapper part: its child matching `selector`, like the
+ * <input> in <ui-combobox-input>, else its first child.
+ * @stable
+ */
+declare const wrappedChild: (selector: string) => (el: HTMLElement) => HTMLElement | null;
+/**
+ * A `target` for a wrapper part that binds a button: the one written inside
+ * it, else a new one holding what the part held. `fill` fills a button that
+ * would be empty, like with an arrow or an icon.
+ */
+declare function ownButton(fill?: (button: HTMLButtonElement) => void): (el: HTMLElement) => HTMLElement;
+/**
+ * How an attribute becomes an option or prop. `"boolean"`: present, empty or
+ * `"true"` is true and `"false"` is false, except `disabled` and `required`,
+ * which are true whenever present, as on native controls. `"number"`: a number. `"list"`:
+ * comma-separated values. `"string"`: the value as written. A function parses
+ * anything else, like `modal`, which is a boolean or a string.
+ * @stable
+ */
+type AttributeType = "boolean" | "number" | "string" | "list" | ((value: string | null) => unknown);
+/**
+ * An attribute's value as an option. Missing attributes are undefined, so the
+ * component's default applies.
+ */
+declare function parseAttribute(type: AttributeType, value: string | null): unknown;
+type BooleanDefaults = Record<string, boolean | ((el: HTMLElement) => boolean)>;
+declare function upgradeProperties(el: HTMLElement, names: Iterable<string>): void;
+declare function instanceOf<Api = unknown>(el: Element | null | undefined): (PrimitiveInstance & {
+    api: Api;
+}) | undefined;
+/**
+ * A part's default CSS display. `contents` keeps it out of layout, for
+ * wrappers, and the table values lay out parts that stand in for a table's
+ * elements, like a calendar's weeks and days.
+ */
+type PartDisplay = "block" | "contents" | "table" | "table-header-group" | "table-row-group" | "table-row" | "table-cell";
+/**
+ * Gives elements matching `selector` a default display, like a part's tag,
+ * or the elements a part generates inside it.
+ */
+declare function setDisplay(selector: string, value?: PartDisplay, align?: boolean): void;
+type Part = {
+    slot: string;
+    feature?: Feature;
+    el: HTMLElement;
+    props: Record<string, unknown>;
+    unbind?: () => void;
+    placeholder?: Comment;
+    disconnect?: () => void;
+    unwatch?: () => void;
+    record?: InstancePart;
+    selected?: string;
+    version?: number;
+    shown?: boolean;
+    dataSlot?: string;
+    sync?: () => void;
+    reread?: () => Record<string, unknown>;
+    keyed?: boolean;
+    observer?: MutationObserver;
+};
+declare function reconfigureInside(el: HTMLElement): void;
+type OwnerElement = HTMLElement & {
+    register: (part: Part) => void;
+    unregister: (part: Part) => void;
+    update: (part: Part, rebind: boolean) => void;
+    rebind: () => void;
+};
+/** Popups inside `container` inherit `to` instead, or render in place for null. */
+declare function passPortalOn(container: Element, to: Element | DocumentFragment | null): void;
+/**
+ * The container the nearest portaled part above `el` renders into. A popup
+ * inside a portaled popup renders there too, unless it names its own.
+ */
+declare function inheritedPortal(el: Element): Element | DocumentFragment | null;
+/**
+ * The nearest owner above `el`, or the owner of the nearest part above it.
+ * Popups may have moved to a portal, so the DOM alone can't answer. A part with
+ * `for="id"` names its owner anywhere on the page, like a trigger in a table row.
+ * Parts of other components in between are skipped, like a popover trigger
+ * inside a tooltip trigger.
+ */
+declare function findOwner(el: Element, selector: string): OwnerElement | undefined;
+/**
+ * The element `selector` matches, like a popup's `container="#id"`. Looked up
+ * in the element's own tree first, like `for`, then in each tree around it up
+ * to the document, so a popup in a shadow root can name a container outside it.
+ */
+declare function findContainer(el: Element, selector: string): Element | null;
+declare function whenGone(el: HTMLElement, run: () => void): void;
+type OwnerConfig<P extends Primitive> = {
+    /**
+     * Attributes, by option name in camelCase. Each is read from its kebab-case
+     * attribute, observed, and parsed by its type. `debug` is always there.
+     */
+    attributes?: Record<string, AttributeType>;
+    /** Options that don't come from attributes, like a group found in the page. */
+    options?: (el: HTMLElement) => Partial<OptionsOf<P>>;
+    /**
+     * Live properties for the state a user controls, like `open` or `value`.
+     * Setting one changes the state as a controller would, and fires the
+     * change event. An attribute of the same name sets the starting state, and
+     * changing it later changes the state the same way.
+     */
+    state?: Record<string, {
+        get: (api: any) => unknown;
+        set: (api: any, value: any) => void;
+    }>;
+    /** The controller's methods, which the element's `api` property exposes. */
+    api?: string[];
+    /** Callbacks that fire no event, because part elements already report them. */
+    silent?: string[];
+    /** Callbacks whose event hands listeners `waitUntil()`, from the schema's `"action"` kind. */
+    actions?: string[];
+    /**
+     * Event names for callbacks whose own name a native event that bubbles in
+     * already takes, like `{ onSelect: "itemselect" }` beside a text field's `select`.
+     */
+    events?: Record<string, string>;
+    /**
+     * Runs once the instance exists, and again when a property is set, with
+     * the element and its instance, which only this hook sees. Data elements
+     * render their parts here. A returned cleanup runs before the next render
+     * and once the element is gone, like a store subscription's.
+     */
+    render?: (el: HTMLElement, instance: ReturnType<P>) => void | (() => void);
+    /**
+     * Attributes for the element itself, like role="none" on wrappers that
+     * must not split a list for assistive technology.
+     */
+    host?: Record<string, string>;
+    /** The element's CSS display. `contents` keeps it out of layout, for wrappers. Inline by default. */
+    display?: PartDisplay;
+    /** The slot the element itself fills, like the root of a tabs widget. */
+    self?: string;
+    /**
+     * Native elements inside it that fill slots, like the <fieldset> inside
+     * <ui-field-set>. They keep their native behavior, which a custom element can't
+     * have, like a fieldset disabling the controls inside it. A missing one
+     * warns, unless its slot is in `optionalChildren`, like a fieldset's legend.
+     */
+    children?: Record<string, (el: HTMLElement) => HTMLElement | null>;
+    /**
+     * The element the `self` slot binds to, when it isn't the element itself,
+     * like the <button> inside <ui-button>, so native button behavior stays.
+     */
+    target?: (el: HTMLElement) => HTMLElement | null;
+    /** Slots in `children` that may be missing without a warning, like a fieldset's legend. */
+    optionalChildren?: string[];
+    /**
+     * The native children's attributes that props or options follow, like an
+     * <input>'s `disabled`, `readonly` and `required`, or its `autocomplete`.
+     * A change reads `read` and the options again.
+     */
+    childProps?: {
+        attributes: string[];
+        read?: (el: HTMLElement) => Record<string, unknown>;
+    };
+    /**
+     * Slots that move into a container while present, like popups. Without
+     * top layer support they move to the body. The container is asked on
+     * every sync, with the part, so a part can move while bound, like a
+     * navigation menu's content into its viewport as it opens.
+     */
+    portal?: {
+        slots: string[];
+        container: (el: HTMLElement, part: {
+            slot: string;
+            el: HTMLElement;
+            props: Record<string, unknown>;
+        }) => Element | DocumentFragment | null;
+    };
+    /**
+     * Properties, like a data menu's items or a `controller`. Each one set goes
+     * into the options, and setting one updates them and renders again.
+     */
+    properties?: string[];
+    /** Takes part in forms like a native control, like <ui-checkbox name="terms">. */
+    formAssociated?: boolean;
+    /**
+     * Boolean options that start on, like `{ loop: true }`, so their
+     * properties read true without the attribute and `false` writes "false".
+     * A function decides from the element, like `closeOnOutsidePress` from `modal`.
+     */
+    defaults?: Partial<Record<keyof OptionsOf<P> & string, BooleanDefaults[string]>>;
+};
+type SlotConfig = {
+    /** The owner primitive's slot this element fills. */
+    slot: string;
+    /** Owner elements this part can belong to. */
+    owner: string;
+    /** Attributes read as props, by name in camelCase, each with its type. */
+    props?: Record<string, AttributeType>;
+    /** Props that come from the surroundings, like the group a radio item is in. */
+    context?: (el: HTMLElement) => Record<string, unknown>;
+    /**
+     * Props that, left out, come from a prop of the nearest part around it of
+     * the slot named, like a handle's `value` from its item's.
+     */
+    from?: Record<string, {
+        slot: string;
+        prop: string;
+    }>;
+    /** Props made unique for each element, like an icon's `id`. */
+    ids?: string[];
+    /**
+     * The element the slot binds to, when it isn't the part itself. Without it,
+     * an as-child attribute binds the part's first child instead, like a link.
+     */
+    target?: (el: HTMLElement) => HTMLElement | null;
+    /** Runs once before the first registration, to add generated children. */
+    render?: (el: HTMLElement) => void;
+    /** Runs when one of its `props` attributes changes, for generated children that follow it. */
+    changed?: (el: HTMLElement) => void;
+    /** The element's CSS display. `contents` keeps it out of layout, for wrappers. Inline by default. */
+    display?: PartDisplay;
+    /** Form-associated, so labels and fieldsets treat it like a native control. */
+    formAssociated?: boolean;
+    /** Properties read as props, like a trigger's `payload`. Setting one re-syncs the part. */
+    properties?: string[];
+    /** Boolean props that start on, like `{ closeOnSelect: true }`, as the owner's `defaults`. */
+    defaults?: BooleanDefaults;
+    /** Props the part's core binding reads once, so a change binds it again. */
+    rebind?: string[];
+    /** @internal The feature that ships the slot, like a select's select-all option. */
+    feature?: Feature;
+    /**
+     * @internal Runs on the element the part binds when no owner is around it,
+     * in place of the warning that it needs one, for a part that works alone,
+     * like a field label wrapping a whole field. It gets the bound element and
+     * the part element, which holds the attributes, and runs again when they change.
+     */
+    alone?: (el: HTMLElement, host: HTMLElement) => void;
+    /** Callbacks whose event hands listeners `waitUntil()`, from the schema's `"action"` kind. */
+    actions?: string[];
+    /** Whether its `value` keys it, like a list item's, from the schema's `"key"` kind. */
+    keyed?: boolean;
+};
+/**
+ * Web-only kinds that replace the schema's, by prop name, like
+ * `{ container: "string" }` for a container named by a selector. `null`
+ * leaves a prop out, for one the element sets itself, like a group it finds
+ * around it.
+ * @stable
+ */
+type Kinds = Record<string, PropSpec | null>;
+/**
+ * How `createParts` and `definePart` define a part's element, beyond its tag.
+ * @stable
+ */
+type PartOptions<P extends Primitive = Primitive> = {
+    /** The element's tag, like `"ui-tabs-tab"`. */
+    tag: string;
+    /**
+     * The slot it fills, when it isn't its key, like a radio filling the root
+     * slot of a radio group whose own element is the group.
+     */
+    slot?: SlotName<P>;
+    /** Owners of another primitive it belongs to as well, like a calendar day's <ui-date-picker>. */
+    owners?: string[];
+    kinds?: Kinds;
+    /** Properties beyond the schema's, read as props. */
+    properties?: string[];
+} & Omit<SlotConfig, "slot" | "owner" | "props" | "properties" | "from" | "ids" | "actions" | "keyed">;
+/**
+ * How `createParts` and `definePart` define the root's element, the one that owns an instance, beyond its tag.
+ * @stable
+ */
+type RootOptions<P extends Primitive> = {
+    /** The element's tag, like `"ui-tabs"`. */
+    tag: string;
+    /**
+     * The slot the element itself fills, when it isn't `root`, like a radio
+     * group's `group`. Without one, it fills `root` when the primitive has it
+     * and no native child fills it.
+     */
+    self?: SlotName<P>;
+    kinds?: Kinds;
+    /**
+     * Properties beyond the schema's, which go into the options, like a
+     * `filter` function beside its attribute.
+     */
+    properties?: string[];
+    /**
+     * Live properties for the state a user controls, like `open` or `value`.
+     * Setting one changes the state as a controller would, and fires the
+     * change event. An attribute of the same name sets the starting state, and
+     * changing it later changes the state the same way.
+     */
+    state?: Record<string, {
+        get: (api: TypesOf<P>["api"]) => unknown;
+        set: (api: TypesOf<P>["api"], value: any) => void;
+    }>;
+    /** The controller's methods, which the element's `api` property exposes. */
+    api?: (keyof TypesOf<P>["api"] & string)[];
+} & Omit<OwnerConfig<P>, "attributes" | "properties" | "self" | "state" | "api" | "actions">;
+/**
+ * What `definePart` defines for a slot: for `root`, the element that owns an
+ * instance, with the primitive's options as attributes and properties; for
+ * any other slot, an element that finds that owner, with the slot's props.
+ * The kinds come from the primitive's schema. A root's tag is remembered, so
+ * the parts defined after it find their owner. The docs' elements manifest
+ * reads it too.
+ */
+declare function partElement<P extends Primitive>(primitive: P, key: string, tagOrOptions: string | RootOptions<P> | PartOptions<P>, root?: string): {
+    kind: "owner";
+    key: string;
+    tagName: string;
+    config: OwnerConfig<P>;
+} | {
+    kind: "part";
+    key: string;
+    tagName: string;
+    config: SlotConfig;
+};
+/**
+ * The tags `createParts` takes: `root` for the element that owns an
+ * instance, and each slot it renders by name. A part under another key
+ * names its slot, like `{ radio: { tag: "ui-radio", slot: "root" } }`.
+ */
+type PartTags<P extends Primitive> = {
+    root: string | RootOptions<P>;
+} & {
+    [S in Exclude<SlotName<P>, "root">]?: string | PartOptions<P>;
+};
+/**
+ * Every element `createParts` defines, as `partElement` describes each, the
+ * root first, so its parts know their owner's tag.
+ */
+declare function partElements<P extends Primitive>(primitive: P, tags: PartTags<P>): ({
+    kind: "owner";
+    key: string;
+    tagName: string;
+    config: OwnerConfig<P>;
+} | {
+    kind: "part";
+    key: string;
+    tagName: string;
+    config: SlotConfig;
+})[];
+type Pascal<Name extends string> = Name extends `${infer Head}-${infer Tail}` ? `${Capitalize<Head>}${Pascal<Tail>}` : Capitalize<Name>;
+/**
+ * The element classes `createParts` returns: `Root`, and one per tagged
+ * part, named in Pascal case. Each is `undefined` on the server.
+ * @stable
+ */
+type Parts<Tags> = {
+    [K in keyof Tags & string as Pascal<K>]: CustomElementConstructor | undefined;
+};
+/**
+ * Defines a custom element for each part of a primitive, typed from it.
+ * `root` is the element that owns an instance: the primitive's options are
+ * its attributes (strings, numbers, booleans and comma-separated lists),
+ * each reflected by a property, and properties (any other value), and its
+ * callbacks are events, like
+ * `onValueChange` firing `valuechange`. Every other slot named becomes an
+ * element that finds the root above it, with the slot's props read the same
+ * way. A part that needs more than a tag takes an object, like
+ * `{ tag, display, target, render }`, and the root's takes `state`, `api` and
+ * `display` too. Defines each tag once, and returns the element classes,
+ * `Root` and one per part named in Pascal case, like `TabIcon` for
+ * `tab-icon`. On the server it defines nothing and the classes are
+ * `undefined`.
+ *
+ * @example
+ * createParts(tabs, {
+ *   root: { tag: "ui-tabs", display: "block", api: ["select"] },
+ *   list: "ui-tabs-list",
+ *   // Binds the <button> inside, so it stays a real button.
+ *   tab: { tag: "ui-tabs-tab", display: "contents", target: wrappedButton },
+ *   panel: "ui-tabs-panel",
+ * })
+ * @stable
+ */
+declare function createParts<P extends Primitive, Tags extends PartTags<P>>(primitive: P, tags: Tags): Parts<Tags>;
+/**
+ * Defines the custom element for one part of a primitive, written by hand:
+ * the root, which owns an instance, or a part that finds the root above it.
+ * Its attributes, properties and events come from the primitive's schema, as
+ * in `createParts`. Define the root first. A second root of the same
+ * primitive, like a submenu's, owns the parts defined after it too.
+ *
+ * @example
+ * definePart(rating, "root", "my-rating")
+ * definePart(rating, "star", { tag: "my-rating-star", target: wrappedButton })
+ */
+declare function definePart<P extends Primitive, S extends SlotName<P> | "root">(primitive: P, slot: S, tagOrOptions: S extends "root" ? string | RootOptions<P> : string | PartOptions<P>): void;
+export { type AttributeType, autoId, claimTag, createParts, definePart, findContainer, findOwner, inheritedPortal, instanceOf, type Kinds, ownButton, parseAttribute, type PartDisplay, partElement, partElements, type PartOptions, type Parts, type PartTags, passPortalOn, type RootOptions, reconfigureInside, setDisplay, upgradeProperties, whenGone, wrappedButton, wrappedChild, };