@microsoft/fast-element 2.10.3 → 3.0.0-rc.1

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

@@ -3,13 +3,7 @@ import { PropertyChangeNotifier } from "../observation/notifier.js";
 import { ExecutionContext, Observable, SourceLifetime, } from "../observation/observable.js";
 import { FAST, makeSerializationNoop } from "../platform.js";
 import { ElementStyles } from "../styles/element-styles.js";
-import { UnobservableMutationObserver } from "../utilities.js";
-import { FASTElementDefinition, TemplateOptions, } from "./fast-definitions.js";
-import { deferHydrationAttribute, HydrationMarkup, isHydratable } from "./hydration.js";
-/**
- * @deprecated Use the export from ./hydration.js instead.
- */
-export { deferHydrationAttribute } from "./hydration.js";
+import { FASTElementDefinition, getLateAttributeLookup, } from "./fast-definitions.js";
 const defaultEventOptions = {
     bubbles: true,
     composed: true,
@@ -17,6 +11,7 @@ const defaultEventOptions = {
 };
 const isConnectedPropertyName = "isConnected";
 const shadowRoots = new WeakMap();
+const lateAttributeObserver = Symbol("fast-late-attribute-observer");
 function getShadowRoot(element) {
     var _a, _b;
     return (_b = (_a = element.shadowRoot) !== null && _a !== void 0 ? _a : shadowRoots.get(element)) !== null && _b !== void 0 ? _b : null;
@@ -41,7 +36,7 @@ export var Stages;
  * Controls the lifecycle and rendering of a `FASTElement`.
  * @public
  */
-export class ElementController extends PropertyChangeNotifier {
+export class ElementController {
     /**
      * Indicates whether or not the custom element has been
      * connected to the document.
@@ -87,7 +82,8 @@ export class ElementController extends PropertyChangeNotifier {
             }
             else if (definition.template) {
                 // 3. Default to the static definition.
-                this._template = (_a = definition.template) !== null && _a !== void 0 ? _a : null;
+                this._template =
+                    (_a = definition.template) !== null && _a !== void 0 ? _a : null;
             }
         }
         return this._template;
@@ -163,7 +159,6 @@ export class ElementController extends PropertyChangeNotifier {
      * @internal
      */
     constructor(element, definition) {
-        super(element);
         /**
          * A map of observable properties that were set on the element before upgrade.
          */
@@ -176,6 +171,22 @@ export class ElementController extends PropertyChangeNotifier {
          * Indicates whether the element has an existing shadow root (e.g. from declarative shadow DOM).
          */
         this.hasExistingShadowRoot = false;
+        /**
+         * Resolves `true` when the element had an existing shadow root
+         * (from SSR or declarative shadow DOM) at connect time, `false`
+         * otherwise.
+         */
+        this.isPrerendered = new Promise(resolve => {
+            this._resolvePrerendered = resolve;
+        });
+        /**
+         * Resolves `true` after prerendered content has been successfully
+         * hydrated, or `false` when the component is client-side rendered
+         * or hydration is not enabled.
+         */
+        this.isHydrated = new Promise(resolve => {
+            this._resolveHydrated = resolve;
+        });
         /**
          * The template used to render the component.
          */
@@ -219,14 +230,12 @@ export class ElementController extends PropertyChangeNotifier {
          * If `null` then the element is managing its own rendering.
          */
         this.view = null;
+        this._notifier = new PropertyChangeNotifier(element);
         this.source = element;
         this.definition = definition;
         this.shadowOptions = definition.shadowOptions;
-        // Capture any observable values that were set by the binding engine before
-        // the browser upgraded the element. Then delete the property since it will
-        // shadow the getter/setter that is required to make the observable operate.
-        // Later, in the connect callback, we'll re-apply the values.
-        const accessors = Observable.getAccessors(element);
+        const prototype = Reflect.getPrototypeOf(element);
+        const accessors = prototype === null ? [] : Observable.getAccessors(prototype);
         if (accessors.length > 0) {
             const boundObservables = (this.boundObservables = Object.create(null));
             for (let i = 0, ii = accessors.length; i < ii; ++i) {
@@ -237,7 +246,42 @@ export class ElementController extends PropertyChangeNotifier {
                     boundObservables[propertyName] = value;
                 }
             }
+            if (Object.keys(boundObservables).length === 0) {
+                this.boundObservables = null;
+            }
         }
+        // Capture any observable values that were set after construction but before
+        // the first connect (for example, late-defined declarative accessors).
+        this.captureBoundObservables();
+    }
+    /**
+     * The subject that subscribers will receive notifications for.
+     */
+    get subject() {
+        return this._notifier.subject;
+    }
+    /**
+     * Notifies all subscribers of a property change.
+     * @param args - The property name that changed.
+     */
+    notify(args) {
+        this._notifier.notify(args);
+    }
+    /**
+     * Subscribes to notification of changes in the element's state.
+     * @param subscriber - The object that is subscribing for change notification.
+     * @param propertyToWatch - The name of the property to watch for changes.
+     */
+    subscribe(subscriber, propertyToWatch) {
+        this._notifier.subscribe(subscriber, propertyToWatch);
+    }
+    /**
+     * Unsubscribes from notification of changes in the element's state.
+     * @param subscriber - The object that is unsubscribing from change notification.
+     * @param propertyToUnwatch - The name of the property to unsubscribe from.
+     */
+    unsubscribe(subscriber, propertyToUnwatch) {
+        this._notifier.unsubscribe(subscriber, propertyToUnwatch);
     }
     /**
      * Registers an unbind handler with the controller.
@@ -308,13 +352,7 @@ export class ElementController extends PropertyChangeNotifier {
             target.append(styles);
         }
         else if (!styles.isAttachedTo(source)) {
-            const sourceBehaviors = styles.behaviors;
             styles.addStylesTo(source);
-            if (sourceBehaviors !== null) {
-                for (let i = 0, ii = sourceBehaviors.length; i < ii; ++i) {
-                    this.addBehavior(sourceBehaviors[i]);
-                }
-            }
         }
     }
     /**
@@ -332,13 +370,7 @@ export class ElementController extends PropertyChangeNotifier {
             target.removeChild(styles);
         }
         else if (styles.isAttachedTo(source)) {
-            const sourceBehaviors = styles.behaviors;
             styles.removeStylesFrom(source);
-            if (sourceBehaviors !== null) {
-                for (let i = 0, ii = sourceBehaviors.length; i < ii; ++i) {
-                    this.removeBehavior(sourceBehaviors[i]);
-                }
-            }
         }
     }
     /**
@@ -349,6 +381,9 @@ export class ElementController extends PropertyChangeNotifier {
             return;
         }
         this.stage = Stages.connecting;
+        this.captureBoundObservables();
+        this.syncLateAttributes();
+        this.observeLateAttributes();
         this.bindObservables();
         this.connectBehaviors();
         if (this.needsInitialization) {
@@ -377,6 +412,95 @@ export class ElementController extends PropertyChangeNotifier {
             this.boundObservables = null;
         }
     }
+    /**
+     * Captures own-properties that shadow observable accessors on the prototype so
+     * they can be rebound through the accessor before rendering.
+     */
+    captureBoundObservables() {
+        const element = this.source;
+        const propertyNames = Object.getOwnPropertyNames(element);
+        const hasPrototypeAccessor = (propertyName) => {
+            let currentTarget = Reflect.getPrototypeOf(element);
+            while (currentTarget !== null) {
+                const descriptor = Reflect.getOwnPropertyDescriptor(currentTarget, propertyName);
+                if ((descriptor === null || descriptor === void 0 ? void 0 : descriptor.get) || (descriptor === null || descriptor === void 0 ? void 0 : descriptor.set)) {
+                    return true;
+                }
+                currentTarget = Reflect.getPrototypeOf(currentTarget);
+            }
+            return false;
+        };
+        let boundObservables = this.boundObservables;
+        for (let i = 0, ii = propertyNames.length; i < ii; ++i) {
+            const ownPropertyName = propertyNames[i];
+            const propertyName = (ownPropertyName[0] === "_" ? ownPropertyName.slice(1) : ownPropertyName);
+            if (!hasPrototypeAccessor(propertyName)) {
+                continue;
+            }
+            const value = element[propertyName];
+            const isBackingField = ownPropertyName !== propertyName;
+            const isRebindableObject = value !== null &&
+                typeof value === "object" &&
+                !(value === null || value === void 0 ? void 0 : value.$isProxy) &&
+                !(Array.isArray(value) && (value === null || value === void 0 ? void 0 : value.$fastController));
+            if (value === void 0) {
+                if (!isBackingField) {
+                    delete element[ownPropertyName];
+                }
+                continue;
+            }
+            if (isBackingField && !isRebindableObject) {
+                continue;
+            }
+            delete element[ownPropertyName];
+            (boundObservables !== null && boundObservables !== void 0 ? boundObservables : (boundObservables = this.boundObservables = Object.create(null)))[propertyName] = value;
+        }
+    }
+    /**
+     * Synchronizes late-defined attribute-map attributes from the live DOM to the
+     * associated property values before the initial render occurs.
+     */
+    syncLateAttributes() {
+        const lateAttributes = getLateAttributeLookup(this.definition);
+        if (lateAttributes === null) {
+            return;
+        }
+        for (const attributeName of Object.keys(lateAttributes)) {
+            if (!this.source.hasAttribute(attributeName)) {
+                continue;
+            }
+            this.onAttributeChangedCallback(attributeName, null, this.source.getAttribute(attributeName));
+        }
+    }
+    /**
+     * Observes late-defined attribute-map attributes that the platform does not
+     * surface through attributeChangedCallback because they were added after
+     * customElements.define() completed.
+     */
+    observeLateAttributes() {
+        if (getLateAttributeLookup(this.definition) === null) {
+            return;
+        }
+        const element = this.source;
+        if (element[lateAttributeObserver] !== void 0) {
+            return;
+        }
+        element[lateAttributeObserver] = new MutationObserver(records => {
+            const controller = element.$fastController;
+            const lateAttributes = getLateAttributeLookup(controller.definition);
+            if (lateAttributes === null) {
+                return;
+            }
+            for (let i = 0, ii = records.length; i < ii; ++i) {
+                const attributeName = records[i].attributeName;
+                if (attributeName === null || lateAttributes[attributeName] === void 0) {
+                    continue;
+                }
+                controller.onAttributeChangedCallback(attributeName, null, element.getAttribute(attributeName));
+            }
+        });
+        element[lateAttributeObserver].observe(element, { attributes: true });
+    }
     /**
      * Connects any existing behaviors on the associated element.
      */
@@ -457,30 +581,51 @@ export class ElementController extends PropertyChangeNotifier {
      */
     renderTemplate(template) {
         var _a;
-        // When getting the host to render to, we start by looking
-        // up the shadow root. If there isn't one, then that means
-        // we're doing a Light DOM render to the element's direct children.
         const element = this.source;
         const host = (_a = getShadowRoot(element)) !== null && _a !== void 0 ? _a : element;
         if (this.view !== null) {
-            // If there's already a view, we need to unbind and remove through dispose.
             this.view.dispose();
             this.view = null;
         }
         else if (!this.needsInitialization || this.hasExistingShadowRoot) {
-            this.hasExistingShadowRoot = false;
-            // If there was previous custom rendering, we need to clear out the host.
-            for (let child = host.firstChild; child !== null; child = host.firstChild) {
-                host.removeChild(child);
+            if (!this.hasExistingShadowRoot || !this.needsInitialization) {
+                for (let child = host.firstChild; child !== null; child = host.firstChild) {
+                    host.removeChild(child);
+                }
             }
         }
         if (template) {
-            // If a new template was provided, render it.
-            this.view = template.render(element, host, element);
-            this.view.sourceLifetime =
-                SourceLifetime.coupled;
+            const hasPrerenderedContent = this.hasExistingShadowRoot && this.needsInitialization;
+            let didHydrate = false;
+            if (hasPrerenderedContent && ElementController.hydrationHook) {
+                didHydrate = ElementController.hydrationHook(this, template, element, host);
+            }
+            if (!didHydrate) {
+                this.renderClientSide(template, element, host);
+            }
+            this._resolvePrerendered(hasPrerenderedContent);
+            this._resolveHydrated(didHydrate);
+        }
+        else if (this.needsInitialization) {
+            this._resolvePrerendered(false);
+            this._resolveHydrated(false);
         }
     }
+    /**
+     * Standard client-side render: clears any stale content, clones the
+     * compiled fragment, binds, and appends to the host.
+     */
+    renderClientSide(template, element, host) {
+        if (this.hasExistingShadowRoot) {
+            for (let child = host.firstChild; child !== null; child = host.firstChild) {
+                host.removeChild(child);
+            }
+            this.hasExistingShadowRoot = false;
+        }
+        this.view = template.render(element, host, element);
+        this.view.sourceLifetime =
+            SourceLifetime.coupled;
+    }
     /**
      * Locates or creates a controller for the specified element.
      * @param element - The element to return the controller for.
@@ -521,7 +666,22 @@ export class ElementController extends PropertyChangeNotifier {
     static setStrategy(strategy) {
         elementControllerStrategy = strategy;
     }
+    /**
+     * Installs the hydration hook. Called by enableHydration().
+     * @internal
+     */
+    static installHydrationHook(hook) {
+        ElementController.hydrationHook = hook;
+    }
 }
+// --- Static hydration hook ---
+/**
+ * A hook that, when set, handles prerendered content hydration.
+ * Called by renderTemplate when an existing shadow root is detected.
+ * Returns true if hydration was performed, false to fall back to client-side.
+ * @internal
+ */
+ElementController.hydrationHook = null;
 makeSerializationNoop(ElementController);
 // Set default strategy for ElementController
 ElementController.setStrategy(ElementController);
@@ -633,7 +793,7 @@ if (ElementStyles.supportsAdoptedStyleSheets) {
             }
         };
     }
-    catch (e) {
+    catch (_e) {
         // Do nothing if an error is thrown, the default
         // case handles FrozenArray.
     }
@@ -642,232 +802,3 @@ if (ElementStyles.supportsAdoptedStyleSheets) {
 else {
     ElementStyles.setDefaultStrategy(StyleElementStrategy);
 }
-/**
- * The attribute used to indicate that an element needs hydration.
- * @public
- */
-export const needsHydrationAttribute = "needs-hydration";
-/**
- * An ElementController capable of hydrating FAST elements from
- * Declarative Shadow DOM.
- *
- * @beta
- */
-export class HydratableElementController extends ElementController {
-    /**
-     * {@inheritdoc ElementController.shadowOptions}
-     */
-    get shadowOptions() {
-        return super.shadowOptions;
-    }
-    set shadowOptions(value) {
-        super.shadowOptions = value;
-        if ((this.hasExistingShadowRoot || (value !== void 0 && !this.template)) &&
-            this.definition.templateOptions === TemplateOptions.deferAndHydrate) {
-            this.source.toggleAttribute(deferHydrationAttribute, true);
-            this.source.toggleAttribute(needsHydrationAttribute, true);
-        }
-    }
-    /**
-     * 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) {
-            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) {
-            try {
-                (_c = (_b = HydratableElementController.lifecycleCallbacks).hydrationComplete) === null || _c === void 0 ? void 0 : _c.call(_b);
-            }
-            catch (_d) {
-                // A lifecycle callback must never prevent post-hydration cleanup.
-            }
-            // Reset to the default strategy after hydration is complete
-            ElementController.setStrategy(ElementController);
-        }
-    }
-    /**
-     * Runs connected lifecycle behavior on the associated element.
-     */
-    connect() {
-        var _a, _b, _c, _d, _e, _f, _g;
-        // Initialize needsHydration on first connect
-        this.needsHydration =
-            (_a = this.needsHydration) !== null && _a !== void 0 ? _a : this.source.hasAttribute(needsHydrationAttribute);
-        if (this.needsHydration) {
-            this.addHydratingInstance();
-        }
-        // 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],
-            });
-            return;
-        }
-        // If the controller does not need to be hydrated, defer connection behavior
-        // to the base-class. This case handles element re-connection and initial connection
-        // of elements that did not get declarative shadow-dom emitted, as well as if an extending
-        // class
-        if (!this.needsHydration) {
-            super.connect();
-            this.removeHydratingInstance();
-            return;
-        }
-        if (this.stage !== Stages.disconnected) {
-            return;
-        }
-        if (!HydratableElementController.hydrationStarted) {
-            HydratableElementController.hydrationStarted = true;
-            try {
-                (_c = (_b = HydratableElementController.lifecycleCallbacks).hydrationStarted) === null || _c === void 0 ? void 0 : _c.call(_b);
-            }
-            catch (_h) {
-                // A lifecycle callback must never prevent hydration.
-            }
-        }
-        try {
-            (_e = (_d = HydratableElementController.lifecycleCallbacks).elementWillHydrate) === null || _e === void 0 ? void 0 : _e.call(_d, this.source);
-        }
-        catch (_j) {
-            // A lifecycle callback must never prevent hydration.
-        }
-        this.stage = Stages.connecting;
-        this.bindObservables();
-        this.connectBehaviors();
-        if (this.template) {
-            if (isHydratable(this.template)) {
-                const element = this.source;
-                const host = (_f = getShadowRoot(element)) !== null && _f !== void 0 ? _f : element;
-                let firstChild = host.firstChild;
-                let lastChild = host.lastChild;
-                if (element.shadowRoot === null) {
-                    // handle element boundary markers when shadowRoot is not present
-                    if (HydrationMarkup.isElementBoundaryStartMarker(firstChild)) {
-                        firstChild.data = "";
-                        firstChild = firstChild.nextSibling;
-                    }
-                    if (HydrationMarkup.isElementBoundaryEndMarker(lastChild)) {
-                        lastChild.data = "";
-                        lastChild = lastChild.previousSibling;
-                    }
-                }
-                this.view = this.template.hydrate(firstChild, lastChild, element);
-                (_g = this.view) === null || _g === void 0 ? void 0 : _g.bind(this.source);
-            }
-            else {
-                this.renderTemplate(this.template);
-            }
-        }
-        this.addStyles(this.mainStyles);
-        this.stage = 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;
-        }
-        try {
-            (_b = (_a = HydratableElementController.lifecycleCallbacks).elementDidHydrate) === null || _b === void 0 ? void 0 : _b.call(_a, this.source);
-        }
-        catch (_c) {
-            // A lifecycle callback must never prevent hydration.
-        }
-        const name = this.definition.name;
-        const instances = HydratableElementController.hydratingInstances.get(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 });
-        }
-    }
-    /**
-     * Unregisters the hydration observer when the element is disconnected.
-     */
-    disconnect() {
-        super.disconnect();
-        HydratableElementController.hydrationObserver.unobserve(this.source);
-    }
-    /**
-     * Sets the ElementController strategy to HydratableElementController.
-     * @remarks
-     * This method is typically called during application startup to enable
-     * hydration support for FAST elements.
-     */
-    static install() {
-        ElementController.setStrategy(HydratableElementController);
-    }
-}
-HydratableElementController.hydrationObserver = new UnobservableMutationObserver(HydratableElementController.hydrationObserverHandler);
-/**
- * Lifecycle callbacks for hydration events
- */
-HydratableElementController.lifecycleCallbacks = {};
-/**
- * Whether the hydrationStarted callback has already been invoked.
- */
-HydratableElementController.hydrationStarted = false;
-/**
- * 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();

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

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