@microsoft/fast-element 2.0.0-beta.14 → 2.0.0-beta.16

package/CHANGELOG.json

@@ -1,6 +1,42 @@
 {
   "name": "@microsoft/fast-element",
   "entries": [
+    {
+      "date": "Fri, 28 Oct 2022 20:44:44 GMT",
+      "tag": "@microsoft/fast-element_v2.0.0-beta.16",
+      "version": "2.0.0-beta.16",
+      "comments": {
+        "prerelease": [
+          {
+            "author": "nicholasrice@users.noreply.github.com",
+            "package": "@microsoft/fast-element",
+            "commit": "5b745b1fb3bf249a7a2d172b7fb69cb08694aadd",
+            "comment": "Fixed bug preventing main component stylesheet behaviors from being connected during connectedCallback"
+          }
+        ]
+      }
+    },
+    {
+      "date": "Tue, 25 Oct 2022 20:24:32 GMT",
+      "tag": "@microsoft/fast-element_v2.0.0-beta.15",
+      "version": "2.0.0-beta.15",
+      "comments": {
+        "prerelease": [
+          {
+            "author": "nicholasrice@users.noreply.github.com",
+            "package": "@microsoft/fast-element",
+            "commit": "220cc7e0e0de490e51cc8b6f42ff46b03228beaa",
+            "comment": "Updated the ElementController to connect behaviors prior to rendering element templates"
+          },
+          {
+            "author": "nicholasrice@users.noreply.github.com",
+            "package": "@microsoft/fast-element",
+            "commit": "32ca5de5feda4870ed36329f58ded4a0a0421f02",
+            "comment": "Added support to fast-element to support element hydration and the `defer-hydration` attribute"
+          }
+        ]
+      }
+    },
     {
       "date": "Fri, 14 Oct 2022 18:26:11 GMT",
       "tag": "@microsoft/fast-element_v2.0.0-beta.14",

package/CHANGELOG.md

@@ -1,9 +1,26 @@
 # Change Log - @microsoft/fast-element
 
-This log was last generated on Fri, 14 Oct 2022 18:26:11 GMT and should not be manually modified.
+This log was last generated on Fri, 28 Oct 2022 20:44:44 GMT and should not be manually modified.
 
 <!-- Start content -->
 
+## 2.0.0-beta.16
+
+Fri, 28 Oct 2022 20:44:44 GMT
+
+### Changes
+
+- Fixed bug preventing main component stylesheet behaviors from being connected during connectedCallback (nicholasrice@users.noreply.github.com)
+
+## 2.0.0-beta.15
+
+Tue, 25 Oct 2022 20:24:32 GMT
+
+### Changes
+
+- Updated the ElementController to connect behaviors prior to rendering element templates (nicholasrice@users.noreply.github.com)
+- Added support to fast-element to support element hydration and the `defer-hydration` attribute (nicholasrice@users.noreply.github.com)
+
 ## 2.0.0-beta.14
 
 Fri, 14 Oct 2022 18:26:11 GMT

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

@@ -1,10 +1,17 @@
 import { StyleStrategy, StyleTarget } from "../interfaces.js";
-import type { HostBehavior, HostController } from "../styles/host.js";
 import { PropertyChangeNotifier } from "../observation/notifier.js";
+import { ElementStyles } from "../styles/element-styles.js";
+import type { HostBehavior, HostController } from "../styles/host.js";
 import type { ElementViewTemplate } from "../templating/template.js";
 import type { ElementView } from "../templating/view.js";
-import { ElementStyles } from "../styles/element-styles.js";
 import { FASTElementDefinition } from "./fast-definitions.js";
+/**
+ * A type that instantiates an ElementController
+ * @public
+ */
+export interface ElementControllerStrategy {
+    new (element: HTMLElement, definition: FASTElementDefinition): ElementController;
+}
 /**
  * Controls the lifecycle and rendering of a `FASTElement`.
  * @public
@@ -14,7 +21,13 @@ export declare class ElementController<TElement extends HTMLElement = HTMLElemen
     private needsInitialization;
     private hasExistingShadowRoot;
     private _template;
-    private _isConnected;
+    private stage;
+    /**
+     * A guard against connecting behaviors multiple times
+     * during connect in scenarios where a behavior adds
+     * another behavior during it's connectedCallback
+     */
+    private guardBehaviorConnection;
     private behaviors;
     private _mainStyles;
     /**
@@ -46,7 +59,6 @@ export declare class ElementController<TElement extends HTMLElement = HTMLElemen
      * connected to the document.
      */
     get isConnected(): boolean;
-    private setIsConnected;
     /**
      * Gets/sets the template used to render the component.
      * @remarks
@@ -113,7 +125,6 @@ export declare class ElementController<TElement extends HTMLElement = HTMLElemen
      * Only emits events if connected.
      */
     emit(type: string, detail?: any, options?: Omit<CustomEventInit, "detail">): void | boolean;
-    private finishInitialization;
     private renderTemplate;
     /**
      * Locates or creates a controller for the specified element.
@@ -124,6 +135,12 @@ export declare class ElementController<TElement extends HTMLElement = HTMLElemen
      * decorator or a call to `FASTElement.define`.
      */
     static forCustomElement(element: HTMLElement): ElementController;
+    /**
+     * Sets the strategy that ElementController.forCustomElement uses to construct
+     * ElementController instances for an element.
+     * @param strategy - The strategy to use.
+     */
+    static setStrategy(strategy: ElementControllerStrategy): void;
 }
 /**
  * https://wicg.github.io/construct-stylesheets/

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

@@ -0,0 +1,14 @@
+import { ElementController } from "./element-controller.js";
+/**
+ * An ElementController capable of hydrating FAST elements from
+ * Declarative Shadow DOM.
+ *
+ * @beta
+ */
+export declare class HydratableElementController<TElement extends HTMLElement = HTMLElement> extends ElementController<TElement> {
+    private static hydrationObserver;
+    private static hydrationObserverHandler;
+    connect(): void;
+    disconnect(): void;
+    static install(): void;
+}

package/dist/dts/components/install-hydration.d.ts

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

package/dist/dts/index.d.ts

@@ -24,4 +24,4 @@ export * from "./templating/node-observation.js";
 export * from "./components/fast-element.js";
 export * from "./components/fast-definitions.js";
 export * from "./components/attributes.js";
-export { ElementController } from "./components/element-controller.js";
+export { ElementController, ElementControllerStrategy, } from "./components/element-controller.js";

package/dist/dts/utilities.d.ts

@@ -20,3 +20,17 @@ export declare function composedParent<T extends HTMLElement>(element: T): HTMLE
  * @public
  */
 export declare function composedContains(reference: HTMLElement, test: HTMLElement): boolean;
+/**
+ * @internal
+ */
+export declare class UnobservableMutationObserver extends MutationObserver {
+    private readonly callback;
+    private observedNodes;
+    /**
+     * An extension of MutationObserver that supports unobserving nodes.
+     * @param callback - The callback to invoke when observed nodes are changed.
+     */
+    constructor(callback: MutationCallback);
+    observe(target: Node, options?: MutationObserverInit | undefined): void;
+    unobserve(target: Node): void;
+}

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

@@ -15,6 +15,7 @@ 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;
 }
+let elementControllerStrategy;
 /**
  * Controls the lifecycle and rendering of a `FASTElement`.
  * @public
@@ -33,7 +34,13 @@ export class ElementController extends PropertyChangeNotifier {
         this.needsInitialization = true;
         this.hasExistingShadowRoot = false;
         this._template = null;
-        this._isConnected = false;
+        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;
         this.behaviors = null;
         this._mainStyles = null;
         /**
@@ -89,11 +96,7 @@ export class ElementController extends PropertyChangeNotifier {
      */
     get isConnected() {
         Observable.track(this, isConnectedPropertyName);
-        return this._isConnected;
-    }
-    setIsConnected(value) {
-        this._isConnected = value;
-        Observable.notify(this, isConnectedPropertyName);
+        return this.stage === 1 /* Stages.connected */;
     }
     /**
      * Gets/sets the template used to render the component.
@@ -168,7 +171,9 @@ export class ElementController extends PropertyChangeNotifier {
         if (count === 0) {
             targetBehaviors.set(behavior, 1);
             behavior.addedCallback && behavior.addedCallback(this);
-            if (behavior.connectedCallback && this.isConnected) {
+            if (behavior.connectedCallback &&
+                !this.guardBehaviorConnection &&
+                (this.stage === 1 /* Stages.connected */ || this.stage === 0 /* Stages.connecting */)) {
                 behavior.connectedCallback(this);
             }
         }
