@lushly-dev/fast-element 3.0.1-preview.0 → 3.0.1-preview.2

package/dist/esm/components/element-hydration.js

@@ -0,0 +1,2 @@
+export { ElementController } from "./element-controller.js";
+export * from "./hydration.js";

package/dist/esm/components/enable-hydration.js

@@ -0,0 +1,123 @@
+import { installHydrationDiagnostic } from "../hydration/diagnostics.js";
+import { ensureHydrationRuntime } from "../hydration/runtime.js";
+import { SourceLifetime } from "../observation/observable.js";
+import { ElementController } from "./element-controller.js";
+import { isHydratable } from "./hydration.js";
+import { HydrationTracker, } from "./hydration-tracker.js";
+export { StopHydration } from "./hydration-tracker.js";
+/**
+ * No-op handler used during prerendered bind to discard the
+ * upgrade-time burst of attributeChangedCallbacks.
+ */
+function noopAttributeHandler() { }
+let tracker = null;
+let hookInstalled = false;
+/**
+ * Enables hydration support for prerendered FAST elements.
+ *
+ * @remarks
+ * Call this before any FAST elements connect to the DOM. Hydration
+ * logic is not active unless this function is called, keeping
+ * `FASTElement` lightweight for client-side-only applications.
+ *
+ * Safe to call multiple times — the hydration hook is installed once
+ * and subsequent calls merge their options into the shared tracker.
+ * By default, the hook stops hydrating new prerendered elements after
+ * the initial hydration batch completes. Await the returned controller's
+ * `whenHydrated()` promise to run code after the active hydration batch
+ * completes.
+ *
+ * Set `stopHydration` to `StopHydration.never` for streaming scenarios
+ * that append hydratable Declarative Shadow DOM after the initial batch.
+ * In this mode, `whenHydrated` intentionally remains pending because
+ * hydration never reaches a global completion point.
+ *
+ * Pass `debugger: hydrationDebugger()` to swap the default minimal
+ * hydration mismatch error message for a rich "Expected / Received"
+ * report including the SSR HTML snippet and structured
+ * `expected`/`received` fields on `HydrationBindingError` /
+ * `HydrationTargetElementError`. The debugger module is tree-shaken
+ * out of production hydration bundles unless explicitly imported.
+ *
+ * @example
+ * ```ts
+ * import { enableHydration } from "@lushly-dev/fast-element/hydration.js";
+ *
+ * const hydration = enableHydration();
+ *
+ * await hydration.whenHydrated();
+ * console.log("hydration complete");
+ * ```
+ *
+ * @example Streaming Declarative Shadow DOM
+ * ```ts
+ * import { enableHydration, StopHydration } from "@lushly-dev/fast-element/hydration.js";
+ *
+ * enableHydration({
+ *     stopHydration: StopHydration.never,
+ * });
+ * ```
+ *
+ * @example Rich hydration mismatch diagnostics
+ * ```ts
+ * import { enableHydration, hydrationDebugger } from "@lushly-dev/fast-element/hydration.js";
+ *
+ * enableHydration({ debugger: hydrationDebugger() });
+ * ```
+ *
+ * @param options - Optional hydration behavior.
+ * @public
+ */
+export function enableHydration(options) {
+    ensureHydrationRuntime();
+    if (options === null || options === void 0 ? void 0 : options.debugger) {
+        installHydrationDiagnostic(options.debugger.diagnostic);
+    }
+    if (!hookInstalled) {
+        tracker = new HydrationTracker(options !== null && options !== void 0 ? options : {});
+        hookInstalled = true;
+        const activeTracker = tracker;
+        ElementController.installHydrationHook((controller, template, element, host) => {
+            if (!activeTracker.shouldHydrate || !isHydratable(template)) {
+                return false;
+            }
+            activeTracker.add(element);
+            try {
+                const firstChild = host.firstChild;
+                const lastChild = host.lastChild;
+                const view = template.hydrate(firstChild, lastChild, element);
+                controller.view = view;
+                const realHandler = controller.onAttributeChangedCallback;
+                controller.onAttributeChangedCallback = noopAttributeHandler;
+                try {
+                    view._skipAttrUpdates = true;
+                    view.isPrerendered = Promise.resolve(true);
+                    view.isHydrated = Promise.resolve(true);
+                    view.bind(controller.source);
+                    view._skipAttrUpdates = false;
+                }
+                finally {
+                    controller.onAttributeChangedCallback = realHandler;
+                }
+                view.sourceLifetime =
+                    SourceLifetime.coupled;
+                controller.hasExistingShadowRoot = false;
+            }
+            finally {
+                activeTracker.remove(element);
+            }
+            return true;
+        });
+    }
+    else if (options && tracker) {
+        // Merge options into existing tracker for subsequent calls
+        tracker.mergeOptions(options);
+    }
+    return tracker;
+}
+/**
+ * The attribute used to defer hydration of an element.
+ * Retained for intersection observer viewport hydration rendering.
+ * @beta
+ */
+export const deferHydrationAttribute = "defer-hydration";

