@microsoft/fast-element 2.7.0 → 2.8.1

package/dist/fast-element.js

@@ -85,6 +85,39 @@ const noop = () => void 0;
         result.globalThis = result;
     }
 })();
+(function requestIdleCallbackPolyfill() {
+    if ("requestIdleCallback" in globalThis) {
+        return;
+    }
+    /**
+     * A polyfill for requestIdleCallback that falls back to setTimeout.
+     *
+     * @param callback - The function to call when the browser is idle.
+     * @param options - Options object that may contain a timeout property.
+     * @returns An ID that can be used to cancel the callback.
+     * @public
+     */
+    globalThis.requestIdleCallback = function requestIdleCallback(callback, options) {
+        const start = Date.now();
+        return setTimeout(() => {
+            callback({
+                didTimeout: (options === null || options === void 0 ? void 0 : options.timeout)
+                    ? Date.now() - start >= options.timeout
+                    : false,
+                timeRemaining: () => 0,
+            });
+        }, 1);
+    };
+    /**
+     * A polyfill for cancelIdleCallback that falls back to clearTimeout.
+     *
+     * @param id - The ID of the callback to cancel.
+     * @public
+     */
+    globalThis.cancelIdleCallback = function cancelIdleCallback(id) {
+        clearTimeout(id);
+    };
+})();
 
 // ensure FAST global - duplicated debug.ts
 const propConfig = {
@@ -3061,7 +3094,7 @@ class HydrationView extends DefaultExecutionContext {
         fragment.appendChild(end);
     }
     bind(source, context = this) {
-        var _b, _c;
+        var _b;
         if (this.hydrationStage !== HydrationStage.hydrated) {
             this._hydrationStage = HydrationStage.hydrating;
         }
@@ -3105,7 +3138,28 @@ class HydrationView extends DefaultExecutionContext {
                     if (typeof templateString !== "string") {
                         templateString = templateString.innerHTML;
                     }
-                    throw new HydrationBindingError(`HydrationView was unable to successfully target bindings inside "${(_c = ((_b = this.firstChild) === null || _b === void 0 ? void 0 : _b.getRootNode()).host) === null || _c === void 0 ? void 0 : _c.nodeName}".`, factory, createRangeForNodes(this.firstChild, this.lastChild).cloneContents(), templateString);
+                    const hostElement = ((_b = this.firstChild) === null || _b === void 0 ? void 0 : _b.getRootNode())
+                        .host;
+                    const hostName = (hostElement === null || hostElement === void 0 ? void 0 : hostElement.nodeName) || "unknown";
+                    const factoryInfo = factory;
+                    // Build detailed error message
+                    const details = [
+                        `HydrationView was unable to successfully target bindings inside "<${hostName.toLowerCase()}>".`,
+                        `\nMismatch Details:`,
+                        `  - Expected target node ID: "${factory.targetNodeId}"`,
+                        `  - Available target IDs: [${Object.keys(this.targets).join(", ") || "none"}]`,
+                    ];
+                    if (factory.targetTagName) {
+                        details.push(`  - Expected tag name: "${factory.targetTagName}"`);
+                    }
+                    if (factoryInfo.sourceAspect) {
+                        details.push(`  - Source aspect: "${factoryInfo.sourceAspect}"`);
+                    }
+                    if (factoryInfo.aspectType !== undefined) {
+                        details.push(`  - Aspect type: ${factoryInfo.aspectType}`);
+                    }
+                    details.push(`\nThis usually means:`, `  1. The server-rendered HTML doesn't match the client template`, `  2. The hydration markers are missing or corrupted`, `  3. The DOM structure was modified before hydration`, `\nTemplate: ${templateString.slice(0, 200)}${templateString.length > 200 ? "..." : ""}`);
+                    throw new HydrationBindingError(details.join("\n"), factory, createRangeForNodes(this.firstChild, this.lastChild).cloneContents(), templateString);
                 }
             }
         }
