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

package/CHANGELOG.json

@@ -1,6 +1,27 @@
 {
   "name": "@microsoft/fast-element",
   "entries": [
+    {
+      "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,18 @@
 # 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 Tue, 25 Oct 2022 20:24:32 GMT and should not be manually modified.
 
 <!-- Start content -->
 
+## 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
@@ -113,7 +120,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 +130,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
@@ -256,11 +257,16 @@ export class ElementController extends PropertyChangeNotifier {
         if (this._isConnected) {
             return;
         }
-        if (this.needsInitialization) {
-            this.finishInitialization();
-        }
-        else if (this.view !== null) {
-            this.view.bind(this.source);
+        // 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) {
@@ -268,6 +274,14 @@ export class ElementController extends PropertyChangeNotifier {
                 key.connectedCallback && key.connectedCallback(this);
             }
         }
+        if (this.needsInitialization) {
+            this.renderTemplate(this.template);
+            this.addStyles(this.mainStyles);
+            this.needsInitialization = false;
+        }
+        else if (this.view !== null) {
+            this.view.bind(this.source);
+        }
         this.setIsConnected(true);
     }
     /**
@@ -314,22 +328,6 @@ export class ElementController extends PropertyChangeNotifier {
         }
         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 +371,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

@@ -755,7 +755,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 +765,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;
 }
 
 /**

package/dist/fast-element.debug.js

@@ -3574,6 +3574,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
@@ -3815,11 +3816,16 @@ class ElementController extends PropertyChangeNotifier {
         if (this._isConnected) {
             return;
         }
-        if (this.needsInitialization) {
-            this.finishInitialization();
-        }
-        else if (this.view !== null) {
-            this.view.bind(this.source);
+        // 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) {
@@ -3827,6 +3833,14 @@ class ElementController extends PropertyChangeNotifier {
                 key.connectedCallback && key.connectedCallback(this);
             }
         }
+        if (this.needsInitialization) {
+            this.renderTemplate(this.template);
+            this.addStyles(this.mainStyles);
+            this.needsInitialization = false;
+        }
+        else if (this.view !== null) {
+            this.view.bind(this.source);
+        }
         this.setIsConnected(true);
     }
     /**
@@ -3873,22 +3887,6 @@ class ElementController extends PropertyChangeNotifier {
         }
         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
@@ -3932,9 +3930,19 @@ 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,