package/dist/esm/components/fast-definitions.js

@@ -0,0 +1,294 @@
+import { isFunction, isString } from "../interfaces.js";
+import { Observable } from "../observation/observable.js";
+import { ElementStyles } from "../styles/element-styles.js";
+import { AttributeDefinition } from "./attributes.js";
+import { fastElementRegistry } from "./fast-element-registry.js";
+const defaultShadowOptions = { mode: "open" };
+const defaultElementOptions = {};
+const fastElementBaseTypes = new Set();
+function normalizeShadowOptions(options) {
+    if (options === null) {
+        return void 0;
+    }
+    const normalized = Object.assign(Object.assign({}, defaultShadowOptions), options);
+    if (normalized.customElementRegistry === void 0 && normalized.registry !== void 0) {
+        normalized.customElementRegistry = normalized.registry;
+    }
+    if (normalized.registry === void 0 && normalized.customElementRegistry !== void 0) {
+        normalized.registry = normalized.customElementRegistry;
+    }
+    return normalized;
+}
+const templateResolvers = new WeakMap();
+const pendingTemplateResolutions = new WeakMap();
+const templateResolutionErrors = new WeakMap();
+const extensionRegistries = new WeakMap();
+const registeredExtensions = new Set();
+const lateAttributeLookups = new WeakMap();
+function isFASTElementTemplateResolver(value) {
+    return isFunction(value);
+}
+function isPromiseLike(value) {
+    return typeof (value === null || value === void 0 ? void 0 : value.then) === "function";
+}
+function finalizeResolvedTemplate(definition, template) {
+    pendingTemplateResolutions.delete(definition);
+    if (definition.template === void 0 && template !== void 0) {
+        definition.template = template;
+    }
+    if (definition.template !== void 0) {
+        templateResolutionErrors.delete(definition);
+        templateResolvers.delete(definition);
+        return definition.template;
+    }
+    return void 0;
+}
+/**
+ * Applies extension callbacks to a FAST element definition.
+ * @internal
+ */
+export function applyFASTElementExtensions(definition, registry = definition.registry, extensions) {
+    if (registeredExtensions.size === 0 && !(extensions === null || extensions === void 0 ? void 0 : extensions.length)) {
+        return;
+    }
+    const typedDefinition = definition;
+    let registries = extensionRegistries.get(typedDefinition);
+    if (registries === null || registries === void 0 ? void 0 : registries.has(registry)) {
+        return;
+    }
+    if (registries === void 0) {
+        registries = new WeakSet();
+        extensionRegistries.set(typedDefinition, registries);
+    }
+    registries.add(registry);
+    for (const extension of registeredExtensions) {
+        extension(definition, registry);
+    }
+    for (const extension of extensions !== null && extensions !== void 0 ? extensions : []) {
+        if (!registeredExtensions.has(extension)) {
+            extension(definition, registry);
+        }
+    }
+}
+/**
+ * Registers an extension that applies to every subsequently defined FAST element.
+ * @param extension - The extension to register.
+ * @returns A callback that removes the extension registration.
+ * @internal
+ */
+export function registerFASTElementExtension(extension) {
+    registeredExtensions.add(extension);
+    return () => {
+        registeredExtensions.delete(extension);
+    };
+}
+/**
+ * Tracks attribute definitions that were added after the element was already
+ * registered with the platform and therefore are not covered by the browser's
+ * static observedAttributes snapshot.
+ * @internal
+ */
+export function trackLateAttributeDefinition(definition, attribute) {
+    const typedDefinition = definition;
+    let lateAttributeLookup = lateAttributeLookups.get(typedDefinition);
+    if (lateAttributeLookup === void 0) {
+        const lookup = Object.create(null);
+        lateAttributeLookups.set(typedDefinition, lookup);
+        lateAttributeLookup = lookup;
+    }
+    lateAttributeLookup[attribute.attribute] = attribute;
+}
+/**
+ * Gets the attribute definitions that were added after platform registration.
+ * @internal
+ */
+export function getLateAttributeLookup(definition) {
+    var _a;
+    return ((_a = lateAttributeLookups.get(definition)) !== null && _a !== void 0 ? _a : null);
+}
+/**
+ * Resolves the concrete template for a FAST element definition when the
+ * definition was composed with a template resolver.
+ * @internal
+ */
+export function resolveFASTElementTemplate(definition) {
+    if (definition.template !== void 0) {
+        templateResolutionErrors.delete(definition);
+        return definition.template;
+    }
+    const pendingResolution = pendingTemplateResolutions.get(definition);
+    if (pendingResolution) {
+        return pendingResolution;
+    }
+    const templateResolver = templateResolvers.get(definition);
+    if (!templateResolver) {
+        return void 0;
+    }
+    templateResolutionErrors.delete(definition);
+    let template;
+    try {
+        template = templateResolver(definition);
+    }
+    catch (error) {
+        templateResolutionErrors.set(definition, error);
+        throw error;
+    }
+    if (isPromiseLike(template)) {
+        const resolution = Promise.resolve(template)
+            .then(resolvedTemplate => finalizeResolvedTemplate(definition, resolvedTemplate))
+            .catch(error => {
+            pendingTemplateResolutions.delete(definition);
+            templateResolutionErrors.set(definition, error);
+            throw error;
+        });
+        pendingTemplateResolutions.set(definition, resolution);
+        return resolution;
+    }
+    return finalizeResolvedTemplate(definition, template);
+}
+/**
+ * Indicates whether a definition still has a pending template resolver.
+ * @internal
+ */
+export function hasFASTElementTemplateResolver(definition) {
+    return templateResolvers.has(definition);
+}
+/**
+ * Gets any pending template resolution error for a FAST element definition.
+ * @internal
+ */
+export function getFASTElementTemplateError(definition) {
+    return templateResolutionErrors.get(definition);
+}
+/**
+ * Sets or clears the template resolution error for a FAST element definition.
+ * @internal
+ */
+export function setFASTElementTemplateError(definition, error) {
+    const typedDefinition = definition;
+    if (error === void 0) {
+        templateResolutionErrors.delete(typedDefinition);
+        return;
+    }
+    templateResolutionErrors.set(typedDefinition, error);
+}
+/**
+ * Defines metadata for a FASTElement.
+ * @public
+ */
+export class FASTElementDefinition {
+    /**
+     * Indicates if this element has been defined in at least one registry.
+     */
+    get isDefined() {
+        return this.platformDefined;
+    }
+    constructor(type, nameOrConfig = type
+        .definition) {
+        var _a;
+        this.platformDefined = false;
+        if (isString(nameOrConfig)) {
+            nameOrConfig = { name: nameOrConfig };
+        }
+        this.type = type;
+        this.name = nameOrConfig.name;
+        this.registry = (_a = nameOrConfig.registry) !== null && _a !== void 0 ? _a : customElements;
+        if (isFASTElementTemplateResolver(nameOrConfig.template)) {
+            templateResolvers.set(this, nameOrConfig.template);
+        }
+        else {
+            this.template = nameOrConfig.template;
+        }
+        const proto = type.prototype;
+        const attributes = AttributeDefinition.collect(type, nameOrConfig.attributes);
+        const observedAttributes = new Array(attributes.length);
+        const propertyLookup = {};
+        const attributeLookup = {};
+        for (let i = 0, ii = attributes.length; i < ii; ++i) {
+            const current = attributes[i];
+            observedAttributes[i] = current.attribute;
+            propertyLookup[current.name] = current;
+            attributeLookup[current.attribute] = current;
+            Observable.defineProperty(proto, current);
+        }
+        Reflect.defineProperty(type, "observedAttributes", {
+            value: observedAttributes,
+            enumerable: true,
+        });
+        this.attributes = attributes;
+        this.propertyLookup = propertyLookup;
+        this.attributeLookup = attributeLookup;
+        this.shadowOptions = normalizeShadowOptions(nameOrConfig.shadowOptions);
+        this.elementOptions =
+            nameOrConfig.elementOptions === void 0
+                ? defaultElementOptions
+                : Object.assign(Object.assign({}, defaultElementOptions), nameOrConfig.elementOptions);
+        this.styles = ElementStyles.normalize(nameOrConfig.styles);
+        this.schema = nameOrConfig.schema;
+        fastElementRegistry.register(this);
+    }
+    /**
+     * Defines a custom element based on this definition.
+     * @param registry - The element registry to define the element in.
+     * @param extensions - An optional array of extension callbacks to invoke
+     * with this definition before platform registration.
+     * @remarks
+     * This operation is idempotent per registry.
+     */
+    define(registry = this.registry, extensions) {
+        const type = this.type;
+        if (!registry.get(this.name)) {
+            applyFASTElementExtensions(this, registry, extensions);
+            if (this.template === void 0 && templateResolvers.has(this)) {
+                void Promise.resolve()
+                    .then(() => resolveFASTElementTemplate(this))
+                    .then(template => {
+                    if (template !== void 0 && !registry.get(this.name)) {
+                        this.platformDefined = true;
+                        registry.define(this.name, type, this.elementOptions);
+                    }
+                })
+                    .catch(error => {
+                    setFASTElementTemplateError(this, error);
+                    Observable.notify(this, "template");
+                });
+                return this;
+            }
+            this.platformDefined = true;
+            registry.define(this.name, type, this.elementOptions);
+        }
+        return this;
+    }
+    /**
+     * Creates an instance of FASTElementDefinition.
+     * @param type - The type this definition is being created for.
+     * @param nameOrDef - The name of the element to define or a config object
+     * that describes the element to define.
+     */
+    static compose(type, nameOrDef) {
+        const definition = fastElementBaseTypes.has(type) || fastElementRegistry.getByType(type)
+            ? new FASTElementDefinition(class extends type {
+            }, nameOrDef)
+            : new FASTElementDefinition(type, nameOrDef);
+        return Promise.resolve(definition);
+    }
+    /**
+     * Registers a FASTElement base type.
+     * @param type - The type to register as a base type.
+     * @internal
+     */
+    static registerBaseType(type) {
+        fastElementBaseTypes.add(type);
+    }
+}
+/**
+ * Gets the element definition associated with the specified type.
+ * @param type - The custom element type to retrieve the definition for.
+ */
+FASTElementDefinition.getByType = fastElementRegistry.getByType;
+/**
+ * Gets the element definition associated with the instance.
+ * @param instance - The custom element instance to retrieve the definition for.
+ */
+FASTElementDefinition.getForInstance = fastElementRegistry.getForInstance;
+Observable.defineProperty(FASTElementDefinition.prototype, "template");