@@ -4689,6 +4743,13 @@ const fastElementBaseTypes = new Set();
  * @internal
  */
 const fastElementRegistry = FAST.getById(KernelServiceId.elementRegistry, () => createTypeRegistry());
+/**
+ * Values for the `templateOptions` property.
+ * @alpha
+ */
+const TemplateOptions = {
+    deferAndHydrate: "defer-and-hydrate",
+};
 /**
  * Defines metadata for a FASTElement.
  * @public
@@ -4752,10 +4813,12 @@ class FASTElementDefinition {
      * This operation is idempotent per registry.
      */
     define(registry = this.registry) {
+        var _b, _c;
         const type = this.type;
         if (!registry.get(this.name)) {
             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);
         }
         return this;
     }
@@ -4796,15 +4859,13 @@ class FASTElementDefinition {
                 }, nameOrDef));
             }
             const definition = new FASTElementDefinition(type, nameOrDef);
-            Promise.all([
-                new Promise(resolve => {
-                    Observable.getNotifier(definition).subscribe({
-                        handleChange: () => resolve(),
-                    }, "template");
-                }),
-            ]).then(() => {
-                resolve(definition);
-            });
+            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");
         });
     }
 }
@@ -4832,9 +4893,7 @@ FASTElementDefinition.registerAsync = (name) => __awaiter(void 0, void 0, void 0
         if (FASTElementDefinition.isRegistered[name]) {
             resolve(FASTElementDefinition.isRegistered[name]);
         }
-        Observable.getNotifier(FASTElementDefinition.isRegistered).subscribe({
-            handleChange: () => resolve(FASTElementDefinition.isRegistered[name]),
-        }, name);
+        Observable.getNotifier(FASTElementDefinition.isRegistered).subscribe({ handleChange: () => resolve(FASTElementDefinition.isRegistered[name]) }, name);
     });
 });
 Observable.defineProperty(FASTElementDefinition.prototype, "template");
