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

package/CHANGELOG.json

@@ -1,6 +1,48 @@
 {
   "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",
+      "version": "2.0.0-beta.14",
+      "comments": {
+        "prerelease": [
+          {
+            "author": "roeisenb@microsoft.com",
+            "package": "@microsoft/fast-element",
+            "commit": "19f1ae727e2ff6e629d2b134fc045a81d83caaed",
+            "comment": "fix: tokenList bindings track adds and removes from multiple sources"
+          },
+          {
+            "author": "roeisenb@microsoft.com",
+            "package": "@microsoft/fast-element",
+            "commit": "0248fa906f986d6b0cbdeb26cf388742e871449e",
+            "comment": "refactor: remove duplication and re-organize binding behavior logic"
+          }
+        ]
+      }
+    },
     {
       "date": "Mon, 10 Oct 2022 20:28:02 GMT",
       "tag": "@microsoft/fast-element_v2.0.0-beta.13",

package/CHANGELOG.md

@@ -1,9 +1,27 @@
 # Change Log - @microsoft/fast-element
 
-This log was last generated on Mon, 10 Oct 2022 20:28:02 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
+
+### Changes
+
+- fix: tokenList bindings track adds and removes from multiple sources (roeisenb@microsoft.com)
+- refactor: remove duplication and re-organize binding behavior logic (roeisenb@microsoft.com)
+
 ## 2.0.0-beta.13
 
 Mon, 10 Oct 2022 20:28:02 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/templating/binding.d.ts

@@ -80,13 +80,7 @@ export declare class HTMLBindingDirective implements HTMLDirective, ViewBehavior
      */
     createBehavior(): ViewBehavior;
     /** @internal */
-    bindDefault(controller: ViewController): void;
-    /** @internal */
-    bind: (controller: ViewController) => void;
-    /** @internal */
-    bindContent(controller: ViewController): void;
-    /** @internal */
-    bindEvent(controller: ViewController): void;
+    bind(controller: ViewController): void;
     /** @internal */
     unbind(controller: ViewController): void;
     /** @internal */
@@ -96,27 +90,27 @@ export declare class HTMLBindingDirective implements HTMLDirective, ViewBehavior
 }
 /**
  * Creates an standard binding.
- * @param binding - The binding to refresh when changed.
+ * @param expression - The binding to refresh when changed.
  * @param isVolatile - Indicates whether the binding is volatile or not.
  * @returns A binding configuration.
  * @public
  */
-export declare function bind<T = any>(binding: Expression<T>, isVolatile?: boolean): Binding<T>;
+export declare function bind<T = any>(expression: Expression<T>, isVolatile?: boolean): Binding<T>;
 /**
  * Creates a one time binding
- * @param binding - The binding to refresh when signaled.
+ * @param expression - The binding to refresh when signaled.
  * @returns A binding configuration.
  * @public
  */
-export declare function oneTime<T = any>(binding: Expression<T>): Binding<T>;
+export declare function oneTime<T = any>(expression: Expression<T>): Binding<T>;
 /**
  * Creates an event listener binding.
- * @param binding - The binding to invoke when the event is raised.
+ * @param expression - The binding to invoke when the event is raised.
  * @param options - Event listener options.
  * @returns A binding configuration.
  * @public
  */
-export declare function listener<T = any>(binding: Expression<T>, options?: AddEventListenerOptions): Binding<T>;
+export declare function listener<T = any>(expression: Expression<T>, options?: AddEventListenerOptions): Binding<T>;
 /**
  * Normalizes the input value into a binding.
  * @param value - The value to create the default binding for.

package/dist/dts/testing/fakes.d.ts

@@ -1,7 +1,7 @@
 import { ExecutionContext, ViewBehavior, ViewBehaviorTargets } from "../index.js";
 export declare const Fake: Readonly<{
     executionContext<TParent = any>(parent?: TParent | undefined, parentContext?: ExecutionContext<TParent> | undefined): ExecutionContext<TParent>;
-    viewController<TSource = any, TParent_1 = any>(targets: ViewBehaviorTargets, ...behaviors: ViewBehavior<TSource, TParent_1>[]): {
+    viewController<TSource = any, TParent_1 = any>(targets?: ViewBehaviorTargets, ...behaviors: ViewBehavior<TSource, TParent_1>[]): {
         isBound: boolean;
         context: ExecutionContext<TParent_1>;
         onUnbind(object: any): void;

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/templating/binding.js

@@ -88,9 +88,9 @@ function updateContent(target, aspect, value, controller) {
 function updateTokenList(target, aspect, value) {
     var _a;
     const lookup = `${this.id}-t`;
-    const state = (_a = target[lookup]) !== null && _a !== void 0 ? _a : (target[lookup] = { c: 0, v: Object.create(null) });
-    const versions = state.v;
-    let currentVersion = state.c;
+    const state = (_a = target[lookup]) !== null && _a !== void 0 ? _a : (target[lookup] = { v: 0, cv: Object.create(null) });
+    const classVersions = state.cv;
+    let version = state.v;
     const tokenList = target[aspect];
     // Add the classes, tracking the version at which they were added.
     if (value !== null && value !== undefined && value.length) {
@@ -100,19 +100,19 @@ function updateTokenList(target, aspect, value) {
             if (currentName === "") {
                 continue;
             }
-            versions[currentName] = currentVersion;
+            classVersions[currentName] = version;
             tokenList.add(currentName);
         }
     }
-    state.v = currentVersion + 1;
+    state.v = version + 1;
     // If this is the first call to add classes, there's no need to remove old ones.
-    if (currentVersion === 0) {
+    if (version === 0) {
         return;
     }
     // Remove classes from the previous version.
-    currentVersion -= 1;
-    for (const name in versions) {
-        if (versions[name] === currentVersion) {
+    version -= 1;
+    for (const name in classVersions) {
+        if (classVersions[name] === version) {
             tokenList.remove(name);
         }
     }
@@ -139,8 +139,6 @@ export class HTMLBindingDirective {
          * The type of aspect to target.
          */
         this.aspectType = Aspect.content;
