@fluixi/web-components 0.0.0-stage → 1.0.0-alpha.100

package/dist/props.cjs

@@ -0,0 +1,114 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/props.ts
+var props_exports = {};
+__export(props_exports, {
+  createPropStates: () => createPropStates,
+  observedFrom: () => observedFrom,
+  prop: () => prop
+});
+module.exports = __toCommonJS(props_exports);
+var import_signal = require("@fluixi/reactive/signal");
+var same = (a, b) => a === b;
+function declare(initial, fromAttribute, toAttribute, options = {}) {
+  return {
+    initial,
+    attribute: options.attribute ?? "",
+    reflect: options.reflect ?? false,
+    fromAttribute,
+    toAttribute,
+    equals: options.equals ?? same
+  };
+}
+var prop = {
+  string: (initial = "", options = {}) => declare(initial, (v) => v ?? initial, (v) => v, options),
+  number: (initial = 0, options = {}) => declare(
+    initial,
+    (v) => {
+      const n = v === null || v.trim() === "" ? NaN : Number(v);
+      return Number.isNaN(n) ? initial : n;
+    },
+    (v) => String(v),
+    options
+  ),
+  boolean: (initial = false, options = {}) => declare(initial, (v) => v !== null, (v) => v ? "" : null, options),
+  /**
+   * JSON in the attribute, the parsed value in the property.
+   *
+   * Unparseable text keeps the initial value rather than throwing: the attribute is
+   * author-supplied and often mid-edit, and an exception in `attributeChangedCallback`
+   * leaves the element half-upgraded.
+   */
+  object: (initial, options = {}) => declare(
+    initial,
+    (v) => {
+      if (v === null) return initial;
+      try {
+        return JSON.parse(v);
+      } catch {
+        return initial;
+      }
+    },
+    (v) => v === void 0 ? null : JSON.stringify(v),
+    options
+  ),
+  /**
+   * Your own conversion, for a type the built-ins don't cover: a date, a list, a unit.
+   *
+   * `fromAttribute` only sees a present attribute; removing it goes back to `initial`, so a
+   * converter never has to handle `null`. It may return `initial` for text it can't read.
+   * `toAttribute` is needed only to reflect, and returning `null` removes the attribute.
+   *
+   * @example
+   * ```ts
+   * due: prop.custom(new Date(0), {
+   *   fromAttribute: (v) => new Date(v),
+   *   toAttribute: (d) => d.toISOString(),
+   * }, { equals: (a, b) => a.getTime() === b.getTime() }),
+   * ```
+   */
+  custom: (initial, converter, options = {}) => declare(
+    initial,
+    (v) => v === null ? initial : converter.fromAttribute(v),
+    converter.toAttribute ?? ((v) => v == null ? null : String(v)),
+    options
+  ),
+  /** No attribute at all. For a value only a property assignment can carry. */
+  any: (initial, options = {}) => declare(initial, () => initial, () => null, { ...options, attribute: false })
+};
+function createPropStates(schema) {
+  const states = {};
+  for (const [name, declaration] of Object.entries(schema)) {
+    const value = (0, import_signal.signal)(declaration.initial, { equals: declaration.equals, name });
+    states[name] = {
+      read: value,
+      // `.set` reads a function argument as an updater and calls it. A property holding
+      // a callback is ordinary for a custom element, so it is wrapped: the value
+      // arrives as the return of an updater that ignores the previous one.
+      write: (next) => void (typeof next === "function" ? value.set(() => next) : value.set(next)),
+      declaration,
+      attribute: declaration.attribute === "" ? name.toLowerCase() : declaration.attribute
+    };
+  }
+  return states;
+}
+function observedFrom(schema) {
+  return Object.entries(schema).map(([name, d]) => d.attribute === "" ? name.toLowerCase() : d.attribute).filter((a) => a !== false);
+}