@@ -192,7 +197,7 @@ export class ElementController extends PropertyChangeNotifier {
         }
         if (count === 1 || force) {
             targetBehaviors.delete(behavior);
-            if (behavior.disconnectedCallback && this.isConnected) {
+            if (behavior.disconnectedCallback && this.stage !== 3 /* Stages.disconnected */) {
                 behavior.disconnectedCallback(this);
             }
             behavior.removedCallback && behavior.removedCallback(this);
@@ -253,31 +258,49 @@ export class ElementController extends PropertyChangeNotifier {
      * Runs connected lifecycle behavior on the associated element.
      */
     connect() {
-        if (this._isConnected) {
+        if (this.stage !== 3 /* Stages.disconnected */) {
             return;
         }
-        if (this.needsInitialization) {
-            this.finishInitialization();
-        }
-        else if (this.view !== null) {
-            this.view.bind(this.source);
+        this.stage = 0 /* Stages.connecting */;
+        // If we have any observables that were bound, re-apply their values.
+        if (this.boundObservables !== null) {
+            const element = this.source;
+            const boundObservables = this.boundObservables;
+            const propertyNames = Object.keys(boundObservables);
+            for (let i = 0, ii = propertyNames.length; i < ii; ++i) {
+                const propertyName = propertyNames[i];
+                element[propertyName] = boundObservables[propertyName];
+            }
+            this.boundObservables = null;
         }
         const behaviors = this.behaviors;
         if (behaviors !== null) {
+            this.guardBehaviorConnection = true;
             for (const key of behaviors.keys()) {
                 key.connectedCallback && key.connectedCallback(this);
             }
+            this.guardBehaviorConnection = false;
+        }
+        if (this.needsInitialization) {
+            this.renderTemplate(this.template);
+            this.addStyles(this.mainStyles);
+            this.needsInitialization = false;
         }
-        this.setIsConnected(true);
+        else if (this.view !== null) {
+            this.view.bind(this.source);
+        }
+        this.stage = 1 /* Stages.connected */;
+        Observable.notify(this, isConnectedPropertyName);
     }
     /**
      * Runs disconnected lifecycle behavior on the associated element.
      */
     disconnect() {
-        if (!this._isConnected) {
+        if (this.stage !== 1 /* Stages.connected */) {
             return;
         }
-        this.setIsConnected(false);
+        this.stage = 2 /* Stages.disconnecting */;
+        Observable.notify(this, isConnectedPropertyName);
         if (this.view !== null) {
             this.view.unbind();
         }
@@ -287,6 +310,7 @@ export class ElementController extends PropertyChangeNotifier {
                 key.disconnectedCallback && key.disconnectedCallback(this);
             }
         }
+        this.stage = 3 /* Stages.disconnected */;
     }
     /**
      * Runs the attribute changed callback for the associated element.
@@ -309,27 +333,11 @@ export class ElementController extends PropertyChangeNotifier {
      * Only emits events if connected.
      */
     emit(type, detail, options) {
-        if (this._isConnected) {
+        if (this.stage === 1 /* Stages.connected */) {
             return this.source.dispatchEvent(new CustomEvent(type, Object.assign(Object.assign({ detail }, defaultEventOptions), options)));
         }
         return false;
     }
-    finishInitialization() {
-        const element = this.source;
-        const boundObservables = this.boundObservables;
-        // If we have any observables that were bound, re-apply their values.
-        if (boundObservables !== null) {
-            const propertyNames = Object.keys(boundObservables);
-            for (let i = 0, ii = propertyNames.length; i < ii; ++i) {
-                const propertyName = propertyNames[i];
-                element[propertyName] = boundObservables[propertyName];
-            }
-            this.boundObservables = null;
-        }
-        this.renderTemplate(this.template);
-        this.addStyles(this.mainStyles);
-        this.needsInitialization = false;
-    }
     renderTemplate(template) {
         var _a;
         // When getting the host to render to, we start by looking
@@ -373,9 +381,19 @@ export class ElementController extends PropertyChangeNotifier {
         if (definition === void 0) {
             throw FAST.error(1401 /* Message.missingElementDefinition */);
         }
-        return (element.$fastController = new ElementController(element, definition));
+        return (element.$fastController = new elementControllerStrategy(element, definition));
+    }
+    /**
+     * Sets the strategy that ElementController.forCustomElement uses to construct
+     * ElementController instances for an element.
+     * @param strategy - The strategy to use.
+     */
+    static setStrategy(strategy) {
+        elementControllerStrategy = strategy;
     }
 }
+// Set default strategy for ElementController
+ElementController.setStrategy(ElementController);
 /**
  * Converts a styleTarget into the operative target. When the provided target is an Element
  * that is a FASTElement, the function will return the ShadowRoot for that element. Otherwise,

package/dist/esm/components/hydration.js

@@ -0,0 +1,35 @@
+import { UnobservableMutationObserver } from "../utilities.js";
+import { ElementController } from "./element-controller.js";
+const deferHydrationAttribute = "defer-hydration";
+/**
+ * An ElementController capable of hydrating FAST elements from
+ * Declarative Shadow DOM.
+ *
+ * @beta
+ */
+export class HydratableElementController extends ElementController {
+    static hydrationObserverHandler(records) {
+        for (const record of records) {
+            HydratableElementController.hydrationObserver.unobserve(record.target);
+            record.target.$fastController.connect();
+        }
+    }
+    connect() {
+        if (this.source.hasAttribute(deferHydrationAttribute)) {
+            HydratableElementController.hydrationObserver.observe(this.source, {
+                attributeFilter: [deferHydrationAttribute],
+            });
+        }
+        else {
+            super.connect();
+        }
+    }
+    disconnect() {
+        super.disconnect();
+        HydratableElementController.hydrationObserver.unobserve(this.source);
+    }
+    static install() {
+        ElementController.setStrategy(HydratableElementController);
+    }
+}
+HydratableElementController.hydrationObserver = new UnobservableMutationObserver(HydratableElementController.hydrationObserverHandler);

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

@@ -0,0 +1,2 @@
+import { HydratableElementController } from "./hydration.js";
+HydratableElementController.install();

package/dist/esm/index.js

@@ -27,4 +27,4 @@ export * from "./templating/node-observation.js";
 export * from "./components/fast-element.js";
 export * from "./components/fast-definitions.js";
 export * from "./components/attributes.js";
-export { ElementController } from "./components/element-controller.js";
+export { ElementController, } from "./components/element-controller.js";

package/dist/esm/utilities.js

@@ -42,3 +42,30 @@ export function composedContains(reference, test) {
     }
     return false;
 }
+/**
+ * @internal
+ */
+export class UnobservableMutationObserver extends MutationObserver {
+    /**
+     * An extension of MutationObserver that supports unobserving nodes.
+     * @param callback - The callback to invoke when observed nodes are changed.
+     */
+    constructor(callback) {
+        function handler(mutations) {
+            this.callback.call(null, mutations.filter(record => this.observedNodes.has(record.target)));
+        }
+        super(handler);
+        this.callback = callback;
+        this.observedNodes = new Set();
+    }
+    observe(target, options) {
+        this.observedNodes.add(target);
+        super.observe(target, options);
+    }
+    unobserve(target) {
+        this.observedNodes.delete(target);
+        if (this.observedNodes.size < 1) {
+            this.disconnect();
+        }
+    }
+}

package/dist/fast-element.api.json

@@ -4267,6 +4267,53 @@
               ],
               "name": "removeStyles"
             },
+            {
+              "kind": "Method",
+              "canonicalReference": "@microsoft/fast-element!ElementController.setStrategy:member(1)",
+              "docComment": "/**\n * Sets the strategy that ElementController.forCustomElement uses to construct ElementController instances for an element.\n *\n * @param strategy - The strategy to use.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "static setStrategy(strategy: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ElementControllerStrategy",
+                  "canonicalReference": "@microsoft/fast-element!ElementControllerStrategy:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isOptional": false,
+              "isStatic": true,
+              "returnTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 4
+              },
+              "releaseTag": "Public",
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "strategy",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                }
+              ],
+              "name": "setStrategy"
+            },
             {
               "kind": "Property",
               "canonicalReference": "@microsoft/fast-element!ElementController#source:member",
@@ -4383,6 +4430,84 @@
             }
           ]
         },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@microsoft/fast-element!ElementControllerStrategy:interface",
