@microsoft/fast-element 1.10.0 → 2.0.0-beta.1

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>;

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

@@ -1,9 +1,9 @@
-import { Binding, ExecutionContext } from "../observation/observable.js";
-import type { Subscriber } from "../observation/notifier.js";
-import type { Splice } from "../observation/array-change-records.js";
 import type { Behavior } from "../observation/behavior.js";
-import { HTMLDirective } from "./html-directive.js";
-import type { CaptureType, SyntheticViewTemplate } from "./template.js";
+import type { Subscriber } from "../observation/notifier.js";
+import { Binding, ChildContext, ExecutionContext, ItemContext, RootContext } from "../observation/observable.js";
+import { Splice } from "../observation/arrays.js";
+import { AddViewBehaviorFactory, HTMLDirective, ViewBehaviorFactory, ViewBehaviorTargets } from "./html-directive.js";
+import type { CaptureType, ChildViewTemplate, ItemViewTemplate, SyntheticViewTemplate, ViewTemplate } from "./template.js";
 /**
  * Options for configuring repeat behavior.
  * @public
@@ -34,7 +34,7 @@ export declare class RepeatBehavior<TSource = any> implements Behavior, Subscrib
     private items;
     private itemsObserver;
     private itemsBindingObserver;
-    private originalContext;
+    private context;
     private childContext;
     private bindView;
     /**
@@ -58,7 +58,11 @@ export declare class RepeatBehavior<TSource = any> implements Behavior, Subscrib
      * @param source - The source to unbind from.
      */
     unbind(): void;
-    /** @internal */
+    /**
+     * Handles changes in the array, its items, and the repeat template.
+     * @param source - The source of the change.
+     * @param args - The details about what was changed.
+     */
     handleChange(source: any, args: Splice[]): void;
     private observeItems;
     private updateViews;
@@ -69,17 +73,25 @@ export declare class RepeatBehavior<TSource = any> implements Behavior, Subscrib
  * A directive that configures list rendering.
  * @public
  */
