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

package/dist/di/di.api.json

@@ -1530,7 +1530,7 @@
             },
             {
               "kind": "Content",
-              "text": "<T>;\n    singleton<T_1 extends "
+              "text": "<T>;\n    singleton<T extends "
             },
             {
               "kind": "Reference",
@@ -1539,7 +1539,7 @@
             },
             {
               "kind": "Content",
-              "text": ">(target: T_1 & "
+              "text": ">(target: T & "
             },
             {
               "kind": "Reference",
@@ -1557,7 +1557,7 @@
             },
             {
               "kind": "Content",
-              "text": "<T_1>>, options?: "
+              "text": "<T>>, options?: "
             },
             {
               "kind": "Reference",
@@ -1566,7 +1566,7 @@
             },
             {
               "kind": "Content",
-              "text": "): T_1 & "
+              "text": "): T & "
             },
             {
               "kind": "Reference",
@@ -1575,7 +1575,7 @@
             },
             {
               "kind": "Content",
-              "text": "<T_1>;\n}>"
+              "text": "<T>;\n}>"
             }
           ],
           "fileUrlPath": "dist/dts/di/di.d.ts",
@@ -2223,7 +2223,7 @@
             {
               "kind": "PropertySignature",
               "canonicalReference": "@microsoft/fast-element!InterfaceConfiguration#respectConnection:member",
-              "docComment": "/**\n * When true, the dependency will be re-resolved when FASTElement connection changes. If the resolved value changes due to connection change, a {@link @microsoft/fast-element#Observable | notification} will be emitted for the property, with the previous and next values provided to any subscriber.\n */\n",
+              "docComment": "/**\n * When true, the dependency will be re-resolved when FASTElement connection changes. If the resolved value changes due to connection change, an observable notification will be emitted for the property, with the previous and next values provided to any subscriber.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -2702,7 +2702,7 @@
             },
             {
               "kind": "Content",
-              "text": "<T>;\n    singleton<T_1 extends "
+              "text": "<T>;\n    singleton<T extends "
             },
             {
               "kind": "Reference",
@@ -2720,7 +2720,7 @@
             },
             {
               "kind": "Content",
-              "text": ", value: T_1): "
+              "text": ", value: T): "
             },
             {
               "kind": "Reference",
@@ -2738,7 +2738,7 @@
             },
             {
               "kind": "Content",
-              "text": "<T_1>>;\n    transient<T_2 extends "
+              "text": "<T>>;\n    transient<T extends "
             },
             {
               "kind": "Reference",
@@ -2756,7 +2756,7 @@
             },
             {
               "kind": "Content",
-              "text": ", value: T_2): "
+              "text": ", value: T): "
             },
             {
               "kind": "Reference",
@@ -2774,7 +2774,7 @@
             },
             {
               "kind": "Content",
-              "text": "<T_2>>;\n    callback<T_3>(key: "
+              "text": "<T>>;\n    callback<T>(key: "
             },
             {
               "kind": "Reference",
@@ -2792,7 +2792,7 @@
             },
             {
               "kind": "Content",
-              "text": "<T_3>): "
+              "text": "<T>): "
             },
             {
               "kind": "Reference",
@@ -2810,7 +2810,7 @@
             },
             {
               "kind": "Content",
-              "text": "<T_3>>;\n    cachedCallback<T_4>(key: "
+              "text": "<T>>;\n    cachedCallback<T>(key: "
             },
             {
               "kind": "Reference",
@@ -2828,7 +2828,7 @@
             },
             {
               "kind": "Content",
-              "text": "<T_4>): "
+              "text": "<T>): "
             },
             {
               "kind": "Reference",
@@ -2846,7 +2846,7 @@
             },
             {
               "kind": "Content",
-              "text": "<T_4>>;\n    aliasTo<T_5>(originalKey: T_5, aliasKey: "
+              "text": "<T>>;\n    aliasTo<T>(originalKey: T, aliasKey: "
             },
             {
               "kind": "Reference",
@@ -2873,7 +2873,7 @@
             },
             {
               "kind": "Content",
-              "text": "<T_5>>;\n}>"
+              "text": "<T>>;\n}>"
             }
           ],
           "fileUrlPath": "dist/dts/di/di.d.ts",

