@microsoft/fast-element 2.8.1 → 2.8.2

package/dist/fast-element.api.json

@@ -4283,6 +4283,33 @@
             "endIndex": 5
           }
         },
+        {
+          "kind": "Variable",
+          "canonicalReference": "@microsoft/fast-element!deferHydrationAttribute:var",
+          "docComment": "/**\n * The attribute used to defer hydration of an element.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "deferHydrationAttribute = "
+            },
+            {
+              "kind": "Content",
+              "text": "\"defer-hydration\""
+            }
+          ],
+          "fileUrlPath": "dist/dts/components/element-controller.d.ts",
+          "initializerTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          },
+          "isReadonly": true,
+          "releaseTag": "Public",
+          "name": "deferHydrationAttribute",
+          "variableTypeTokenRange": {
+            "startIndex": 0,
+            "endIndex": 0
+          }
+        },
         {
           "kind": "Interface",
           "canonicalReference": "@microsoft/fast-element!Disposable:interface",
@@ -4855,7 +4882,7 @@
             {
               "kind": "Property",
               "canonicalReference": "@microsoft/fast-element!ElementController#behaviors:member",
-              "docComment": "",
+              "docComment": "/**\n * The behaviors associated with the component.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -4899,7 +4926,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@microsoft/fast-element!ElementController#bindObservables:member(1)",
-              "docComment": "",
+              "docComment": "/**\n * Binds any observables that were set before upgrade.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -4961,7 +4988,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@microsoft/fast-element!ElementController#connectBehaviors:member(1)",
-              "docComment": "",
+              "docComment": "/**\n * Connects any existing behaviors on the associated element.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -5085,7 +5112,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@microsoft/fast-element!ElementController#disconnectBehaviors:member(1)",
-              "docComment": "",
+              "docComment": "/**\n * Disconnects any behaviors on the associated element.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -5273,6 +5300,36 @@
               "isAbstract": false,
               "name": "forCustomElement"
             },
+            {
+              "kind": "Property",
+              "canonicalReference": "@microsoft/fast-element!ElementController#hasExistingShadowRoot:member",
+              "docComment": "/**\n * Indicates whether the element has an existing shadow root (e.g. from declarative shadow DOM).\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "protected hasExistingShadowRoot: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "hasExistingShadowRoot",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": true,
+              "isAbstract": false
+            },
             {
               "kind": "Property",
               "canonicalReference": "@microsoft/fast-element!ElementController#isBound:member",
@@ -5380,7 +5437,7 @@
             {
               "kind": "Property",
               "canonicalReference": "@microsoft/fast-element!ElementController#needsInitialization:member",
-              "docComment": "",
+              "docComment": "/**\n * Indicates whether the controller needs to perform initial rendering.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -5678,7 +5735,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@microsoft/fast-element!ElementController#renderTemplate:member(1)",
-              "docComment": "",
+              "docComment": "/**\n * Renders the provided template to the element.\n *\n * @remarks\n *\n * If `null` is provided, any existing view will be removed.\n *\n * @param template - The template to render.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -5780,7 +5837,7 @@
             {
               "kind": "Property",
               "canonicalReference": "@microsoft/fast-element!ElementController#shadowOptions:member",
-              "docComment": "",
+              "docComment": "/**\n * The shadow root options for the component.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -5889,7 +5946,7 @@
             {
               "kind": "Property",
               "canonicalReference": "@microsoft/fast-element!ElementController#stage:member",
-              "docComment": "",
+              "docComment": "/**\n * The current lifecycle stage of the controller.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -5898,7 +5955,7 @@
                 {
                   "kind": "Reference",
                   "text": "Stages",
-                  "canonicalReference": "@microsoft/fast-element!~Stages:enum"
+                  "canonicalReference": "@microsoft/fast-element!Stages:enum"
                 },
                 {
                   "kind": "Content",
@@ -12424,7 +12481,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@microsoft/fast-element!HydratableElementController#connect:member(1)",
-              "docComment": "",
+              "docComment": "/**\n * Runs connected lifecycle behavior on the associated element.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -12455,7 +12512,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@microsoft/fast-element!HydratableElementController#disconnect:member(1)",
-              "docComment": "",
+              "docComment": "/**\n * Unregisters the hydration observer when the element is disconnected.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -12483,89 +12540,10 @@
               "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)",
-              "docComment": "",
+              "docComment": "/**\n * Sets the ElementController strategy to HydratableElementController.\n *\n * @remarks\n *\n * This method is typically called during application startup to enable hydration support for FAST elements.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -12653,6 +12631,50 @@
               "isStatic": false,
               "isProtected": true,
               "isAbstract": false
+            },
+            {
+              "kind": "Property",
+              "canonicalReference": "@microsoft/fast-element!HydratableElementController#shadowOptions:member",
+              "docComment": "/**\n * The shadow root options for the component.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "get shadowOptions(): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ShadowRootOptions",
+                  "canonicalReference": "@microsoft/fast-element!ShadowRootOptions:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": " | undefined"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";\n\nset shadowOptions(value: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ShadowRootOptions",
+                  "canonicalReference": "@microsoft/fast-element!ShadowRootOptions:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": " | undefined);"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "shadowOptions",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 3
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
             }
           ],
           "extendsTokenRange": {
@@ -13627,6 +13649,33 @@
             "endIndex": 3
           }
         },
+        {
+          "kind": "Variable",
+          "canonicalReference": "@microsoft/fast-element!needsHydrationAttribute:var",
+          "docComment": "/**\n * The attribute used to indicate that an element needs hydration.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "needsHydrationAttribute = "
+            },
+            {
+              "kind": "Content",
+              "text": "\"needs-hydration\""
+            }
+          ],
+          "fileUrlPath": "dist/dts/components/element-controller.d.ts",
+          "initializerTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          },
+          "isReadonly": true,
+          "releaseTag": "Public",
+          "name": "needsHydrationAttribute",
+          "variableTypeTokenRange": {
+            "startIndex": 0,
+            "endIndex": 0
+          }
+        },
         {
           "kind": "Interface",
           "canonicalReference": "@microsoft/fast-element!NodeBehaviorOptions:interface",
@@ -19593,6 +19642,107 @@
             "endIndex": 3
           }
         },
