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

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

@@ -1,6 +1,7 @@
+import type { HostBehavior } from "../index.js";
 import type { Constructable } from "../interfaces.js";
-import type { Behavior } from "../observation/behavior.js";
-import type { Binding, ExecutionContext } from "../observation/observable.js";
+import type { Subscriber } from "../observation/notifier.js";
+import { Expression, ExpressionController, ExpressionObserver } from "../observation/observable.js";
 /**
  * The target nodes available to a behavior.
  * @public
@@ -9,27 +10,65 @@ export declare type ViewBehaviorTargets = {
     [id: string]: Node;
 };
 /**
- * Represents an object that can contribute behavior to a view.
+ * Controls the lifecycle of a view and provides relevant context.
  * @public
  */
-export interface ViewBehavior<TSource = any, TParent = any> {
+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;
     /**
-     * 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.
+     * Adds a behavior.
+     * @param behavior - The behavior to add.
      */
-    bind(source: TSource, context: ExecutionContext<TParent>, targets: ViewBehaviorTargets): void;
+    addBehavior(behavior: ViewBehavior): 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.
+     * Adds a behavior factory.
+     * @param factory - The behavior factory to add.
+     * @param target - The target the factory will create behaviors for.
      */
-    unbind(source: TSource, context: ExecutionContext<TParent>, targets: ViewBehaviorTargets): void;
+    addBehaviorFactory(factory: ViewBehaviorFactory, target: Node): void;
 }
 /**
- * A factory that can create a {@link Behavior} associated with a particular
+ * 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
  */
@@ -44,9 +83,8 @@ export interface ViewBehaviorFactory {
     nodeId: string;
     /**
      * Creates a behavior.
-     * @param targets - The targets available for behaviors to be attached to.
      */
-    createBehavior(targets: ViewBehaviorTargets): Behavior | ViewBehavior;
+    createBehavior(): ViewBehavior;
 }
 /**
  * Used to add behavior factories when constructing templates.
@@ -113,6 +151,31 @@ export declare const HTMLDirective: Readonly<{
  * @public
  */
 export declare function htmlDirective(options?: PartialHTMLDirectiveDefinition): (type: Constructable<HTMLDirective>) => void;
+/**
+ * Captures a binding expression along with related information and capabilities.
+ *
+ * @public
+ */
+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
@@ -150,8 +213,10 @@ export declare const Aspect: Readonly<{
      *
      * @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;
+    readonly assign: (directive: Aspected, value?: string) => void;
 }>;
 /**
  * The type of HTML aspect to target.
@@ -178,14 +243,14 @@ export interface Aspected {
     /**
      * A binding if one is associated with the aspect.
      */
-    binding?: Binding;
+    dataBinding?: 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;
+export declare abstract class StatelessAttachedAttributeDirective<TOptions> implements HTMLDirective, ViewBehaviorFactory, ViewBehavior {
+    protected options: TOptions;
     /**
      * The unique id of the factory.
      */
@@ -198,12 +263,7 @@ export declare abstract class StatelessAttachedAttributeDirective<T> implements
      * 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;
+    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.
@@ -212,15 +272,13 @@ export declare abstract class StatelessAttachedAttributeDirective<T> implements
      */
     createHTML(add: AddViewBehaviorFactory): 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.
+     * Creates a behavior.
+     * @param targets - The targets available for behaviors to be attached to.
      */
-    abstract bind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
+    createBehavior(): ViewBehavior;
     /**
-     * Unbinds this behavior from the source.
-     * @param source - The source to unbind from.
+     * Bind this behavior.
+     * @param controller - The view controller that manages the lifecycle of this behavior.
      */
-    abstract unbind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
+    abstract bind(controller: ViewController): void;
 }

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

