@microsoft/fast-element 2.10.4 → 3.0.0-rc.2

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

@@ -0,0 +1,124 @@
+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 global `hydrationComplete` callback. Set
+ * `stopHydration` to `StopHydration.never` for streaming scenarios
+ * that append hydratable Declarative Shadow DOM after the initial batch.
+ *
+ * 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, StopHydration } from "@microsoft/fast-element/hydration.js";
+ *
+ * enableHydration({
+ *     stopHydration: StopHydration.never,
+ *     hydrationComplete() {
+ *         console.log("hydration complete");
+ *     },
+ * });
+ * ```
+ *
+ * @example Rich hydration mismatch diagnostics
+ * ```ts
+ * import { enableHydration, hydrationDebugger } from "@microsoft/fast-element/hydration.js";
+ *
+ * enableHydration({ debugger: hydrationDebugger() });
+ * ```
+ *
+ * @param options - Optional global hydration callbacks and 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) => {
+            var _a, _b;
+            if (!activeTracker.shouldHydrate || !isHydratable(template)) {
+                return false;
+            }
+            const callbacks = controller.definition.lifecycleCallbacks;
+            activeTracker.add(element);
+            try {
+                try {
+                    (_a = callbacks === null || callbacks === void 0 ? void 0 : callbacks.elementWillHydrate) === null || _a === void 0 ? void 0 : _a.call(callbacks, element);
+                }
+                catch (_c) {
+                    // A lifecycle callback must never prevent hydration.
+                }
+                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;
+                try {
+                    (_b = callbacks === null || callbacks === void 0 ? void 0 : callbacks.elementDidHydrate) === null || _b === void 0 ? void 0 : _b.call(callbacks, element);
+                }
+                catch (_d) {
+                    // A lifecycle callback must never prevent post-hydration work.
+                }
+            }
+            finally {
+                activeTracker.remove(element);
+            }
+            return true;
+        });
+    }
+    else if (options && tracker) {
+        // Merge options into existing tracker for subsequent calls
+        tracker.mergeOptions(options);
+    }
+}
+/**
+ * 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

@@ -7,27 +7,171 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-var _a;
-import { isString, KernelServiceId } from "../interfaces.js";
+import { isFunction, isString } from "../interfaces.js";
 import { Observable } from "../observation/observable.js";
-import { createTypeRegistry, FAST } from "../platform.js";
+import { createTypeRegistry, } from "../platform.js";
 import { ElementStyles } from "../styles/element-styles.js";
-import { AttributeConfiguration, AttributeDefinition } from "./attributes.js";
+import { AttributeDefinition } from "./attributes.js";
 const defaultShadowOptions = { mode: "open" };
 const defaultElementOptions = {};
 const fastElementBaseTypes = new Set();
 /**
- * The FAST custom element registry
+ * 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 or instance.
+ * @public
+ */
+export const fastElementRegistry = createTypeRegistry();
+const templateResolvers = new WeakMap();
+const pendingTemplateResolutions = new WeakMap();
+const templateResolutionErrors = new WeakMap();
+const registeredTypesByRegistry = new WeakMap();
+const extensionRegistries = new WeakMap();
+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 getRegisteredTypes(registry = customElements) {
+    if (registry === customElements) {
+        return FASTElementDefinition.isRegistered;
+    }
+    let registeredTypes = registeredTypesByRegistry.get(registry);
+    if (!registeredTypes) {
+        registeredTypes = {};
+        registeredTypesByRegistry.set(registry, registeredTypes);
+    }
+    return registeredTypes;
+}
+function finalizeResolvedTemplate(definition, template) {
+    var _a, _b;
+    pendingTemplateResolutions.delete(definition);
+    if (definition.template === void 0 && template !== void 0) {
+        definition.template = template;
+        (_b = (_a = definition.lifecycleCallbacks) === null || _a === void 0 ? void 0 : _a.templateDidUpdate) === null || _b === void 0 ? void 0 : _b.call(_a, definition.name);
+    }
+    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 (!(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 extensions) {
+        extension(definition);
+    }
+}
+/**
+ * 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 const fastElementRegistry = FAST.getById(KernelServiceId.elementRegistry, () => createTypeRegistry());
+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;
+}
 /**
- * Values for the `templateOptions` property.
- * @alpha
+ * Gets the attribute definitions that were added after platform registration.
+ * @internal
  */
-export const TemplateOptions = {
-    deferAndHydrate: "defer-and-hydrate",
-};
+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
@@ -39,17 +183,22 @@ export class FASTElementDefinition {
     get isDefined() {
         return this.platformDefined;
     }
-    constructor(type, nameOrConfig = type.definition) {
-        var _b;
+    constructor(type, nameOrConfig = type
+        .definition) {
+        var _a;
         this.platformDefined = false;
         if (isString(nameOrConfig)) {
             nameOrConfig = { name: nameOrConfig };
         }
         this.type = type;
         this.name = nameOrConfig.name;
-        this.template = nameOrConfig.template;
-        this.templateOptions = nameOrConfig.templateOptions;
-        this.registry = (_b = nameOrConfig.registry) !== null && _b !== void 0 ? _b : customElements;
+        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);
@@ -80,23 +229,47 @@ export class FASTElementDefinition {
                 ? defaultElementOptions
                 : Object.assign(Object.assign({}, defaultElementOptions), nameOrConfig.elementOptions);
         this.styles = ElementStyles.normalize(nameOrConfig.styles);
+        this.schema = nameOrConfig.schema;
         fastElementRegistry.register(this);
-        Observable.defineProperty(_a.isRegistered, this.name);
-        _a.isRegistered[this.name] = this.type;
+        const registeredTypes = getRegisteredTypes(this.registry);
+        if (!Object.prototype.hasOwnProperty.call(registeredTypes, this.name)) {
+            Observable.defineProperty(registeredTypes, this.name);
+        }
+        registeredTypes[this.name] = this.type;
     }
     /**
      * 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) {
-        var _b, _c;
+    define(registry = this.registry, extensions) {
+        var _a, _b;
         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 => {
+                    var _a, _b;
+                    if (template !== void 0 && !registry.get(this.name)) {
+                        this.platformDefined = true;
+                        registry.define(this.name, type, this.elementOptions);
+                        (_b = (_a = this.lifecycleCallbacks) === null || _a === void 0 ? void 0 : _a.elementDidDefine) === null || _b === void 0 ? void 0 : _b.call(_a, this.name);
+                    }
+                })
+                    .catch(error => {
+                    setFASTElementTemplateError(this, error);
+                    Observable.notify(this, "template");
+                });
+                return this;
+            }
             this.platformDefined = true;
             registry.define(this.name, type, this.elementOptions);
-            (_c = (_b = this.lifecycleCallbacks) === null || _b === void 0 ? void 0 : _b.elementDidDefine) === null || _c === void 0 ? void 0 : _c.call(_b, this.name);
+            (_b = (_a = this.lifecycleCallbacks) === null || _a === void 0 ? void 0 : _a.elementDidDefine) === null || _b === void 0 ? void 0 : _b.call(_a, this.name);
         }
         return this;
     }
@@ -107,11 +280,11 @@ export class FASTElementDefinition {
      * that describes the element to define.
      */
     static compose(type, nameOrDef) {
-        if (fastElementBaseTypes.has(type) || fastElementRegistry.getByType(type)) {
-            return new _a(class extends type {
-            }, nameOrDef);
-        }
-        return new _a(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.
@@ -121,33 +294,7 @@ export class FASTElementDefinition {
     static registerBaseType(type) {
         fastElementBaseTypes.add(type);
     }
-    /**
-     * Creates an instance of FASTElementDefinition asynchronously. This option assumes
-     * that a template and shadowOptions will be provided and completes when those requirements
-     * are met.
-     * @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.
-     * @alpha
-     */
-    static composeAsync(type, nameOrDef) {
-        return new Promise(resolve => {
-            if (fastElementBaseTypes.has(type) || fastElementRegistry.getByType(type)) {
-                resolve(new _a(class extends type {
-                }, nameOrDef));
-            }
-            const definition = new _a(type, nameOrDef);
-            Observable.getNotifier(definition).subscribe({
-                handleChange: () => {
-                    var _b, _c;
-                    (_c = (_b = definition.lifecycleCallbacks) === null || _b === void 0 ? void 0 : _b.templateDidUpdate) === null || _c === void 0 ? void 0 : _c.call(_b, definition.name);
-                    resolve(definition);
-                },
-            }, "template");
-        });
-    }
 }
-_a = FASTElementDefinition;
 /**
  * The definition has been registered to the FAST element registry.
  */
@@ -167,12 +314,28 @@ FASTElementDefinition.getForInstance = fastElementRegistry.getForInstance;
  * @param name - The name of the defined custom element.
  * @alpha
  */
-FASTElementDefinition.registerAsync = (name) => __awaiter(void 0, void 0, void 0, function* () {
+FASTElementDefinition.register = (name_1, ...args_1) => __awaiter(void 0, [name_1, ...args_1], void 0, function* (name, registry = customElements) {
+    const registeredTypes = getRegisteredTypes(registry);
+    if (!Object.prototype.hasOwnProperty.call(registeredTypes, name)) {
+        Observable.defineProperty(registeredTypes, name);
+    }
     return new Promise(resolve => {
-        if (_a.isRegistered[name]) {
-            resolve(_a.isRegistered[name]);
+        if (registeredTypes[name]) {
+            resolve(registeredTypes[name]);
+            return;
         }
-        Observable.getNotifier(_a.isRegistered).subscribe({ handleChange: () => resolve(_a.isRegistered[name]) }, name);
+        const notifier = Observable.getNotifier(registeredTypes);
+        const subscriber = {
+            handleChange: () => {
+                const value = registeredTypes[name];
+                if (!value) {
+                    return;
+                }
+                notifier.unsubscribe(subscriber, name);
+                resolve(value);
+            },
+        };
+        notifier.subscribe(subscriber, name);
     });
 });
 Observable.defineProperty(FASTElementDefinition.prototype, "template");

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

@@ -1,6 +1,6 @@
 import { isFunction } from "../interfaces.js";
 import { ElementController } from "./element-controller.js";
-import { FASTElementDefinition, } from "./fast-definitions.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 {
@@ -31,29 +31,25 @@ function compose(type, nameOrDef) {
     }
     return FASTElementDefinition.compose(this, type);
 }
-function defineAsync(type, nameOrDef) {
-    if (isFunction(type)) {
-        return new Promise(resolve => {
-            FASTElementDefinition.composeAsync(type, nameOrDef).then(value => {
-                resolve(value);
-            });
-        }).then(value => {
-            return value.define().type;
-        });
-    }
-    return new Promise(resolve => {
-        FASTElementDefinition.composeAsync(this, type).then(value => {
-            resolve(value);
-        });
-    }).then(value => {
-        return value.define().type;
-    });
+function isPromiseLike(value) {
+    return typeof (value === null || value === void 0 ? void 0 : value.then) === "function";
 }
-function define(type, nameOrDef) {
-    if (isFunction(type)) {
-        return FASTElementDefinition.compose(type, nameOrDef).define().type;
+function define(type, nameOrDef, extensions) {
+    if (Array.isArray(nameOrDef)) {
+        extensions = nameOrDef;
+        nameOrDef = undefined;
     }
-    return FASTElementDefinition.compose(this, type).define().type;
+    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);
@@ -82,11 +78,6 @@ export const FASTElement = Object.assign(createFASTElement(HTMLElement), {
      * @public
      */
     compose,
-    /**
-     * Defines metadata for a FASTElement which can be used after it has been resolved to define the element.
-     * @alpha
-     */
-    defineAsync,
 });
 /**
  * Decorator: Defines a platform custom element based on `FASTElement`.

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

@@ -0,0 +1,122 @@
+/**
+ * Describes when FAST should stop hydrating newly connected prerendered elements.
+ * @public
+ */
+export const StopHydration = Object.freeze({
+    /**
+     * Stop hydrating new prerendered elements after the active hydration batch completes.
+     */
+    hydrationComplete: "hydration-complete",
+    /**
+     * Keep the hydration hook active for later prerendered elements.
+     */
+    never: "never",
+});
+/**
+ * Tracks prerendered elements through the hydration lifecycle and
+ * fires global callbacks at start and completion. Per-element callbacks
+ * (`elementWillHydrate`, `elementDidHydrate`) are handled through
+ * definition-level `TemplateLifecycleCallbacks`.
+ *
+ * @public
+ */
+export class HydrationTracker {
+    constructor(options) {
+        var _a;
+        this.elements = new Set();
+        this.started = false;
+        this.completed = false;
+        this.checkTimer = null;
+        this.callbacks = options;
+        this.stopHydration = (_a = options.stopHydration) !== null && _a !== void 0 ? _a : StopHydration.hydrationComplete;
+    }
+    /**
+     * Indicates whether the hydration hook should attempt to hydrate
+     * prerendered elements.
+     */
+    get shouldHydrate() {
+        return !this.completed || this.stopHydration === StopHydration.never;
+    }
+    /**
+     * Registers an element as pending hydration.
+     * Fires `hydrationStarted` on the first call.
+     */
+    add(element) {
+        var _a, _b;
+        this.completed = false;
+        if (!this.started) {
+            this.started = true;
+            try {
+                (_b = (_a = this.callbacks).hydrationStarted) === null || _b === void 0 ? void 0 : _b.call(_a);
+            }
+            catch (_c) {
+                // A lifecycle callback must never prevent hydration.
+            }
+        }
+        this.elements.add(element);
+    }
+    /**
+     * Removes an element from the pending set and schedules
+     * a debounced completion check.
+     */
+    remove(element) {
+        this.elements.delete(element);
+        // Debounce: reset on every removal so we wait until no
+        // new elements arrive before declaring complete.
+        if (this.checkTimer !== null) {
+            clearTimeout(this.checkTimer);
+        }
+        if (this.elements.size === 0) {
+            this.checkTimer = setTimeout(() => {
+                var _a, _b;
+                this.checkTimer = null;
+                if (this.elements.size === 0) {
+                    try {
+                        (_b = (_a = this.callbacks).hydrationComplete) === null || _b === void 0 ? void 0 : _b.call(_a);
+                    }
+                    catch (_c) {
+                        // A lifecycle callback must never prevent post-hydration cleanup.
+                    }
+                    finally {
+                        this.started = false;
+                        this.completed = true;
+                    }
+                }
+            }, 0);
+        }
+    }
+    /**
+     * Merges additional options into the tracker, chaining
+     * callbacks so both the original and new callbacks fire.
+     */
+    mergeOptions(incoming) {
+        const prev = this.callbacks;
+        this.callbacks = {
+            hydrationStarted: chainCallback(prev.hydrationStarted, incoming.hydrationStarted),
+            hydrationComplete: chainCallback(prev.hydrationComplete, incoming.hydrationComplete),
+        };
+        if (incoming.stopHydration !== void 0) {
+            this.stopHydration = incoming.stopHydration;
+        }
+    }
+}
+function chainCallback(first, second) {
+    if (!first)
+        return second;
+    if (!second)
+        return first;
+    return () => {
+        try {
+            first();
+        }
+        catch (_a) {
+            // Isolate callbacks so one consumer cannot suppress another.
+        }
+        try {
+            second();
+        }
+        catch (_b) {
+            // Isolate callbacks so one consumer cannot suppress another.
+        }
+    };
+}