package/dist/dts/__test__/helpers.d.ts

@@ -0,0 +1,6 @@
+export declare function toHTML(node: Node, preserveCommentMarkup?: boolean): string;
+export declare function createTrackableDOMPolicy(): {
+    used: boolean;
+    createHTML: (html: string) => string;
+    protect(tagName: any, aspect: any, aspectName: any, sink: any): (node: any, aspectName: any, value: any, ...args: any[]) => void;
+};

package/dist/dts/array-observer.d.ts

@@ -0,0 +1,2 @@
+export { ArrayObserver, type LengthObserver, Sort, type SortObserver, Splice, SpliceStrategy, SpliceStrategySupport, } from "./observation/arrays.js";
+export type { Notifier, Subscriber, SubscriberSet } from "./observation/notifier.js";

package/dist/dts/arrays.d.ts

@@ -0,0 +1,2 @@
+export { type ArrayObserver, type LengthObserver, lengthOf, Sort, type SortObserver, Splice, SpliceStrategy, SpliceStrategySupport, sortedCount, } from "./observation/arrays.js";
+export type { Notifier, Subscriber, SubscriberSet } from "./observation/notifier.js";

package/dist/dts/attr.d.ts

@@ -0,0 +1 @@
+export { AttributeConfiguration, AttributeDefinition, type AttributeMode, attr, booleanConverter, type DecoratorAttributeConfiguration, nullableBooleanConverter, nullableNumberConverter, type ValueConverter, } from "./components/attributes.js";

package/dist/dts/binding/binding.d.ts

