@microsoft/fast-element 2.4.0 → 2.5.0

package/CHANGELOG.json

@@ -2,7 +2,37 @@
   "name": "@microsoft/fast-element",
   "entries": [
     {
-      "date": "Fri, 23 May 2025 23:51:58 GMT",
+      "date": "Wed, 16 Jul 2025 22:43:21 GMT",
+      "version": "2.5.0",
+      "tag": "@microsoft/fast-element_v2.5.0",
+      "comments": {
+        "minor": [
+          {
+            "author": "7559015+janechu@users.noreply.github.com",
+            "package": "@microsoft/fast-element",
+            "commit": "245c8e45d68513ee5d733340784bdaa2afcaf909",
+            "comment": "Update component lifecycles with async methods to allow for a deferred define step"
+          }
+        ]
+      }
+    },
+    {
+      "date": "Fri, 30 May 2025 05:02:03 GMT",
+      "version": "2.4.1",
+      "tag": "@microsoft/fast-element_v2.4.1",
+      "comments": {
+        "patch": [
+          {
+            "author": "7559015+janechu@users.noreply.github.com",
+            "package": "@microsoft/fast-element",
+            "commit": "a31632f4c15256f2fe89c8f0decaba1fa8b5905b",
+            "comment": "Update logic for enumerated attribute hydration markers, add view hydration as export"
+          }
+        ]
+      }
+    },
+    {
+      "date": "Fri, 23 May 2025 23:52:29 GMT",
       "version": "2.4.0",
       "tag": "@microsoft/fast-element_v2.4.0",
       "comments": {

package/CHANGELOG.md

@@ -1,12 +1,28 @@
 # Change Log - @microsoft/fast-element
 
-<!-- This log was last generated on Fri, 23 May 2025 23:51:58 GMT and should not be manually modified. -->
+<!-- This log was last generated on Wed, 16 Jul 2025 22:43:21 GMT and should not be manually modified. -->
 
 <!-- Start content -->
 
+## 2.5.0
+
+Wed, 16 Jul 2025 22:43:21 GMT
+
+### Minor changes
+
+- Update component lifecycles with async methods to allow for a deferred define step (7559015+janechu@users.noreply.github.com)
+
+## 2.4.1
+
+Fri, 30 May 2025 05:02:03 GMT
+
+### Patches
+
+- Update logic for enumerated attribute hydration markers, add view hydration as export (7559015+janechu@users.noreply.github.com)
+
 ## 2.4.0
 
-Fri, 23 May 2025 23:51:58 GMT
+Fri, 23 May 2025 23:52:29 GMT
 
 ### Minor changes
 

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

@@ -204,6 +204,8 @@ export declare class StyleElementStrategy implements StyleStrategy {
     addStylesTo(target: StyleTarget): void;
     removeStylesFrom(target: StyleTarget): void;
 }
+export declare const deferHydrationAttribute = "defer-hydration";
+export declare const needsHydrationAttribute = "needs-hydration";
 /**
  * An ElementController capable of hydrating FAST elements from
  * Declarative Shadow DOM.
@@ -219,6 +221,7 @@ export declare class HydratableElementController<TElement extends HTMLElement =
     protected needsHydration?: boolean;
     private static hydrationObserver;
     private static hydrationObserverHandler;
+    static forCustomElement(element: HTMLElement, override?: boolean): ElementController<HTMLElement>;
     connect(): void;
     disconnect(): void;
     static install(): void;

package/dist/dts/components/fast-definitions.d.ts

@@ -21,6 +21,11 @@ export interface ShadowRootOptions extends ShadowRootInit {
      */
     registry?: CustomElementRegistry;
 }
+/**
+ * Template options.
+ * @alpha
+ */
+export declare type TemplateOptions = "defer-and-hydrate";
 /**
  * Represents metadata configuration for a custom element.
  * @public
@@ -34,6 +39,11 @@ export interface PartialFASTElementDefinition {
      * The template to render for the custom element.
      */
     readonly template?: ElementViewTemplate;
+    /**
+     * Options controlling how the template will be created.
+     * @alpha
+     */
+    readonly templateOptions?: TemplateOptions;
     /**
      * The styles to associate with the custom element.
      */
@@ -94,6 +104,11 @@ export declare class FASTElementDefinition<TType extends Constructable<HTMLEleme
      * The template to render for the custom element.
      */
     template?: ElementViewTemplate;
+    /**
+     * The template options.
+     * @alpha
+     */
+    templateOptions?: TemplateOptions;
     /**
      * The styles to associate with the custom element.
      */
@@ -110,6 +125,10 @@ export declare class FASTElementDefinition<TType extends Constructable<HTMLEleme
      * The registry to register this component in by default.
      */
     readonly registry: CustomElementRegistry;
+    /**
+     * The definition has been registered to the FAST element registry.
+     */
+    static isRegistered: Record<string, Function>;
     private constructor();
     /**
      * Defines a custom element based on this definition.
@@ -141,4 +160,20 @@ export declare class FASTElementDefinition<TType extends Constructable<HTMLEleme
      * @param instance - The custom element instance to retrieve the definition for.
      */
     static readonly getForInstance: (object: any) => FASTElementDefinition<Constructable<HTMLElement>> | undefined;
+    /**
+     * Indicates when a custom elements definition has been registered with the fastElementRegistry.
+     * @param name - The name of the defined custom element.
+     * @alpha
+     */
+    static registerAsync: (name: string) => Promise<Function>;
+    /**
+     * 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<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition): Promise<FASTElementDefinition<TType>>;
 }

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

@@ -47,6 +47,8 @@ export interface FASTElement extends HTMLElement {
 }
 declare function compose<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(this: TType, nameOrDef: string | PartialFASTElementDefinition): FASTElementDefinition<TType>;
 declare function compose<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition): FASTElementDefinition<TType>;
+declare function defineAsync<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(this: TType, nameOrDef: string | PartialFASTElementDefinition): Promise<FASTElementDefinition<TType>>;
+declare function defineAsync<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition): Promise<FASTElementDefinition<TType>>;
 declare function define<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(this: TType, nameOrDef: string | PartialFASTElementDefinition): TType;
 declare function define<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition): TType;
 declare function from<TBase extends typeof HTMLElement>(BaseType: TBase): new () => InstanceType<TBase> & FASTElement;
@@ -59,6 +61,7 @@ export declare const FASTElement: {
     new (): FASTElement;
     define: typeof define;
     compose: typeof compose;
+    defineAsync: typeof defineAsync;
     from: typeof from;
 };
 /**

package/dist/dts/index.d.ts

@@ -29,6 +29,6 @@ export { ElementView, HTMLView, SyntheticView, View, HydratableView, HydrationBi
 export { elements, ElementsFilter, NodeBehaviorOptions, NodeObservationDirective, } from "./templating/node-observation.js";
 export { render, RenderBehavior, RenderDirective } from "./templating/render.js";
 export { customElement, FASTElement } from "./components/fast-element.js";
-export { FASTElementDefinition, PartialFASTElementDefinition, ShadowRootOptions, fastElementRegistry, TypeRegistry, } from "./components/fast-definitions.js";
+export { FASTElementDefinition, PartialFASTElementDefinition, ShadowRootOptions, fastElementRegistry, TemplateOptions, TypeRegistry, } from "./components/fast-definitions.js";
 export { attr, AttributeConfiguration, AttributeDefinition, AttributeMode, booleanConverter, DecoratorAttributeConfiguration, nullableBooleanConverter, nullableNumberConverter, ValueConverter, } from "./components/attributes.js";
 export { ElementController, ElementControllerStrategy, HydratableElementController, } from "./components/element-controller.js";

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

@@ -582,8 +582,8 @@ if (ElementStyles.supportsAdoptedStyleSheets) {
 else {
     ElementStyles.setDefaultStrategy(StyleElementStrategy);
 }
-const deferHydrationAttribute = "defer-hydration";
-const needsHydrationAttribute = "needs-hydration";
+export const deferHydrationAttribute = "defer-hydration";
+export const needsHydrationAttribute = "needs-hydration";
 /**
  * An ElementController capable of hydrating FAST elements from
  * Declarative Shadow DOM.
@@ -597,6 +597,16 @@ export 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

package/dist/esm/components/fast-definitions.js

@@ -1,3 +1,13 @@
+var __awaiter = (this && this.__awaiter) || function (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());
+    });
+};
+var _a;
 import { isString, KernelServiceId } from "../interfaces.js";
 import { Observable } from "../observation/observable.js";
 import { createTypeRegistry, FAST } from "../platform.js";
@@ -17,7 +27,7 @@ export const fastElementRegistry = FAST.getById(KernelServiceId.elementRegistry,
  */
 export class FASTElementDefinition {
     constructor(type, nameOrConfig = type.definition) {
-        var _a;
+        var _b;
         this.platformDefined = false;
         if (isString(nameOrConfig)) {
             nameOrConfig = { name: nameOrConfig };
@@ -25,7 +35,8 @@ export 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);
@@ -57,6 +68,8 @@ export 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.
@@ -99,7 +112,44 @@ export 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);
+            });
+        });
+    }
 }
+_a = FASTElementDefinition;
+/**
+ * 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.
@@ -110,5 +160,20 @@ 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");

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

@@ -31,6 +31,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;
@@ -64,6 +82,11 @@ export 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`.

package/dist/esm/components/hydration.js

@@ -62,11 +62,20 @@ export const HydrationMarkup = Object.freeze({
      */
     parseEnumeratedAttributeBinding(node) {
         const attrs = [];
-        let count = 0;
-        while (node.hasAttribute(`${this.attributeMarkerName}-${count}`)) {
-            attrs.push(count++);
+        const prefixLength = this.attributeMarkerName.length + 1;
+        const prefix = `${this.attributeMarkerName}-`;
+        for (const attr of node.getAttributeNames()) {
+            if (attr.startsWith(prefix)) {
+                const count = Number(attr.slice(prefixLength));
+                if (!Number.isNaN(count)) {
+                    attrs.push(count);
+                }
+                else {
+                    throw new Error(`Invalid attribute marker name: ${attr}. Expected format is ${prefix}<number>.`);
+                }
+            }
         }
-        return count === 0 ? null : attrs;
+        return attrs.length === 0 ? null : attrs;
     },
     /**
      * Parses the ViewBehaviorFactory index from string data. Returns