@microsoft/fast-element 1.10.5 → 2.0.0-beta.10

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,284 @@
-import type { Behavior } from "../observation/behavior.js";
+import type { HostBehavior } from "../index.js";
+import type { Constructable } from "../interfaces.js";
+import type { Subscriber } from "../observation/notifier.js";
+import { Expression, ExpressionController, ExpressionObserver } from "../observation/observable.js";
 /**
- * A factory that can create a {@link Behavior} associated with a particular
+ * The target nodes available to a behavior.
+ * @public
+ */
+export declare type ViewBehaviorTargets = {
+    [id: string]: Node;
+};
+/**
+ * Controls the lifecycle of a view and provides relevant context.
+ * @public
+ */
+export interface ViewController<TSource = any, TParent = any> extends ExpressionController<TSource, TParent> {
+    /**
+     * The parts of the view that are targeted by view behaviors.
+     */
+    readonly targets: ViewBehaviorTargets;
+}
+/**
+ * Bridges between ViewBehaviors and HostBehaviors, enabling a host to
+ * control ViewBehaviors.
+ * @public
+ */
+export interface ViewBehaviorOrchestrator<TSource = any, TParent = any> extends ViewController<TSource, TParent>, HostBehavior<TSource> {
+    /**
+     *
+     * @param nodeId - The structural id of the DOM node to which a behavior will apply.
+     * @param target - The DOM node associated with the id.
+     */
+    addTarget(nodeId: string, target: Node): void;
+    /**
+     * Adds a behavior.
+     * @param behavior - The behavior to add.
+     */
+    addBehavior(behavior: ViewBehavior): void;
+    /**
+     * Adds a behavior factory.
+     * @param factory - The behavior factory to add.
+     * @param target - The target the factory will create behaviors for.
+     */
+    addBehaviorFactory(factory: ViewBehaviorFactory, target: Node): void;
+}
+/**
+ * Bridges between ViewBehaviors and HostBehaviors, enabling a host to
+ * control ViewBehaviors.
+ * @public
+ */
+export declare const ViewBehaviorOrchestrator: Readonly<{
+    /**
+     * Creates a ViewBehaviorOrchestrator.
+     * @param source - The source to to associate behaviors with.
+     * @returns A ViewBehaviorOrchestrator.
+     */
+    create<TSource = any, TParent = any>(source: TSource): ViewBehaviorOrchestrator<TSource, TParent>;
+}>;
+/**
+ * Represents an object that can contribute behavior to a view.
+ * @public
+ */
+export interface ViewBehavior<TSource = any, TParent = any> {
+    /**
+     * Bind this behavior.
+     * @param controller - The view controller that manages the lifecycle of this behavior.
+     */
+    bind(controller: ViewController<TSource, TParent>): void;
+}
+/**
+ * A factory that can create a {@link ViewBehavior} 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.
      */
-    createBehavior(target: Node): Behavior;
+    createBehavior(): 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.
+ * Captures a binding expression along with related information and capabilities.
+ *
  * @public
  */
-export declare class AttachedBehaviorHTMLDirective<T = any> extends HTMLDirective {
-    private name;
-    private behavior;
-    private options;
+export declare abstract class Binding<TSource = any, TReturn = any, TParent = any> {
+    evaluate: Expression<TSource, TReturn, TParent>;
+    isVolatile: boolean;
+    /**
+     * Options associated with the binding.
+     */
+    options?: any;
+    /**
+     * Creates a binding.
+     * @param evaluate - Evaluates the binding.
+     * @param isVolatile - Indicates whether the binding is volatile.
+     */
+    constructor(evaluate: Expression<TSource, TReturn, TParent>, isVolatile?: boolean);
+    /**
+     * Creates an observer capable of notifying a subscriber when the output of a binding changes.
+     * @param directive - The HTML Directive to create the observer for.
+     * @param subscriber - The subscriber to changes in the binding.
+     */
+    abstract createObserver(directive: HTMLDirective, subscriber: Subscriber): ExpressionObserver<TSource, TReturn, TParent>;
+}
+/**
+ * The type of HTML aspect to target.
+ * @public
+ */
+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.
+     * @remarks
+     * If a falsy value is provided, then the content aspect will be assigned.
+     */
+    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.
      */
-    constructor(name: string, behavior: AttachedBehaviorType<T>, options: T);
+    dataBinding?: Binding;
+}
+/**
+ * A base class used for attribute directives that don't need internal state.
+ * @public
+ */
+export declare abstract class StatelessAttachedAttributeDirective<TOptions> implements HTMLDirective, ViewBehaviorFactory, ViewBehavior {
+    protected options: TOptions;
+    /**
+     * 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: TOptions);
     /**
      * 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.
+     * Creates a behavior.
+     * @param targets - The targets available for behaviors to be attached to.
+     */
+    createBehavior(): ViewBehavior;
+    /**
+     * Bind this behavior.
+     * @param controller - The view controller that manages the lifecycle of this behavior.
      */
-    createBehavior(target: Node): Behavior;
+    abstract bind(controller: ViewController): 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,4 @@
-import type { Behavior } from "../observation/behavior.js";
+import { StatelessAttachedAttributeDirective, ViewController } from "./html-directive.js";
 /**
  * Options for configuring node observation behavior.
  * @public
@@ -22,53 +22,68 @@ export interface NodeBehaviorOptions<T = any> {
  *
  * @public
  */
-export declare type ElementsFilter = (value: Node, index: number, array: Node[]) => boolean;
+export declare type ElementsFilter = (value: Node, index?: number, array?: Node[]) => boolean;
 /**
  * Creates a function that can be used to filter a Node array, selecting only elements.
  * @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(controller: ViewController): 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(controller: ViewController): 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,33 +1,19 @@
-import type { Behavior } from "../observation/behavior.js";
+import { StatelessAttachedAttributeDirective, ViewController } 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;
+export declare class RefDirective extends StatelessAttachedAttributeDirective<string> {
     /**
-     * Creates an instance of RefBehavior.
-     * @param target - The element to reference.
-     * @param propertyName - The name of the property to assign the reference to.
+     * Bind this behavior.
+     * @param controller - The view controller that manages the lifecycle of this behavior.
      */
-    constructor(target: HTMLElement, propertyName: 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.
-     */
-    bind(source: any): void;
-    /**
-     * Unbinds this behavior from the source.
-     * @param source - The source to unbind from.
-     */
-    unbind(): void;
+    bind(controller: ViewController): void;
 }
 /**
  * A directive that observes the updates a property with a reference to the element.
  * @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: <TSource = any, TParent = any>(propertyName: keyof TSource & string) => CaptureType<TSource, TParent>;