@microsoft/fast-element 2.10.3 → 3.0.0-rc.1

package/dist/dts/declarative/template-bridge.d.ts

@@ -0,0 +1,33 @@
+import type { FASTElementDefinition } from "../components/fast-definitions.js";
+import type { ElementViewTemplate } from "../templating/template.js";
+/**
+ * Publishes a concrete template for a definition.
+ * @internal
+ */
+export interface TemplatePublisher {
+    publishTemplate(definition: FASTElementDefinition): ElementViewTemplate | Promise<ElementViewTemplate>;
+}
+/**
+ * Coordinates declarative template publishers and FAST element definitions.
+ * Requests are keyed by registry + element name so scoped registries can
+ * resolve templates independently.
+ * @internal
+ */
+export declare class DeclarativeTemplateBridge {
+    private readonly buckets;
+    requestTemplate(definition: FASTElementDefinition): Promise<ElementViewTemplate>;
+    registerPublisher(registry: CustomElementRegistry, name: string | undefined, publisher: TemplatePublisher): void;
+    unregisterPublisher(registry: CustomElementRegistry, name: string | undefined, publisher: TemplatePublisher): void;
+    movePublisher(registry: CustomElementRegistry, previousName: string | undefined, nextName: string | undefined, publisher: TemplatePublisher): void;
+    private getBucket;
+    private processBucket;
+    private resetPublisherRequests;
+    private resolveRequest;
+    private rejectRequest;
+    private cleanupBucket;
+}
+/**
+ * Shared template bridge storage for the current FAST runtime.
+ * @internal
+ */
+export declare const declarativeTemplateBridge: DeclarativeTemplateBridge;

package/dist/dts/declarative/template-parser.d.ts

@@ -0,0 +1,98 @@
+import type { Schema } from "../components/schema.js";
+import { ViewTemplate } from "../templating/template.js";
+/**
+ * The return type for {@link TemplateParser.parse}.
+ * @public
+ */
+export interface ResolvedStringsAndValues {
+    strings: Array<string>;
+    values: Array<any>;
+}
+/**
+ * Converts declarative HTML template markup into the `strings` and `values`
+ * arrays that `ViewTemplate.create()` consumes.
+ *
+ * This class is intentionally stateless across invocations — all mutable
+ * parsing state lives on the call stack or in the `TemplateResolutionContext`.
+ *
+ * The parsing pipeline is fully synchronous — no promises are allocated
+ * during template resolution.
+ * @public
+ */
+export declare class TemplateParser {
+    /**
+     * Parse declarative HTML into strings and values for ViewTemplate creation.
+     * @param innerHTML - The transformed innerHTML to parse.
+     * @param schema - The Schema instance for property tracking.
+     * @returns The resolved strings and values.
+     */
+    parse(innerHTML: string, schema: Schema): ResolvedStringsAndValues;
+    /**
+     * Create a ViewTemplate from resolved strings and values.
+     * @param strings - The strings array.
+     * @param values - The interpreted values.
+     */
+    createTemplate(strings: Array<string>, values: Array<any>): ViewTemplate<any, any>;
+    /**
+     * Resolve strings and values from an innerHTML string.
+     * @param rootPropertyName - The root property name for schema registration.
+     * @param innerHTML - The innerHTML.
+     * @param context - The template resolution context.
+     */
+    private resolveStringsAndValues;
+    /**
+     * Resolve a template directive (when/repeat).
+     * @param rootPropertyName - The root property name for schema registration.
+     * @param behaviorConfig - The directive behavior configuration object.
+     * @param externalValues - The interpreted values from the parent.
+     * @param innerHTML - The innerHTML.
+     * @param context - The template resolution context.
+     */
+    private resolveTemplateDirective;
+    /**
+     * Resolve an attribute directive (children/slotted/ref).
+     * @param name - The name of the directive.
+     * @param propName - The property name to pass to the directive.
+     * @param externalValues - The interpreted values from the parent.
+     */
+    private resolveAttributeDirective;
+    /**
+     * Resolve an access binding — shared by content bindings, boolean-attribute
+     * fallback, and default attribute bindings.
+     * @returns An object with the resolved binding function and the updated rootPropertyName.
+     */
+    private resolveAccessBinding;
+    /**
+     * Resolve an event binding (the "\@" aspect).
+     * @returns An object with the event binding function and the updated rootPropertyName.
+     */
+    private resolveEventBinding;
+    /**
+     * Resolve a content data binding (`{{expression}}` in text content).
+     */
+    private resolveContentBinding;
+    /**
+     * Resolve an attribute data binding (`{{expression}}` in an HTML attribute).
+     * Dispatches to event, expression, or access binding handlers based on aspect.
+     */
+    private resolveAttributeBinding;
+    /**
+     * Resolve an attribute directive binding (`f-children`, `f-slotted`, `f-ref`).
+     */
+    private resolveAttributeDirectiveBinding;
+    /**
+     * Dispatcher for data binding resolution. Routes to the appropriate handler
+     * based on the binding subtype.
+     */
+    private resolveDataBinding;
+    /**
+     * Resolver of the innerHTML string. Finds the next binding or directive
+     * in the HTML and dispatches to the appropriate handler.
+     * @param rootPropertyName - The root property name for schema registration.
+     * @param innerHTML - The innerHTML to parse.
+     * @param strings - Accumulator for literal HTML segments and running previous-string.
+     * @param values - The values array (accumulates binding functions and directives).
+     * @param context - The template resolution context.
+     */
+    private resolveInnerHTML;
+}

