@microsoft/fast-element 1.10.1 → 2.0.0-beta.2

package/dist/dts/templating/compiler.d.ts

@@ -1,38 +1,56 @@
-import type { HTMLDirective, NodeBehaviorFactory } from "./html-directive.js";
+import { TrustedTypesPolicy } from "../interfaces.js";
+import { ViewBehaviorFactory } from "./html-directive.js";
+import type { HTMLTemplateCompilationResult as TemplateCompilationResult } from "./template.js";
 /**
- * The result of compiling a template and its directives.
- * @beta
+ * A function capable of compiling a template from the preprocessed form produced
+ * by the html template function into a result that can instantiate views.
+ * @public
+ */
+export declare type CompilationStrategy = (
+/**
+ * The preprocessed HTML string or template to compile.
  */
-export interface CompilationResult {
+html: string | HTMLTemplateElement, 
+/**
+ * The behavior factories used within the html that is being compiled.
+ */
+factories: Record<string, ViewBehaviorFactory>) => TemplateCompilationResult;
+/**
+ * Common APIs related to compilation.
+ * @public
+ */
+export declare const Compiler: {
     /**
-     * A cloneable DocumentFragment representing the compiled HTML.
+     * Sets the HTML trusted types policy used by the compiler.
+     * @param policy - The policy to set for HTML.
+     * @remarks
+     * This API can only be called once, for security reasons. It should be
+     * called by the application developer at the start of their program.
      */
-    fragment: DocumentFragment;
+    setHTMLPolicy(policy: TrustedTypesPolicy): void;
     /**
-     * The behaviors that should be applied to the template's HTML.
+     * Compiles a template and associated directives into a compilation
+     * result which can be used to create views.
+     * @param html - The html string or template element to compile.
+     * @param directives - The directives referenced by the template.
+     * @remarks
+     * The template that is provided for compilation is altered in-place
+     * and cannot be compiled again. If the original template must be preserved,
+     * it is recommended that you clone the original and pass the clone to this API.
+     * @public
      */
-    viewBehaviorFactories: NodeBehaviorFactory[];
+    compile<TSource = any, TParent = any>(html: string | HTMLTemplateElement, directives: Record<string, ViewBehaviorFactory>): TemplateCompilationResult<TSource, TParent>;
     /**
-     * The behaviors that should be applied to the host element that
-     * the template is rendered into.
+     * Sets the default compilation strategy that will be used by the ViewTemplate whenever
+     * it needs to compile a view preprocessed with the html template function.
+     * @param strategy - The compilation strategy to use when compiling templates.
      */
-    hostBehaviorFactories: NodeBehaviorFactory[];
+    setDefaultStrategy(strategy: CompilationStrategy): void;
     /**
-     * An index offset to apply to BehaviorFactory target indexes when
-     * matching factories to targets.
+     * Aggregates an array of strings and directives into a single directive.
+     * @param parts - A heterogeneous array of static strings interspersed with
+     * directives.
+     * @returns A single inline directive that aggregates the behavior of all the parts.
      */
-    targetOffset: number;
-}
-/**
- * Compiles a template and associated directives into a raw compilation
- * result which include a cloneable DocumentFragment and factories capable
- * of attaching runtime behavior to nodes within the fragment.
- * @param template - The template to compile.
- * @param directives - The directives referenced by the template.
- * @remarks
- * The template that is provided for compilation is altered in-place
- * and cannot be compiled again. If the original template must be preserved,
- * it is recommended that you clone the original and pass the clone to this API.
- * @public
- */
-export declare function compileTemplate(template: HTMLTemplateElement, directives: ReadonlyArray<HTMLDirective>): CompilationResult;
+    aggregate(parts: (string | ViewBehaviorFactory)[]): ViewBehaviorFactory;
+};

package/dist/dts/templating/dom.d.ts