-        /** @internal */
-        this.bind = this.bindDefault;
         this.data = `${this.id}-d`;
     }
     /**
@@ -169,14 +167,12 @@ export class HTMLBindingDirective {
                     this.updateTarget = setProperty;
                     break;
                 case 4:
-                    this.bind = this.bindContent;
                     this.updateTarget = updateContent;
                     break;
                 case 5:
                     this.updateTarget = updateTokenList;
                     break;
                 case 6:
-                    this.bind = this.bindEvent;
                     this.updateTarget = eventTarget;
                     break;
                 default:
@@ -186,29 +182,26 @@ export class HTMLBindingDirective {
         return this;
     }
     /** @internal */
-    bindDefault(controller) {
+    bind(controller) {
         var _a;
         const target = controller.targets[this.nodeId];
-        const observer = (_a = target[this.data]) !== null && _a !== void 0 ? _a : (target[this.data] = this.dataBinding.createObserver(this, this));
-        observer.target = target;
-        observer.controller = controller;
-        this.updateTarget(target, this.targetAspect, observer.bind(controller), controller);
-        if (this.updateTarget === updateContent) {
-            controller.onUnbind(this);
+        switch (this.updateTarget) {
+            case eventTarget:
+                target[this.data] = controller;
+                target.addEventListener(this.targetAspect, this, this.dataBinding.options);
+                break;
+            case updateContent:
+                controller.onUnbind(this);
+            // intentional fall through
+            default:
+                const observer = (_a = target[this.data]) !== null && _a !== void 0 ? _a : (target[this.data] = this.dataBinding.createObserver(this, this));
+                observer.target = target;
+                observer.controller = controller;
+                this.updateTarget(target, this.targetAspect, observer.bind(controller), controller);
+                break;
         }
     }
     /** @internal */
-    bindContent(controller) {
-        this.bindDefault(controller);
-        controller.onUnbind(this);
-    }
-    /** @internal */
-    bindEvent(controller) {
-        const target = controller.targets[this.nodeId];
-        target[this.data] = controller;
-        target.addEventListener(this.targetAspect, this, this.dataBinding.options);
-    }
-    /** @internal */
     unbind(controller) {
         const target = controller.targets[this.nodeId];
         const view = target.$fastView;
@@ -239,32 +232,32 @@ export class HTMLBindingDirective {
 HTMLDirective.define(HTMLBindingDirective, { aspected: true });
 /**
  * Creates an standard binding.
- * @param binding - The binding to refresh when changed.
+ * @param expression - The binding to refresh when changed.
  * @param isVolatile - Indicates whether the binding is volatile or not.
  * @returns A binding configuration.
  * @public
  */
-export function bind(binding, isVolatile = Observable.isVolatileBinding(binding)) {
-    return new OnChangeBinding(binding, isVolatile);
+export function bind(expression, isVolatile = Observable.isVolatileBinding(expression)) {
+    return new OnChangeBinding(expression, isVolatile);
 }
 /**
  * Creates a one time binding
- * @param binding - The binding to refresh when signaled.
+ * @param expression - The binding to refresh when signaled.
  * @returns A binding configuration.
  * @public
  */
-export function oneTime(binding) {
-    return new OneTimeBinding(binding);
+export function oneTime(expression) {
+    return new OneTimeBinding(expression);
 }
 /**
  * Creates an event listener binding.
- * @param binding - The binding to invoke when the event is raised.
+ * @param expression - The binding to invoke when the event is raised.
  * @param options - Event listener options.
  * @returns A binding configuration.
  * @public
  */
-export function listener(binding, options) {
-    const config = new OnChangeBinding(binding, false);
+export function listener(expression, options) {
+    const config = new OnChangeBinding(expression, false);
     config.options = options;
     return config;
 }

package/dist/esm/testing/fakes.js

@@ -73,7 +73,7 @@ export const Fake = Object.freeze({
             },
         };
     },
-    viewController(targets, ...behaviors) {
+    viewController(targets = {}, ...behaviors) {
         const unbindables = new Set();
         return {
             isBound: false,

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();
+        }
+    }
+}