package/dist/props.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Properties, and the attributes that mirror them.
+ *
+ * A custom element has two ways in. A property assignment (`el.count = 3`) carries a
+ * real value and is what a framework binding uses. An attribute (`count="3"`) carries
+ * a string and is what HTML and a server render can express. Both have to land on the
+ * same signal or the two go out of sync.
+ *
+ * Each declaration owns the conversion in one place, so the element never guesses.
+ * `attribute: false` opts a property out of HTML entirely, which is the right answer
+ * for anything a string cannot carry: a function, a Date, a large object.
+ */
+import { type Accessor } from '@fluixi/reactive/signal';
+export interface PropDeclaration<T> {
+    /** Value before anything sets one. */
+    readonly initial: T;
+    /**
+     * The attribute this mirrors, or false for a property with no HTML form.
+     * Defaults to the property name lowercased.
+     */
+    readonly attribute: string | false;
+    /** Write the property back out to the attribute whenever it changes. */
+    readonly reflect: boolean;
+    /** Attribute string to property value. `null` means the attribute was removed. */
+    fromAttribute(value: string | null): T;
+    /** Property value to attribute string. `null` removes the attribute. */
+    toAttribute(value: T): string | null;
+    /** Skip a write that would not change anything, so a reflect loop terminates. */
+    equals(a: T, b: T): boolean;
+}
+export type PropsSchema = Record<string, PropDeclaration<never>>;
+/** The reactive accessors an element exposes for its declared properties. */
+export type PropAccessors<S extends Record<string, PropDeclaration<unknown>>> = {
+    readonly [K in keyof S]: Accessor<S[K] extends PropDeclaration<infer T> ? T : never>;
+};
+export interface PropOptions<T> {
+    attribute?: string | false;
+    reflect?: boolean;
+    equals?: (a: T, b: T) => boolean;
+}
+/**
+ * The built-in conversions.
+ *
+ * `boolean` follows HTML rather than JSON: presence is true, absence is false, and the
+ * value is ignored, so `disabled=""` and `disabled="false"` are both true. Anything
+ * else would disagree with every native element on the page.
+ */
+export declare const prop: {
+    string: (initial?: string, options?: PropOptions<string>) => PropDeclaration<string>;
+    number: (initial?: number, options?: PropOptions<number>) => PropDeclaration<number>;
+    boolean: (initial?: boolean, options?: PropOptions<boolean>) => PropDeclaration<boolean>;
+    /**
+     * JSON in the attribute, the parsed value in the property.
+     *
+     * Unparseable text keeps the initial value rather than throwing: the attribute is
+     * author-supplied and often mid-edit, and an exception in `attributeChangedCallback`
+     * leaves the element half-upgraded.
+     */
+    object: <T>(initial: T, options?: PropOptions<T>) => PropDeclaration<T>;
+    /**
+     * Your own conversion, for a type the built-ins don't cover: a date, a list, a unit.
+     *
+     * `fromAttribute` only sees a present attribute; removing it goes back to `initial`, so a
+     * converter never has to handle `null`. It may return `initial` for text it can't read.
+     * `toAttribute` is needed only to reflect, and returning `null` removes the attribute.
+     *
+     * @example
+     * ```ts
+     * due: prop.custom(new Date(0), {
+     *   fromAttribute: (v) => new Date(v),
+     *   toAttribute: (d) => d.toISOString(),
+     * }, { equals: (a, b) => a.getTime() === b.getTime() }),
+     * ```
+     */
+    custom: <T>(initial: T, converter: {
+        fromAttribute: (value: string) => T;
+        toAttribute?: (value: T) => string | null;
+    }, options?: PropOptions<T>) => PropDeclaration<T>;
+    /** No attribute at all. For a value only a property assignment can carry. */
+    any: <T>(initial: T, options?: Omit<PropOptions<T>, "attribute" | "reflect">) => PropDeclaration<T>;
+};
+/** One property's signal plus the declaration that drives its attribute. */
+export interface PropState<T> {
+    read: Accessor<T>;
+    write(value: T): void;
+    declaration: PropDeclaration<T>;
+    /** The attribute name, resolved from the property name when it was left blank. */
+    attribute: string | false;
+}
+export declare function createPropStates(schema: Record<string, PropDeclaration<unknown>>): Record<string, PropState<unknown>>;
+/** The attribute names an element has to observe, derived from its schema. */
+export declare function observedFrom(schema: Record<string, PropDeclaration<unknown>>): string[];
+//# sourceMappingURL=props.d.ts.map