@@ -0,0 +1,41 @@
+import type { Callable } from "../interfaces.js";
+/**
+ * Common DOM APIs.
+ * @public
+ */
+export declare const DOM: Readonly<{
+    /**
+     * @deprecated
+     * Use Updates.enqueue().
+     */
+    queueUpdate: (callable: Callable) => void;
+    /**
+     * @deprecated
+     * Use Updates.next()
+     */
+    nextUpdate: () => Promise<void>;
+    /**
+     * @deprecated
+     * Use Updates.process()
+     */
+    processUpdates: () => void;
+    /**
+     * Sets an attribute value on an element.
+     * @param element - The element to set the attribute value on.
+     * @param attributeName - The attribute name to set.
+     * @param value - The value of the attribute to set.
+     * @remarks
+     * If the value is `null` or `undefined`, the attribute is removed, otherwise
+     * it is set to the provided value using the standard `setAttribute` API.
+     */
+    setAttribute(element: HTMLElement, attributeName: string, value: any): void;
+    /**
+     * Sets a boolean attribute value.
+     * @param element - The element to set the boolean attribute value on.
+     * @param attributeName - The attribute name to set.
+     * @param value - The value of the attribute to set.
+     * @remarks
+     * If the value is true, the attribute is added; otherwise it is removed.
+     */
+    setBooleanAttribute(element: HTMLElement, attributeName: string, value: boolean): void;
+}>;

package/dist/dts/templating/html-directive.d.ts

@@ -1,90 +1,226 @@
+import type { Constructable } from "../interfaces.js";
 import type { Behavior } from "../observation/behavior.js";
+import type { Binding, ExecutionContext } from "../observation/observable.js";
+/**
+ * The target nodes available to a behavior.
+ * @public
+ */
+export declare type ViewBehaviorTargets = {
+    [id: string]: Node;
+};
+/**
+ * Represents an object that can contribute behavior to a view.
+ * @public
+ */
+export interface ViewBehavior<TSource = any, TParent = any> {
+    /**
+     * Bind this behavior to the source.
+     * @param source - The source to bind to.
+     * @param context - The execution context that the binding is operating within.
+     * @param targets - The targets that behaviors in a view can attach to.
+     */
+    bind(source: TSource, context: ExecutionContext<TParent>, targets: ViewBehaviorTargets): void;
+    /**
+     * Unbinds this behavior from the source.
+     * @param source - The source to unbind from.
+     * @param context - The execution context that the binding is operating within.
+     * @param targets - The targets that behaviors in a view can attach to.
+     */
+    unbind(source: TSource, context: ExecutionContext<TParent>, targets: ViewBehaviorTargets): void;
+}
 /**
  * A factory that can create a {@link Behavior} associated with a particular
  * location within a DOM fragment.
  * @public
  */