@@ -1,5 +1,4 @@
-import type { ExecutionContext } from "../observation/observable.js";
-import { StatelessAttachedAttributeDirective, ViewBehaviorTargets } from "./html-directive.js";
+import { StatelessAttachedAttributeDirective, ViewController } from "./html-directive.js";
 /**
  * Options for configuring node observation behavior.
  * @public
@@ -23,7 +22,7 @@ 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.
@@ -44,14 +43,14 @@ export declare abstract class NodeObservationDirective<T extends NodeBehaviorOpt
      * @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, context: ExecutionContext, targets: ViewBehaviorTargets): void;
+    bind(controller: ViewController): 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: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
+    unbind(controller: ViewController): void;
     /**
      * Gets the data source for the target.
      * @param target - The target to get the source for.

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

@@ -1,5 +1,4 @@
-import type { ExecutionContext } from "../observation/observable.js";
-import { StatelessAttachedAttributeDirective, ViewBehaviorTargets } from "./html-directive.js";
+import { StatelessAttachedAttributeDirective, ViewController } from "./html-directive.js";
 import type { CaptureType } from "./template.js";
 /**
  * The runtime behavior for template references.
@@ -7,21 +6,14 @@ import type { CaptureType } from "./template.js";
  */
 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 this behavior.
+     * @param controller - The view controller that manages the lifecycle of this behavior.
      */
-    bind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): 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 const ref: <T = any>(propertyName: keyof T & string) => CaptureType<T>;
+export declare const ref: <TSource = any, TParent = any>(propertyName: keyof TSource & string) => CaptureType<TSource, TParent>;

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