@@ -1,4 +1,5 @@
-import type { DOMAspect, DOMPolicy } from "../dom.js";
+import type { DOMAspect } from "../dom.js";
+import type { DOMPolicy } from "../dom-policy.js";
 import type { Subscriber } from "../observation/notifier.js";
 import type { Expression, ExpressionObserver } from "../observation/observable.js";
 /**
@@ -26,20 +27,29 @@ export interface BindingDirective {
  * @public
  */
 export declare abstract class Binding<TSource = any, TReturn = any, TParent = any> {
-    evaluate: Expression<TSource, TReturn, TParent>;
-    policy?: DOMPolicy | undefined;
-    isVolatile: boolean;
     /**
      * Options associated with the binding.
      */
     options?: any;
+    /**
+     * Evaluates the binding.
+     */
+    evaluate: Expression<TSource, TReturn, TParent>;
+    /**
+     * The security policy to associate with this binding.
+     */
+    policy?: DOMPolicy;
+    /**
+     * Indicates whether the binding is volatile.
+     */
+    isVolatile: boolean;
     /**
      * Creates a binding.
      * @param evaluate - Evaluates the binding.
      * @param policy - The security policy to associate with this binding.
      * @param isVolatile - Indicates whether the binding is volatile.
      */
-    constructor(evaluate: Expression<TSource, TReturn, TParent>, policy?: DOMPolicy | undefined, isVolatile?: boolean);
+    constructor(evaluate: Expression<TSource, TReturn, TParent>, policy?: DOMPolicy, isVolatile?: boolean);
     /**
      * Creates an observer capable of notifying a subscriber when the output of a binding changes.
      * @param subscriber - The subscriber to changes in the binding.

package/dist/dts/binding/one-time.d.ts

@@ -1,4 +1,4 @@
-import type { DOMPolicy } from "../dom.js";
+import type { DOMPolicy } from "../dom-policy.js";
 import type { Expression } from "../observation/observable.js";
 import { Binding } from "./binding.js";
 /**

package/dist/dts/binding/one-way.d.ts

@@ -1,4 +1,4 @@
-import type { DOMPolicy } from "../dom.js";
+import type { DOMPolicy } from "../dom-policy.js";
 import { type Expression } from "../observation/observable.js";
 import { Binding } from "./binding.js";
 /**

package/dist/dts/binding/signal.d.ts

@@ -1,6 +1,6 @@
-import type { Expression } from "../observation/observable.js";
+import type { DOMPolicy } from "../dom-policy.js";
 import type { Subscriber } from "../observation/notifier.js";
-import type { DOMPolicy } from "../dom.js";
+import type { Expression } from "../observation/observable.js";
 import { Binding } from "./binding.js";
 /**
  * The gateway to signal APIs.
@@ -9,14 +9,14 @@ import { Binding } from "./binding.js";
 export declare const Signal: Readonly<{
     /**
      * Subscribes to a signal.
-     * @param signal The signal to subscribe to.
-     * @param subscriber The subscriber.
+     * @param signal - The signal to subscribe to.
+     * @param subscriber - The subscriber.
      */
     subscribe(signal: string, subscriber: Subscriber): void;
     /**
      * Unsubscribes from the signal.
-     * @param signal The signal to unsubscribe from.
-     * @param subscriber The subscriber.
+     * @param signal - The signal to unsubscribe from.
+     * @param subscriber - The subscriber.
      */
     unsubscribe(signal: string, subscriber: Subscriber): void;
     /**

package/dist/dts/binding/two-way.d.ts

@@ -1,4 +1,4 @@
-import type { DOMPolicy } from "../dom.js";
+import type { DOMPolicy } from "../dom-policy.js";
 import { type Expression } from "../observation/observable.js";
 import { Binding, type BindingDirective } from "./binding.js";
 /**
@@ -23,6 +23,7 @@ export interface TwoWaySettings {
 }
 /**
  * Enables configuring two-way binding settings.
+ * @public
  */
 export declare const TwoWaySettings: Readonly<{
     /**

package/dist/dts/binding.d.ts

@@ -0,0 +1,7 @@
+export { Binding, type BindingDirective } from "./binding/binding.js";
+export { normalizeBinding } from "./binding/normalize.js";
+export { oneTime } from "./binding/one-time.js";
+export { listener, oneWay } from "./binding/one-way.js";
+export type { DOMAspect, DOMPolicy } from "./dom.js";
+export type { Subscriber } from "./observation/notifier.js";
+export type { Expression, ExpressionObserver } from "./observation/observable.js";

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

@@ -16,8 +16,6 @@ export interface ValueConverter {
      */
     fromView(value: any): any;
 }
-declare const booleanMode = "boolean";
-declare const reflectMode = "reflect";
 /**
  * The mode that specifies the runtime behavior of the attribute.
  * @remarks
@@ -29,7 +27,7 @@ declare const reflectMode = "reflect";
  * changes in the DOM, but does not reflect property changes back.
  * @public
  */
-export type AttributeMode = typeof reflectMode | typeof booleanMode | "fromView";
+export type AttributeMode = "reflect" | "boolean" | "fromView";
 /**
  * Metadata used to configure a custom attribute's behavior.
  * @public
@@ -153,4 +151,3 @@ export declare function attr(config?: DecoratorAttributeConfiguration): (target:
  * @public
  */
 export declare function attr(target: {}, prop: string): void;
-export {};

package/dist/dts/components/definition-schema-transforms.d.ts

@@ -0,0 +1,9 @@
+import type { FASTElementDefinition } from "../components/fast-definitions.js";
+import type { Schema } from "./schema.js";
+export interface DeclarativeSchemaTransformContext {
+    definition: FASTElementDefinition;
+    schema: Schema;
+}
+export type DeclarativeSchemaTransform = (context: DeclarativeSchemaTransformContext) => void;
+export declare function setDefinitionSchemaTransform(definition: FASTElementDefinition, key: string, transform: DeclarativeSchemaTransform, priority: number): void;
+export declare function getDefinitionSchemaTransforms(definition?: FASTElementDefinition): readonly DeclarativeSchemaTransform[];

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

@@ -1,4 +1,4 @@
-import { PropertyChangeNotifier } from "../observation/notifier.js";
+import type { Notifier, Subscriber } from "../observation/notifier.js";
 import { ExecutionContext, type ExpressionController, SourceLifetime } from "../observation/observable.js";
 import { ElementStyles } from "../styles/element-styles.js";
 import type { HostBehavior, HostController } from "../styles/host.js";
@@ -6,10 +6,6 @@ import type { StyleStrategy, StyleTarget } from "../styles/style-strategy.js";
 import type { ElementViewTemplate } from "../templating/template.js";
 import type { ElementView } from "../templating/view.js";
 import { FASTElementDefinition, type ShadowRootOptions } from "./fast-definitions.js";
-/**
- * @deprecated Use the export from ./hydration.js instead.
- */
-export { deferHydrationAttribute } from "./hydration.js";
 /**
  * A type that instantiates an ElementController
  * @public
@@ -35,7 +31,11 @@ export declare const enum Stages {
  * Controls the lifecycle and rendering of a `FASTElement`.
  * @public
  */
-export declare class ElementController<TElement extends HTMLElement = HTMLElement> extends PropertyChangeNotifier implements HostController<TElement> {
+export declare class ElementController<TElement extends HTMLElement = HTMLElement> implements Notifier, HostController<TElement> {
+    /**
+     * Internal notifier used to delegate subscriber management.
+     */
+    private _notifier;
     /**
      * A map of observable properties that were set on the element before upgrade.
      */
@@ -48,6 +48,26 @@ export declare class ElementController<TElement extends HTMLElement = HTMLElemen
      * Indicates whether the element has an existing shadow root (e.g. from declarative shadow DOM).
      */
     protected hasExistingShadowRoot: boolean;
+    /**
+     * Resolves the isPrerendered promise.
+     */
+    private _resolvePrerendered;
+    /**
+     * Resolves the isHydrated promise.
+     */
+    private _resolveHydrated;
+    /**
+     * Resolves `true` when the element had an existing shadow root
+     * (from SSR or declarative shadow DOM) at connect time, `false`
+     * otherwise.
+     */
+    readonly isPrerendered: Promise<boolean>;
+    /**
+     * Resolves `true` after prerendered content has been successfully
+     * hydrated, or `false` when the component is client-side rendered
+     * or hydration is not enabled.
+     */
+    readonly isHydrated: Promise<boolean>;
     /**
      * The template used to render the component.
      */
@@ -147,6 +167,27 @@ export declare class ElementController<TElement extends HTMLElement = HTMLElemen
      * @internal
      */
     constructor(element: TElement, definition: FASTElementDefinition);
+    /**
+     * The subject that subscribers will receive notifications for.
+     */
+    get subject(): TElement;
+    /**
+     * Notifies all subscribers of a property change.
+     * @param args - The property name that changed.
+     */
+    notify(args: any): void;
+    /**
+     * Subscribes to notification of changes in the element's state.
+     * @param subscriber - The object that is subscribing for change notification.
+     * @param propertyToWatch - The name of the property to watch for changes.
+     */
+    subscribe(subscriber: Subscriber, propertyToWatch?: any): void;
+    /**
+     * Unsubscribes from notification of changes in the element's state.
+     * @param subscriber - The object that is unsubscribing from change notification.
+     * @param propertyToUnwatch - The name of the property to unsubscribe from.
+     */
+    unsubscribe(subscriber: Subscriber, propertyToUnwatch?: any): void;
     /**
      * Registers an unbind handler with the controller.
      * @param behavior - An object to call when the controller unbinds.
@@ -183,6 +224,22 @@ export declare class ElementController<TElement extends HTMLElement = HTMLElemen
      * Binds any observables that were set before upgrade.
      */
     protected bindObservables(): void;
+    /**
+     * Captures own-properties that shadow observable accessors on the prototype so
+     * they can be rebound through the accessor before rendering.
+     */
+    protected captureBoundObservables(): void;
+    /**
+     * Synchronizes late-defined attribute-map attributes from the live DOM to the
+     * associated property values before the initial render occurs.
+     */
+    protected syncLateAttributes(): void;
+    /**
+     * Observes late-defined attribute-map attributes that the platform does not
+     * surface through attributeChangedCallback because they were added after
+     * customElements.define() completed.
+     */
+    protected observeLateAttributes(): void;
     /**
      * Connects any existing behaviors on the associated element.
      */
@@ -219,6 +276,11 @@ export declare class ElementController<TElement extends HTMLElement = HTMLElemen
      * If `null` is provided, any existing view will be removed.
      */
     protected renderTemplate(template: ElementViewTemplate | null | undefined): void;
+    /**
+     * Standard client-side render: clears any stale content, clones the
+     * compiled fragment, binds, and appends to the host.
+     */
+    private renderClientSide;
     /**
      * Locates or creates a controller for the specified element.
      * @param element - The element to return the controller for.
@@ -235,6 +297,18 @@ export declare class ElementController<TElement extends HTMLElement = HTMLElemen
      * @param strategy - The strategy to use.
      */
     static setStrategy(strategy: ElementControllerStrategy): void;
+    /**
+     * A hook that, when set, handles prerendered content hydration.
+     * Called by renderTemplate when an existing shadow root is detected.
+     * Returns true if hydration was performed, false to fall back to client-side.
+     * @internal
+     */
+    private static hydrationHook;
+    /**
+     * Installs the hydration hook. Called by enableHydration().
+     * @internal
+     */
+    static installHydrationHook(hook: (controller: ElementController, template: ElementViewTemplate, element: HTMLElement, host: Node) => boolean): void;
 }
 /**
  * https://wicg.github.io/construct-stylesheets/
@@ -260,111 +334,3 @@ export declare class StyleElementStrategy implements StyleStrategy {
     addStylesTo(target: StyleTarget): void;
     removeStylesFrom(target: StyleTarget): void;
 }
-/**
- * The attribute used to indicate that an element needs hydration.
- * @public
- */
-export declare const needsHydrationAttribute = "needs-hydration";
-/**
- * Lifecycle callbacks for element hydration events
- * @public
- */
-export interface HydrationControllerCallbacks<TElement extends HTMLElement = HTMLElement> {
-    /**
-     * Called once when the first element enters the hydration pipeline.
-     * This is the earliest point at which we know a component has been
-     * async-defined with `defer-and-hydrate`, a template is pending via
-     * `<f-template>`, and the element has `needs-hydration`.
-     */
-    hydrationStarted?(): void;
-    /**
-     * Called before an individual element's hydration begins
-     */
-    elementWillHydrate?(source: TElement): void;
-    /**
-     * Called after an individual element's hydration has finished
-     */
-    elementDidHydrate?(source: TElement): void;
-    /**
-     * Called after all elements have completed hydration
-     */
-    hydrationComplete?(): void;
-}
-/**
- * An ElementController capable of hydrating FAST elements from
- * Declarative Shadow DOM.
- *
- * @beta
- */
-export declare class HydratableElementController<TElement extends HTMLElement = HTMLElement> extends ElementController<TElement> {
-    /**
-     * Controls whether the controller will hydrate during the connect() method.
-     * Initialized during the first connect() call to true when the `needs-hydration`
-     * attribute is present on the element.
-     */
-    protected needsHydration?: boolean;
-    private static hydrationObserver;
-    /**
-     * {@inheritdoc ElementController.shadowOptions}
-     */
-    get shadowOptions(): ShadowRootOptions | undefined;
-    set shadowOptions(value: ShadowRootOptions | undefined);
-    /**
-     * Lifecycle callbacks for hydration events
-     */
-    static lifecycleCallbacks: HydrationControllerCallbacks;
-    /**
-     * Whether the hydrationStarted callback has already been invoked.
-     */
-    private static hydrationStarted;
-    /**
-     * An idle callback ID used to track hydration completion
-     */
-    private static idleCallbackId;
-    /**
-     * Adds the current element instance to the hydrating instances map
-     */
-    private addHydratingInstance;
-    /**
-     * Configure lifecycle callbacks for hydration events
-     */
-    static config(callbacks: HydrationControllerCallbacks): typeof HydratableElementController;
-    private static hydrationObserverHandler;
-    /**
-     * Checks to see if hydration is complete and if so, invokes the hydrationComplete callback.
-     * Then resets the ElementController strategy to the default so that future elements
-     * don't use the HydratableElementController.
-     *
-     * @param deadline - the idle deadline object
-     */
-    private static checkHydrationComplete;
-    /**
-     * Runs connected lifecycle behavior on the associated element.
-     */
-    connect(): void;
-    /**
-     * A map of element instances by the name of the custom element they are
-     * associated with. The key is the custom element name, and the value is the
-     * instances of hydratable elements which currently need to be hydrated.
-     *
-     * When all of the instances in the set have been hydrated, the set is
-     * cleared and removed from the map. If the map is empty, the
-     * hydrationComplete callback is invoked.
-     */
-    private static hydratingInstances?;
-    /**
-     * 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;
-}

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

@@ -1,2 +1,2 @@
-export { HydratableElementController } from "./element-controller.js";
+export { ElementController } from "./element-controller.js";
 export * from "./hydration.js";

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

@@ -0,0 +1,54 @@
+import { type HydrationOptions } from "./hydration-tracker.js";
+export { StopHydration } from "./hydration-tracker.js";
+export type { HydrationOptions };
+/**
+ * Enables hydration support for prerendered FAST elements.
+ *
+ * @remarks
+ * Call this before any FAST elements connect to the DOM. Hydration
+ * logic is not active unless this function is called, keeping
+ * `FASTElement` lightweight for client-side-only applications.
+ *
+ * Safe to call multiple times — the hydration hook is installed once
+ * and subsequent calls merge their options into the shared tracker.
+ * By default, the hook stops hydrating new prerendered elements after
+ * the global `hydrationComplete` callback. Set
+ * `stopHydration` to `StopHydration.never` for streaming scenarios
+ * that append hydratable Declarative Shadow DOM after the initial batch.
+ *
+ * Pass `debugger: hydrationDebugger()` to swap the default minimal
+ * hydration mismatch error message for a rich "Expected / Received"
+ * report including the SSR HTML snippet and structured
+ * `expected`/`received` fields on `HydrationBindingError` /
+ * `HydrationTargetElementError`. The debugger module is tree-shaken
+ * out of production hydration bundles unless explicitly imported.
+ *
+ * @example
+ * ```ts
+ * import { enableHydration, StopHydration } from "@microsoft/fast-element/hydration.js";
+ *
+ * enableHydration({
+ *     stopHydration: StopHydration.never,
+ *     hydrationComplete() {
+ *         console.log("hydration complete");
+ *     },
+ * });
+ * ```
+ *
+ * @example Rich hydration mismatch diagnostics
+ * ```ts
+ * import { enableHydration, hydrationDebugger } from "@microsoft/fast-element/hydration.js";
+ *
+ * enableHydration({ debugger: hydrationDebugger() });
+ * ```
+ *
+ * @param options - Optional global hydration callbacks and behavior.
+ * @public
+ */
+export declare function enableHydration(options?: HydrationOptions): void;
+/**
+ * The attribute used to defer hydration of an element.
+ * Retained for intersection observer viewport hydration rendering.
+ * @beta
+ */
+export declare const deferHydrationAttribute = "defer-hydration";