package/dist/esm/components/fast-element-registry.js

@@ -0,0 +1,67 @@
+import { Observable } from "../observation/observable.js";
+import { createTypeRegistry } from "../platform.js";
+const globalRegisteredTypes = {};
+const registeredTypesByRegistry = new WeakMap();
+const typeRegistry = createTypeRegistry();
+/**
+ * The FAST custom element registry.
+ * @remarks
+ * This registry stores FAST element definitions by constructor so consumers can
+ * look up the `FASTElementDefinition` associated with an element type, instance,
+ * or registered tag name.
+ * @public
+ */
+export const fastElementRegistry = Object.freeze({
+    register(definition) {
+        if (!typeRegistry.register(definition)) {
+            return false;
+        }
+        const registeredTypes = getRegisteredTypes(definition.registry);
+        if (!Object.prototype.hasOwnProperty.call(registeredTypes, definition.name)) {
+            Observable.defineProperty(registeredTypes, definition.name);
+        }
+        registeredTypes[definition.name] = definition.type;
+        return true;
+    },
+    getByType: typeRegistry.getByType,
+    getForInstance: typeRegistry.getForInstance,
+    whenRegistered,
+});
+function getRegisteredTypes(registry = customElements) {
+    if (registry === customElements) {
+        return globalRegisteredTypes;
+    }
+    let registeredTypes = registeredTypesByRegistry.get(registry);
+    if (!registeredTypes) {
+        registeredTypes = {};
+        registeredTypesByRegistry.set(registry, registeredTypes);
+    }
+    return registeredTypes;
+}
+function getDefinitionForType(type) {
+    return type === void 0 ? void 0 : fastElementRegistry.getByType(type);
+}
+function whenRegistered(name, registry = customElements) {
+    const registeredTypes = getRegisteredTypes(registry);
+    if (!Object.prototype.hasOwnProperty.call(registeredTypes, name)) {
+        Observable.defineProperty(registeredTypes, name);
+    }
+    const definition = getDefinitionForType(registeredTypes[name]);
+    if (definition !== void 0) {
+        return Promise.resolve(definition);
+    }
+    return new Promise(resolve => {
+        const notifier = Observable.getNotifier(registeredTypes);
+        const subscriber = {
+            handleChange: () => {
+                const definition = getDefinitionForType(registeredTypes[name]);
+                if (definition === void 0) {
+                    return;
+                }
+                notifier.unsubscribe(subscriber, name);
+                resolve(definition);
+            },
+        };
+        notifier.subscribe(subscriber, name);
+    });
+}