package/dist/props.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"props.d.ts","sourceRoot":"","sources":["../src/props.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAU,KAAK,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEhE,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,sCAAsC;IACtC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CAAC;IACnC,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,kFAAkF;IAClF,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC;IACvC,wEAAwE;IACxE,WAAW,CAAC,KAAK,EAAE,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC;IACrC,iFAAiF;IACjF,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC;CAC7B;AAED,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC;AAEjE,6EAA6E;AAC7E,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC,IAAI;IAC9E,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,eAAe,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;CACrF,CAAC;AAEF,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;CAClC;AAoBD;;;;;;GAMG;AACH,eAAO,MAAM,IAAI;yCACiB,WAAW,CAAC,MAAM,CAAC;yCAGpB,WAAW,CAAC,MAAM,CAAC;2CAad,WAAW,CAAC,OAAO,CAAC;IAGxD;;;;;;OAMG;aACM,CAAC,WAAW,CAAC,YAAW,WAAW,CAAC,CAAC,CAAC;IAe/C;;;;;;;;;;;;;;OAcG;aACM,CAAC,WACC,CAAC,aACC;QAAE,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,CAAC,CAAC;QAAC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,GAAG,IAAI,CAAA;KAAE,YACpF,WAAW,CAAC,CAAC,CAAC;IASzB,6EAA6E;UACvE,CAAC,WAAW,CAAC,YAAW,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAE5E,CAAC;AAEF,4EAA4E;AAC5E,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IAClB,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACtB,WAAW,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC;IAChC,kFAAkF;IAClF,SAAS,EAAE,MAAM,GAAG,KAAK,CAAC;CAC3B;AAED,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC,GAC/C,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC,CAiBpC;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC,GAAG,MAAM,EAAE,CAIvF"}

package/dist/props.js

@@ -0,0 +1,99 @@
+/**
+ * Properties, and the attributes that mirror them.
+ *
+ * A custom element has two ways in. A property assignment (`el.count = 3`) carries a
+ * real value and is what a framework binding uses. An attribute (`count="3"`) carries
+ * a string and is what HTML and a server render can express. Both have to land on the
+ * same signal or the two go out of sync.
+ *
+ * Each declaration owns the conversion in one place, so the element never guesses.
+ * `attribute: false` opts a property out of HTML entirely, which is the right answer
+ * for anything a string cannot carry: a function, a Date, a large object.
+ */
+import { signal } from '@fluixi/reactive/signal';
+const same = (a, b) => a === b;
+function declare(initial, fromAttribute, toAttribute, options = {}) {
+    return {
+        initial,
+        attribute: options.attribute ?? '',
+        reflect: options.reflect ?? false,
+        fromAttribute,
+        toAttribute,
+        equals: options.equals ?? same,
+    };
+}
+/**
+ * The built-in conversions.
+ *
+ * `boolean` follows HTML rather than JSON: presence is true, absence is false, and the
+ * value is ignored, so `disabled=""` and `disabled="false"` are both true. Anything
+ * else would disagree with every native element on the page.
+ */
+export const prop = {
+    string: (initial = '', options = {}) => declare(initial, (v) => v ?? initial, (v) => v, options),
+    number: (initial = 0, options = {}) => declare(initial, (v) => {
+        // Unparseable text keeps the initial value, as `object` does: NaN would pass every
+        // type check and then poison arithmetic downstream.
+        const n = v === null || v.trim() === '' ? NaN : Number(v);
+        return Number.isNaN(n) ? initial : n;
+    }, (v) => String(v), options),
+    boolean: (initial = false, options = {}) => declare(initial, (v) => v !== null, (v) => (v ? '' : null), options),
+    /**
+     * JSON in the attribute, the parsed value in the property.
+     *
+     * Unparseable text keeps the initial value rather than throwing: the attribute is
+     * author-supplied and often mid-edit, and an exception in `attributeChangedCallback`
+     * leaves the element half-upgraded.
+     */
+    object: (initial, options = {}) => declare(initial, (v) => {
+        if (v === null)
+            return initial;
+        try {
+            return JSON.parse(v);
+        }
+        catch {
+            return initial;
+        }
+    }, (v) => (v === undefined ? null : JSON.stringify(v)), options),
+    /**
+     * Your own conversion, for a type the built-ins don't cover: a date, a list, a unit.
+     *
+     * `fromAttribute` only sees a present attribute; removing it goes back to `initial`, so a
+     * converter never has to handle `null`. It may return `initial` for text it can't read.
+     * `toAttribute` is needed only to reflect, and returning `null` removes the attribute.
+     *
+     * @example
+     * ```ts
+     * due: prop.custom(new Date(0), {
+     *   fromAttribute: (v) => new Date(v),
+     *   toAttribute: (d) => d.toISOString(),
+     * }, { equals: (a, b) => a.getTime() === b.getTime() }),
+     * ```
+     */
+    custom: (initial, converter, options = {}) => declare(initial, (v) => (v === null ? initial : converter.fromAttribute(v)), converter.toAttribute ?? ((v) => (v == null ? null : String(v))), options),
+    /** No attribute at all. For a value only a property assignment can carry. */
+    any: (initial, options = {}) => declare(initial, () => initial, () => null, { ...options, attribute: false }),
+};
+export function createPropStates(schema) {
+    const states = {};
+    for (const [name, declaration] of Object.entries(schema)) {
+        // Named, so the devtools graph shows `step` rather than an anonymous signal.
+        const value = signal(declaration.initial, { equals: declaration.equals, name });
+        states[name] = {
+            read: value,
+            // `.set` reads a function argument as an updater and calls it. A property holding
+            // a callback is ordinary for a custom element, so it is wrapped: the value
+            // arrives as the return of an updater that ignores the previous one.
+            write: (next) => void (typeof next === 'function' ? value.set(() => next) : value.set(next)),
+            declaration,
+            attribute: declaration.attribute === '' ? name.toLowerCase() : declaration.attribute,
+        };
+    }
+    return states;
+}
+/** The attribute names an element has to observe, derived from its schema. */
+export function observedFrom(schema) {
+    return Object.entries(schema)
+        .map(([name, d]) => (d.attribute === '' ? name.toLowerCase() : d.attribute))
+        .filter((a) => a !== false);
+}

