@microsoft/fast-element 2.10.4 → 3.0.0-rc.2

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

@@ -1,14 +1,18 @@
 import { type Constructable } from "../interfaces.js";
-import { type TypeRegistry } from "../platform.js";
+import { type TypeDefinition, type TypeRegistry } from "../platform.js";
 import { type ComposableStyles, ElementStyles } from "../styles/element-styles.js";
 import type { ElementViewTemplate } from "../templating/template.js";
-import { AttributeConfiguration, AttributeDefinition } from "./attributes.js";
+import { type AttributeConfiguration, AttributeDefinition } from "./attributes.js";
+import type { Schema } from "./schema.js";
 /**
- * The FAST custom element registry
- * @internal
+ * The FAST custom element registry.
+ * @remarks
+ * This registry stores FAST element definitions by constructor so consumers can
+ * look up the `FASTElementDefinition` associated with an element type or instance.
+ * @public
  */
 export declare const fastElementRegistry: TypeRegistry<FASTElementDefinition>;
-export type { TypeRegistry };
+export type { TypeDefinition, TypeRegistry };
 /**
  * Shadow root initialization options.
  * @public
@@ -21,50 +25,99 @@ export interface ShadowRootOptions extends ShadowRootInit {
      */
     registry?: CustomElementRegistry;
 }
-/**
- * Values for the `templateOptions` property.
- * @alpha
- */
-export declare const TemplateOptions: {
-    readonly deferAndHydrate: "defer-and-hydrate";
-};
-/**
- * Type for the `TemplateOptions` const enum.
- * @alpha
- */
-export type TemplateOptions = (typeof TemplateOptions)[keyof typeof TemplateOptions];
 /**
  * Lifecycle callbacks for template events.
  * @public
  */
 export interface TemplateLifecycleCallbacks {
     /**
-     * Called after the template has been assigned to the definition
+     * Called after the JS class definition has been registered.
+     */
+    elementDidRegister?(name: string): void;
+    /**
+     * Called before the template has been evaluated and assigned.
+     */
+    templateWillUpdate?(name: string): void;
+    /**
+     * Called after the template has been assigned to the definition.
      */
     templateDidUpdate?(name: string): void;
     /**
-     * Called after the custom element has been defined
+     * Called after the custom element has been defined.
      */
     elementDidDefine?(name: string): void;
+    /**
+     * Called before an individual element's hydration begins.
+     */
+    elementWillHydrate?(source: HTMLElement): void;
+    /**
+     * Called after an individual element's hydration has finished.
+     */
+    elementDidHydrate?(source: HTMLElement): void;
 }
+/**
+ * A callback that receives a FASTElementDefinition during element registration.
+ * Extensions are invoked before the element is registered with the platform,
+ * allowing plugins to inspect or act on the resolved definition.
+ * @public
+ */
+export type FASTElementExtension = (definition: FASTElementDefinition) => void;
+/**
+ * Resolves an element template from a composed definition.
+ * @public
+ */
+export type FASTElementTemplateResolver<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>> = (definition: FASTElementDefinition<TType>) => ElementViewTemplate<InstanceType<TType>> | Promise<ElementViewTemplate<InstanceType<TType>>>;
+/**
+ * Applies extension callbacks to a FAST element definition.
+ * @internal
+ */
+export declare function applyFASTElementExtensions(definition: FASTElementDefinition, registry?: CustomElementRegistry, extensions?: FASTElementExtension[]): void;
+/**
+ * Tracks attribute definitions that were added after the element was already
+ * registered with the platform and therefore are not covered by the browser's
+ * static observedAttributes snapshot.
+ * @internal
+ */
+export declare function trackLateAttributeDefinition(definition: FASTElementDefinition, attribute: AttributeDefinition): void;
+/**
+ * Gets the attribute definitions that were added after platform registration.
+ * @internal
+ */
+export declare function getLateAttributeLookup(definition: FASTElementDefinition): Readonly<Record<string, AttributeDefinition>> | null;
+/**
+ * Resolves the concrete template for a FAST element definition when the
+ * definition was composed with a template resolver.
+ * @internal
+ */
+export declare function resolveFASTElementTemplate<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(definition: FASTElementDefinition<TType>): ElementViewTemplate<InstanceType<TType>> | Promise<ElementViewTemplate<InstanceType<TType>> | undefined> | undefined;
+/**
+ * Indicates whether a definition still has a pending template resolver.
+ * @internal
+ */
+export declare function hasFASTElementTemplateResolver<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(definition: FASTElementDefinition<TType>): boolean;
+/**
+ * Gets any pending template resolution error for a FAST element definition.
+ * @internal
+ */
+export declare function getFASTElementTemplateError<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(definition: FASTElementDefinition<TType>): unknown;
+/**
+ * Sets or clears the template resolution error for a FAST element definition.
+ * @internal
+ */
+export declare function setFASTElementTemplateError<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(definition: FASTElementDefinition<TType>, error?: unknown): void;
 /**
  * Represents metadata configuration for a custom element.
  * @public
  */