+        {
+          "kind": "Enum",
+          "canonicalReference": "@microsoft/fast-element!Stages:enum",
+          "docComment": "/**\n * The various lifecycle stages of an ElementController.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare const enum Stages "
+            }
+          ],
+          "fileUrlPath": "dist/dts/components/element-controller.d.ts",
+          "releaseTag": "Public",
+          "name": "Stages",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "EnumMember",
+              "canonicalReference": "@microsoft/fast-element!Stages.connected:member",
+              "docComment": "/**\n * The element is connected.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "connected = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "1"
+                }
+              ],
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "name": "connected"
+            },
+            {
+              "kind": "EnumMember",
+              "canonicalReference": "@microsoft/fast-element!Stages.connecting:member",
+              "docComment": "/**\n * The element is in the process of connecting.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "connecting = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "0"
+                }
+              ],
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "name": "connecting"
+            },
+            {
+              "kind": "EnumMember",
+              "canonicalReference": "@microsoft/fast-element!Stages.disconnected:member",
+              "docComment": "/**\n * The element is disconnected.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "disconnected = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "3"
+                }
+              ],
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "name": "disconnected"
+            },
+            {
+              "kind": "EnumMember",
+              "canonicalReference": "@microsoft/fast-element!Stages.disconnecting:member",
+              "docComment": "/**\n * The element is in the process of disconnecting.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "disconnecting = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "2"
+                }
+              ],
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "name": "disconnecting"
+            }
+          ]
+        },
         {
           "kind": "Class",
           "canonicalReference": "@microsoft/fast-element!StatelessAttachedAttributeDirective:class",

package/dist/fast-element.debug.js

@@ -5497,10 +5497,25 @@ class ElementController extends PropertyChangeNotifier {
      */
     constructor(element, definition) {
         super(element);
+        /**
+         * A map of observable properties that were set on the element before upgrade.
+         */
         this.boundObservables = null;
+        /**
+         * Indicates whether the controller needs to perform initial rendering.
+         */
         this.needsInitialization = true;
+        /**
+         * Indicates whether the element has an existing shadow root (e.g. from declarative shadow DOM).
+         */
         this.hasExistingShadowRoot = false;
+        /**
+         * The template used to render the component.
+         */
         this._template = null;
+        /**
+         * The current lifecycle stage of the controller.
+         */
         this.stage = 3 /* Stages.disconnected */;
         /**
          * A guard against connecting behaviors multiple times
@@ -5508,12 +5523,19 @@ class ElementController extends PropertyChangeNotifier {
          * another behavior during it's connectedCallback
          */
         this.guardBehaviorConnection = false;
+        /**
+         * The behaviors associated with the component.
+         */
         this.behaviors = null;
         /**
          * Tracks whether behaviors are connected so that
          * behaviors cant be connected multiple times
          */
         this.behaviorsConnected = false;
+        /**
+         * The main set of styles used for the component, independent of any
+         * dynamically added styles.
+         */
         this._mainStyles = null;
         /**
          * This allows Observable.getNotifier(...) to return the Controller
@@ -5609,6 +5631,9 @@ class ElementController extends PropertyChangeNotifier {
             this.renderTemplate(value);
         }
     }
+    /**
+     * The shadow root options for the component.
+     */
     get shadowOptions() {
         return this._shadowRootOptions;
     }
@@ -5783,6 +5808,9 @@ class ElementController extends PropertyChangeNotifier {
         this.stage = 1 /* Stages.connected */;
         Observable.notify(this, isConnectedPropertyName);
     }
+    /**
+     * Binds any observables that were set before upgrade.
+     */
     bindObservables() {
         if (this.boundObservables !== null) {
             const element = this.source;
@@ -5795,6 +5823,9 @@ class ElementController extends PropertyChangeNotifier {
             this.boundObservables = null;
         }
     }
+    /**
+     * Connects any existing behaviors on the associated element.
+     */
     connectBehaviors() {
         if (this.behaviorsConnected === false) {
             const behaviors = this.behaviors;
@@ -5808,6 +5839,9 @@ class ElementController extends PropertyChangeNotifier {
             this.behaviorsConnected = true;
         }
     }
+    /**
+     * Disconnects any behaviors on the associated element.
+     */
     disconnectBehaviors() {
         if (this.behaviorsConnected === true) {
             const behaviors = this.behaviors;
@@ -5860,6 +5894,13 @@ class ElementController extends PropertyChangeNotifier {
         }
         return false;
     }
+    /**
+     * Renders the provided template to the element.
+     *
+     * @param template - The template to render.
+     * @remarks
+     * If `null` is provided, any existing view will be removed.
+     */
     renderTemplate(template) {
         var _a;
         // When getting the host to render to, we start by looking
@@ -6047,7 +6088,15 @@ if (ElementStyles.supportsAdoptedStyleSheets) {
 else {
     ElementStyles.setDefaultStrategy(StyleElementStrategy);
 }
+/**
+ * The attribute used to defer hydration of an element.
+ * @public
+ */
 const deferHydrationAttribute = "defer-hydration";
+/**
+ * The attribute used to indicate that an element needs hydration.
+ * @public
+ */
 const needsHydrationAttribute = "needs-hydration";
 /**
  * An ElementController capable of hydrating FAST elements from
@@ -6056,6 +6105,20 @@ const needsHydrationAttribute = "needs-hydration";
  * @beta
  */
 class HydratableElementController extends ElementController {
+    /**
+     * {@inheritdoc ElementController.shadowOptions}
+     */
+    get shadowOptions() {
+        return super.shadowOptions;
+    }
+    set shadowOptions(value) {
+        super.shadowOptions = value;
+        if (this.hasExistingShadowRoot &&
+            this.definition.templateOptions === TemplateOptions.deferAndHydrate) {
+            this.source.toggleAttribute(deferHydrationAttribute, true);
+            this.source.toggleAttribute(needsHydrationAttribute, true);
+        }
+    }
     /**
      * Adds the current element instance to the hydrating instances map
      */
@@ -6106,20 +6169,14 @@ class HydratableElementController extends ElementController {
             ElementController.setStrategy(ElementController);
         }
     }
-    static forCustomElement(element, override) {
-        const definition = FASTElementDefinition.getForInstance(element);
-        if ((definition === null || definition === void 0 ? void 0 : definition.templateOptions) === TemplateOptions.deferAndHydrate &&
-            !definition.template) {
-            element.toggleAttribute(deferHydrationAttribute, true);
-            element.toggleAttribute(needsHydrationAttribute, true);
-        }
-        return super.forCustomElement(element, override);
-    }
+    /**
+     * Runs connected lifecycle behavior on the associated element.
+     */
     connect() {
         var _a, _b, _c, _d, _e;
         // Initialize needsHydration on first connect
         this.needsHydration =
-            (_a = this.needsHydration) !== null && _a !== void 0 ? _a : this.source.getAttribute(needsHydrationAttribute) !== null;
+            (_a = this.needsHydration) !== null && _a !== void 0 ? _a : this.source.hasAttribute(needsHydrationAttribute);
         if (this.needsHydration) {
             (_c = (_b = HydratableElementController.lifecycleCallbacks) === null || _b === void 0 ? void 0 : _b.elementWillHydrate) === null || _c === void 0 ? void 0 : _c.call(_b, this.definition.name);
         }
@@ -6201,10 +6258,19 @@ class HydratableElementController extends ElementController {
             HydratableElementController.idleCallbackId = requestIdleCallback(HydratableElementController.checkHydrationComplete, { timeout: 50 });
         }
     }
+    /**
+     * Unregisters the hydration observer when the element is disconnected.
+     */
     disconnect() {
         super.disconnect();
         HydratableElementController.hydrationObserver.unobserve(this.source);
     }
+    /**
+     * Sets the ElementController strategy to HydratableElementController.
+     * @remarks
+     * This method is typically called during application startup to enable
+     * hydration support for FAST elements.
+     */
     static install() {
         ElementController.setStrategy(HydratableElementController);
     }
@@ -6327,4 +6393,4 @@ function customElement(nameOrDef) {
 
 DOM.setPolicy(DOMPolicy.create());
 
-export { ArrayObserver, AttributeConfiguration, AttributeDefinition, Binding, CSSBindingDirective, CSSDirective, ChildrenDirective, Compiler, DOM, DOMAspect, ElementController, ElementStyles, ExecutionContext, FAST, FASTElement, FASTElementDefinition, HTMLBindingDirective, HTMLDirective, HTMLView, HydratableElementController, HydrationBindingError, InlineTemplateDirective, Markup, NodeObservationDirective, Observable, Parser, PropertyChangeNotifier, RefDirective, RenderBehavior, RenderDirective, RepeatBehavior, RepeatDirective, SlottedDirective, Sort, SourceLifetime, Splice, SpliceStrategy, SpliceStrategySupport, StatelessAttachedAttributeDirective, SubscriberSet, TemplateOptions, Updates, ViewTemplate, attr, booleanConverter, children, css, cssDirective, customElement, elements, emptyArray, fastElementRegistry, html, htmlDirective, lengthOf, listener, normalizeBinding$1 as normalizeBinding, nullableBooleanConverter, nullableNumberConverter, observable, oneTime, oneWay, ref, render, repeat, slotted, sortedCount, volatile, when };
+export { ArrayObserver, AttributeConfiguration, AttributeDefinition, Binding, CSSBindingDirective, CSSDirective, ChildrenDirective, Compiler, DOM, DOMAspect, ElementController, ElementStyles, ExecutionContext, FAST, FASTElement, FASTElementDefinition, HTMLBindingDirective, HTMLDirective, HTMLView, HydratableElementController, HydrationBindingError, InlineTemplateDirective, Markup, NodeObservationDirective, Observable, Parser, PropertyChangeNotifier, RefDirective, RenderBehavior, RenderDirective, RepeatBehavior, RepeatDirective, SlottedDirective, Sort, SourceLifetime, Splice, SpliceStrategy, SpliceStrategySupport, StatelessAttachedAttributeDirective, SubscriberSet, TemplateOptions, Updates, ViewTemplate, attr, booleanConverter, children, css, cssDirective, customElement, deferHydrationAttribute, elements, emptyArray, fastElementRegistry, html, htmlDirective, lengthOf, listener, needsHydrationAttribute, normalizeBinding$1 as normalizeBinding, nullableBooleanConverter, nullableNumberConverter, observable, oneTime, oneWay, ref, render, repeat, slotted, sortedCount, volatile, when };