package/dist/props.mjs

@@ -0,0 +1,93 @@
+// src/props.ts
+import { signal } from "@fluixi/reactive/signal";
+var same = (a, b) => a === b;
+function declare(initial, fromAttribute, toAttribute, options = {}) {
+  return {
+    initial,
+    attribute: options.attribute ?? "",
+    reflect: options.reflect ?? false,
+    fromAttribute,
+    toAttribute,
+    equals: options.equals ?? same
+  };
+}
+var prop = {
+  string: (initial = "", options = {}) => declare(initial, (v) => v ?? initial, (v) => v, options),
+  number: (initial = 0, options = {}) => declare(
+    initial,
+    (v) => {
+      const n = v === null || v.trim() === "" ? NaN : Number(v);
+      return Number.isNaN(n) ? initial : n;
+    },
+    (v) => String(v),
+    options
+  ),
+  boolean: (initial = false, options = {}) => declare(initial, (v) => v !== null, (v) => v ? "" : null, options),
+  /**
+   * JSON in the attribute, the parsed value in the property.
+   *
+   * Unparseable text keeps the initial value rather than throwing: the attribute is
+   * author-supplied and often mid-edit, and an exception in `attributeChangedCallback`
+   * leaves the element half-upgraded.
+   */
+  object: (initial, options = {}) => declare(
+    initial,
+    (v) => {
+      if (v === null) return initial;
+      try {
+        return JSON.parse(v);
+      } catch {
+        return initial;
+      }
+    },
+    (v) => v === void 0 ? null : JSON.stringify(v),
+    options
+  ),
+  /**
+   * Your own conversion, for a type the built-ins don't cover: a date, a list, a unit.
+   *
+   * `fromAttribute` only sees a present attribute; removing it goes back to `initial`, so a
+   * converter never has to handle `null`. It may return `initial` for text it can't read.
+   * `toAttribute` is needed only to reflect, and returning `null` removes the attribute.
+   *
+   * @example
+   * ```ts
+   * due: prop.custom(new Date(0), {
+   *   fromAttribute: (v) => new Date(v),
+   *   toAttribute: (d) => d.toISOString(),
+   * }, { equals: (a, b) => a.getTime() === b.getTime() }),
+   * ```
+   */
+  custom: (initial, converter, options = {}) => declare(
+    initial,
+    (v) => v === null ? initial : converter.fromAttribute(v),
+    converter.toAttribute ?? ((v) => v == null ? null : String(v)),
+    options
+  ),
+  /** No attribute at all. For a value only a property assignment can carry. */
+  any: (initial, options = {}) => declare(initial, () => initial, () => null, { ...options, attribute: false })
+};
+function createPropStates(schema) {
+  const states = {};
+  for (const [name, declaration] of Object.entries(schema)) {
+    const value = signal(declaration.initial, { equals: declaration.equals, name });
+    states[name] = {
+      read: value,
+      // `.set` reads a function argument as an updater and calls it. A property holding
+      // a callback is ordinary for a custom element, so it is wrapped: the value
+      // arrives as the return of an updater that ignores the previous one.
+      write: (next) => void (typeof next === "function" ? value.set(() => next) : value.set(next)),
+      declaration,
+      attribute: declaration.attribute === "" ? name.toLowerCase() : declaration.attribute
+    };
+  }
+  return states;
+}
+function observedFrom(schema) {
+  return Object.entries(schema).map(([name, d]) => d.attribute === "" ? name.toLowerCase() : d.attribute).filter((a) => a !== false);
+}
+export {
+  createPropStates,
+  observedFrom,
+  prop
+};