package/dist/dts/declarative/template.d.ts

@@ -0,0 +1,9 @@
+import type { FASTElementTemplateResolver, TemplateLifecycleCallbacks } from "../components/fast-definitions.js";
+/**
+ * Returns a declarative template resolver that waits for the matching
+ * `<f-template>` element and resolves it into a concrete `ViewTemplate`.
+ *
+ * @param callbacks - Optional per-element lifecycle callbacks.
+ * @public
+ */
+export declare function declarativeTemplate(callbacks?: TemplateLifecycleCallbacks): FASTElementTemplateResolver;

package/dist/dts/declarative/utilities.d.ts

@@ -0,0 +1,312 @@
+import { type JSONSchema, type Schema } from "../components/schema.js";
+import { eventArgAccessor, executionContextAccessor } from "./syntax.js";
+export { assignObservables, assignProxy, deepEqual, deepMerge, findDef, isPlainObject, } from "./observer-map-utilities.js";
+/**
+ * Declarative behavior type.
+ * @public
+ */
+export type BehaviorType = "dataBinding" | "templateDirective";
+/**
+ * Declarative attribute directive names.
+ * @public
+ */
+export type AttributeDirective = "children" | "slotted" | "ref";
+/**
+ * Declarative data binding marker type.
+ * @public
+ */
+export type DataBindingBindingType = "client" | "default" | "unescaped";
+/**
+ * Base behavior configuration.
+ * @public
+ */
+export interface BehaviorConfig {
+    type: BehaviorType;
+}
+/**
+ * Declarative schema path type.
+ * @public
+ */
+export type PathType = "access" | "default" | "event" | "repeat";
+/**
+ * Content binding behavior configuration.
+ * @public
+ */
+export interface ContentDataBindingBehaviorConfig extends BaseDataBindingBehaviorConfig {
+    subtype: "content";
+}
+/**
+ * Attribute binding behavior configuration.
+ * @public
+ */
+export interface AttributeDataBindingBehaviorConfig extends BaseDataBindingBehaviorConfig {
+    subtype: "attribute";
+    aspect: "@" | ":" | "?" | null;
+}
+/**
+ * Attribute directive binding behavior configuration.
+ * @public
+ */
+export interface AttributeDirectiveBindingBehaviorConfig extends BaseDataBindingBehaviorConfig {
+    subtype: "attributeDirective";
+    name: AttributeDirective;
+}
+/**
+ * Declarative data binding behavior configuration.
+ * @public
+ */
+export type DataBindingBehaviorConfig = ContentDataBindingBehaviorConfig | AttributeDataBindingBehaviorConfig | AttributeDirectiveBindingBehaviorConfig;
+/**
+ * Base data binding behavior configuration.
+ * @public
+ */
+export interface BaseDataBindingBehaviorConfig extends BehaviorConfig {
+    type: "dataBinding";
+    bindingType: DataBindingBindingType;
+    openingStartIndex: number;
+    openingEndIndex: number;
+    closingStartIndex: number;
+    closingEndIndex: number;
+}
+/**
+ * Declarative template directive names.
+ * @public
+ */
+export type TemplateDirective = "when" | "repeat";
+/**
+ * Template directive behavior configuration.
+ * @public
+ */
+export interface TemplateDirectiveBehaviorConfig extends BehaviorConfig {
+    type: "templateDirective";
+    name: TemplateDirective;
+    value: string;
+    openingTagStartIndex: number;
+    openingTagEndIndex: number;
+    closingTagStartIndex: number;
+    closingTagEndIndex: number;
+}
+/**
+ * Map between child component attribute references and custom element names.
+ * @public
+ */
+export interface ChildrenMap {
+    customElementName: string;
+    attributeName: string;
+}
+/**
+ * Prefix used for execution context paths.
+ * @public
+ */
+export declare const contextPrefixDot: string;
+export { eventArgAccessor, executionContextAccessor };
+/**
+ * The type of a parsed event handler argument.
+ * @public
+ */
+export type EventArgType = "event" | "context" | "binding";
+/**
+ * A parsed event handler argument descriptor.
+ * @public
+ */
+export interface ParsedEventArg {
+    type: EventArgType;
+    /** The raw argument string, present only when `type` is `"binding"`. */
+    rawArg?: string;
+}
+/**
+ * Parses the arguments string of an event handler binding into an array of
+ * typed argument descriptors. Unrecognised tokens are returned as `"binding"`
+ * type with their raw string preserved.
+ *
+ * Special arguments:
+ * - `$e` — resolves to the DOM event object
+ * - `$c` — resolves to the full execution context object
+ *
+ * Any other token is treated as a binding path and resolved against the current
+ * data source.
+ *
+ * @param argsString - The raw arguments string from between the parentheses,
+ *   e.g. `""`, `"$e"`, `"$c"`, or `"$e, $c"`.
+ * @returns An array of {@link ParsedEventArg} descriptors.
+ * @public
+ */
+export declare function parseEventArgs(argsString: string): ParsedEventArg[];
+/**
+ * Logical operator tokens.
+ * @public
+ */
+export declare const LogicalOperator: {
+    readonly AND: "&&";
+    readonly OR: "||";
+};
+/**
+ * Logical operator token.
+ * @public
+ */
+export type LogicalOperator = (typeof LogicalOperator)[keyof typeof LogicalOperator];
+/**
+ * Comparison operator tokens.
+ * @public
+ */
+export declare const ComparisonOperator: {
+    readonly ACCESS: "access";
+    readonly EQUALS: "==";
+    readonly GREATER_THAN: ">";
+    readonly GREATER_THAN_OR_EQUALS: ">=";
+    readonly LESS_THAN: "<";
+    readonly LESS_THAN_OR_EQUALS: "<=";
+    readonly NOT: "!";
+    readonly NOT_EQUALS: "!=";
+};
+/**
+ * Comparison operator token.
+ * @public
+ */
+export type ComparisonOperator = (typeof ComparisonOperator)[keyof typeof ComparisonOperator];
+/**
+ * Declarative expression operator tokens.
+ * @public
+ */
+export declare const Operator: {
+    readonly ACCESS: "access";
+    readonly EQUALS: "==";
+    readonly GREATER_THAN: ">";
+    readonly GREATER_THAN_OR_EQUALS: ">=";
+    readonly LESS_THAN: "<";
+    readonly LESS_THAN_OR_EQUALS: "<=";
+    readonly NOT: "!";
+    readonly NOT_EQUALS: "!=";
+    readonly AND: "&&";
+    readonly OR: "||";
+};
+/**
+ * Declarative expression operator token.
+ * @public
+ */
+export type Operator = (typeof Operator)[keyof typeof Operator];
+/**
+ * Get the index of the next matching tag
+ * @param openingTagStartSlice - The slice starting from the opening tag
+ * @param openingTag - The opening tag string
+ * @param closingTag - The closing tag
+ * @param openingTagStartIndex - The opening tag start index derived from the innerHTML
+ * @returns index
+ * @public
+ */
+export declare function getIndexOfNextMatchingTag(openingTagStartSlice: string, openingTag: string, closingTag: string, openingTagStartIndex: number): number;
+/**
+ * Get the next behavior
+ * @param innerHTML - The innerHTML string to evaluate
+ * @param offset - The current offset in the original string.
+ * @returns DataBindingBehaviorConfig | DirectiveBehaviorConfig | null - A configuration object or null
+ * @public
+ */
+export declare function getNextBehavior(innerHTML: string, offset?: number): DataBindingBehaviorConfig | TemplateDirectiveBehaviorConfig | null;
+/**
+ * Create a function to resolve a value from an object using a path with dot syntax.
+ * e.g. "foo.bar"
+ * @param path - The dot syntax path to an objects property.
+ * @param contextPath - The current repeat context path.
+ * @param level - The current repeat nesting level.
+ * @param rootSchema - The root schema for resolving context paths.
+ * @returns A function to access the value from a given path.
+ * @public
+ */
+export declare function pathResolver(path: string, contextPath: string | null, level: number, rootSchema: JSONSchema): (accessibleObject: any, context: any) => any;
+/**
+ * Creates a binding resolver and records the binding path in the schema.
+ * @param previousString - The previous literal string before the binding.
+ * @param rootPropertyName - The current root property name.
+ * @param path - The binding path to resolve.
+ * @param parentContext - The parent repeat context.
+ * @param type - The schema path type.
+ * @param schema - The schema to record paths in.
+ * @param currentContext - The current repeat context.
+ * @param level - The current repeat nesting level.
+ * @returns A function that resolves the binding path.
+ * @public
+ */
+export declare function bindingResolver(previousString: string | null, rootPropertyName: string | null, path: string, parentContext: string | null, type: PathType, schema: Schema, currentContext: string | null, level: number): (accessibleObject: any, context: any) => any;
+/**
+ * Creates a resolver for a chained expression and records its paths in the schema.
+ * @param rootPropertyName - The current root property name.
+ * @param expression - The expression to resolve.
+ * @param parentContext - The parent repeat context.
+ * @param level - The current repeat nesting level.
+ * @param schema - The schema to record paths in.
+ * @returns A function that resolves the expression.
+ * @public
+ */
+export declare function expressionResolver(rootPropertyName: string | null, expression: ChainedExpression, parentContext: string | null, level: number, schema: Schema): (accessibleObject: any, context: any) => any;
+/**
+ * Extracts all paths from a ChainedExpression, including nested expressions
+ * @param chainedExpression - The chained expression to extract paths from
+ * @returns A Set containing all unique paths found in the expression chain
+ * @public
+ */
+export declare function extractPathsFromChainedExpression(chainedExpression: ChainedExpression): Set<string>;
+/**
+ * Declarative expression descriptor.
+ * @public
+ */
+export interface DeclarativeExpression {
+    operator: Operator;
+    left: string;
+    leftIsValue: boolean | null;
+    right: string | boolean | number | null;
+    rightIsValue: boolean | null;
+}
+/**
+ * Declarative chained expression descriptor.
+ * @public
+ */
+export interface ChainedExpression {
+    operator?: LogicalOperator;
+    expression: DeclarativeExpression;
+    next?: ChainedExpression;
+}
+/**
+ * Gets the expression chain as a configuration object
+ * @param value - The binding string value
+ * @returns - A configuration object containing information about the expression
+ * @public
+ */
+export declare function getExpressionChain(value: string): ChainedExpression | void;
+/**
+ * This is the transform utility for rationalizing declarative HTML syntax
+ * with bindings in the ViewTemplate
+ * @param innerHTML - The innerHTML to transform.
+ * @param index - The index to start the current slice of HTML to evaluate.
+ * @public
+ */
+export declare function transformInnerHTML(innerHTML: string, index?: number): string;
+/**
+ * Resolves boolean logic
+ * used for f-when and boolean attributes
+ * @param rootPropertyName - The current root property name.
+ * @param expression - The chained expression to resolve.
+ * @param parentContext - The parent repeat context.
+ * @param level - The current repeat nesting level.
+ * @param schema - The schema to record paths in.
+ * @returns - A binding that resolves the chained expression logic
+ * @public
+ */
+export declare function getBooleanBinding(rootPropertyName: string | null, expression: ChainedExpression, parentContext: string | null, level: number, schema: Schema): (x: boolean, c: any) => any;
+/**
+ * Get the root property name
+ * @param rootPropertyName - The root property
+ * @param path - The dot syntax path
+ * @param context - The context created by a repeat
+ * @param type - The type of path binding
+ * @returns
+ * @public
+ */
+export declare function getRootPropertyName(rootPropertyName: string | null, path: string, context: null | string, type: PathType): string | null;
+/**
+ * Get details of bindings to the attributes of child custom elements
+ * @param previousString - The previous string before the binding
+ * @returns null, or a custom element name and attribute name
+ * @public
+ */
+export declare function getChildrenMap(previousString: string | null): ChildrenMap | null;

