@microsoft/fast-element 2.4.1 → 2.6.0

package/dist/fast-element.api.json

@@ -8566,6 +8566,15 @@
               "text": "compose",
               "canonicalReference": "@microsoft/fast-element!~compose:function"
             },
+            {
+              "kind": "Content",
+              "text": ";\n    defineAsync: typeof "
+            },
+            {
+              "kind": "Reference",
+              "text": "defineAsync",
+              "canonicalReference": "@microsoft/fast-element!~defineAsync:function"
+            },
             {
               "kind": "Content",
               "text": ";\n    from: typeof "
@@ -8586,7 +8595,7 @@
           "name": "FASTElement",
           "variableTypeTokenRange": {
             "startIndex": 1,
-            "endIndex": 10
+            "endIndex": 12
           }
         },
         {
@@ -9114,6 +9123,50 @@
               "isProtected": false,
               "isAbstract": false
             },
+            {
+              "kind": "Property",
+              "canonicalReference": "@microsoft/fast-element!FASTElementDefinition.isRegistered:member",
+              "docComment": "/**\n * The definition has been registered to the FAST element registry.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "static isRegistered: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Record",
+                  "canonicalReference": "!Record:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<string, "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Function",
+                  "canonicalReference": "!Function:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ">"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "isRegistered",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 5
+              },
+              "isStatic": true,
+              "isProtected": false,
+              "isAbstract": false
+            },
             {
               "kind": "Property",
               "canonicalReference": "@microsoft/fast-element!FASTElementDefinition#name:member",
@@ -9188,6 +9241,54 @@
               "isProtected": false,
               "isAbstract": false
             },
+            {
+              "kind": "Property",
+              "canonicalReference": "@microsoft/fast-element!FASTElementDefinition.registerAsync:member",
+              "docComment": "/**\n * Indicates when a custom elements definition has been registered with the fastElementRegistry.\n *\n * @param name - The name of the defined custom element.\n *\n * @alpha\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "static registerAsync: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "(name: string) => "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Promise",
+                  "canonicalReference": "!Promise:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<"
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Function",
+                  "canonicalReference": "!Function:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ">"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Alpha",
+              "name": "registerAsync",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 6
+              },
+              "isStatic": true,
+              "isProtected": false,
+              "isAbstract": false
+            },
             {
               "kind": "Property",
               "canonicalReference": "@microsoft/fast-element!FASTElementDefinition#registry:member",
@@ -9312,6 +9413,37 @@
               "isProtected": false,
               "isAbstract": false
             },
+            {
+              "kind": "Property",
+              "canonicalReference": "@microsoft/fast-element!FASTElementDefinition#templateOptions:member",
+              "docComment": "/**\n * The template options.\n *\n * @alpha\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "templateOptions?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "TemplateOptions",
+                  "canonicalReference": "@microsoft/fast-element!TemplateOptions:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Alpha",
+              "name": "templateOptions",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
             {
               "kind": "Property",
               "canonicalReference": "@microsoft/fast-element!FASTElementDefinition#type:member",
@@ -12266,6 +12398,85 @@
               "isAbstract": false,
               "name": "disconnect"
             },
+            {
+              "kind": "Method",
+              "canonicalReference": "@microsoft/fast-element!HydratableElementController.forCustomElement:member(1)",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "static forCustomElement(element: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "HTMLElement",
+                  "canonicalReference": "!HTMLElement:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", override?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ElementController",
+                  "canonicalReference": "@microsoft/fast-element!ElementController:class"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<"
+                },
+                {
+                  "kind": "Reference",
+                  "text": "HTMLElement",
+                  "canonicalReference": "!HTMLElement:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ">"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": true,
+              "returnTypeTokenRange": {
+                "startIndex": 5,
+                "endIndex": 9
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "element",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "override",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 3,
+                    "endIndex": 4
+                  },
+                  "isOptional": true
+                }
+              ],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "forCustomElement"
+            },
             {
               "kind": "Method",
               "canonicalReference": "@microsoft/fast-element!HydratableElementController.install:member(1)",
@@ -14926,6 +15137,34 @@
                 "startIndex": 1,
                 "endIndex": 2
               }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@microsoft/fast-element!PartialFASTElementDefinition#templateOptions:member",
+              "docComment": "/**\n * Options controlling how the template will be created.\n *\n * @alpha\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly templateOptions?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "TemplateOptions",
+                  "canonicalReference": "@microsoft/fast-element!TemplateOptions:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": true,
+              "releaseTag": "Alpha",
+              "name": "templateOptions",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
             }
           ],
           "extendsTokenRanges": []
@@ -20551,6 +20790,32 @@
           ],
           "extendsTokenRanges": []
         },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@microsoft/fast-element!TemplateOptions:type",