package/dist/registry.cjs

@@ -0,0 +1,77 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/registry.ts
+var registry_exports = {};
+__export(registry_exports, {
+  defineCustomElement: () => defineCustomElement,
+  defineWhenUsed: () => defineWhenUsed,
+  isDefined: () => isDefined,
+  resetRegistryTracking: () => resetRegistryTracking
+});
+module.exports = __toCommonJS(registry_exports);
+var import_dom = require("@fluixi/dom");
+var defined = /* @__PURE__ */ new Map();
+function registry() {
+  return typeof customElements === "undefined" ? null : customElements;
+}
+function defineCustomElement(name, constructor, options = {}) {
+  if ((0, import_dom.isServer)() && typeof HTMLElement !== "undefined") return constructor;
+  const registered = defined.get(name);
+  if (registered) return registered;
+  const ce = registry();
+  if (!ce) return constructor;
+  const existing = ce.get(name);
+  if (existing) {
+    defined.set(name, existing);
+    return existing;
+  }
+  ce.define(name, constructor, options.extends ? { extends: options.extends } : void 0);
+  defined.set(name, constructor);
+  return constructor;
+}
+function isDefined(name) {
+  return defined.has(name) || registry()?.get(name) !== void 0;
+}
+function defineWhenUsed(name, load, options = {}) {
+  if ((0, import_dom.isServer)() || typeof document === "undefined") return;
+  let started = false;
+  const start = async () => {
+    if (started) return;
+    started = true;
+    defineCustomElement(name, await load(), options);
+  };
+  if (document.querySelector(name)) {
+    void start();
+    return;
+  }
+  if (typeof MutationObserver === "undefined") {
+    void start();
+    return;
+  }
+  const observer = new MutationObserver(() => {
+    if (!document.querySelector(name)) return;
+    observer.disconnect();
+    void start();
+  });
+  observer.observe(document.documentElement, { childList: true, subtree: true });
+}
+function resetRegistryTracking() {
+  defined.clear();
+}

package/dist/registry.d.ts

@@ -0,0 +1,26 @@
+export interface DefineOptions {
+    /** Extend a built-in, as `is="..."`. Safari does not implement this. */
+    extends?: string;
+}
+/**
+ * Register a constructor under a name, at most once.
+ *
+ * Returns the constructor actually registered, which is the previously registered one
+ * when the name is already taken. That matters for a standalone bundle: two copies of
+ * the same component on a page should agree on which class the tag upgrades to, and
+ * the first to load wins.
+ */
+export declare function defineCustomElement(name: string, constructor: CustomElementConstructor, options?: DefineOptions): CustomElementConstructor;
+/** Whether a name has been claimed, by this module or anyone else. */
+export declare function isDefined(name: string): boolean;
+/**
+ * Register only once the tag is actually in the document.
+ *
+ * A component that costs something to load should not cost it on a page that never
+ * uses the tag. The observer disconnects after the first match, so the scan is paid
+ * for once.
+ */
+export declare function defineWhenUsed(name: string, load: () => CustomElementConstructor | Promise<CustomElementConstructor>, options?: DefineOptions): void;
+/** Test seam: forget what this module has registered. The registry itself is permanent. */
+export declare function resetRegistryTracking(): void;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AASD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,wBAAwB,EACrC,OAAO,GAAE,aAAkB,GAC1B,wBAAwB,CAuB1B;AAED,sEAAsE;AACtE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,wBAAwB,GAAG,OAAO,CAAC,wBAAwB,CAAC,EACxE,OAAO,GAAE,aAAkB,GAC1B,IAAI,CA0BN;AAED,2FAA2F;AAC3F,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C"}

package/dist/registry.js