-export interface NodeBehaviorFactory {
+export interface ViewBehaviorFactory {
+    /**
+     * The unique id of the factory.
+     */
+    id: string;
     /**
-     * The index of the DOM node to which the created behavior will apply.
+     * The structural id of the DOM node to which the created behavior will apply.
      */
-    targetIndex: number;
+    nodeId: string;
     /**
-     * Creates a behavior for the provided target node.
-     * @param target - The node instance to create the behavior for.
+     * Creates a behavior.
+     * @param targets - The targets available for behaviors to be attached to.
      */
-    createBehavior(target: Node): Behavior;
+    createBehavior(targets: ViewBehaviorTargets): Behavior | ViewBehavior;
 }
+/**
+ * Used to add behavior factories when constructing templates.
+ * @public
+ */
+export declare type AddViewBehaviorFactory = (factory: ViewBehaviorFactory) => string;
 /**
  * Instructs the template engine to apply behavior to a node.
  * @public
  */
-export declare abstract class HTMLDirective implements NodeBehaviorFactory {
+export interface HTMLDirective {
     /**
-     * The index of the DOM node to which the created behavior will apply.
+     * Creates HTML to be used within a template.
+     * @param add - Can be used to add  behavior factories to a template.
      */
-    targetIndex: number;
+    createHTML(add: AddViewBehaviorFactory): string;
+}
+/**
+ * Represents metadata configuration for an HTMLDirective.
+ * @public
+ */
+export interface PartialHTMLDirectiveDefinition {
     /**
-     * Creates a placeholder string based on the directive's index within the template.
-     * @param index - The index of the directive within the template.
+     * Indicates whether the directive needs access to template contextual information
+     * such as the sourceAspect, targetAspect, and aspectType.
      */
-    abstract createPlaceholder(index: number): string;
+    aspected?: boolean;
+}
+/**
+ * Defines metadata for an HTMLDirective.
+ * @public
+ */
+export interface HTMLDirectiveDefinition<TType extends Constructable<HTMLDirective> = Constructable<HTMLDirective>> extends Required<PartialHTMLDirectiveDefinition> {
     /**
-     * Creates a behavior for the provided target node.
-     * @param target - The node instance to create the behavior for.
+     * The type that the definition provides metadata for.
      */
-    abstract createBehavior(target: Node): Behavior;
+    readonly type: TType;
 }
 /**
- * A {@link HTMLDirective} that targets a named attribute or property on a node.
+ * Instructs the template engine to apply behavior to a node.
  * @public
  */
-export declare abstract class TargetedHTMLDirective extends HTMLDirective {
+export declare const HTMLDirective: Readonly<{
     /**
-     * Gets/sets the name of the attribute or property that this
-     * directive is targeting on the associated node.
+     * Gets the directive definition associated with the instance.
+     * @param instance - The directive instance to retrieve the definition for.
      */
-    abstract targetName: string | undefined;
+    getForInstance: (object: any) => HTMLDirectiveDefinition<Constructable<HTMLDirective>> | undefined;
     /**
-     * Creates a placeholder string based on the directive's index within the template.
-     * @param index - The index of the directive within the template.
+     * Gets the directive definition associated with the specified type.
+     * @param type - The directive type to retrieve the definition for.
      */
-    createPlaceholder: (index: number) => string;
-}
+    getByType: (key: Function) => HTMLDirectiveDefinition<Constructable<HTMLDirective>> | undefined;
+    /**
+     * Defines an HTMLDirective based on the options.
+     * @param type - The type to define as a directive.
+     * @param options - Options that specify the directive's application.
+     */
+    define<TType extends Constructable<HTMLDirective>>(type: TType, options?: PartialHTMLDirectiveDefinition): TType;
+}>;
 /**
- * Describes the shape of a behavior constructor that can be created by
- * an {@link AttachedBehaviorHTMLDirective}.
+ * Decorator: Defines an HTMLDirective.
+ * @param options - Provides options that specify the directive's application.
  * @public
  */
-export declare type AttachedBehaviorType<T = any> = new (target: any, options: T) => Behavior;
+export declare function htmlDirective(options?: PartialHTMLDirectiveDefinition): (type: Constructable<HTMLDirective>) => void;
 /**
- * A directive that attaches special behavior to an element via a custom attribute.
+ * The type of HTML aspect to target.
  * @public
  */
-export declare class AttachedBehaviorHTMLDirective<T = any> extends HTMLDirective {
-    private name;
-    private behavior;
-    private options;
+export declare const Aspect: Readonly<{
+    /**
+     * Not aspected.
+     */
+    readonly none: 0;
+    /**
+     * An attribute.
+     */
+    readonly attribute: 1;
+    /**
+     * A boolean attribute.
+     */
+    readonly booleanAttribute: 2;
+    /**
+     * A property.
+     */
+    readonly property: 3;
+    /**
+     * Content
+     */
+    readonly content: 4;
+    /**
+     * A token list.
+     */
+    readonly tokenList: 5;
+    /**
+     * An event.
+     */
+    readonly event: 6;
     /**
      *
-     * @param name - The name of the behavior; used as a custom attribute on the element.
-     * @param behavior - The behavior to instantiate and attach to the element.
-     * @param options - Options to pass to the behavior during creation.
+     * @param directive - The directive to assign the aspect to.
+     * @param value - The value to base the aspect determination on.
      */
-    constructor(name: string, behavior: AttachedBehaviorType<T>, options: T);
+    readonly assign: (directive: Aspected, value: string) => void;
+}>;
+/**
+ * The type of HTML aspect to target.
+ * @public
+ */
+export declare type Aspect = typeof Aspect[Exclude<keyof typeof Aspect, "assign" | "none">];
+/**
+ * Represents something that applies to a specific aspect of the DOM.
+ * @public
+ */
+export interface Aspected {
+    /**
+     * The original source aspect exactly as represented in markup.
+     */
+    sourceAspect: string;
+    /**
+     * The evaluated target aspect, determined after processing the source.
+     */
+    targetAspect: string;
+    /**
+     * The type of aspect to target.
+     */
+    aspectType: Aspect;
+    /**
+     * A binding if one is associated with the aspect.
+     */
+    binding?: Binding;
+}
+/**
+ * A base class used for attribute directives that don't need internal state.
+ * @public
+ */
+export declare abstract class StatelessAttachedAttributeDirective<T> implements HTMLDirective, ViewBehaviorFactory, ViewBehavior {
+    protected options: T;
+    /**
+     * The unique id of the factory.
+     */
+    id: string;
+    /**
+     * The structural id of the DOM node to which the created behavior will apply.
+     */
+    nodeId: string;
+    /**
+     * Creates an instance of RefDirective.
+     * @param options - The options to use in configuring the directive.
+     */
+    constructor(options: T);
+    /**
+     * Creates a behavior.
+     * @param targets - The targets available for behaviors to be attached to.
+     */
+    createBehavior(targets: ViewBehaviorTargets): ViewBehavior;
     /**
      * Creates a placeholder string based on the directive's index within the template.
      * @param index - The index of the directive within the template.
      * @remarks
      * Creates a custom attribute placeholder.
      */
-    createPlaceholder(index: number): string;
+    createHTML(add: AddViewBehaviorFactory): string;
     /**
-     * Creates a behavior for the provided target node.
-     * @param target - The node instance to create the behavior for.
-     * @remarks
-     * Creates an instance of the `behavior` type this directive was constructed with
-     * and passes the target and options to that `behavior`'s constructor.
+     * Bind this behavior to the source.
+     * @param source - The source to bind to.
+     * @param context - The execution context that the binding is operating within.
+     * @param targets - The targets that behaviors in a view can attach to.
+     */
+    abstract bind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
+    /**
+     * Unbinds this behavior from the source.
+     * @param source - The source to unbind from.
      */
-    createBehavior(target: Node): Behavior;
+    abstract unbind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
 }

package/dist/dts/templating/markup.d.ts

@@ -0,0 +1,48 @@
+import type { ViewBehaviorFactory } from "./html-directive.js";
+/** @internal */
+export declare const nextId: () => string;
+/**
+ * Common APIs related to markup generation.
+ * @public
+ */
+export declare const Markup: Readonly<{
+    /**
+     * Creates a placeholder string suitable for marking out a location *within*
+     * an attribute value or HTML content.
+     * @param index - The directive index to create the placeholder for.
+     * @remarks
+     * Used internally by binding directives.
+     */
+    interpolation: (id: string) => string;
+    /**
+     * Creates a placeholder that manifests itself as an attribute on an
+     * element.
+     * @param attributeName - The name of the custom attribute.
+     * @param index - The directive index to create the placeholder for.
+     * @remarks
+     * Used internally by attribute directives such as `ref`, `slotted`, and `children`.
+     */
+    attribute: (id: string) => string;
+    /**
+     * Creates a placeholder that manifests itself as a marker within the DOM structure.
+     * @param index - The directive index to create the placeholder for.
+     * @remarks
+     * Used internally by structural directives such as `repeat`.
+     */
+    comment: (id: string) => string;
+}>;
+/**
+ * Common APIs related to content parsing.
+ * @public
+ */
+export declare const Parser: Readonly<{
+    /**
+     * Parses text content or HTML attribute content, separating out the static strings
+     * from the directives.
+     * @param value - The content or attribute string to parse.
+     * @param factories - A list of directives to search for in the string.
+     * @returns A heterogeneous array of static strings interspersed with
+     * directives or null if no directives are found in the string.
+     */
+    parse(value: string, factories: Record<string, ViewBehaviorFactory>): (string | ViewBehaviorFactory)[] | null;
+}>;

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

@@ -1,4 +1,5 @@
-import type { Behavior } from "../observation/behavior.js";
+import type { ExecutionContext } from "../observation/observable.js";
+import { StatelessAttachedAttributeDirective, ViewBehaviorTargets } from "./html-directive.js";
 /**
  * Options for configuring node observation behavior.
  * @public
@@ -28,47 +29,62 @@ export declare type ElementsFilter = (value: Node, index: number, array: Node[])
  * @param selector - An optional selector to restrict the filter to.
  * @public
  */
-export declare function elements(selector?: string): ElementsFilter;
+export declare const elements: (selector?: string) => ElementsFilter;
 /**
  * A base class for node observation.
- * @internal
+ * @public
+ * @remarks
+ * Internally used by the SlottedDirective and the ChildrenDirective.
  */
-export declare abstract class NodeObservationBehavior<T extends NodeBehaviorOptions> implements Behavior {
-    protected target: HTMLElement;
-    protected options: T;
-    private source;
-    private shouldUpdate;
+export declare abstract class NodeObservationDirective<T extends NodeBehaviorOptions> extends StatelessAttachedAttributeDirective<T> {
+    private sourceProperty;
     /**
-     * Creates an instance of NodeObservationBehavior.
-     * @param target - The target to assign the nodes property on.
-     * @param options - The options to use in configuring node observation.
+     * Bind this behavior to the source.
+     * @param source - The source to bind to.
+     * @param context - The execution context that the binding is operating within.
+     * @param targets - The targets that behaviors in a view can attach to.
      */
-    constructor(target: HTMLElement, options: T);
+    bind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
     /**
-     * Begins observation of the nodes.
+     * Unbinds this behavior from the source.
+     * @param source - The source to unbind from.
+     * @param context - The execution context that the binding is operating within.
+     * @param targets - The targets that behaviors in a view can attach to.
      */
-    abstract observe(): void;
+    unbind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
     /**
-     * Disconnects observation of the nodes.
+     * Gets the data source for the target.
+     * @param target - The target to get the source for.
+     * @returns The source.
      */
-    abstract disconnect(): void;
+    protected getSource(target: Node): any;
     /**
-     * Retrieves the nodes that should be assigned to the target.
+     * Updates the source property with the computed nodes.
+     * @param source - The source object to assign the nodes property to.
+     * @param value - The nodes to assign to the source object property.
      */
-    protected abstract getNodes(): Node[];
+    protected updateTarget(source: any, value: ReadonlyArray<any>): void;
     /**
-     * Bind this behavior to the source.
-     * @param source - The source to bind to.
-     * @param context - The execution context that the binding is operating within.
+     * Computes the set of nodes that should be assigned to the source property.
+     * @param target - The target to compute the nodes for.
+     * @returns The computed nodes.
+     * @remarks
+     * Applies filters if provided.
      */
-    bind(source: any): void;
+    protected computeNodes(target: any): Node[];
     /**
-     * Unbinds this behavior from the source.
-     * @param source - The source to unbind from.
+     * Begins observation of the nodes.
+     * @param target - The target to observe.
+     */
+    protected abstract observe(target: any): void;
+    /**
+     * Disconnects observation of the nodes.
+     * @param target - The target to unobserve.
+     */
+    protected abstract disconnect(target: any): void;
+    /**
+     * Retrieves the raw nodes that should be assigned to the source property.
+     * @param target - The target to get the node to.
      */
-    unbind(): void;
-    /** @internal */
-    handleEvent(): void;
-    private computeNodes;
-    private updateTarget;
+    protected abstract getNodes(target: any): Node[];
 }

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

@@ -1,24 +1,18 @@
-import type { Behavior } from "../observation/behavior.js";
+import type { ExecutionContext } from "../observation/observable.js";
+import { StatelessAttachedAttributeDirective, ViewBehaviorTargets } from "./html-directive.js";
 import type { CaptureType } from "./template.js";
 /**
  * The runtime behavior for template references.
  * @public
  */
-export declare class RefBehavior implements Behavior {
-    private target;
-    private propertyName;
-    /**
-     * Creates an instance of RefBehavior.
-     * @param target - The element to reference.
-     * @param propertyName - The name of the property to assign the reference to.
-     */
-    constructor(target: HTMLElement, propertyName: string);
+export declare class RefDirective extends StatelessAttachedAttributeDirective<string> {
     /**
      * Bind this behavior to the source.
      * @param source - The source to bind to.
      * @param context - The execution context that the binding is operating within.
+     * @param targets - The targets that behaviors in a view can attach to.
      */
-    bind(source: any): void;
+    bind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
     /**
      * Unbinds this behavior from the source.
      * @param source - The source to unbind from.
@@ -30,4 +24,4 @@ export declare class RefBehavior implements Behavior {
  * @param propertyName - The name of the property to assign the reference to.
  * @public
  */
-export declare function ref<T = any>(propertyName: keyof T & string): CaptureType<T>;
+export declare const ref: <T = any>(propertyName: keyof T & string) => CaptureType<T>;