+          "docComment": "/**\n * Template options.\n *\n * @alpha\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare type TemplateOptions = "
+            },
+            {
+              "kind": "Content",
+              "text": "\"defer-and-hydrate\""
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "dist/dts/components/fast-definitions.d.ts",
+          "releaseTag": "Alpha",
+          "name": "TemplateOptions",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          }
+        },
         {
           "kind": "TypeAlias",
           "canonicalReference": "@microsoft/fast-element!TemplateValue:type",

package/dist/fast-element.debug.js

@@ -4510,6 +4510,36 @@ function children(propertyOrOptions) {
     return new ChildrenDirective(propertyOrOptions);
 }
 
+/******************************************************************************
+Copyright (c) Microsoft Corporation.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+***************************************************************************** */
+
+function __awaiter(thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+}
+
+typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+};
+
 const booleanMode = "boolean";
 const reflectMode = "reflect";
 /**
@@ -4732,7 +4762,7 @@ const fastElementRegistry = FAST.getById(KernelServiceId.elementRegistry, () =>
  */
 class FASTElementDefinition {
     constructor(type, nameOrConfig = type.definition) {
-        var _a;
+        var _b;
         this.platformDefined = false;
         if (isString(nameOrConfig)) {
             nameOrConfig = { name: nameOrConfig };
@@ -4740,7 +4770,8 @@ class FASTElementDefinition {
         this.type = type;
         this.name = nameOrConfig.name;
         this.template = nameOrConfig.template;
-        this.registry = (_a = nameOrConfig.registry) !== null && _a !== void 0 ? _a : customElements;
+        this.templateOptions = nameOrConfig.templateOptions;
+        this.registry = (_b = nameOrConfig.registry) !== null && _b !== void 0 ? _b : customElements;
         const proto = type.prototype;
         const attributes = AttributeDefinition.collect(type, nameOrConfig.attributes);
         const observedAttributes = new Array(attributes.length);
@@ -4772,6 +4803,8 @@ 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.
@@ -4814,7 +4847,43 @@ class FASTElementDefinition {
     static registerBaseType(type) {
         fastElementBaseTypes.add(type);
     }
+    /**
+     * Creates an instance of FASTElementDefinition asynchronously. This option assumes
+     * that a template and shadowOptions will be provided and completes when those requirements
+     * are met.
+     * @param type - The type this definition is being created for.
+     * @param nameOrDef - The name of the element to define or a config object
+     * that describes the element to define.
+     * @alpha
+     */
+    static composeAsync(type, nameOrDef) {
+        return new Promise(resolve => {
+            if (fastElementBaseTypes.has(type) || fastElementRegistry.getByType(type)) {
+                resolve(new FASTElementDefinition(class extends type {
+                }, nameOrDef));
+            }
+            const definition = new FASTElementDefinition(type, nameOrDef);
+            Promise.all([
+                new Promise(resolve => {
+                    Observable.getNotifier(definition).subscribe({
+                        handleChange: () => resolve(),
+                    }, "template");
+                }),
+                new Promise(resolve => {
+                    Observable.getNotifier(definition).subscribe({
+                        handleChange: () => resolve(),
+                    }, "shadowOptions");
+                }),
+            ]).then(() => {
+                resolve(definition);
+            });
+        });
+    }
 }
+/**
+ * The definition has been registered to the FAST element registry.
+ */
+FASTElementDefinition.isRegistered = {};
 /**
  * Gets the element definition associated with the specified type.
  * @param type - The custom element type to retrieve the definition for.
@@ -4825,6 +4894,21 @@ FASTElementDefinition.getByType = fastElementRegistry.getByType;
  * @param instance - The custom element instance to retrieve the definition for.
  */
 FASTElementDefinition.getForInstance = fastElementRegistry.getForInstance;
+/**
+ * Indicates when a custom elements definition has been registered with the fastElementRegistry.
+ * @param name - The name of the defined custom element.
+ * @alpha
+ */
+FASTElementDefinition.registerAsync = (name) => __awaiter(void 0, void 0, void 0, function* () {
+    return new Promise(resolve => {
+        if (FASTElementDefinition.isRegistered[name]) {
+            resolve(FASTElementDefinition.isRegistered[name]);
+        }
+        Observable.getNotifier(FASTElementDefinition.isRegistered).subscribe({
+            handleChange: () => resolve(FASTElementDefinition.isRegistered[name]),
+        }, name);
+    });
+});
 Observable.defineProperty(FASTElementDefinition.prototype, "template");
 Observable.defineProperty(FASTElementDefinition.prototype, "shadowOptions");
 
@@ -5925,6 +6009,16 @@ class HydratableElementController extends ElementController {
             record.target.$fastController.connect();
         }
     }
+    static forCustomElement(element, override) {
+        const definition = FASTElementDefinition.getForInstance(element);
+        if (definition !== undefined &&
+            definition.templateOptions === "defer-and-hydrate" &&
+            !definition.template) {
+            element.setAttribute(deferHydrationAttribute, "");
+            element.setAttribute(needsHydrationAttribute, "");
+        }
+        return super.forCustomElement(element, override);
+    }
     connect() {
         var _a, _b;
         // Initialize needsHydration on first connect
@@ -6024,6 +6118,24 @@ function compose(type, nameOrDef) {
     }
     return FASTElementDefinition.compose(this, type);
 }
+function defineAsync(type, nameOrDef) {
+    if (isFunction(type)) {
+        return new Promise(resolve => {
+            FASTElementDefinition.composeAsync(type, nameOrDef).then(value => {
+                resolve(value);
+            });
+        }).then(value => {
+            return value.define().type;
+        });
+    }
+    return new Promise(resolve => {
+        FASTElementDefinition.composeAsync(this, type).then(value => {
+            resolve(value);
+        });
+    }).then(value => {
+        return value.define().type;
+    });
+}
 function define(type, nameOrDef) {
     if (isFunction(type)) {
         return FASTElementDefinition.compose(type, nameOrDef).define().type;
@@ -6057,6 +6169,11 @@ const FASTElement = Object.assign(createFASTElement(HTMLElement), {
      * @public
      */
     compose,
+    /**
+     * Defines metadata for a FASTElement which can be used after it has been resolved to define the element.
+     * @alpha
+     */
+    defineAsync,
 });
 /**
  * Decorator: Defines a platform custom element based on `FASTElement`.