-export declare class RepeatDirective<TSource = any> extends HTMLDirective {
-    private itemsBinding;
-    private templateBinding;
-    private options;
+export declare class RepeatDirective<TSource = any> implements HTMLDirective, ViewBehaviorFactory {
+    readonly itemsBinding: Binding;
+    readonly templateBinding: Binding<TSource, SyntheticViewTemplate>;
+    readonly options: RepeatOptions;
     private isItemsBindingVolatile;
     private isTemplateBindingVolatile;
+    /**
+     * 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 a placeholder string based on the directive's index within the template.
      * @param index - The index of the directive within the template.
      */
-    createPlaceholder: (index: number) => string;
+    createHTML(add: AddViewBehaviorFactory): string;
     /**
      * Creates an instance of RepeatDirective.
      * @param itemsBinding - The binding that provides the array to render.
@@ -91,7 +103,7 @@ export declare class RepeatDirective<TSource = any> extends HTMLDirective {
      * Creates a behavior for the provided target node.
      * @param target - The node instance to create the behavior for.
      */
-    createBehavior(target: Node): RepeatBehavior<TSource>;
+    createBehavior(targets: ViewBehaviorTargets): RepeatBehavior<TSource>;
 }
 /**
  * A directive that enables list rendering.
@@ -101,4 +113,50 @@ export declare class RepeatDirective<TSource = any> extends HTMLDirective {
  * @param options - Options used to turn on special repeat features.
  * @public
  */
-export declare function repeat<TSource = any, TItem = any>(itemsBinding: Binding<TSource, readonly TItem[]>, templateOrTemplateBinding: SyntheticViewTemplate | Binding<TSource, SyntheticViewTemplate>, options?: RepeatOptions): CaptureType<TSource>;
+export declare function repeat<TSource = any, TArray extends ReadonlyArray<any> = ReadonlyArray<any>>(itemsBinding: Binding<TSource, TArray, ExecutionContext<TSource>>, templateOrTemplateBinding: ViewTemplate | Binding<TSource, ViewTemplate, RootContext>, options?: {
+    positioning: false;
+} | {
+    recycle: true;
+} | {
+    positioning: false;
+    recycle: false;
+} | {
+    positioning: false;
+    recycle: true;
+}): CaptureType<TSource>;
+/**
+ * A directive that enables list rendering.
+ * @param itemsBinding - The array to render.
+ * @param templateOrTemplateBinding - The template or a template binding used obtain a template
+ * to render for each item in the array.
+ * @param options - Options used to turn on special repeat features.
+ * @public
+ */
+export declare function repeat<TSource = any, TArray extends ReadonlyArray<any> = ReadonlyArray<any>>(itemsBinding: Binding<TSource, TArray, ExecutionContext<TSource>>, templateOrTemplateBinding: ChildViewTemplate | Binding<TSource, ChildViewTemplate, ChildContext>, options?: {
+    positioning: false;
+} | {
+    recycle: true;
+} | {
+    positioning: false;
+    recycle: false;
+} | {
+    positioning: false;
+    recycle: true;
+}): CaptureType<TSource>;
+/**
+ * A directive that enables list rendering.
+ * @param itemsBinding - The array to render.
+ * @param templateOrTemplateBinding - The template or a template binding used obtain a template
+ * to render for each item in the array.
+ * @param options - Options used to turn on special repeat features.
+ * @public
+ */
+export declare function repeat<TSource = any, TArray extends ReadonlyArray<any> = ReadonlyArray<any>>(itemsBinding: Binding<TSource, TArray, ExecutionContext<TSource>>, templateOrTemplateBinding: ItemViewTemplate | Binding<TSource, ItemViewTemplate, ItemContext>, options: {
+    positioning: true;
+} | {
+    positioning: true;
+    recycle: true;
+} | {
+    positioning: true;
+    recycle: false;
+}): CaptureType<TSource>;

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

@@ -1,34 +1,33 @@
-import { NodeBehaviorOptions, NodeObservationBehavior } from "./node-observation.js";
+import { NodeBehaviorOptions, NodeObservationDirective } from "./node-observation.js";
 import type { CaptureType } from "./template.js";
 /**
  * The options used to configure slotted node observation.
  * @public
  */
-export interface SlottedBehaviorOptions<T = any> extends NodeBehaviorOptions<T>, AssignedNodesOptions {
+export interface SlottedDirectiveOptions<T = any> extends NodeBehaviorOptions<T>, AssignedNodesOptions {
 }
 /**
  * The runtime behavior for slotted node observation.
  * @public
  */
-export declare class SlottedBehavior extends NodeObservationBehavior<SlottedBehaviorOptions> {
-    /**
-     * Creates an instance of SlottedBehavior.
-     * @param target - The slot element target to observe.
-     * @param options - The options to use when observing the slot.
-     */
-    constructor(target: HTMLSlotElement, options: SlottedBehaviorOptions);
+export declare class SlottedDirective extends NodeObservationDirective<SlottedDirectiveOptions> {
     /**
      * Begins observation of the nodes.
+     * @param target - The target to observe.
      */
-    observe(): void;
+    observe(target: EventSource): void;
     /**
      * Disconnects observation of the nodes.
+     * @param target - The target to unobserve.
      */
-    disconnect(): void;
+    disconnect(target: EventSource): void;
     /**
-     * Retrieves the nodes that should be assigned to the target.
+     * Retrieves the raw nodes that should be assigned to the source property.
+     * @param target - The target to get the node to.
      */
-    protected getNodes(): Node[];
+    getNodes(target: HTMLSlotElement): Node[];
+    /** @internal */
+    handleEvent(event: Event): void;
 }
 /**
  * A directive that observes the `assignedNodes()` of a slot and updates a property
@@ -36,4 +35,4 @@ export declare class SlottedBehavior extends NodeObservationBehavior<SlottedBeha
  * @param propertyOrOptions - The options used to configure slotted node observation.
  * @public
  */
-export declare function slotted<T = any>(propertyOrOptions: (keyof T & string) | SlottedBehaviorOptions<keyof T & string>): CaptureType<T>;
+export declare function slotted<T = any>(propertyOrOptions: (keyof T & string) | SlottedDirectiveOptions<keyof T & string>): CaptureType<T>;