@microsoft/fast-element 2.9.1 → 2.10.0

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

@@ -1,4 +1,4 @@
-import "../interfaces.js";
+import { Message } from "../interfaces.js";
 import { PropertyChangeNotifier } from "../observation/notifier.js";
 import { ExecutionContext, Observable, SourceLifetime, } from "../observation/observable.js";
 import { FAST, makeSerializationNoop } from "../platform.js";
@@ -22,102 +22,33 @@ function getShadowRoot(element) {
     return (_b = (_a = element.shadowRoot) !== null && _a !== void 0 ? _a : shadowRoots.get(element)) !== null && _b !== void 0 ? _b : null;
 }
 let elementControllerStrategy;
+/**
+ * The various lifecycle stages of an ElementController.
+ * @public
+ */
+export var Stages;
+(function (Stages) {
+    /** The element is in the process of connecting. */
+    Stages[Stages["connecting"] = 0] = "connecting";
+    /** The element is connected. */
+    Stages[Stages["connected"] = 1] = "connected";
+    /** The element is in the process of disconnecting. */
+    Stages[Stages["disconnecting"] = 2] = "disconnecting";
+    /** The element is disconnected. */
+    Stages[Stages["disconnected"] = 3] = "disconnected";
+})(Stages || (Stages = {}));
 /**
  * Controls the lifecycle and rendering of a `FASTElement`.
  * @public
  */
 export class ElementController extends PropertyChangeNotifier {
-    /**
-     * Creates a Controller to control the specified element.
-     * @param element - The element to be controlled by this controller.
-     * @param definition - The element definition metadata that instructs this
-     * controller in how to handle rendering and other platform integrations.
-     * @internal
-     */
-    constructor(element, definition) {
-        super(element);
-        /**
-         * A map of observable properties that were set on the element before upgrade.
-         */
-        this.boundObservables = null;
-        /**
-         * Indicates whether the controller needs to perform initial rendering.
-         */
-        this.needsInitialization = true;
-        /**
-         * Indicates whether the element has an existing shadow root (e.g. from declarative shadow DOM).
-         */
-        this.hasExistingShadowRoot = false;
-        /**
-         * The template used to render the component.
-         */
-        this._template = null;
-        /**
-         * The current lifecycle stage of the controller.
-         */
-        this.stage = 3 /* Stages.disconnected */;
-        /**
-         * A guard against connecting behaviors multiple times
-         * during connect in scenarios where a behavior adds
-         * another behavior during it's connectedCallback
-         */
-        this.guardBehaviorConnection = false;
-        /**
-         * The behaviors associated with the component.
-         */
-        this.behaviors = null;
-        /**
-         * Tracks whether behaviors are connected so that
-         * behaviors cant be connected multiple times
-         */
-        this.behaviorsConnected = false;
-        /**
-         * The main set of styles used for the component, independent of any
-         * dynamically added styles.
-         */
-        this._mainStyles = null;
-        /**
-         * This allows Observable.getNotifier(...) to return the Controller
-         * when the notifier for the Controller itself is being requested. The
-         * result is that the Observable system does not need to create a separate
-         * instance of Notifier for observables on the Controller. The component and
-         * the controller will now share the same notifier, removing one-object construct
-         * per web component instance.
-         */
-        this.$fastController = this;
-        /**
-         * The view associated with the custom element.
-         * @remarks
-         * If `null` then the element is managing its own rendering.
-         */
-        this.view = null;
-        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);
-        if (accessors.length > 0) {
-            const boundObservables = (this.boundObservables = Object.create(null));
-            for (let i = 0, ii = accessors.length; i < ii; ++i) {
-                const propertyName = accessors[i].name;
-                const value = element[propertyName];
-                if (value !== void 0) {
-                    delete element[propertyName];
-                    boundObservables[propertyName] = value;
-                }
-            }
-        }
-    }
     /**
      * Indicates whether or not the custom element has been
      * connected to the document.
      */
     get isConnected() {
         Observable.track(this, isConnectedPropertyName);
-        return this.stage === 1 /* Stages.connected */;
+        return this.stage === Stages.connected;
     }
     /**
      * The context the expression is evaluated against.
@@ -224,6 +155,90 @@ export class ElementController extends PropertyChangeNotifier {
             this.addStyles(value);
         }
     }
+    /**
+     * Creates a Controller to control the specified element.
+     * @param element - The element to be controlled by this controller.
+     * @param definition - The element definition metadata that instructs this
+     * controller in how to handle rendering and other platform integrations.
+     * @internal
+     */
+    constructor(element, definition) {
+        super(element);
+        /**
+         * A map of observable properties that were set on the element before upgrade.
+         */
+        this.boundObservables = null;
+        /**
+         * Indicates whether the controller needs to perform initial rendering.
+         */
+        this.needsInitialization = true;
+        /**
+         * Indicates whether the element has an existing shadow root (e.g. from declarative shadow DOM).
+         */
+        this.hasExistingShadowRoot = false;
+        /**
+         * The template used to render the component.
+         */
+        this._template = null;
+        /**
+         * The current lifecycle stage of the controller.
+         */
+        this.stage = Stages.disconnected;
+        /**
+         * A guard against connecting behaviors multiple times
+         * during connect in scenarios where a behavior adds
+         * another behavior during it's connectedCallback
+         */
+        this.guardBehaviorConnection = false;
+        /**
+         * The behaviors associated with the component.
+         */
+        this.behaviors = null;
+        /**
+         * Tracks whether behaviors are connected so that
+         * behaviors cant be connected multiple times
+         */
+        this.behaviorsConnected = false;
+        /**
+         * The main set of styles used for the component, independent of any
+         * dynamically added styles.
+         */
+        this._mainStyles = null;
+        /**
+         * This allows Observable.getNotifier(...) to return the Controller
+         * when the notifier for the Controller itself is being requested. The
+         * result is that the Observable system does not need to create a separate
+         * instance of Notifier for observables on the Controller. The component and
+         * the controller will now share the same notifier, removing one-object construct
+         * per web component instance.
+         */
+        this.$fastController = this;
+        /**
+         * The view associated with the custom element.
+         * @remarks
+         * If `null` then the element is managing its own rendering.
+         */
+        this.view = null;
+        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);
+        if (accessors.length > 0) {
+            const boundObservables = (this.boundObservables = Object.create(null));
+            for (let i = 0, ii = accessors.length; i < ii; ++i) {
+                const propertyName = accessors[i].name;
+                const value = element[propertyName];
+                if (value !== void 0) {
+                    delete element[propertyName];
+                    boundObservables[propertyName] = value;
+                }
+            }
+        }
+    }
     /**
      * Registers an unbind handler with the controller.
      * @param behavior - An object to call when the controller unbinds.
@@ -245,7 +260,7 @@ export class ElementController extends PropertyChangeNotifier {
             behavior.addedCallback && behavior.addedCallback(this);
             if (behavior.connectedCallback &&
                 !this.guardBehaviorConnection &&
-                (this.stage === 1 /* Stages.connected */ || this.stage === 0 /* Stages.connecting */)) {
+                (this.stage === Stages.connected || this.stage === Stages.connecting)) {
                 behavior.connectedCallback(this);
             }
         }