+          "docComment": "/**\n * A type that instantiates an ElementController\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface ElementControllerStrategy "
+            }
+          ],
+          "releaseTag": "Public",
+          "name": "ElementControllerStrategy",
+          "members": [
+            {
+              "kind": "ConstructSignature",
+              "canonicalReference": "@microsoft/fast-element!ElementControllerStrategy:new(1)",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "new (element: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "HTMLElement",
+                  "canonicalReference": "!HTMLElement:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", definition: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "FASTElementDefinition",
+                  "canonicalReference": "@microsoft/fast-element!FASTElementDefinition:class"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ElementController",
+                  "canonicalReference": "@microsoft/fast-element!ElementController:class"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "returnTypeTokenRange": {
+                "startIndex": 5,
+                "endIndex": 6
+              },
+              "releaseTag": "Public",
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "element",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "definition",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 3,
+                    "endIndex": 4
+                  },
+                  "isOptional": false
+                }
+              ]
+            }
+          ],
+          "extendsTokenRanges": []
+        },
         {
           "kind": "Variable",
           "canonicalReference": "@microsoft/fast-element!elements:var",

package/dist/fast-element.d.ts

@@ -663,7 +663,13 @@ export declare class ElementController<TElement extends HTMLElement = HTMLElemen
     private needsInitialization;
     private hasExistingShadowRoot;
     private _template;
-    private _isConnected;
+    private stage;
+    /**
+     * A guard against connecting behaviors multiple times
+     * during connect in scenarios where a behavior adds
+     * another behavior during it's connectedCallback
+     */
+    private guardBehaviorConnection;
     private behaviors;
     private _mainStyles;
     /**
@@ -695,7 +701,6 @@ export declare class ElementController<TElement extends HTMLElement = HTMLElemen
      * connected to the document.
      */
     get isConnected(): boolean;
-    private setIsConnected;
     /**
      * Gets/sets the template used to render the component.
      * @remarks
@@ -755,7 +760,6 @@ export declare class ElementController<TElement extends HTMLElement = HTMLElemen
      * Only emits events if connected.
      */
     emit(type: string, detail?: any, options?: Omit<CustomEventInit, "detail">): void | boolean;
-    private finishInitialization;
     private renderTemplate;
     /**
      * Locates or creates a controller for the specified element.
@@ -766,6 +770,20 @@ export declare class ElementController<TElement extends HTMLElement = HTMLElemen
      * decorator or a call to `FASTElement.define`.
      */
     static forCustomElement(element: HTMLElement): ElementController;
+    /**
+     * Sets the strategy that ElementController.forCustomElement uses to construct
+     * ElementController instances for an element.
+     * @param strategy - The strategy to use.
+     */
+    static setStrategy(strategy: ElementControllerStrategy): void;
+}
+
+/**
+ * A type that instantiates an ElementController
+ * @public
+ */
+export declare interface ElementControllerStrategy {
+    new (element: HTMLElement, definition: FASTElementDefinition): ElementController;
 }
 
 /**