-export interface PartialFASTElementDefinition {
+export interface PartialFASTElementDefinition<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>> {
     /**
      * The name of the custom element.
      */
     readonly name: string;
     /**
-     * The template to render for the custom element.
+     * The template, or template resolver, for the custom element.
      */
-    readonly template?: ElementViewTemplate;
-    /**
-     * Options controlling how the template will be created.
-     * @alpha
-     */
-    readonly templateOptions?: TemplateOptions;
+    readonly template?: ElementViewTemplate<InstanceType<TType>> | FASTElementTemplateResolver<TType>;
     /**
      * The styles to associate with the custom element.
      */
@@ -94,6 +147,12 @@ export interface PartialFASTElementDefinition {
      * Lifecycle callbacks for template events.
      */
     readonly lifecycleCallbacks?: TemplateLifecycleCallbacks;
+    /**
+     * The optional schema associated with the custom element definition.
+     * Declarative templates assign this automatically during template resolution.
+     * Non-declarative callers can provide one for schema-driven extensions.
+     */
+    readonly schema?: Schema;
 }
 /**
  * Defines metadata for a FASTElement.
@@ -128,12 +187,7 @@ export declare class FASTElementDefinition<TType extends Constructable<HTMLEleme
     /**
      * The template to render for the custom element.
      */
-    template?: ElementViewTemplate;
-    /**
-     * The template options.
-     * @alpha
-     */
-    templateOptions?: TemplateOptions;
+    template?: ElementViewTemplate<InstanceType<TType>>;
     /**
      * The styles to associate with the custom element.
      */
@@ -154,6 +208,12 @@ export declare class FASTElementDefinition<TType extends Constructable<HTMLEleme
      * Lifecycle callbacks for template events.
      */
     readonly lifecycleCallbacks?: TemplateLifecycleCallbacks;
+    /**
+     * The optional schema associated with the custom element definition.
+     * Declarative templates assign this automatically during template resolution.
+     * Non-declarative callers can provide one for schema-driven extensions.
+     */
+    schema?: Schema;
     /**
      * The definition has been registered to the FAST element registry.
      */
@@ -162,17 +222,19 @@ export declare class FASTElementDefinition<TType extends Constructable<HTMLEleme
     /**
      * Defines a custom element based on this definition.
      * @param registry - The element registry to define the element in.
+     * @param extensions - An optional array of extension callbacks to invoke
+     * with this definition before platform registration.
      * @remarks
      * This operation is idempotent per registry.
      */
-    define(registry?: CustomElementRegistry): this;
+    define(registry?: CustomElementRegistry, extensions?: FASTElementExtension[]): this;
     /**
      * Creates an instance of FASTElementDefinition.
      * @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.
      */
-    static compose<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition): FASTElementDefinition<TType>;
+    static compose<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition<TType>): Promise<FASTElementDefinition<TType>>;
     /**
      * Registers a FASTElement base type.
      * @param type - The type to register as a base type.
@@ -194,15 +256,5 @@ export declare class FASTElementDefinition<TType extends Constructable<HTMLEleme
      * @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>>;
+    static register: (name: string, registry?: CustomElementRegistry) => Promise<Function>;
 }

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

@@ -1,6 +1,6 @@
 import { type Constructable } from "../interfaces.js";
 import { ElementController } from "./element-controller.js";
-import { FASTElementDefinition, type PartialFASTElementDefinition } from "./fast-definitions.js";
+import { FASTElementDefinition, type FASTElementExtension, type PartialFASTElementDefinition } from "./fast-definitions.js";
 /**
  * Represents a custom element based on the FASTElement infrastructure.
  * @public
@@ -45,25 +45,53 @@ export interface FASTElement extends HTMLElement {
      */
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
 }
