@microsoft/fast-element 2.7.0 → 2.8.0

package/CHANGELOG.json

@@ -2,7 +2,22 @@
   "name": "@microsoft/fast-element",
   "entries": [
     {
-      "date": "Wed, 20 Aug 2025 20:56:28 GMT",
+      "date": "Mon, 13 Oct 2025 00:36:35 GMT",
+      "version": "2.8.0",
+      "tag": "@microsoft/fast-element_v2.8.0",
+      "comments": {
+        "minor": [
+          {
+            "author": "863023+radium-v@users.noreply.github.com",
+            "package": "@microsoft/fast-element",
+            "commit": "28a1d5dcae41f04e2ff8cb9114c312efb88fb1e1",
+            "comment": "[feat]: implement lifecycle callbacks for hydration and template events"
+          }
+        ]
+      }
+    },
+    {
+      "date": "Wed, 20 Aug 2025 20:57:02 GMT",
       "version": "2.7.0",
       "tag": "@microsoft/fast-element_v2.7.0",
       "comments": {

package/CHANGELOG.md

@@ -1,12 +1,20 @@
 # Change Log - @microsoft/fast-element
 
-<!-- This log was last generated on Wed, 20 Aug 2025 20:56:28 GMT and should not be manually modified. -->
+<!-- This log was last generated on Mon, 13 Oct 2025 00:36:35 GMT and should not be manually modified. -->
 
 <!-- Start content -->
 
+## 2.8.0
+
+Mon, 13 Oct 2025 00:36:35 GMT
+
+### Minor changes
+
+- [feat]: implement lifecycle callbacks for hydration and template events (863023+radium-v@users.noreply.github.com)
+
 ## 2.7.0
 
-Wed, 20 Aug 2025 20:56:28 GMT
+Wed, 20 Aug 2025 20:57:02 GMT
 
 ### Minor changes
 

package/dist/dts/components/element-controller.d.ts

@@ -206,6 +206,24 @@ export declare class StyleElementStrategy implements StyleStrategy {
 }
 export declare const deferHydrationAttribute = "defer-hydration";
 export declare const needsHydrationAttribute = "needs-hydration";
+/**
+ * Lifecycle callbacks for element hydration events
+ * @public
+ */
+export interface HydrationControllerCallbacks {
+    /**
+     * Called before hydration has started
+     */
+    elementWillHydrate?(name: string): void;
+    /**
+     * Called after hydration has finished
+     */
+    elementDidHydrate?(name: string): void;
+    /**
+     * Called after all elements have completed hydration
+     */
+    hydrationComplete?(): void;
+}
 /**
  * An ElementController capable of hydrating FAST elements from
  * Declarative Shadow DOM.
@@ -220,7 +238,19 @@ export declare class HydratableElementController<TElement extends HTMLElement =
      */
     protected needsHydration?: boolean;
     private static hydrationObserver;
+    /**
+     * Lifecycle callbacks for hydration events
+     */
+    private static lifecycleCallbacks?;
+    /**
+     * Configure lifecycle callbacks for hydration events
+     */
+    static config(callbacks: HydrationControllerCallbacks): typeof HydratableElementController;
     private static hydrationObserverHandler;
+    /**
+     * Checks if all elements have completed hydration and dispatches event if complete
+     */
+    private static checkHydrationComplete;
     static forCustomElement(element: HTMLElement, override?: boolean): ElementController<HTMLElement>;
     connect(): void;
     disconnect(): void;

package/dist/dts/components/fast-definitions.d.ts

@@ -22,10 +22,31 @@ export interface ShadowRootOptions extends ShadowRootInit {
     registry?: CustomElementRegistry;
 }
 /**
- * Template options.
+ * Values for the `templateOptions` property.
  * @alpha
  */
-export declare type TemplateOptions = "defer-and-hydrate";
+export declare const TemplateOptions: {
+    readonly deferAndHydrate: "defer-and-hydrate";
+};
+/**
+ * Type for the `TemplateOptions` const enum.
+ * @alpha
+ */
+export declare type TemplateOptions = (typeof TemplateOptions)[keyof typeof TemplateOptions];
+/**
+ * Lifecycle callbacks for template events.
+ * @public
+ */
+export interface TemplateLifecycleCallbacks {
+    /**
+     * Called after the template has been assigned to the definition
+     */
+    templateDidUpdate?(name: string): void;
+    /**
+     * Called after the custom element has been defined
+     */
+    elementDidDefine?(name: string): void;
+}
 /**
  * Represents metadata configuration for a custom element.
  * @public
@@ -69,6 +90,10 @@ export interface PartialFASTElementDefinition {
      * If not provided, defaults to the global registry.
      */
     readonly registry?: CustomElementRegistry;
+    /**
+     * Lifecycle callbacks for template events.
+     */
+    readonly lifecycleCallbacks?: TemplateLifecycleCallbacks;
 }
 /**
  * Defines metadata for a FASTElement.
@@ -125,6 +150,10 @@ export declare class FASTElementDefinition<TType extends Constructable<HTMLEleme
      * The registry to register this component in by default.
      */
     readonly registry: CustomElementRegistry;
+    /**
+     * Lifecycle callbacks for template events.
+     */
+    readonly lifecycleCallbacks?: TemplateLifecycleCallbacks;
     /**
      * The definition has been registered to the FAST element registry.
      */

package/dist/dts/index.d.ts

@@ -29,6 +29,6 @@ export { ElementView, HTMLView, SyntheticView, View, HydratableView, HydrationBi
 export { elements, ElementsFilter, NodeBehaviorOptions, NodeObservationDirective, } from "./templating/node-observation.js";
 export { render, RenderBehavior, RenderDirective } from "./templating/render.js";
 export { customElement, FASTElement } from "./components/fast-element.js";
-export { FASTElementDefinition, PartialFASTElementDefinition, ShadowRootOptions, fastElementRegistry, TemplateOptions, TypeRegistry, } from "./components/fast-definitions.js";
+export { FASTElementDefinition, PartialFASTElementDefinition, ShadowRootOptions, fastElementRegistry, TemplateOptions, TypeRegistry, type TemplateLifecycleCallbacks, } from "./components/fast-definitions.js";
 export { attr, AttributeConfiguration, AttributeDefinition, AttributeMode, booleanConverter, DecoratorAttributeConfiguration, nullableBooleanConverter, nullableNumberConverter, ValueConverter, } from "./components/attributes.js";
-export { ElementController, ElementControllerStrategy, HydratableElementController, } from "./components/element-controller.js";
+export { ElementController, ElementControllerStrategy, HydratableElementController, type HydrationControllerCallbacks, } from "./components/element-controller.js";

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

@@ -4,7 +4,7 @@ import { ExecutionContext, Observable, SourceLifetime, } from "../observation/ob
 import { FAST, makeSerializationNoop } from "../platform.js";
 import { ElementStyles } from "../styles/element-styles.js";
 import { UnobservableMutationObserver } from "../utilities.js";
-import { FASTElementDefinition } from "./fast-definitions.js";
+import { FASTElementDefinition, TemplateOptions, } from "./fast-definitions.js";
 import { HydrationMarkup, isHydratable } from "./hydration.js";
 const defaultEventOptions = {
     bubbles: true,
@@ -591,24 +591,39 @@ export const needsHydrationAttribute = "needs-hydration";
  * @beta
  */
 export class HydratableElementController extends ElementController {
+    /**
+     * 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();
         }
     }
+    /**
+     * Checks if all elements have completed hydration and dispatches event if complete
+     */
+    static checkHydrationComplete() {
+        var _a, _b;
+        if (!document.querySelector(`[${needsHydrationAttribute}]`)) {
+            (_b = (_a = HydratableElementController.lifecycleCallbacks) === null || _a === void 0 ? void 0 : _a.hydrationComplete) === null || _b === void 0 ? void 0 : _b.call(_a);
+        }
+    }
     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, _f;
         // Initialize needsHydration on first connect
         if (this.needsHydration === undefined) {
             this.needsHydration =
@@ -633,11 +648,13 @@ export class HydratableElementController extends ElementController {
         if (this.stage !== 3 /* Stages.disconnected */) {
             return;
         }
+        // Callback: Before hydration has started
+        (_b = (_a = HydratableElementController.lifecycleCallbacks) === null || _a === void 0 ? void 0 : _a.elementWillHydrate) === null || _b === void 0 ? void 0 : _b.call(_a, this.definition.name);
         this.stage = 0 /* Stages.connecting */;
         this.bindObservables();
         this.connectBehaviors();
         const element = this.source;
-        const host = (_a = getShadowRoot(element)) !== null && _a !== void 0 ? _a : element;
+        const host = (_c = getShadowRoot(element)) !== null && _c !== void 0 ? _c : element;
         if (this.template) {
             if (isHydratable(this.template)) {
                 let firstChild = host.firstChild;
@@ -654,7 +671,7 @@ export 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);
+                (_d = this.view) === null || _d === void 0 ? void 0 : _d.bind(this.source);
             }
             else {
                 this.renderTemplate(this.template);
@@ -665,6 +682,10 @@ export class HydratableElementController extends ElementController {
         this.source.removeAttribute(needsHydrationAttribute);
         this.needsInitialization = this.needsHydration = false;
         Observable.notify(this, isConnectedPropertyName);
+        // Callback: After hydration has finished
+        (_f = (_e = HydratableElementController.lifecycleCallbacks) === null || _e === void 0 ? void 0 : _e.elementDidHydrate) === null || _f === void 0 ? void 0 : _f.call(_e, this.definition.name);
+        // Check if hydration is complete after this element is hydrated
+        HydratableElementController.checkHydrationComplete();
     }
     disconnect() {
         super.disconnect();

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

@@ -21,6 +21,13 @@ const fastElementBaseTypes = new Set();
  * @internal
  */
 export const fastElementRegistry = FAST.getById(KernelServiceId.elementRegistry, () => createTypeRegistry());
+/**
+ * Values for the `templateOptions` property.
+ * @alpha
+ */
+export const TemplateOptions = {
+    deferAndHydrate: "defer-and-hydrate",
+};
 /**
  * Defines metadata for a FASTElement.
  * @public
@@ -84,10 +91,12 @@ export 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;
     }
@@ -128,15 +137,13 @@ export 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");
         });
     }
 }
@@ -165,9 +172,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");

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

@@ -1,3 +1,12 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 import { isFunction } from "../interfaces.js";
 import { ElementController } from "./element-controller.js";
 import { FASTElementDefinition, } from "./fast-definitions.js";
@@ -32,21 +41,11 @@ 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;
+    return __awaiter(this, void 0, void 0, function* () {
+        if (isFunction(type)) {
+            return (yield FASTElementDefinition.composeAsync(type, nameOrDef)).define().type;
+        }
+        return (yield FASTElementDefinition.composeAsync(this, type)).define().type;
     });
 }
 function define(type, nameOrDef) {

package/dist/esm/index.js

@@ -34,6 +34,6 @@ export { elements, NodeObservationDirective, } from "./templating/node-observati
 export { render, RenderBehavior, RenderDirective } from "./templating/render.js";
 // Components
 export { customElement, FASTElement } from "./components/fast-element.js";
-export { FASTElementDefinition, fastElementRegistry, } from "./components/fast-definitions.js";
+export { FASTElementDefinition, fastElementRegistry, TemplateOptions, } from "./components/fast-definitions.js";
 export { attr, AttributeConfiguration, AttributeDefinition, booleanConverter, nullableBooleanConverter, nullableNumberConverter, } from "./components/attributes.js";
 export { ElementController, HydratableElementController, } from "./components/element-controller.js";

package/dist/esm/templating/view.js

@@ -360,7 +360,7 @@ export 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;
         }
@@ -404,7 +404,28 @@ export 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);
                 }
             }
         }