@microsoft/fast-element 2.8.1 → 2.8.3

package/CHANGELOG.json

@@ -2,7 +2,37 @@
   "name": "@microsoft/fast-element",
   "entries": [
     {
-      "date": "Tue, 21 Oct 2025 16:17:03 GMT",
+      "date": "Wed, 12 Nov 2025 20:41:22 GMT",
+      "version": "2.8.3",
+      "tag": "@microsoft/fast-element_v2.8.3",
+      "comments": {
+        "patch": [
+          {
+            "author": "863023+radium-v@users.noreply.github.com",
+            "package": "@microsoft/fast-element",
+            "commit": "2601b22d4bfabc277ddb259dbe028d695712986b",
+            "comment": "fix: update hydration attribute logic in HydratableElementController tests and implementation"
+          }
+        ]
+      }
+    },
+    {
+      "date": "Fri, 31 Oct 2025 20:45:55 GMT",
+      "version": "2.8.2",
+      "tag": "@microsoft/fast-element_v2.8.2",
+      "comments": {
+        "patch": [
+          {
+            "author": "863023+radium-v@users.noreply.github.com",
+            "package": "@microsoft/fast-element",
+            "commit": "1c008047c3c0b651dbec6dd74ece2da71693cbf3",
+            "comment": "fix: use shadowOptions getter override to set hydration attributes"
+          }
+        ]
+      }
+    },
+    {
+      "date": "Tue, 21 Oct 2025 16:17:27 GMT",
       "version": "2.8.1",
       "tag": "@microsoft/fast-element_v2.8.1",
       "comments": {

package/CHANGELOG.md

@@ -1,12 +1,28 @@
 # Change Log - @microsoft/fast-element
 
-<!-- This log was last generated on Tue, 21 Oct 2025 16:17:03 GMT and should not be manually modified. -->
+<!-- This log was last generated on Wed, 12 Nov 2025 20:41:22 GMT and should not be manually modified. -->
 
 <!-- Start content -->
 
+## 2.8.3
+
+Wed, 12 Nov 2025 20:41:22 GMT
+
+### Patches
+
+- fix: update hydration attribute logic in HydratableElementController tests and implementation (863023+radium-v@users.noreply.github.com)
+
+## 2.8.2
+
+Fri, 31 Oct 2025 20:45:55 GMT
+
+### Patches
+
+- fix: use shadowOptions getter override to set hydration attributes (863023+radium-v@users.noreply.github.com)
+
 ## 2.8.1
 
-Tue, 21 Oct 2025 16:17:03 GMT
+Tue, 21 Oct 2025 16:17:27 GMT
 
 ### Patches
 

package/dist/dts/components/element-controller.d.ts

@@ -13,10 +13,18 @@ import { FASTElementDefinition, ShadowRootOptions } from "./fast-definitions.js"
 export interface ElementControllerStrategy {
     new (element: HTMLElement, definition: FASTElementDefinition): ElementController;
 }
-declare const enum Stages {
+/**
+ * The various lifecycle stages of an ElementController.
+ * @public
+ */
+export declare const enum Stages {
+    /** The element is in the process of connecting. */
     connecting = 0,
+    /** The element is connected. */
     connected = 1,
+    /** The element is in the process of disconnecting. */
     disconnecting = 2,
+    /** The element is disconnected. */
     disconnected = 3
 }
 /**
@@ -24,11 +32,29 @@ declare const enum Stages {
  * @public
  */
 export declare class ElementController<TElement extends HTMLElement = HTMLElement> extends PropertyChangeNotifier implements HostController<TElement> {
+    /**
+     * A map of observable properties that were set on the element before upgrade.
+     */
     private boundObservables;
+    /**
+     * Indicates whether the controller needs to perform initial rendering.
+     */
     protected needsInitialization: boolean;
-    private hasExistingShadowRoot;
+    /**
+     * Indicates whether the element has an existing shadow root (e.g. from declarative shadow DOM).
+     */
+    protected hasExistingShadowRoot: boolean;
+    /**
+     * The template used to render the component.
+     */
     private _template;
+    /**
+     * The shadow root options for the component.
+     */
     private _shadowRootOptions;
+    /**
+     * The current lifecycle stage of the controller.
+     */
     protected stage: Stages;
     /**
      * A guard against connecting behaviors multiple times
@@ -36,12 +62,19 @@ export declare class ElementController<TElement extends HTMLElement = HTMLElemen
      * another behavior during it's connectedCallback
      */
     private guardBehaviorConnection;
+    /**
+     * The behaviors associated with the component.
+     */
     protected behaviors: Map<HostBehavior<TElement>, number> | null;
     /**
      * Tracks whether behaviors are connected so that
      * behaviors cant be connected multiple times
      */
     private behaviorsConnected;
+    /**
+     * The main set of styles used for the component, independent of any
+     * dynamically added styles.
+     */
     private _mainStyles;
     /**
      * This allows Observable.getNotifier(...) to return the Controller
@@ -91,6 +124,9 @@ export declare class ElementController<TElement extends HTMLElement = HTMLElemen
      */
     get template(): ElementViewTemplate<TElement> | null;
     set template(value: ElementViewTemplate<TElement> | null);
+    /**
+     * The shadow root options for the component.
+     */
     get shadowOptions(): ShadowRootOptions | undefined;
     set shadowOptions(value: ShadowRootOptions | undefined);
     /**
@@ -139,8 +175,17 @@ export declare class ElementController<TElement extends HTMLElement = HTMLElemen
      * Runs connected lifecycle behavior on the associated element.
      */
     connect(): void;
+    /**
+     * Binds any observables that were set before upgrade.
+     */
     protected bindObservables(): void;
+    /**
+     * Connects any existing behaviors on the associated element.
+     */
     protected connectBehaviors(): void;
+    /**
+     * Disconnects any behaviors on the associated element.
+     */
     protected disconnectBehaviors(): void;
     /**
      * Runs disconnected lifecycle behavior on the associated element.
@@ -162,6 +207,13 @@ export declare class ElementController<TElement extends HTMLElement = HTMLElemen
      * Only emits events if connected.
      */
     emit(type: string, detail?: any, options?: Omit<CustomEventInit, "detail">): void | boolean;
+    /**
+     * Renders the provided template to the element.
+     *
+     * @param template - The template to render.
+     * @remarks
+     * If `null` is provided, any existing view will be removed.
+     */
     protected renderTemplate(template: ElementViewTemplate | null | undefined): void;
     /**
      * Locates or creates a controller for the specified element.
@@ -204,7 +256,15 @@ export declare class StyleElementStrategy implements StyleStrategy {
     addStylesTo(target: StyleTarget): void;
     removeStylesFrom(target: StyleTarget): void;
 }
+/**
+ * The attribute used to defer hydration of an element.
+ * @public
+ */
 export declare const deferHydrationAttribute = "defer-hydration";
+/**
+ * The attribute used to indicate that an element needs hydration.
+ * @public
+ */
 export declare const needsHydrationAttribute = "needs-hydration";
 /**
  * Lifecycle callbacks for element hydration events
@@ -238,6 +298,11 @@ export declare class HydratableElementController<TElement extends HTMLElement =
      */
     protected needsHydration?: boolean;
     private static hydrationObserver;
+    /**
+     * {@inheritdoc ElementController.shadowOptions}
+     */
+    get shadowOptions(): ShadowRootOptions | undefined;
+    set shadowOptions(value: ShadowRootOptions | undefined);
     /**
      * Lifecycle callbacks for hydration events
      */
@@ -263,7 +328,9 @@ export declare class HydratableElementController<TElement extends HTMLElement =
      * @param deadline - the idle deadline object
      */
     private static checkHydrationComplete;
-    static forCustomElement(element: HTMLElement, override?: boolean): ElementController<HTMLElement>;
+    /**
+     * Runs connected lifecycle behavior on the associated element.
+     */
     connect(): void;
     /**
      * A map of element instances by the name of the custom element they are
@@ -279,7 +346,15 @@ export declare class HydratableElementController<TElement extends HTMLElement =
      * Removes the current element instance from the hydrating instances map
      */
     private removeHydratingInstance;
+    /**
+     * Unregisters the hydration observer when the element is disconnected.
+     */
     disconnect(): void;
+    /**
+     * Sets the ElementController strategy to HydratableElementController.
+     * @remarks
+     * This method is typically called during application startup to enable
+     * hydration support for FAST elements.
+     */
     static install(): void;
 }
-export {};

package/dist/dts/index.d.ts

@@ -31,4 +31,4 @@ export { render, RenderBehavior, RenderDirective } from "./templating/render.js"
 export { customElement, FASTElement } from "./components/fast-element.js";
 export { FASTElementDefinition, PartialFASTElementDefinition, ShadowRootOptions, fastElementRegistry, TemplateOptions, TypeRegistry, type TemplateLifecycleCallbacks, } from "./components/fast-definitions.js";
 export { attr, AttributeConfiguration, AttributeDefinition, AttributeMode, booleanConverter, DecoratorAttributeConfiguration, nullableBooleanConverter, nullableNumberConverter, ValueConverter, } from "./components/attributes.js";
-export { ElementController, ElementControllerStrategy, HydratableElementController, type HydrationControllerCallbacks, } from "./components/element-controller.js";
+export { deferHydrationAttribute, ElementController, ElementControllerStrategy, HydratableElementController, type HydrationControllerCallbacks, needsHydrationAttribute, Stages, } from "./components/element-controller.js";

package/dist/esm/components/element-controller.js

@@ -32,10 +32,25 @@ export 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
@@ -43,12 +58,19 @@ export 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
@@ -144,6 +166,9 @@ export class ElementController extends PropertyChangeNotifier {
             this.renderTemplate(value);
         }
     }
+    /**
+     * The shadow root options for the component.
+     */
     get shadowOptions() {
         return this._shadowRootOptions;
     }
@@ -318,6 +343,9 @@ export 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;
@@ -330,6 +358,9 @@ export class ElementController extends PropertyChangeNotifier {
             this.boundObservables = null;
         }
     }
+    /**
+     * Connects any existing behaviors on the associated element.
+     */
     connectBehaviors() {
         if (this.behaviorsConnected === false) {
             const behaviors = this.behaviors;
@@ -343,6 +374,9 @@ export class ElementController extends PropertyChangeNotifier {
             this.behaviorsConnected = true;
         }
     }
+    /**
+     * Disconnects any behaviors on the associated element.
+     */
     disconnectBehaviors() {
         if (this.behaviorsConnected === true) {
             const behaviors = this.behaviors;
@@ -395,6 +429,13 @@ export 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
@@ -582,7 +623,15 @@ if (ElementStyles.supportsAdoptedStyleSheets) {
 else {
     ElementStyles.setDefaultStrategy(StyleElementStrategy);
 }
+/**
+ * The attribute used to defer hydration of an element.
+ * @public
+ */
 export const deferHydrationAttribute = "defer-hydration";
+/**
+ * The attribute used to indicate that an element needs hydration.
+ * @public
+ */
 export const needsHydrationAttribute = "needs-hydration";
 /**
  * An ElementController capable of hydrating FAST elements from
@@ -591,6 +640,20 @@ export const needsHydrationAttribute = "needs-hydration";
  * @beta
  */
 export class HydratableElementController extends ElementController {
+    /**
+     * {@inheritdoc ElementController.shadowOptions}
+     */
+    get shadowOptions() {
+        return super.shadowOptions;
+    }
+    set shadowOptions(value) {
+        super.shadowOptions = value;
+        if ((this.hasExistingShadowRoot || (value !== void 0 && !this.template)) &&
+            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
      */
@@ -641,20 +704,14 @@ export 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);
         }
@@ -736,10 +793,19 @@ export 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);
     }

package/dist/esm/index.js

@@ -36,4 +36,4 @@ export { render, RenderBehavior, RenderDirective } from "./templating/render.js"
 export { customElement, FASTElement } from "./components/fast-element.js";
 export { FASTElementDefinition, fastElementRegistry, TemplateOptions, } from "./components/fast-definitions.js";
 export { attr, AttributeConfiguration, AttributeDefinition, booleanConverter, nullableBooleanConverter, nullableNumberConverter, } from "./components/attributes.js";
-export { ElementController, HydratableElementController, } from "./components/element-controller.js";
+export { deferHydrationAttribute, ElementController, HydratableElementController, needsHydrationAttribute, } from "./components/element-controller.js";