-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;
+/**
+ * The FASTElement constructor and static registration helpers.
+ * @public
+ */
+export interface FASTElementConstructor {
+    /**
+     * Creates a FASTElement instance.
+     */
+    new (): FASTElement;
+    /**
+     * Defines a platform custom element based on the provided type and definition.
+     * @param nameOrDef - The name of the element to define or a definition object.
+     * @param extensions - Optional callbacks to run before registration.
+     */
+    define<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(this: TType, nameOrDef: string | PartialFASTElementDefinition<TType>, extensions?: FASTElementExtension[]): Promise<TType>;
+    /**
+     * Defines a platform custom element based on the provided type and definition.
+     * @param type - The custom element type to define.
+     * @param nameOrDef - The name of the element to define or a definition object.
+     * @param extensions - Optional callbacks to run before registration.
+     */
+    define<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition<TType>, extensions?: FASTElementExtension[]): Promise<TType>;
+    /**
+     * Composes FASTElement metadata without registering the element.
+     * @param nameOrDef - The name of the element to compose or a definition object.
+     */
+    compose<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(this: TType, nameOrDef: string | PartialFASTElementDefinition<TType>): Promise<FASTElementDefinition<TType>>;
+    /**
+     * Composes FASTElement metadata without registering the element.
+     * @param type - The custom element type to compose.
+     * @param nameOrDef - The name of the element to compose or a definition object.
+     */
+    compose<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition<TType>): Promise<FASTElementDefinition<TType>>;
+    /**
+     * Creates a new FASTElement base class inherited from the provided base type.
+     * @param BaseType - The base element type to inherit from.
+     */
+    from<TBase extends typeof HTMLElement>(BaseType: TBase): {
+        new (): InstanceType<TBase> & FASTElement;
+    };
+}
 /**
  * A minimal base class for FASTElements that also provides
  * static helpers for working with FASTElements.
  * @public
  */
-export declare const FASTElement: {
-    new (): FASTElement;
-    define: typeof define;
-    compose: typeof compose;
-    defineAsync: typeof defineAsync;
-    from: typeof from;
-};
+export declare const FASTElement: FASTElementConstructor;
 /**
  * Decorator: Defines a platform custom element based on `FASTElement`.
  * @param nameOrDef - The name of the element to define or a definition object
@@ -71,4 +99,3 @@ export declare const FASTElement: {
  * @public
  */
 export declare function customElement(nameOrDef: string | PartialFASTElementDefinition): (type: Constructable<HTMLElement>) => void;
-export {};

