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

package/dist/fast-element.api.json

@@ -1442,7 +1442,7 @@
         {
           "kind": "Function",
           "canonicalReference": "@microsoft/fast-element!bind:function(1)",
-          "docComment": "/**\n * Creates an standard binding.\n *\n * @param binding - The binding to refresh when changed.\n *\n * @param isVolatile - Indicates whether the binding is volatile or not.\n *\n * @returns A binding configuration.\n *\n * @public\n */\n",
+          "docComment": "/**\n * Creates an standard binding.\n *\n * @param expression - The binding to refresh when changed.\n *\n * @param isVolatile - Indicates whether the binding is volatile or not.\n *\n * @returns A binding configuration.\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -1454,7 +1454,7 @@
             },
             {
               "kind": "Content",
-              "text": ">(binding: "
+              "text": ">(expression: "
             },
             {
               "kind": "Reference",
@@ -1499,7 +1499,7 @@
           "overloadIndex": 1,
           "parameters": [
             {
-              "parameterName": "binding",
+              "parameterName": "expression",
               "parameterTypeTokenRange": {
                 "startIndex": 3,
                 "endIndex": 5
@@ -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",
@@ -10141,7 +10266,7 @@
         {
           "kind": "Function",
           "canonicalReference": "@microsoft/fast-element!listener:function(1)",
-          "docComment": "/**\n * Creates an event listener binding.\n *\n * @param binding - The binding to invoke when the event is raised.\n *\n * @param options - Event listener options.\n *\n * @returns A binding configuration.\n *\n * @public\n */\n",
+          "docComment": "/**\n * Creates an event listener binding.\n *\n * @param expression - The binding to invoke when the event is raised.\n *\n * @param options - Event listener options.\n *\n * @returns A binding configuration.\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -10153,7 +10278,7 @@
             },
             {
               "kind": "Content",
-              "text": ">(binding: "
+              "text": ">(expression: "
             },
             {
               "kind": "Reference",
@@ -10199,7 +10324,7 @@
           "overloadIndex": 1,
           "parameters": [
             {
-              "parameterName": "binding",
+              "parameterName": "expression",
               "parameterTypeTokenRange": {
                 "startIndex": 3,
                 "endIndex": 5
@@ -11397,7 +11522,7 @@
         {
           "kind": "Function",
           "canonicalReference": "@microsoft/fast-element!oneTime:function(1)",
-          "docComment": "/**\n * Creates a one time binding\n *\n * @param binding - The binding to refresh when signaled.\n *\n * @returns A binding configuration.\n *\n * @public\n */\n",
+          "docComment": "/**\n * Creates a one time binding\n *\n * @param expression - The binding to refresh when signaled.\n *\n * @returns A binding configuration.\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -11409,7 +11534,7 @@
             },
             {
               "kind": "Content",
-              "text": ">(binding: "
+              "text": ">(expression: "
             },
             {
               "kind": "Reference",
@@ -11446,7 +11571,7 @@
           "overloadIndex": 1,
           "parameters": [
             {
-              "parameterName": "binding",
+              "parameterName": "expression",
               "parameterTypeTokenRange": {
                 "startIndex": 3,
                 "endIndex": 5

package/dist/fast-element.d.ts

@@ -258,12 +258,12 @@ export declare type AttributeMode = typeof reflectMode | typeof booleanMode | "f
 
 /**
  * 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>;
 
 /**
  * Captures a binding expression along with related information and capabilities.
@@ -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;
 }
 
 /**
@@ -1295,10 +1308,7 @@ export declare class HTMLBindingDirective implements HTMLDirective, ViewBehavior
      * Creates a behavior.
      */
     createBehavior(): ViewBehavior;
-    /* Excluded from this release type: bindDefault */
     /* Excluded from this release type: bind */
-    /* Excluded from this release type: bindContent */
-    /* Excluded from this release type: bindEvent */
     /* Excluded from this release type: unbind */
     /* Excluded from this release type: handleEvent */
     /* Excluded from this release type: handleChange */
@@ -1524,12 +1534,12 @@ export declare function lengthOf<T>(array: readonly T[]): number;
 
 /**
  * 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>;
 
 /**
  * Common APIs related to markup generation.
@@ -1776,11 +1786,11 @@ export declare interface ObservationRecord {
 
 /**
  * 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>;
 
 /**
  * Common APIs related to content parsing.

package/dist/fast-element.debug.js

@@ -1963,9 +1963,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) {
@@ -1975,19 +1975,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);
         }
     }
@@ -2014,8 +2014,6 @@ class HTMLBindingDirective {
          * The type of aspect to target.
          */
         this.aspectType = Aspect.content;
-        /** @internal */
-        this.bind = this.bindDefault;
         this.data = `${this.id}-d`;
     }
     /**
@@ -2044,14 +2042,12 @@ 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:
@@ -2061,29 +2057,26 @@ 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;
@@ -2114,32 +2107,32 @@ 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
  */
-function bind(binding, isVolatile = Observable.isVolatileBinding(binding)) {
-    return new OnChangeBinding(binding, isVolatile);
+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
  */
-function oneTime(binding) {
-    return new OneTimeBinding(binding);
+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
  */
-function listener(binding, options) {
-    const config = new OnChangeBinding(binding, false);
+function listener(expression, options) {
+    const config = new OnChangeBinding(expression, false);
     config.options = options;
     return config;
 }
@@ -3581,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
@@ -3822,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) {
@@ -3834,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);
     }
     /**
@@ -3880,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
@@ -3939,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,