@@ -5930,32 +5989,77 @@ const needsHydrationAttribute = "needs-hydration";
  * @beta
  */
 class HydratableElementController extends ElementController {
+    /**
+     * Adds the current element instance to the hydrating instances map
+     */
+    addHydratingInstance() {
+        if (!HydratableElementController.hydratingInstances) {
+            return;
+        }
+        const name = this.definition.name;
+        let instances = HydratableElementController.hydratingInstances.get(name);
+        if (!instances) {
+            instances = new Set();
+            HydratableElementController.hydratingInstances.set(name, instances);
+        }
+        instances.add(this.source);
+    }
+    /**
+     * Configure lifecycle callbacks for hydration events
+     */
+    static config(callbacks) {
+        HydratableElementController.lifecycleCallbacks = callbacks;
+        return this;
+    }
     static hydrationObserverHandler(records) {
         for (const record of records) {
-            HydratableElementController.hydrationObserver.unobserve(record.target);
-            record.target.$fastController.connect();
+            if (!record.target.hasAttribute(deferHydrationAttribute)) {
+                HydratableElementController.hydrationObserver.unobserve(record.target);
+                record.target.$fastController.connect();
+            }
+        }
+    }
+    /**
+     * Checks to see if hydration is complete and if so, invokes the hydrationComplete callback.
+     * Then resets the ElementController strategy to the default so that future elements
+     * don't use the HydratableElementController.
+     *
+     * @param deadline - the idle deadline object
+     */
+    static checkHydrationComplete(deadline) {
+        var _a, _b, _c;
+        if (deadline.didTimeout) {
+            HydratableElementController.idleCallbackId = requestIdleCallback(HydratableElementController.checkHydrationComplete, { timeout: 50 });
+            return;
+        }
+        // If there are no more hydrating instances, invoke the hydrationComplete callback
+        if (((_a = HydratableElementController.hydratingInstances) === null || _a === void 0 ? void 0 : _a.size) === 0) {
+            (_c = (_b = HydratableElementController.lifecycleCallbacks) === null || _b === void 0 ? void 0 : _b.hydrationComplete) === null || _c === void 0 ? void 0 : _c.call(_b);
+            // Reset to the default strategy after hydration is complete
+            ElementController.setStrategy(ElementController);
         }
     }
     static forCustomElement(element, override) {
         const definition = FASTElementDefinition.getForInstance(element);
-        if (definition !== undefined &&
-            definition.templateOptions === "defer-and-hydrate" &&
+        if ((definition === null || definition === void 0 ? void 0 : definition.templateOptions) === TemplateOptions.deferAndHydrate &&
             !definition.template) {
-            element.setAttribute(deferHydrationAttribute, "");
-            element.setAttribute(needsHydrationAttribute, "");
+            element.toggleAttribute(deferHydrationAttribute, true);
+            element.toggleAttribute(needsHydrationAttribute, true);
         }
         return super.forCustomElement(element, override);
     }
     connect() {
-        var _a, _b;
+        var _a, _b, _c, _d, _e;
         // Initialize needsHydration on first connect
-        if (this.needsHydration === undefined) {
-            this.needsHydration =
-                this.source.getAttribute(needsHydrationAttribute) !== null;
+        this.needsHydration =
+            (_a = this.needsHydration) !== null && _a !== void 0 ? _a : this.source.getAttribute(needsHydrationAttribute) !== null;
+        if (this.needsHydration) {
+            (_c = (_b = HydratableElementController.lifecycleCallbacks) === null || _b === void 0 ? void 0 : _b.elementWillHydrate) === null || _c === void 0 ? void 0 : _c.call(_b, this.definition.name);
         }
         // If the `defer-hydration` attribute exists on the source,
         // wait for it to be removed before continuing connection behavior.
         if (this.source.hasAttribute(deferHydrationAttribute)) {
+            this.addHydratingInstance();
             HydratableElementController.hydrationObserver.observe(this.source, {
                 attributeFilter: [deferHydrationAttribute],
             });
@@ -5967,6 +6071,7 @@ class HydratableElementController extends ElementController {
         // class
         if (!this.needsHydration) {
             super.connect();
+            this.removeHydratingInstance();
             return;
         }
         if (this.stage !== 3 /* Stages.disconnected */) {
@@ -5975,10 +6080,10 @@ class HydratableElementController extends ElementController {
         this.stage = 0 /* Stages.connecting */;
         this.bindObservables();
         this.connectBehaviors();
-        const element = this.source;
-        const host = (_a = getShadowRoot(element)) !== null && _a !== void 0 ? _a : element;
         if (this.template) {
             if (isHydratable(this.template)) {
+                const element = this.source;
+                const host = (_d = getShadowRoot(element)) !== null && _d !== void 0 ? _d : element;
                 let firstChild = host.firstChild;
                 let lastChild = host.lastChild;
                 if (element.shadowRoot === null) {
@@ -5993,7 +6098,7 @@ class HydratableElementController extends ElementController {
                     }
                 }
                 this.view = this.template.hydrate(firstChild, lastChild, element);
-                (_b = this.view) === null || _b === void 0 ? void 0 : _b.bind(this.source);
+                (_e = this.view) === null || _e === void 0 ? void 0 : _e.bind(this.source);
             }
             else {
                 this.renderTemplate(this.template);
@@ -6003,8 +6108,32 @@ class HydratableElementController extends ElementController {
         this.stage = 1 /* Stages.connected */;
         this.source.removeAttribute(needsHydrationAttribute);
         this.needsInitialization = this.needsHydration = false;
+        this.removeHydratingInstance();
         Observable.notify(this, isConnectedPropertyName);
     }
+    /**
+     * Removes the current element instance from the hydrating instances map
+     */
+    removeHydratingInstance() {
+        var _a, _b;
+        if (!HydratableElementController.hydratingInstances) {
+            return;
+        }
+        const name = this.definition.name;
+        const instances = HydratableElementController.hydratingInstances.get(name);
+        // Callback: After hydration has finished
+        (_b = (_a = HydratableElementController.lifecycleCallbacks) === null || _a === void 0 ? void 0 : _a.elementDidHydrate) === null || _b === void 0 ? void 0 : _b.call(_a, this.definition.name);
+        if (instances) {
+            instances.delete(this.source);
+            if (!instances.size) {
+                HydratableElementController.hydratingInstances.delete(name);
+            }
+            if (HydratableElementController.idleCallbackId) {
+                cancelIdleCallback(HydratableElementController.idleCallbackId);
+            }
+            HydratableElementController.idleCallbackId = requestIdleCallback(HydratableElementController.checkHydrationComplete, { timeout: 50 });
+        }
+    }
     disconnect() {
         super.disconnect();
         HydratableElementController.hydrationObserver.unobserve(this.source);
@@ -6014,6 +6143,20 @@ class HydratableElementController extends ElementController {
     }
 }
 HydratableElementController.hydrationObserver = new UnobservableMutationObserver(HydratableElementController.hydrationObserverHandler);
+/**
+ * An idle callback ID used to track hydration completion
+ */
+HydratableElementController.idleCallbackId = null;
+/**
+ * A map of element instances by the name of the custom element they are
+ * associated with. The key is the custom element name, and the value is the
+ * instances of hydratable elements which currently need to be hydrated.
+ *
+ * When all of the instances in the set have been hydrated, the set is
+ * cleared and removed from the map. If the map is empty, the
+ * hydrationComplete callback is invoked.
+ */
+HydratableElementController.hydratingInstances = new Map();
 
 /* eslint-disable-next-line @typescript-eslint/explicit-function-return-type */
 function createFASTElement(BaseType) {
@@ -6117,4 +6260,4 @@ function customElement(nameOrDef) {
 
 DOM.setPolicy(DOMPolicy.create());
 
-export { ArrayObserver, AttributeConfiguration, AttributeDefinition, Binding, CSSBindingDirective, CSSDirective, ChildrenDirective, Compiler, DOM, DOMAspect, ElementController, ElementStyles, ExecutionContext, FAST, FASTElement, FASTElementDefinition, HTMLBindingDirective, HTMLDirective, HTMLView, HydratableElementController, HydrationBindingError, InlineTemplateDirective, Markup, NodeObservationDirective, Observable, Parser, PropertyChangeNotifier, RefDirective, RenderBehavior, RenderDirective, RepeatBehavior, RepeatDirective, SlottedDirective, Sort, SourceLifetime, Splice, SpliceStrategy, SpliceStrategySupport, StatelessAttachedAttributeDirective, SubscriberSet, Updates, ViewTemplate, attr, booleanConverter, children, css, cssDirective, customElement, elements, emptyArray, fastElementRegistry, html, htmlDirective, lengthOf, listener, normalizeBinding$1 as normalizeBinding, nullableBooleanConverter, nullableNumberConverter, observable, oneTime, oneWay, ref, render, repeat, slotted, sortedCount, volatile, when };
+export { ArrayObserver, AttributeConfiguration, AttributeDefinition, Binding, CSSBindingDirective, CSSDirective, ChildrenDirective, Compiler, DOM, DOMAspect, ElementController, ElementStyles, ExecutionContext, FAST, FASTElement, FASTElementDefinition, HTMLBindingDirective, HTMLDirective, HTMLView, HydratableElementController, HydrationBindingError, InlineTemplateDirective, Markup, NodeObservationDirective, Observable, Parser, PropertyChangeNotifier, RefDirective, RenderBehavior, RenderDirective, RepeatBehavior, RepeatDirective, SlottedDirective, Sort, SourceLifetime, Splice, SpliceStrategy, SpliceStrategySupport, StatelessAttachedAttributeDirective, SubscriberSet, TemplateOptions, Updates, ViewTemplate, attr, booleanConverter, children, css, cssDirective, customElement, elements, emptyArray, fastElementRegistry, html, htmlDirective, lengthOf, listener, normalizeBinding$1 as normalizeBinding, nullableBooleanConverter, nullableNumberConverter, observable, oneTime, oneWay, ref, render, repeat, slotted, sortedCount, volatile, when };