package/dist/dts/components/hydration-tracker.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Describes when FAST should stop hydrating newly connected prerendered elements.
+ * @public
+ */
+export declare const StopHydration: Readonly<{
+    /**
+     * Stop hydrating new prerendered elements after the active hydration batch completes.
+     */
+    readonly hydrationComplete: "hydration-complete";
+    /**
+     * Keep the hydration hook active for later prerendered elements.
+     */
+    readonly never: "never";
+}>;
+/**
+ * Describes when FAST should stop hydrating newly connected prerendered elements.
+ * @public
+ */
+export type StopHydration = (typeof StopHydration)[keyof typeof StopHydration];
+import type { HydrationDebugger } from "../hydration/hydration-debugger.js";
+/**
+ * Options for configuring global hydration lifecycle events and behavior.
+ * @public
+ */
+export interface HydrationOptions {
+    /** Called when a prerendered hydration batch begins. */
+    hydrationStarted?(): void;
+    /** Called after all prerendered elements in a hydration batch complete. */
+    hydrationComplete?(): void;
+    /**
+     * Indicates when the hydration hook should stop handling new
+     * prerendered elements.
+     *
+     * @defaultValue StopHydration.hydrationComplete
+     */
+    stopHydration?: StopHydration;
+    /**
+     * Optional opt-in debugger that swaps the default minimal hydration
+     * mismatch error message for a rich "Expected … / Received …" report
+     * including an HTML snippet of the SSR DOM and structured
+     * `expected`/`received` fields on `HydrationBindingError` /
+     * `HydrationTargetElementError`. Obtained via
+     * `hydrationDebugger()` from `@microsoft/fast-element/hydration.js`.
+     */
+    debugger?: HydrationDebugger;
+}
+/**
+ * Tracks prerendered elements through the hydration lifecycle and
+ * fires global callbacks at start and completion. Per-element callbacks
+ * (`elementWillHydrate`, `elementDidHydrate`) are handled through
+ * definition-level `TemplateLifecycleCallbacks`.
+ *
+ * @public
+ */
+export declare class HydrationTracker {
+    private elements;
+    private started;
+    private completed;
+    private checkTimer;
+    private callbacks;
+    private stopHydration;
+    constructor(options: HydrationOptions);
+    /**
+     * Indicates whether the hydration hook should attempt to hydrate
+     * prerendered elements.
+     */
+    get shouldHydrate(): boolean;
+    /**
+     * Registers an element as pending hydration.
+     * Fires `hydrationStarted` on the first call.
+     */
+    add(element: HTMLElement): void;
+    /**
+     * Removes an element from the pending set and schedules
+     * a debounced completion check.
+     */
+    remove(element: HTMLElement): void;
+    /**
+     * Merges additional options into the tracker, chaining
+     * callbacks so both the original and new callbacks fire.
+     */
+    mergeOptions(incoming: HydrationOptions): void;
+}

package/dist/dts/components/hydration.d.ts

@@ -1,63 +1,38 @@
 import type { ContentTemplate, HydratableContentTemplate } from "../templating/html-binding-directive.js";
 import type { ViewController } from "../templating/html-directive.js";
+import type { HydratableViewController } from "../templating/hydration-view.js";
 import type { ElementViewTemplate, HydratableElementViewTemplate, HydratableSyntheticViewTemplate, SyntheticViewTemplate } from "../templating/template.js";