package/dist/dts/di/di.d.ts

@@ -390,7 +390,7 @@ export interface InterfaceConfiguration {
     friendlyName?: string;
     /**
      * 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 }
+     * 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.
      */
     respectConnection?: boolean;

package/dist/dts/directives/children.d.ts

@@ -0,0 +1,2 @@
+export { type ChildListDirectiveOptions, ChildrenDirective, type ChildrenDirectiveOptions, children, type SubtreeDirectiveOptions, } from "../templating/children.js";
+export type { CaptureType } from "../templating/template.js";

package/dist/dts/directives/node-observation.d.ts

@@ -0,0 +1,2 @@
+export { type ElementsFilter, elements, type NodeBehaviorOptions, NodeObservationDirective, } from "../templating/node-observation.js";
+export type { CaptureType } from "../templating/template.js";

package/dist/dts/directives/ref.d.ts

@@ -0,0 +1,2 @@
+export { RefDirective, ref } from "../templating/ref.js";
+export type { CaptureType } from "../templating/template.js";

package/dist/dts/directives/repeat.d.ts

@@ -0,0 +1,4 @@
+export type { Binding } from "../binding/binding.js";
+export type { Expression } from "../observation/observable.js";
+export { RepeatBehavior, RepeatDirective, type RepeatOptions, repeat, } from "../templating/repeat.js";
+export type { CaptureType, ViewTemplate } from "../templating/template.js";

package/dist/dts/directives/slotted.d.ts

@@ -0,0 +1,2 @@
+export { SlottedDirective, type SlottedDirectiveOptions, slotted, } from "../templating/slotted.js";
+export type { CaptureType } from "../templating/template.js";

package/dist/dts/directives/when.d.ts

@@ -0,0 +1,3 @@
+export type { ExecutionContext, Expression } from "../observation/observable.js";
+export type { CaptureType, SyntheticViewTemplate } from "../templating/template.js";
+export { when } from "../templating/when.js";

package/dist/dts/dom-policy.d.ts

@@ -75,7 +75,7 @@ export type DOMPolicyOptions = {
 declare const DOMPolicy: Readonly<{
     /**
      * Creates a new DOM Policy object.
-     * @param options The options to use in creating the policy.
+     * @param options - The options to use in creating the policy.
      * @returns The newly created DOMPolicy.
      */
     create(options?: DOMPolicyOptions): Readonly<IDOMPolicy>;

package/dist/dts/html.d.ts

@@ -0,0 +1,5 @@
+export type { Binding } from "./binding/binding.js";
+export type { DOMPolicy } from "./dom.js";
+export type { Expression } from "./observation/observable.js";
+export { type ElementViewTemplate, type HTMLTemplateCompilationResult, type HTMLTemplateTag, html, InlineTemplateDirective, type SyntheticViewTemplate, type TemplateValue, ViewTemplate, } from "./templating/template.js";
+export { type ElementView, HTMLView, type SyntheticView } from "./templating/view.js";

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

@@ -0,0 +1,7 @@
+/**
+ * Installs the hydration runtime on `ViewTemplate.prototype`,
+ * making all templates hydratable. Call this before any hydration
+ * occurs. Safe to call multiple times — subsequent calls are no-ops.
+ * @internal
+ */
+export declare function ensureHydrationRuntime(): void;

package/dist/dts/hydration/target-builder.d.ts

@@ -7,7 +7,7 @@ export declare class HydrationTargetElementError extends Error {
     /**
      * The node to target factory.
      */
-    readonly node: Element;
+    readonly node: Node;
     /**
      * String representation of the HTML in the template that
      * threw the target element error.
@@ -25,10 +25,11 @@ export declare class HydrationTargetElementError extends Error {
     /**
      * The node to target factory.
      */
-    node: Element);
+    node: Node);
 }
 /**
  * Represents the DOM boundaries controlled by a view
+ * @public
  */
 export interface ViewBoundaries {
     first: Node;
@@ -37,6 +38,7 @@ export interface ViewBoundaries {
 /**
  * Stores relationships between a {@link ViewBehaviorFactory} and
  * the {@link ViewBoundaries} the factory created.
+ * @public
  */
 export interface ViewBehaviorBoundaries {
     [factoryId: string]: ViewBoundaries;
@@ -52,20 +54,21 @@ export declare function createRangeForNodes(first: Node, last: Node): Range;
 /**
  * Maps compiled ViewBehaviorFactory IDs to their corresponding DOM nodes in the
  * server-rendered shadow root. Uses a TreeWalker to scan the existing DOM between
- * firstNode and lastNode, parsing hydration markers to build the targets map.
+ * firstNode and lastNode, processing data-free sequential hydration markers.
  *
- * For element nodes: parses `data-fe-b` (or variant) attributes to identify which
- * factories target each element, then removes the marker attribute.
+ * A sequential factory pointer advances through the factories array in DFS order.
+ * Since the template compiler and hydration walker both traverse the DOM in
+ * identical depth-first order, no embedded indices are needed in markers.
  *
- * For comment nodes: parses content binding markers (`fe-b$$start/end$$`) to find
- * the DOM range controlled by each content binding. Single text nodes become the
- * direct target; multi-node ranges are stored in boundaries for structural directives.
- * Element boundary markers (`fe-eb$$start/end$$`) cause the walker to skip over
- * nested custom elements that handle their own hydration.
+ * For element nodes: parses `data-fe="N"` to determine the count of attribute
+ * binding factories, then consumes N factories sequentially.
+ *
+ * For comment nodes: `fe:b` markers consume the next factory for content bindings,
+ * using balanced depth counting for nested marker pairing. `fe:e` markers cause
+ * the walker to skip nested custom element subtrees.
  *
  * Host bindings (targetNodeId='h') appear at the start of the factories array but
- * have no SSR markers — getHydrationIndexOffset() computes how many to skip so that
- * marker indices align with the correct non-host factories.
+ * have no SSR markers — getHydrationIndexOffset() computes the initial pointer value.
  *
  * @param firstNode - The first node of the view.
  * @param lastNode -  The last node of the view.

package/dist/dts/hydration.d.ts

@@ -0,0 +1,14 @@
+export type { HydrationOptions } from "./components/enable-hydration.js";
+export { deferHydrationAttribute, enableHydration, } from "./components/enable-hydration.js";
+export { isHydratable } from "./components/hydration.js";
+export { HydrationTracker } from "./components/hydration-tracker.js";
+export type { DOMAspect, DOMPolicy, DOMSink, } from "./dom.js";
+export type { ViewBehaviorBoundaries, ViewBoundaries, } from "./hydration/target-builder.js";
+export type { Disposable } from "./interfaces.js";
+export type { ExecutionContext, ExpressionController, SourceLifetime, } from "./observation/observable.js";
+export type { ContentTemplate, ContentView, HydratableContentTemplate, } from "./templating/html-binding-directive.js";
+export type { ViewBehavior, ViewBehaviorFactory, ViewBehaviorTargets, ViewController, } from "./templating/html-directive.js";
+export type { HydratableView, HydratableViewController, ViewNodes, } from "./templating/hydration-view.js";
+export { HydrationBindingError, HydrationStage, } from "./templating/hydration-view.js";
+export type { CaptureType, ElementViewTemplate, HydratableElementViewTemplate, HydratableSyntheticViewTemplate, SyntheticViewTemplate, } from "./templating/template.js";
+export type { DefaultExecutionContext, ElementView, SyntheticView, View, } from "./templating/view.js";