@@ -269,7 +284,7 @@ export class ElementController extends PropertyChangeNotifier {
         }
         if (count === 1 || force) {
             targetBehaviors.delete(behavior);
-            if (behavior.disconnectedCallback && this.stage !== 3 /* Stages.disconnected */) {
+            if (behavior.disconnectedCallback && this.stage !== Stages.disconnected) {
                 behavior.disconnectedCallback(this);
             }
             behavior.removedCallback && behavior.removedCallback(this);
@@ -330,10 +345,10 @@ export class ElementController extends PropertyChangeNotifier {
      * Runs connected lifecycle behavior on the associated element.
      */
     connect() {
-        if (this.stage !== 3 /* Stages.disconnected */) {
+        if (this.stage !== Stages.disconnected) {
             return;
         }
-        this.stage = 0 /* Stages.connecting */;
+        this.stage = Stages.connecting;
         this.bindObservables();
         this.connectBehaviors();
         if (this.needsInitialization) {
@@ -344,7 +359,7 @@ export class ElementController extends PropertyChangeNotifier {
         else if (this.view !== null) {
             this.view.bind(this.source);
         }
-        this.stage = 1 /* Stages.connected */;
+        this.stage = Stages.connected;
         Observable.notify(this, isConnectedPropertyName);
     }
     /**
@@ -396,16 +411,16 @@ export class ElementController extends PropertyChangeNotifier {
      * Runs disconnected lifecycle behavior on the associated element.
      */
     disconnect() {
-        if (this.stage !== 1 /* Stages.connected */) {
+        if (this.stage !== Stages.connected) {
             return;
         }
-        this.stage = 2 /* Stages.disconnecting */;
+        this.stage = Stages.disconnecting;
         Observable.notify(this, isConnectedPropertyName);
         if (this.view !== null) {
             this.view.unbind();
         }
         this.disconnectBehaviors();
-        this.stage = 3 /* Stages.disconnected */;
+        this.stage = Stages.disconnected;
     }
     /**
      * Runs the attribute changed callback for the associated element.
@@ -428,7 +443,7 @@ export class ElementController extends PropertyChangeNotifier {
      * Only emits events if connected.
      */
     emit(type, detail, options) {
-        if (this.stage === 1 /* Stages.connected */) {
+        if (this.stage === Stages.connected) {
             return this.source.dispatchEvent(new CustomEvent(type, Object.assign(Object.assign({ detail }, defaultEventOptions), options)));
         }
         return false;
@@ -482,7 +497,7 @@ export class ElementController extends PropertyChangeNotifier {
         }
         const definition = FASTElementDefinition.getForInstance(element);
         if (definition === void 0) {
-            throw FAST.error(1401 /* Message.missingElementDefinition */);
+            throw FAST.error(Message.missingElementDefinition);
         }
         Observable.getNotifier(definition).subscribe({
             handleChange: () => {
@@ -698,7 +713,12 @@ export class HydratableElementController extends ElementController {
         }
         // 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);
+            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);
         }
@@ -707,7 +727,7 @@ export class HydratableElementController extends ElementController {
      * Runs connected lifecycle behavior on the associated element.
      */
     connect() {
-        var _a, _b, _c, _d, _e;
+        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);
@@ -729,17 +749,31 @@ export class HydratableElementController extends ElementController {
             this.removeHydratingInstance();
             return;
         }
-        if (this.stage !== 3 /* Stages.disconnected */) {
+        if (this.stage !== Stages.disconnected) {
             return;
         }
-        (_c = (_b = HydratableElementController.lifecycleCallbacks) === null || _b === void 0 ? void 0 : _b.elementWillHydrate) === null || _c === void 0 ? void 0 : _c.call(_b, this.definition.name);
-        this.stage = 0 /* Stages.connecting */;
+        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 = (_d = getShadowRoot(element)) !== null && _d !== void 0 ? _d : element;
+                const host = (_f = getShadowRoot(element)) !== null && _f !== void 0 ? _f : element;
                 let firstChild = host.firstChild;
                 let lastChild = host.lastChild;
                 if (element.shadowRoot === null) {
@@ -754,14 +788,14 @@ export class HydratableElementController extends ElementController {
                     }
                 }
                 this.view = this.template.hydrate(firstChild, lastChild, element);
-                (_e = this.view) === null || _e === void 0 ? void 0 : _e.bind(this.source);
+                (_g = this.view) === null || _g === void 0 ? void 0 : _g.bind(this.source);
             }
             else {
                 this.renderTemplate(this.template);
             }
         }
         this.addStyles(this.mainStyles);
-        this.stage = 1 /* Stages.connected */;
+        this.stage = Stages.connected;
         this.source.removeAttribute(needsHydrationAttribute);
         this.needsInitialization = this.needsHydration = false;
         this.removeHydratingInstance();
@@ -775,10 +809,14 @@ export class HydratableElementController extends ElementController {
         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);
-        // 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) {
@@ -808,6 +846,14 @@ export class HydratableElementController extends ElementController {
     }
 }
 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
  */

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

@@ -12,7 +12,7 @@ import { isString, KernelServiceId } from "../interfaces.js";
 import { Observable } from "../observation/observable.js";
 import { createTypeRegistry, FAST } from "../platform.js";
 import { ElementStyles } from "../styles/element-styles.js";
-import { AttributeDefinition } from "./attributes.js";
+import { AttributeConfiguration, AttributeDefinition } from "./attributes.js";
 const defaultShadowOptions = { mode: "open" };
 const defaultElementOptions = {};
 const fastElementBaseTypes = new Set();
@@ -33,6 +33,12 @@ export const TemplateOptions = {
  * @public
  */
 export class FASTElementDefinition {
+    /**
+     * Indicates if this element has been defined in at least one registry.
+     */
+    get isDefined() {
+        return this.platformDefined;
+    }
     constructor(type, nameOrConfig = type.definition) {
         var _b;
         this.platformDefined = false;
@@ -75,14 +81,8 @@ export class FASTElementDefinition {
                 : Object.assign(Object.assign({}, defaultElementOptions), nameOrConfig.elementOptions);
         this.styles = ElementStyles.normalize(nameOrConfig.styles);
         fastElementRegistry.register(this);
-        Observable.defineProperty(FASTElementDefinition.isRegistered, this.name);
-        FASTElementDefinition.isRegistered[this.name] = this.type;
-    }
-    /**
-     * Indicates if this element has been defined in at least one registry.
-     */
-    get isDefined() {
-        return this.platformDefined;
+        Observable.defineProperty(_a.isRegistered, this.name);
+        _a.isRegistered[this.name] = this.type;
     }
     /**
      * Defines a custom element based on this definition.
@@ -108,10 +108,10 @@ export class FASTElementDefinition {
      */
     static compose(type, nameOrDef) {
         if (fastElementBaseTypes.has(type) || fastElementRegistry.getByType(type)) {
-            return new FASTElementDefinition(class extends type {
+            return new _a(class extends type {
             }, nameOrDef);
         }
-        return new FASTElementDefinition(type, nameOrDef);
+        return new _a(type, nameOrDef);
     }
     /**
      * Registers a FASTElement base type.
@@ -133,10 +133,10 @@ export class FASTElementDefinition {
     static composeAsync(type, nameOrDef) {
         return new Promise(resolve => {
             if (fastElementBaseTypes.has(type) || fastElementRegistry.getByType(type)) {
-                resolve(new FASTElementDefinition(class extends type {
+                resolve(new _a(class extends type {
                 }, nameOrDef));
             }
-            const definition = new FASTElementDefinition(type, nameOrDef);
+            const definition = new _a(type, nameOrDef);
             Observable.getNotifier(definition).subscribe({
                 handleChange: () => {
                     var _b, _c;
@@ -169,10 +169,10 @@ FASTElementDefinition.getForInstance = fastElementRegistry.getForInstance;
  */
 FASTElementDefinition.registerAsync = (name) => __awaiter(void 0, void 0, void 0, function* () {
     return new Promise(resolve => {
-        if (FASTElementDefinition.isRegistered[name]) {
-            resolve(FASTElementDefinition.isRegistered[name]);
+        if (_a.isRegistered[name]) {
+            resolve(_a.isRegistered[name]);
         }
-        Observable.getNotifier(FASTElementDefinition.isRegistered).subscribe({ handleChange: () => resolve(FASTElementDefinition.isRegistered[name]) }, name);
+        Observable.getNotifier(_a.isRegistered).subscribe({ handleChange: () => resolve(_a.isRegistered[name]) }, name);
     });
 });
 Observable.defineProperty(FASTElementDefinition.prototype, "template");

package/dist/esm/context.js

@@ -1,4 +1,4 @@
-import "./interfaces.js";
+import { Message } from "./interfaces.js";
 import { Metadata } from "./metadata.js";
 import { FAST } from "./platform.js";
 const contextsByName = new Map();
@@ -37,7 +37,7 @@ export const Context = Object.freeze({
     create(name, initialValue) {
         const Interface = function (target, property, index) {
             if (target == null || new.target !== undefined) {
-                throw FAST.error(1501 /* Message.noRegistrationForContext */, {
+                throw FAST.error(Message.noRegistrationForContext, {
                     name: Interface.name,
                 });
             }