-import type { HydrationView } from "../templating/view.js";
 /**
  * Markup utilities to aid in template hydration.
  * @internal
  */
 export declare const HydrationMarkup: Readonly<{
-    attributeMarkerName: "data-fe-b";
-    compactAttributeMarkerName: "data-fe-c";
-    attributeBindingSeparator: " ";
-    contentBindingStartMarker(index: number, uniqueId: string): string;
-    contentBindingEndMarker(index: number, uniqueId: string): string;
-    repeatStartMarker(index: number): string;
-    repeatEndMarker(index: number): string;
-    isContentBindingStartMarker(content: string): boolean;
-    isContentBindingEndMarker(content: string): boolean;
-    isRepeatViewStartMarker(content: string): boolean;
-    isRepeatViewEndMarker(content: string): boolean;
+    attributeMarkerName: "data-fe";
+    legacyAttributeMarkerName: "data-fe-b";
+    legacyCompactAttributeMarkerName: "data-fe-c";
+    contentBindingStartMarker(): string;
+    contentBindingEndMarker(): string;
+    repeatStartMarker(): string;
+    repeatEndMarker(): string;
+    elementBoundaryStartMarker(): string;
+    elementBoundaryEndMarker(): string;
+    isContentBindingStartMarker(data: string): boolean;
+    isContentBindingEndMarker(data: string): boolean;
+    isRepeatViewStartMarker(data: string): boolean;
+    isRepeatViewEndMarker(data: string): boolean;
     isElementBoundaryStartMarker(node: Node): boolean;
     isElementBoundaryEndMarker(node: Node): boolean;
     /**
-     * Returns the indexes of the ViewBehaviorFactories affecting
-     * attributes for the element, or null if no factories were found.
+     * Returns the count of attribute bindings on the element, or null
+     * if no attribute binding marker is present.
      *
-     * This method parses the space-separated format: `data-fe-b="0 1 2"`.
+     * Parses the `data-fe="N"` attribute format where N is the count
+     * of attribute binding factories targeting this element.
      */
-    parseAttributeBinding(node: Element): null | number[];
-    /**
-     * Returns the indexes of the ViewBehaviorFactories affecting
-     * attributes for the element, or null if no factories were found.
-     *
-     * This method parses the enumerated format: `data-fe-b-0`, `data-fe-b-1`, `data-fe-b-2`.
-     * This is an alternative format that uses separate attributes for each binding index.
-     */
-    parseEnumeratedAttributeBinding(node: Element): null | number[];
-    /**
-     * Returns the indexes of the ViewBehaviorFactories affecting
-     * attributes for the element, or null if no factories were found.
-     *
-     * This method parses the compact format: `data-fe-c-{index}-{count}`.
-     */
-    parseCompactAttributeBinding(node: Element): null | number[];
-    /**
-     * Parses the ViewBehaviorFactory index from string data. Returns
-     * the binding index or null if the index cannot be retrieved.
-     */
-    parseContentBindingStartMarker(content: string): null | [index: number, id: string];
-    parseContentBindingEndMarker(content: string): null | [index: number, id: string];
-    /**
-     * Parses the index of a repeat directive from a content string.
-     */
-    parseRepeatStartMarker(content: string): null | number;
-    parseRepeatEndMarker(content: string): null | number;
-    /**
-     * Parses element Id from element boundary markers
-     */
-    parseElementBoundaryStartMarker(content: string): null | string;
-    parseElementBoundaryEndMarker(content: string): null | string;
+    parseAttributeBindingCount(node: Element): number | null;
+    parseLegacyAttributeBindingIndices(node: Element): number[] | null;
+    removeLegacyAttributeBindingMarkers(node: Element): void;
+    parseLegacyContentBindingStartIndex(data: string): number | null;
 }>;
 /**
  * @internal
@@ -68,15 +43,10 @@ export declare const Hydratable: unique symbol;
  *
  * @beta
  */
-export declare function isHydratable(view: ViewController): view is HydrationView;
+export declare function isHydratable(view: ViewController): view is HydratableViewController;
 /** @beta */
 export declare function isHydratable<TSource = any, TParent = any>(template: SyntheticViewTemplate<TSource, TParent>): template is HydratableSyntheticViewTemplate<TSource, TParent>;
 /** @beta */
 export declare function isHydratable<TSource = any, TParent = any>(template: ElementViewTemplate<TSource, TParent>): template is HydratableElementViewTemplate<TSource, TParent>;
 /** @beta */
 export declare function isHydratable(template: ContentTemplate): template is HydratableContentTemplate;
-/**
- * The attribute used to defer hydration of an element.
- * @beta
- */
-export declare const deferHydrationAttribute = "defer-hydration";