package/dist/esm/components/fast-element.js

@@ -0,0 +1,82 @@
+import { isFunction } from "../interfaces.js";
+import { ElementController } from "./element-controller.js";
+import { applyFASTElementExtensions, FASTElementDefinition, resolveFASTElementTemplate, } from "./fast-definitions.js";
+/* eslint-disable-next-line @typescript-eslint/explicit-function-return-type */
+function createFASTElement(BaseType) {
+    const type = class extends BaseType {
+        constructor() {
+            /* eslint-disable-next-line */
+            super();
+            ElementController.forCustomElement(this);
+        }
+        $emit(type, detail, options) {
+            return this.$fastController.emit(type, detail, options);
+        }
+        connectedCallback() {
+            this.$fastController.connect();
+        }
+        disconnectedCallback() {
+            this.$fastController.disconnect();
+        }
+        attributeChangedCallback(name, oldValue, newValue) {
+            this.$fastController.onAttributeChangedCallback(name, oldValue, newValue);
+        }
+    };
+    FASTElementDefinition.registerBaseType(type);
+    return type;
+}
+function isPromiseLike(value) {
+    return typeof (value === null || value === void 0 ? void 0 : value.then) === "function";
+}
+function define(type, nameOrDef, extensions) {
+    if (Array.isArray(nameOrDef)) {
+        extensions = nameOrDef;
+        nameOrDef = undefined;
+    }
+    const composePromise = isFunction(type)
+        ? FASTElementDefinition.compose(type, nameOrDef)
+        : FASTElementDefinition.compose(this, type);
+    return composePromise.then(def => {
+        applyFASTElementExtensions(def, def.registry, extensions);
+        const template = resolveFASTElementTemplate(def);
+        if (isPromiseLike(template)) {
+            return template.then(() => def.define().type);
+        }
+        return def.define().type;
+    });
+}
+function from(BaseType) {
+    return createFASTElement(BaseType);
+}
+/**
+ * A minimal base class for FASTElements that also provides
+ * static helpers for working with FASTElements.
+ * @public
+ */
+export const FASTElement = Object.assign(createFASTElement(HTMLElement), {
+    /**
+     * Creates a new FASTElement base class inherited from the
+     * provided base type.
+     * @param BaseType - The base element type to inherit from.
+     */
+    from,
+    /**
+     * Defines a platform custom element based on the provided type and definition.
+     * @param type - The custom element type to define.
+     * @param nameOrDef - The name of the element to define or a definition object
+     * that describes the element to define.
+     */
+    define,
+});
+/**
+ * Decorator: Defines a platform custom element based on `FASTElement`.
+ * @param nameOrDef - The name of the element to define or a definition object
+ * that describes the element to define.
+ * @public
+ */
+export function customElement(nameOrDef) {
+    /* eslint-disable-next-line @typescript-eslint/explicit-function-return-type */
+    return function (type) {
+        define(type, nameOrDef);
+    };
+}