@microsoft/fast-html 1.0.0-alpha.29 → 1.0.0-alpha.30

package/README.md

@@ -73,6 +73,150 @@ RenderableFASTElement(MyCustomElement).defineAsync({
 });
 ```
 
+#### Lifecycle Callbacks
+
+FAST HTML provides lifecycle callbacks that allow you to hook into various stages of template processing and element hydration. These callbacks are useful for tracking the rendering lifecycle, gathering analytics, or coordinating complex initialization sequences.
+
+##### Available Callbacks
+
+**Template Lifecycle Callbacks:**
+- `elementDidRegister(name: string)` - Called after the JavaScript class definition has been registered
+- `templateWillUpdate(name: string)` - Called before the template has been evaluated and assigned
+- `templateDidUpdate(name: string)` - Called after the template has been assigned to the definition
+- `elementDidDefine(name: string)` - Called after the custom element has been defined
+
+**Hydration Lifecycle Callbacks:**
+- `elementWillHydrate(name: string)` - Called before an element begins hydration
+- `elementDidHydrate(name: string)` - Called after an element completes hydration
+- `hydrationComplete()` - Called after all elements have completed hydration
+
+##### Configuring Callbacks
+
+Configure lifecycle callbacks using `TemplateElement.config()`:
+
+```typescript
+import { TemplateElement, type HydrationLifecycleCallbacks } from "@microsoft/fast-html";
+
+// You can configure all callbacks at once
+const callbacks: HydrationLifecycleCallbacks = {
+    elementDidRegister(name: string) {
+        console.log(`Element registered: ${name}`);
+    },
+    templateWillUpdate(name: string) {
+        console.log(`Template updating: ${name}`);
+    },
+    templateDidUpdate(name: string) {
+        console.log(`Template updated: ${name}`);
+    },
+    elementDidDefine(name: string) {
+        console.log(`Element defined: ${name}`);
+    },
+    elementWillHydrate(name: string) {
+        console.log(`Element will hydrate: ${name}`);
+    },
+    elementDidHydrate(name: string) {
+        console.log(`Element hydrated: ${name}`);
+    },
+    hydrationComplete() {
+        console.log('All elements hydrated');
+    }
+};
+
+TemplateElement.config(callbacks);
+
+// Or configure only the callbacks you need
+TemplateElement.config({
+    elementDidHydrate(name: string) {
+        console.log(`${name} is ready`);
+    },
+    hydrationComplete() {
+        console.log('Page is interactive');
+    }
+});
+```
+
+##### Lifecycle Order
+
+The lifecycle callbacks occur in the following general sequence:
+
+1. **Registration Phase**: `elementDidRegister` is called when the element class is registered
+2. **Template Phase**: `templateWillUpdate` → (template processing) → `templateDidUpdate` → `elementDidDefine`
+3. **Hydration Phase**: `elementWillHydrate` → (hydration) → `elementDidHydrate`
+4. **Completion**: `hydrationComplete` is called after all elements finish hydrating
+
+**Note:** Template processing is asynchronous and happens independently for each element. The template and hydration phases can be interleaved when multiple elements are being processed simultaneously.
+
+##### Use Cases
+
+**Performance Monitoring:**
+```typescript
+TemplateElement.config({
+    elementWillHydrate(name: string) {
+        performance.mark(`${name}-hydration-start`);
+    },
+    elementDidHydrate(name: string) {
+        performance.mark(`${name}-hydration-end`);
+        performance.measure(
+            `${name}-hydration`,
+            `${name}-hydration-start`,
+            `${name}-hydration-end`
+        );
+    },
+    hydrationComplete() {
+        // Report to analytics
+        const entries = performance.getEntriesByType('measure');
+        console.log('Hydration metrics:', entries);
+    }
+});
+```
+
+**Loading State Management:**
+```typescript
+TemplateElement.config({
+    elementWillHydrate(name: string) {
+        // Show loading indicator
+        document.body.classList.add('hydrating');
+    },
+    hydrationComplete() {
+        // Hide loading indicator once all elements are ready
+        document.body.classList.remove('hydrating');
+        document.body.classList.add('hydrated');
+    }
+});
+```
+
+**Debugging and Development:**
+```typescript
+if (process.env.NODE_ENV === 'development') {
+    const events: Array<{callback: string; name?: string; timestamp: number}> = [];
+    
+    TemplateElement.config({
+        elementDidRegister(name) {
+            events.push({ callback: 'elementDidRegister', name, timestamp: Date.now() });
+        },
+        templateWillUpdate(name) {
+            events.push({ callback: 'templateWillUpdate', name, timestamp: Date.now() });
+        },
+        templateDidUpdate(name) {
+            events.push({ callback: 'templateDidUpdate', name, timestamp: Date.now() });
+        },
+        elementDidDefine(name) {
+            events.push({ callback: 'elementDidDefine', name, timestamp: Date.now() });
+        },
+        elementWillHydrate(name) {
+            events.push({ callback: 'elementWillHydrate', name, timestamp: Date.now() });
+        },
+        elementDidHydrate(name) {
+            events.push({ callback: 'elementDidHydrate', name, timestamp: Date.now() });
+        },
+        hydrationComplete() {
+            events.push({ callback: 'hydrationComplete', timestamp: Date.now() });
+            console.table(events);
+        }
+    });
+}
+```
+
 ### Syntax
 
 All bindings use a handlebars-like syntax.

package/dist/dts/components/index.d.ts

@@ -1,3 +1,3 @@
-export { TemplateElement } from "./template.js";
 export { RenderableFASTElement } from "./element.js";
 export { ObserverMap } from "./observer-map.js";
+export { ObserverMapOption, TemplateElement, type ElementOptions, type ElementOptionsDictionary, type HydrationLifecycleCallbacks, } from "./template.js";

package/dist/dts/components/request-idle-callback.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A ponyfill for requestIdleCallback that falls back to setTimeout.
+ * Uses the native requestIdleCallback when available.
+ *
+ * @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
+ */
+export declare function requestIdleCallback(callback: (deadline: IdleDeadline) => void, options?: {
+    timeout: number;
+}): ReturnType<typeof globalThis.requestIdleCallback | typeof setTimeout>;
+/**
+ * A ponyfill for cancelIdleCallback that falls back to clearTimeout.
+ * Uses the native cancelIdleCallback when available.
+ *
+ * @param id - The ID of the callback to cancel.
+ * @public
+ */
+export declare function cancelIdleCallback(id: ReturnType<typeof globalThis.requestIdleCallback | typeof setTimeout>): void;
+/**
+ * Waits for all custom element descendants of a target element to be connected.
+ *
+ * @param target - The target element to observe.
+ * @param callback - The function to call when all custom element descendants are connected.
+ * @param options - Options object that may contain a timeout property for the idle callback.
+ *
+ * @remarks
+ * This function uses requestIdleCallback to periodically check if all custom element
+ * descendants (elements with a hyphen in their tag name) are connected to the DOM.
+ * Once all such elements are connected, the provided callback is invoked.
+ *
+ * The `timeout` option specifies the maximum time to wait for each idle callback before
+ * rechecking, defaulting to 50 milliseconds.
+ *
+ * @public
+ */
+export declare function waitForConnectedDescendants(target: HTMLElement, callback: () => void, options?: {
+    shallow?: boolean;
+    timeout?: number;
+}): void;

package/dist/dts/components/template.d.ts

@@ -1,8 +1,20 @@
-import { FASTElement } from "@microsoft/fast-element";
+import { FASTElement, HydrationControllerCallbacks, TemplateLifecycleCallbacks } from "@microsoft/fast-element";
 import "@microsoft/fast-element/install-hydratable-view-templates.js";
-export type ObserverMapOption = "all";
+/**
+ * Values for the observerMap element option.
+ */
+export declare const ObserverMapOption: {
+    readonly all: "all";
+};
+/**
+ * Type for the observerMap element option.
+ */
+export type ObserverMapOption = (typeof ObserverMapOption)[keyof typeof ObserverMapOption];
+/**
+ * Element options the TemplateElement will use to update the registered element
+ */
 export interface ElementOptions {
-    observerMap?: ObserverMapOption | undefined;
+    observerMap?: ObserverMapOption;
 }
 /**
  * A dictionary of element options the TemplateElement will use to update the registered element
@@ -10,6 +22,20 @@ export interface ElementOptions {
 export interface ElementOptionsDictionary<ElementOptionsType = ElementOptions> {
     [key: string]: ElementOptionsType;
 }
+/**
+ * Lifecycle callbacks for template and hydration events.
+ * Combines template lifecycle callbacks with hydration callbacks and adds template-processing events.
+ */
+export interface HydrationLifecycleCallbacks extends HydrationControllerCallbacks, TemplateLifecycleCallbacks {
+    /**
+     * Called after the JS class definition has been registered
+     */
+    elementDidRegister?(name: string): void;
+    /**
+     * Called before the template has been evaluated and assigned
+     */
+    templateWillUpdate?(name: string): void;
+}
 /**
  * The <f-template> custom element that will provide view logic to the element
  */
@@ -34,6 +60,23 @@ declare class TemplateElement extends FASTElement {
      * Metadata containing JSON schema for properties on a custom eleemnt
      */
     private schema?;
+    /**
+     * Lifecycle callbacks for hydration events
+     */
+    private static lifecycleCallbacks;
+    /**
+     * Configure lifecycle callbacks for hydration events.
+     *
+     * @param callbacks - Lifecycle callbacks to configure.
+     * @returns The {@link TemplateElement} class.
+     */
+    static config(callbacks: HydrationLifecycleCallbacks): typeof TemplateElement;
+    /**
+     * Set options for custom elements.
+     *
+     * @param elementOptions - A dictionary of custom element options
+     * @returns The TemplateElement class.
+     */
     static options(elementOptions?: ElementOptionsDictionary): typeof TemplateElement;
     constructor();
     /**

package/dist/dts/fixtures/lifecycle-callbacks/lifecycle-callbacks.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dts/fixtures/lifecycle-callbacks/main.d.ts

@@ -0,0 +1,5 @@
+export declare const lifecycleEvents: Array<{
+    callback: string;
+    name?: string;
+}>;
+export declare let hydrationCompleteEmitted: boolean;

package/dist/esm/components/element.js

@@ -10,16 +10,12 @@ import { attr } from "@microsoft/fast-element";
 export function RenderableFASTElement(BaseCtor) {
     const C = class extends BaseCtor {
         constructor(...args) {
+            var _a, _b;
             super(...args);
             this.deferHydration = true;
-            if (this.prepare) {
-                this.prepare().then(() => {
-                    this.deferHydration = false;
-                });
-            }
-            else {
+            ((_b = (_a = this.prepare) === null || _a === void 0 ? void 0 : _a.call(this)) !== null && _b !== void 0 ? _b : Promise.resolve()).then(() => {
                 this.deferHydration = false;
-            }
+            });
         }
     };
     attr({ mode: "boolean", attribute: "defer-hydration" })(C.prototype, "deferHydration");

package/dist/esm/components/index.js

@@ -1,3 +1,3 @@
-export { TemplateElement } from "./template.js";
 export { RenderableFASTElement } from "./element.js";
 export { ObserverMap } from "./observer-map.js";
+export { ObserverMapOption, TemplateElement, } from "./template.js";

package/dist/esm/components/request-idle-callback.js

@@ -0,0 +1,72 @@
+/**
+ * A ponyfill for requestIdleCallback that falls back to setTimeout.
+ * Uses the native requestIdleCallback when available.
+ *
+ * @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
+ */
+export function requestIdleCallback(callback, options) {
+    if ("requestIdleCallback" in globalThis) {
+        return globalThis.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 ponyfill for cancelIdleCallback that falls back to clearTimeout.
+ * Uses the native cancelIdleCallback when available.
+ *
+ * @param id - The ID of the callback to cancel.
+ * @public
+ */
+export function cancelIdleCallback(id) {
+    if ("cancelIdleCallback" in globalThis) {
+        globalThis.cancelIdleCallback(id);
+    }
+    else {
+        clearTimeout(id);
+    }
+}
+/**
+ * Waits for all custom element descendants of a target element to be connected.
+ *
+ * @param target - The target element to observe.
+ * @param callback - The function to call when all custom element descendants are connected.
+ * @param options - Options object that may contain a timeout property for the idle callback.
+ *
+ * @remarks
+ * This function uses requestIdleCallback to periodically check if all custom element
+ * descendants (elements with a hyphen in their tag name) are connected to the DOM.
+ * Once all such elements are connected, the provided callback is invoked.
+ *
+ * The `timeout` option specifies the maximum time to wait for each idle callback before
+ * rechecking, defaulting to 50 milliseconds.
+ *
+ * @public
+ */
+export function waitForConnectedDescendants(target, callback, options) {
+    var _a, _b;
+    let idleCallbackId;
+    const shallow = (_a = options === null || options === void 0 ? void 0 : options.shallow) !== null && _a !== void 0 ? _a : false;
+    const query = `${shallow ? ":scope > " : ""}:not(:defined)`;
+    const timeout = (_b = options === null || options === void 0 ? void 0 : options.timeout) !== null && _b !== void 0 ? _b : 50;
+    const scheduleCheck = (deadline) => {
+        if (idleCallbackId) {
+            cancelIdleCallback(idleCallbackId);
+            idleCallbackId = undefined;
+        }
+        if (!target.querySelector(query) || (deadline && deadline.timeRemaining() <= 0)) {
+            callback();
+            return;
+        }
+        idleCallbackId = requestIdleCallback(scheduleCheck, { timeout });
+    };
+    scheduleCheck();
+}

package/dist/esm/components/template.js

@@ -1,13 +1,37 @@
 import { __awaiter, __decorate, __metadata } from "tslib";
 import { attr, children, elements, FAST, FASTElement, FASTElementDefinition, fastElementRegistry, HydratableElementController, ref, repeat, slotted, ViewTemplate, when, } from "@microsoft/fast-element";
 import "@microsoft/fast-element/install-hydratable-view-templates.js";
-import { bindingResolver, getExpressionChain, getNextBehavior, getRootPropertyName, resolveWhen, transformInnerHTML, } from "./utilities.js";
 import { ObserverMap } from "./observer-map.js";
 import { Schema } from "./schema.js";
+import { bindingResolver, getExpressionChain, getNextBehavior, getRootPropertyName, resolveWhen, transformInnerHTML, } from "./utilities.js";
+/**
+ * Values for the observerMap element option.
+ */
+export const ObserverMapOption = {
+    all: "all",
+};
 /**
  * The <f-template> custom element that will provide view logic to the element
  */
 class TemplateElement extends FASTElement {
+    /**
+     * Configure lifecycle callbacks for hydration events.
+     *
+     * @param callbacks - Lifecycle callbacks to configure.
+     * @returns The {@link TemplateElement} class.
+     */
+    static config(callbacks) {
+        TemplateElement.lifecycleCallbacks = callbacks;
+        // Pass the hydration-specific callbacks to HydratableElementController
+        HydratableElementController.config(Object.assign({}, callbacks));
+        return this;
+    }
+    /**
+     * Set options for custom elements.
+     *
+     * @param elementOptions - A dictionary of custom element options
+     * @returns The TemplateElement class.
+     */
     static options(elementOptions = {}) {
         const result = {};
         for (const key in elementOptions) {
@@ -39,35 +63,46 @@ class TemplateElement extends FASTElement {
     }
     connectedCallback() {
         super.connectedCallback();
-        if (typeof this.name === "string") {
-            this.schema = new Schema(this.name);
-            FASTElementDefinition.registerAsync(this.name).then((value) => __awaiter(this, void 0, void 0, function* () {
-                var _a, _b, _c;
-                if (!((_a = TemplateElement.elementOptions) === null || _a === void 0 ? void 0 : _a[this.name])) {
-                    TemplateElement.setOptions(this.name);
-                }
-                if (((_b = TemplateElement.elementOptions[this.name]) === null || _b === void 0 ? void 0 : _b.observerMap) ===
-                    "all") {
-                    this.observerMap = new ObserverMap(value.prototype, this.schema);
-                }
-                const registeredFastElement = fastElementRegistry.getByType(value);
-                const template = this.getElementsByTagName("template").item(0);
-                if (template) {
-                    const innerHTML = yield transformInnerHTML(this.innerHTML);
-                    // Cache paths during template processing (pass undefined if observerMap is not available)
-                    const { strings, values } = yield this.resolveStringsAndValues(null, innerHTML, false, null, 0, this.schema, this.observerMap);
-                    // Define the root properties cached in the observer map as observable (only if observerMap exists)
-                    (_c = this.observerMap) === null || _c === void 0 ? void 0 : _c.defineProperties();
-                    if (registeredFastElement) {
-                        // all new elements will get the updated template
-                        registeredFastElement.template = this.resolveTemplateOrBehavior(strings, values);
-                    }
-                }
-                else {
-                    throw FAST.error(2000 /* Message.noTemplateProvided */, { name: this.name });
-                }
-            }));
+        const name = this.name;
+        if (typeof name !== "string") {
+            return;
         }
+        this.schema = new Schema(name);
+        FASTElementDefinition.registerAsync(name).then((value) => __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d, _e, _f, _g;
+            (_b = (_a = TemplateElement.lifecycleCallbacks).elementDidRegister) === null || _b === void 0 ? void 0 : _b.call(_a, name);
+            if (!((_c = TemplateElement.elementOptions) === null || _c === void 0 ? void 0 : _c[name])) {
+                TemplateElement.setOptions(name);
+            }
+            if (((_d = TemplateElement.elementOptions[name]) === null || _d === void 0 ? void 0 : _d.observerMap) === "all") {
+                this.observerMap = new ObserverMap(value.prototype, this.schema);
+            }
+            const registeredFastElement = fastElementRegistry.getByType(value);
+            const template = this.getElementsByTagName("template").item(0);
+            if (template) {
+                // Callback: Before template has been evaluated and assigned
+                (_f = (_e = TemplateElement.lifecycleCallbacks).templateWillUpdate) === null || _f === void 0 ? void 0 : _f.call(_e, name);
+                const innerHTML = transformInnerHTML(this.innerHTML);
+                // Cache paths during template processing (pass undefined if observerMap is not available)
+                const { strings, values } = yield this.resolveStringsAndValues(null, innerHTML, false, null, 0, this.schema, this.observerMap);
+                // Define the root properties cached in the observer map as observable (only if observerMap exists)
+                (_g = this.observerMap) === null || _g === void 0 ? void 0 : _g.defineProperties();
+                if (registeredFastElement) {
+                    // Attach lifecycle callbacks to the definition before assigning template
+                    // This allows the Observable notification to trigger the callbacks
+                    registeredFastElement.lifecycleCallbacks = {
+                        templateDidUpdate: TemplateElement.lifecycleCallbacks.templateDidUpdate,
+                        elementDidDefine: TemplateElement.lifecycleCallbacks.elementDidDefine,
+                    };
+                    // All new elements will get the updated template
+                    // This assignment triggers the Observable notification → callbacks fire
+                    registeredFastElement.template = this.resolveTemplateOrBehavior(strings, values);
+                }
+            }
+            else {
+                throw FAST.error(2000 /* Message.noTemplateProvided */, { name: this.name });
+            }
+        }));
     }
     /**
      * Resolve strings and values from an innerHTML string
@@ -265,6 +300,10 @@ TemplateElement.elementOptions = {};
  * Default element options
  */
 TemplateElement.defaultElementOptions = {};
+/**
+ * Lifecycle callbacks for hydration events
+ */
+TemplateElement.lifecycleCallbacks = {};
 __decorate([
     attr,
     __metadata("design:type", String)

package/dist/esm/fixtures/lifecycle-callbacks/lifecycle-callbacks.spec.js

@@ -0,0 +1,166 @@
+import { __awaiter } from "tslib";
+import { expect, test } from "@playwright/test";
+test.describe("Lifecycle Callbacks", () => __awaiter(void 0, void 0, void 0, function* () {
+    test("should invoke all lifecycle callbacks in correct order for simple element", ({ page, }) => __awaiter(void 0, void 0, void 0, function* () {
+        yield page.goto("/lifecycle-callbacks");
+        // Wait for hydration to complete
+        yield page.waitForFunction(() => window.getHydrationCompleteStatus());
+        const events = yield page.evaluate(() => window.lifecycleEvents);
+        // Verify callbacks for simple-element were called
+        const simpleElementEvents = events.filter((e) => e.name === "simple-element");
+        expect(simpleElementEvents.length).toBeGreaterThan(0);
+        // Check that callbacks were called in the correct order
+        const callbackOrder = simpleElementEvents.map((e) => e.callback);
+        expect(callbackOrder).toContain("elementDidRegister");
+        expect(callbackOrder).toContain("templateWillUpdate");
+        expect(callbackOrder).toContain("templateDidUpdate");
+        expect(callbackOrder).toContain("elementDidDefine");
+        expect(callbackOrder).toContain("elementWillHydrate");
+        expect(callbackOrder).toContain("elementDidHydrate");
+        // Verify the order is correct
+        const registerIndex = callbackOrder.indexOf("elementDidRegister");
+        const willUpdateIndex = callbackOrder.indexOf("templateWillUpdate");
+        const didUpdateIndex = callbackOrder.indexOf("templateDidUpdate");
+        const defineIndex = callbackOrder.indexOf("elementDidDefine");
+        const willHydrateIndex = callbackOrder.indexOf("elementWillHydrate");
+        const didHydrateIndex = callbackOrder.indexOf("elementDidHydrate");
+        expect(registerIndex).toBeLessThan(willUpdateIndex);
+        expect(willUpdateIndex).toBeLessThan(didUpdateIndex);
+        expect(didUpdateIndex).toBeLessThan(defineIndex);
+        expect(willHydrateIndex).toBeGreaterThan(-1);
+        expect(didHydrateIndex).toBeGreaterThan(willHydrateIndex);
+    }));
+    test("should invoke callbacks for multiple elements", ({ page }) => __awaiter(void 0, void 0, void 0, function* () {
+        yield page.goto("/lifecycle-callbacks");
+        yield page.waitForFunction(() => window.getHydrationCompleteStatus());
+        const events = yield page.evaluate(() => window.lifecycleEvents);
+        // Check that callbacks were invoked for all elements
+        const elementNames = new Set(events.map((e) => e.name));
+        expect(elementNames.has("simple-element")).toBe(true);
+        expect(elementNames.has("complex-element")).toBe(true);
+        expect(elementNames.has("nested-element")).toBe(true);
+    }));
+    test("should invoke elementWillHydrate before hydration", ({ page }) => __awaiter(void 0, void 0, void 0, function* () {
+        yield page.goto("/lifecycle-callbacks");
+        yield page.waitForFunction(() => window.getHydrationCompleteStatus());
+        const events = yield page.evaluate(() => window.lifecycleEvents);
+        const willHydrateEvents = events.filter((e) => e.callback === "elementWillHydrate");
+        const didHydrateEvents = events.filter((e) => e.callback === "elementDidHydrate");
+        // Every elementWillHydrate should be followed by elementDidHydrate for the same element
+        willHydrateEvents.forEach((willEvent) => {
+            const correspondingDidEvent = didHydrateEvents.find((e) => e.name === willEvent.name);
+            expect(correspondingDidEvent).toBeDefined();
+        });
+    }));
+    test("should invoke hydrationComplete callback after all elements hydrate", ({ page, }) => __awaiter(void 0, void 0, void 0, function* () {
+        yield page.goto("/lifecycle-callbacks");
+        const hydrationComplete = yield page.waitForFunction(() => window.getHydrationCompleteStatus(), { timeout: 5000 });
+        expect(hydrationComplete).toBeTruthy();
+        const events = yield page.evaluate(() => window.lifecycleEvents);
+        // Verify hydrationComplete callback was invoked
+        const hydrationCompleteEvents = events.filter((e) => e.callback === "hydrationComplete");
+        expect(hydrationCompleteEvents.length).toBe(1);
+        // Verify all elements are hydrated
+        const simpleElement = yield page.locator("simple-element");
+        const complexElement = yield page.locator("complex-element");
+        const nestedElement = yield page.locator("nested-element");
+        yield expect(simpleElement).not.toHaveAttribute("needs-hydration");
+        yield expect(complexElement).not.toHaveAttribute("needs-hydration");
+        yield expect(nestedElement).not.toHaveAttribute("needs-hydration");
+        // Verify hydrationComplete was called AFTER all individual element hydrations
+        const lastElementDidHydrateIndex = events.reduce((maxIndex, e, index) => {
+            return e.callback === "elementDidHydrate" ? index : maxIndex;
+        }, -1);
+        const hydrationCompleteIndex = events.findIndex((e) => e.callback === "hydrationComplete");
+        expect(hydrationCompleteIndex).toBeGreaterThan(lastElementDidHydrateIndex);
+    }));
+    test("should handle complex element with observer map", ({ page }) => __awaiter(void 0, void 0, void 0, function* () {
+        yield page.goto("/lifecycle-callbacks");
+        yield page.waitForFunction(() => window.getHydrationCompleteStatus());
+        const complexElement = yield page.locator("complex-element");
+        // Verify the element has hydrated correctly
+        yield expect(complexElement).toHaveText(/Complex/);
+        yield expect(complexElement).not.toHaveAttribute("needs-hydration");
+        const events = yield page.evaluate(() => window.lifecycleEvents);
+        const complexEvents = events.filter((e) => e.name === "complex-element");
+        // Complex element should have all lifecycle callbacks
+        expect(complexEvents.length).toBeGreaterThan(0);
+        expect(complexEvents.some((e) => e.callback === "elementDidHydrate")).toBe(true);
+    }));
+    test("should handle nested elements correctly", ({ page }) => __awaiter(void 0, void 0, void 0, function* () {
+        yield page.goto("/lifecycle-callbacks");
+        yield page.waitForFunction(() => window.getHydrationCompleteStatus());
+        const events = yield page.evaluate(() => window.lifecycleEvents);
+        // Both parent complex-element and nested nested-element should have callbacks
+        const complexEvents = events.filter((e) => e.name === "complex-element");
+        const nestedEvents = events.filter((e) => e.name === "nested-element");
+        expect(complexEvents.length).toBeGreaterThan(0);
+        expect(nestedEvents.length).toBeGreaterThan(0);
+        // Both should have hydrated
+        expect(complexEvents.some((e) => e.callback === "elementDidHydrate")).toBe(true);
+        expect(nestedEvents.some((e) => e.callback === "elementDidHydrate")).toBe(true);
+    }));
+    test("should handle deferred hydration element", ({ page }) => __awaiter(void 0, void 0, void 0, function* () {
+        yield page.goto("/lifecycle-callbacks");
+        // The deferred element has a prepare() method that delays hydration
+        yield page.waitForFunction(() => window.getHydrationCompleteStatus(), {
+            timeout: 5000,
+        });
+        const events = yield page.evaluate(() => window.lifecycleEvents);
+        const deferredEvents = events.filter((e) => e.name === "deferred-element");
+        // Should have hydration callbacks
+        expect(deferredEvents.some((e) => e.callback === "elementWillHydrate")).toBe(true);
+        expect(deferredEvents.some((e) => e.callback === "elementDidHydrate")).toBe(true);
+        const deferredElement = yield page.locator("deferred-element");
+        yield expect(deferredElement).not.toHaveAttribute("needs-hydration");
+        yield expect(deferredElement).not.toHaveAttribute("defer-hydration");
+    }));
+    test("should verify template and hydration callbacks are invoked", ({ page, }) => __awaiter(void 0, void 0, void 0, function* () {
+        yield page.goto("/lifecycle-callbacks");
+        yield page.waitForFunction(() => window.getHydrationCompleteStatus());
+        const events = yield page.evaluate(() => window.lifecycleEvents);
+        // For each element, verify both template and hydration callbacks are invoked
+        // Note: These callbacks can be interleaved as template processing is async
+        const elementNames = ["simple-element", "complex-element", "nested-element"];
+        elementNames.forEach(name => {
+            const elementEvents = events.filter((e) => e.name === name);
+            const callbacks = elementEvents.map((e) => e.callback);
+            // Verify all expected callbacks were invoked
+            expect(callbacks).toContain("elementDidRegister");
+            expect(callbacks).toContain("templateWillUpdate");
+            expect(callbacks).toContain("templateDidUpdate");
+            expect(callbacks).toContain("elementDidDefine");
+            expect(callbacks).toContain("elementWillHydrate");
+            expect(callbacks).toContain("elementDidHydrate");
+            // Verify hydration callbacks are in order
+            const willHydrateIndex = callbacks.indexOf("elementWillHydrate");
+            const didHydrateIndex = callbacks.indexOf("elementDidHydrate");
+            expect(willHydrateIndex).toBeLessThan(didHydrateIndex);
+            // Verify template callbacks are in order
+            const registerIndex = callbacks.indexOf("elementDidRegister");
+            const willUpdateIndex = callbacks.indexOf("templateWillUpdate");
+            const didUpdateIndex = callbacks.indexOf("templateDidUpdate");
+            const defineIndex = callbacks.indexOf("elementDidDefine");
+            expect(registerIndex).toBeLessThan(willUpdateIndex);
+            expect(willUpdateIndex).toBeLessThan(didUpdateIndex);
+            expect(didUpdateIndex).toBeLessThan(defineIndex);
+        });
+    }));
+    test("should properly hydrate elements and maintain functionality", ({ page, }) => __awaiter(void 0, void 0, void 0, function* () {
+        yield page.goto("/lifecycle-callbacks");
+        yield page.waitForFunction(() => window.getHydrationCompleteStatus());
+        const simpleElement = yield page.locator("simple-element");
+        const complexElement = yield page.locator("complex-element");
+        // Verify simple element displays correctly
+        yield expect(simpleElement).toHaveText("Hello World");
+        // Verify complex element displays correctly
+        yield expect(complexElement).toHaveText(/Complex/);
+        // Verify elements are interactive after hydration
+        const currentCount = yield complexElement.evaluate((el) => el.count);
+        expect(currentCount).toBe(0);
+        // Interact with the element
+        yield complexElement.evaluate((el) => el.increment());
+        const newCount = yield complexElement.evaluate((el) => el.count);
+        expect(newCount).toBe(1);
+    }));
+}));