@@ -0,0 +1,91 @@
+/**
+ * Registration, which is global and happens once.
+ *
+ * `customElements.define` throws on a repeated name, and a module that registers on
+ * import gets evaluated more than once more often than people expect: two bundles on
+ * a page, a dev server round trip, a test file importing the module twice. The throw
+ * is a `NotSupportedError` that surfaces far from its cause.
+ *
+ * Registration is also the one part of this package that cannot run on a server. The
+ * guard is `isServer()` from @fluixi/dom rather than a `typeof window` test, because
+ * that flag is a realm singleton the server renderer sets. Four copies of a local
+ * `isServer` was the alpha.83 SSR bug, and this package does not add a fifth.
+ */
+import { isServer } from '@fluixi/dom';
+/** Names this module has defined, so a second call is a no-op rather than a throw. */
+const defined = new Map();
+function registry() {
+    return typeof customElements === 'undefined' ? null : customElements;
+}
+/**
+ * Register a constructor under a name, at most once.
+ *
+ * Returns the constructor actually registered, which is the previously registered one
+ * when the name is already taken. That matters for a standalone bundle: two copies of
+ * the same component on a page should agree on which class the tag upgrades to, and
+ * the first to load wins.
+ */
+export function defineCustomElement(name, constructor, options = {}) {
+    // A server render in a browser-like realm (a jsdom test) must not define for real. On Node
+    // the stand-in registry takes it, so the server renderer can find the element by its tag.
+    if (isServer() && typeof HTMLElement !== 'undefined')
+        return constructor;
+    const registered = defined.get(name);
+    if (registered)
+        return registered;
+    const ce = registry();
+    // No registry means a non-browser realm that is not the server renderer either,
+    // such as a worker. Nothing to register into, and nothing to warn about.
+    if (!ce)
+        return constructor;
+    const existing = ce.get(name);
+    if (existing) {
+        // Another bundle got here first. Remember it so this module stops asking.
+        defined.set(name, existing);
+        return existing;
+    }
+    ce.define(name, constructor, options.extends ? { extends: options.extends } : undefined);
+    defined.set(name, constructor);
+    return constructor;
+}
+/** Whether a name has been claimed, by this module or anyone else. */
+export function isDefined(name) {
+    return defined.has(name) || registry()?.get(name) !== undefined;
+}
+/**
+ * Register only once the tag is actually in the document.
+ *
+ * A component that costs something to load should not cost it on a page that never
+ * uses the tag. The observer disconnects after the first match, so the scan is paid
+ * for once.
+ */
+export function defineWhenUsed(name, load, options = {}) {
+    if (isServer() || typeof document === 'undefined')
+        return;
+    let started = false;
+    const start = async () => {
+        if (started)
+            return;
+        started = true;
+        defineCustomElement(name, await load(), options);
+    };
+    if (document.querySelector(name)) {
+        void start();
+        return;
+    }
+    if (typeof MutationObserver === 'undefined') {
+        void start();
+        return;
+    }
+    const observer = new MutationObserver(() => {
+        if (!document.querySelector(name))
+            return;
+        observer.disconnect();
+        void start();
+    });
+    observer.observe(document.documentElement, { childList: true, subtree: true });
+}
+/** Test seam: forget what this module has registered. The registry itself is permanent. */
+export function resetRegistryTracking() {
+    defined.clear();
+}

package/dist/registry.mjs

@@ -0,0 +1,56 @@
+// src/registry.ts
+import { isServer } from "@fluixi/dom";
+var defined = /* @__PURE__ */ new Map();
+function registry() {
+  return typeof customElements === "undefined" ? null : customElements;
+}
+function defineCustomElement(name, constructor, options = {}) {
+  if (isServer() && typeof HTMLElement !== "undefined") return constructor;
+  const registered = defined.get(name);
+  if (registered) return registered;
+  const ce = registry();
+  if (!ce) return constructor;
+  const existing = ce.get(name);
+  if (existing) {
+    defined.set(name, existing);
+    return existing;
+  }
+  ce.define(name, constructor, options.extends ? { extends: options.extends } : void 0);
+  defined.set(name, constructor);
+  return constructor;
+}
+function isDefined(name) {
+  return defined.has(name) || registry()?.get(name) !== void 0;
+}
+function defineWhenUsed(name, load, options = {}) {
+  if (isServer() || typeof document === "undefined") return;
+  let started = false;
+  const start = async () => {
+    if (started) return;
+    started = true;
+    defineCustomElement(name, await load(), options);
+  };
+  if (document.querySelector(name)) {
+    void start();
+    return;
+  }
+  if (typeof MutationObserver === "undefined") {
+    void start();
+    return;
+  }
+  const observer = new MutationObserver(() => {
+    if (!document.querySelector(name)) return;
+    observer.disconnect();
+    void start();
+  });
+  observer.observe(document.documentElement, { childList: true, subtree: true });
+}
+function resetRegistryTracking() {
+  defined.clear();
+}
+export {
+  defineCustomElement,
+  defineWhenUsed,
+  isDefined,
+  resetRegistryTracking
+};