@@ -0,0 +1,272 @@
+import type { FASTElement } from "../components/fast-element.js";
+import { Constructable } from "../interfaces.js";
+import type { Subscriber } from "../observation/notifier.js";
+import type { ExecutionContext, Expression, ExpressionObserver } from "../observation/observable.js";
+import { ContentTemplate, ContentView } from "./binding.js";
+import { AddViewBehaviorFactory, Binding, HTMLDirective, ViewBehavior, ViewBehaviorFactory, ViewController } from "./html-directive.js";
+import { CaptureType, SyntheticViewTemplate, TemplateValue, ViewTemplate } from "./template.js";
+/**
+ * A Behavior that enables advanced rendering.
+ * @public
+ */
+export declare class RenderBehavior<TSource = any> implements ViewBehavior, Subscriber {
+    private directive;
+    private location;
+    private controller;
+    private view;
+    private template;
+    private templateBindingObserver;
+    private data;
+    private dataBindingObserver;
+    /**
+     * Creates an instance of RenderBehavior.
+     * @param directive - The render directive that created this behavior.
+     */
+    constructor(directive: RenderDirective);
+    /**
+     * Bind this behavior.
+     * @param controller - The view controller that manages the lifecycle of this behavior.
+     */
+    bind(controller: ViewController): void;
+    /**
+     * Unbinds this behavior.
+     * @param controller - The view controller that manages the lifecycle of this behavior.
+     */
+    unbind(controller: ViewController): void;
+    /** @internal */
+    handleChange(source: any, observer: ExpressionObserver): void;
+    private refreshView;
+}
+/**
+ * A Directive that enables use of the RenderBehavior.
+ * @public
+ */
+export declare class RenderDirective<TSource = any> implements HTMLDirective, ViewBehaviorFactory {
+    readonly dataBinding: Binding<TSource>;
+    readonly templateBinding: Binding<TSource, ContentTemplate>;
+    readonly templateBindingDependsOnData: boolean;
+    /**
+     * 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 RenderDirective.
+     * @param dataBinding - A binding expression that returns the data to render.
+     * @param templateBinding - A binding expression that returns the template to use to render the data.
+     */
+    constructor(dataBinding: Binding<TSource>, templateBinding: Binding<TSource, ContentTemplate>, templateBindingDependsOnData: boolean);
+    /**
+     * Creates HTML to be used within a template.
+     * @param add - Can be used to add  behavior factories to a template.
+     */
+    createHTML(add: AddViewBehaviorFactory): string;
+    /**
+     * Creates a behavior.
+     * @param targets - The targets available for behaviors to be attached to.
+     */
+    createBehavior(): RenderBehavior<TSource>;
+}
+/**
+ * Provides instructions for how to render a type.
+ * @public
+ */
+export interface RenderInstruction {
+    /**
+     * Identifies this as a RenderInstruction.
+     */
+    brand: symbol;
+    /**
+     * The type this instruction is associated with.
+     */
+    type: Constructable;
+    /**
+     * The template to use when rendering.
+     */
+    template: ContentTemplate;
+    /**
+     * A name that can be used to identify the instruction.
+     */
+    name: string;
+}
+/**
+ * Render options that are common to all configurations.
+ * @public
+ */
+export declare type CommonRenderOptions = {
+    /**
+     * The type this instruction is associated with.
+     */
+    type: Constructable;
+    /**
+     * A name that can be used to identify the instruction.
+     */
+    name?: string;
+};
+/**
+ * Render options used to specify a template.
+ * @public
+ */
+export declare type TemplateRenderOptions = CommonRenderOptions & {
+    /**
+     * The template to use when rendering.
+     */
+    template: ContentTemplate;
+};
+/**
+ * Render options that are common to all element render instructions.
+ * @public
+ */
+export declare type BaseElementRenderOptions<TSource = any, TParent = any> = CommonRenderOptions & {
+    /**
+     * Attributes to use when creating the element template.
+     */
+    attributes?: Record<string, string | TemplateValue<TSource, TParent>>;
+    /**
+     * Content to use when creating the element template.
+     */
+    content?: string | SyntheticViewTemplate;
+};
+/**
+ * Render options used to specify an element.
+ * @public
+ */
+export declare type ElementConstructorRenderOptions<TSource = any, TParent = any> = BaseElementRenderOptions<TSource, TParent> & {
+    /**
+     * The element to use when rendering.
+     */
+    element: Constructable<FASTElement>;
+};
+/**
+ * Render options use to specify an element by tag name.
+ * @public
+ */
+export declare type TagNameRenderOptions<TSource = any, TParent = any> = BaseElementRenderOptions<TSource, TParent> & {
+    /**
+     * The tag name to use when rendering.
+     */
+    tagName: string;
+};
+declare function createElementTemplate<TSource = any, TParent = any>(tagName: string, attributes?: Record<string, string | TemplateValue<TSource, TParent>>, content?: string | ContentTemplate): ViewTemplate<TSource, TParent>;
+declare function create(options: TagNameRenderOptions): RenderInstruction;
+declare function create(options: ElementConstructorRenderOptions): RenderInstruction;
+declare function create(options: TemplateRenderOptions): RenderInstruction;
+declare function instanceOf(object: any): object is RenderInstruction;
+declare function register(options: TagNameRenderOptions): RenderInstruction;
+declare function register(options: ElementConstructorRenderOptions): RenderInstruction;
+declare function register(options: TemplateRenderOptions): RenderInstruction;
+declare function register(instruction: RenderInstruction): RenderInstruction;
+declare function getByType(type: Constructable, name?: string): RenderInstruction | undefined;
+declare function getForInstance(object: any, name?: string): RenderInstruction | undefined;
+/**
+ * Provides APIs for creating and interacting with render instructions.
+ * @public
+ */
+export declare const RenderInstruction: Readonly<{
+    /**
+     * Checks whether the provided object is a RenderInstruction.
+     * @param object - The object to check.
+     * @returns true if the object is a RenderInstruction; false otherwise
+     */
+    instanceOf: typeof instanceOf;
+    /**
+     * Creates a RenderInstruction for a set of options.
+     * @param options - The options to use when creating the RenderInstruction.
+     */
+    create: typeof create;
+    /**
+     * Creates a template based on a tag name.
+     * @param tagName - The tag name to use when creating the template.
+     * @param attributes - The attributes to apply to the element.
+     * @param content - The content to insert into the element.
+     * @returns A template based on the provided specifications.
+     */
+    createElementTemplate: typeof createElementTemplate;
+    /**
+     * Creates and registers an instruction.
+     * @param options The options to use when creating the RenderInstruction.
+     * @remarks
+     * A previously created RenderInstruction can also be registered.
+     */
+    register: typeof register;
+    /**
+     * Finds a previously registered RenderInstruction by type and optionally by name.
+     * @param type - The type to retrieve the RenderInstruction for.
+     * @param name - An optional name used in differentiating between multiple registered instructions.
+     * @returns The located RenderInstruction that matches the criteria or undefined if none is found.
+     */
+    getByType: typeof getByType;
+    /**
+     * Finds a previously registered RenderInstruction for the instance's type and optionally by name.
+     * @param object - The instance to retrieve the RenderInstruction for.
+     * @param name - An optional name used in differentiating between multiple registered instructions.
+     * @returns The located RenderInstruction that matches the criteria or undefined if none is found.
+     */
+    getForInstance: typeof getForInstance;
+}>;
+/**
+ * Decorates a type with render instruction metadata.
+ * @param options - The options used in creating the RenderInstruction.
+ * @public
+ */
+export declare function renderWith(options: Omit<TagNameRenderOptions, "type">): ClassDecorator;
+/**
+ * Decorates a type with render instruction metadata.
+ * @param options - The options used in creating the RenderInstruction.
+ * @public
+ */
+export declare function renderWith(options: Omit<ElementConstructorRenderOptions, "type">): ClassDecorator;
+/**
+ * Decorates a type with render instruction metadata.
+ * @param options - The options used in creating the RenderInstruction.
+ * @public
+ */
+export declare function renderWith(options: Omit<TemplateRenderOptions, "type">): ClassDecorator;
+/**
+ * Decorates a type with render instruction metadata.
+ * @param element - The element to use to render the decorated class.
+ * @param name - An optional name to differentiate the render instruction.
+ * @public
+ */
+export declare function renderWith(element: Constructable<FASTElement>, name?: string): ClassDecorator;
+/**
+ * Decorates a type with render instruction metadata.
+ * @param template - The template to use to render the decorated class.
+ * @param name - An optional name to differentiate the render instruction.
+ * @public
+ */
+export declare function renderWith(template: ContentTemplate, name?: string): ClassDecorator;
+/**
+ * @internal
+ */
+export declare class NodeTemplate implements ContentTemplate, ContentView {
+    readonly node: Node;
+    constructor(node: Node);
+    get context(): ExecutionContext<any>;
+    bind(source: any): void;
+    unbind(): void;
+    insertBefore(refNode: Node): void;
+    remove(): void;
+    create(): ContentView;
+}
+/**
+ * Creates a RenderDirective for use in advanced rendering scenarios.
+ * @param value - The binding expression that returns the data to be rendered. The expression
+ * can also return a Node to render directly.
+ * @param template - A template to render the data with
+ * or a string to indicate which RenderInstruction to use when looking up a RenderInstruction.
+ * Expressions can also be provided to dynamically determine either the template or the name.
+ * @returns A RenderDirective suitable for use in a template.
+ * @remarks
+ * If no binding is provided, then a default binding that returns the source is created.
+ * If no template is provided, then a binding is created that will use registered
+ * RenderInstructions to determine the view.
+ * If the template binding returns a string, then it will be used to look up a
+ * RenderInstruction to determine the view.
+ * @public
+ */
+export declare function render<TSource = any, TItem = any, TParent = any>(value?: Expression<TSource, TItem> | Binding<TSource, TItem> | {}, template?: ContentTemplate | string | Expression<TSource, ContentTemplate | string | Node, TParent> | Binding<TSource, ContentTemplate | string | Node, TParent>): CaptureType<TSource, TParent>;
+export {};