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

package/dist/dts/styles/element-styles.d.ts

@@ -1,5 +1,5 @@
-import type { Behavior } from "../observation/behavior.js";
-import { StyleStrategy, StyleTarget } from "../interfaces.js";
+import type { StyleStrategy, StyleTarget } from "../interfaces.js";
+import type { HostBehavior } from "./host.js";
 /**
  * Represents styles that can be composed into the ShadowDOM of a custom element.
  * @public
@@ -27,7 +27,7 @@ export declare class ElementStyles {
     /**
      * The behaviors associated with this set of styles.
      */
-    readonly behaviors: ReadonlyArray<Behavior<HTMLElement>> | null;
+    readonly behaviors: ReadonlyArray<HostBehavior<HTMLElement>> | null;
     /**
      * Gets the StyleStrategy associated with these element styles.
      */
@@ -47,7 +47,7 @@ export declare class ElementStyles {
      * Associates behaviors with this set of styles.
      * @param behaviors - The behaviors to associate.
      */
-    withBehaviors(...behaviors: Behavior<HTMLElement>[]): this;
+    withBehaviors(...behaviors: HostBehavior<HTMLElement>[]): this;
     /**
      * Sets the strategy that handles adding/removing these styles for an element.
      * @param strategy - The strategy to use.
@@ -58,21 +58,14 @@ export declare class ElementStyles {
      * @param Strategy - The strategy type to construct.
      */
     static setDefaultStrategy(Strategy: ConstructibleStyleStrategy): void;
+    /**
+     * Normalizes a set of composable style options.
+     * @param styles - The style options to normalize.
+     * @returns A singular ElementStyles instance or undefined.
+     */
+    static normalize(styles: ComposableStyles | ComposableStyles[] | undefined): ElementStyles | undefined;
     /**
      * Indicates whether the DOM supports the adoptedStyleSheets feature.
      */
     static readonly supportsAdoptedStyleSheets: boolean;
 }
-/**
- * https://wicg.github.io/construct-stylesheets/
- * https://developers.google.com/web/updates/2019/02/constructable-stylesheets
- *
- * @internal
- */
-export declare class AdoptedStyleSheetsStrategy implements StyleStrategy {
-    /** @internal */
-    readonly sheets: CSSStyleSheet[];
-    constructor(styles: (string | CSSStyleSheet)[]);
-    addStylesTo(target: StyleTarget): void;
-    removeStylesFrom(target: StyleTarget): void;
-}

package/dist/dts/styles/host.d.ts

@@ -0,0 +1,68 @@
+import type { ElementStyles } from "./element-styles.js";
+/**
+ * Controls the lifecycle and context of behaviors and styles
+ * associated with a component host.
+ * @public
+ */
+export interface HostController<TSource = any> {
+    /**
+     * The component source.
+     */
+    readonly source: TSource;
+    /**
+     * Indicates whether the host is connected or not.
+     */
+    readonly isConnected: boolean;
+    /**
+     * The main set of styles used for the component, independent
+     * of any behavior-specific styles.
+     */
+    mainStyles: ElementStyles | null;
+    /**
+     * Adds the behavior to the component.
+     * @param behavior - The behavior to add.
+     */
+    addBehavior(behavior: HostBehavior<TSource>): void;
+    /**
+     * Removes the behavior from the component.
+     * @param behavior - The behavior to remove.
+     * @param force - Forces removal even if this behavior was added more than once.
+     */
+    removeBehavior(behavior: HostBehavior<TSource>, force?: boolean): void;
+    /**
+     * Adds styles to this element. Providing an HTMLStyleElement will attach the element instance to the shadowRoot.
+     * @param styles - The styles to add.
+     */
+    addStyles(styles: ElementStyles | HTMLStyleElement | null | undefined): void;
+    /**
+     * Removes styles from this element. Providing an HTMLStyleElement will detach the element instance from the shadowRoot.
+     * @param styles - the styles to remove.
+     */
+    removeStyles(styles: ElementStyles | HTMLStyleElement | null | undefined): void;
+}
+/**
+ * Represents an object that can contribute behavior to a host.
+ * @public
+ */
+export interface HostBehavior<TSource = any> {
+    /**
+     * Executed when this behavior is attached to a controller.
+     * @param controller - Controls the behavior lifecycle.
+     */
+    addedCallback?(controller: HostController<TSource>): void;
+    /**
+     * Executed when this behavior is detached from a controller.
+     * @param controller - Controls the behavior lifecycle.
+     */
+    removedCallback?(controller: HostController<TSource>): void;
+    /**
+     * Executed when this behavior's host is connected.
+     * @param controller - Controls the behavior lifecycle.
+     */
+    connectedCallback?(controller: HostController<TSource>): void;
+    /**
+     * Executed when this behavior's host is disconnected.
+     * @param controller - Controls the behavior lifecycle.
+     */
+    disconnectedCallback?(controller: HostController<TSource>): void;
+}

package/dist/dts/templating/binding-signal.d.ts

@@ -0,0 +1,21 @@
+import type { Expression } from "../observation/observable.js";
+import type { Subscriber } from "../observation/notifier.js";
+import { Binding } from "./html-directive.js";
+export declare const Signal: Readonly<{
+    subscribe(signal: string, subscriber: Subscriber): void;
+    unsubscribe(signal: string, subscriber: Subscriber): void;
+    /**
+     * Sends the specified signal to signaled bindings.
+     * @param signal - The signal to send.
+     * @public
+     */
+    send(signal: string): void;
+}>;
+/**
+ * Creates a signal binding configuration with the supplied options.
+ * @param expression - The binding to refresh when signaled.
+ * @param options - The signal name or a binding to use to retrieve the signal name.
+ * @returns A binding configuration.
+ * @public
+ */
+export declare function signal<T = any>(expression: Expression<T>, options: string | Expression<T>): Binding<T>;

package/dist/dts/templating/binding-two-way.d.ts

@@ -0,0 +1,39 @@
+import { Expression } from "../observation/observable.js";
+import type { HTMLBindingDirective } from "./binding.js";
+import { Binding } from "./html-directive.js";
+/**
+ * The twoWay binding options.
+ * @public
+ */
+export declare type TwoWayBindingOptions = {
+    changeEvent?: string;
+    fromView?: (value: any) => any;
+};
+/**
+ * The settings required to enable two-way binding.
+ * @public
+ */
+export interface TwoWaySettings {
+    /**
+     * Determines which event to listen to, to detect changes in the view.
+     * @param directive - The directive to determine the change event for.
+     * @param target - The target element to determine the change event for.
+     */
+    determineChangeEvent(directive: HTMLBindingDirective, target: HTMLElement): string;
+}
+export declare const TwoWaySettings: Readonly<{
+    /**
+     * Configures two-way binding.
+     * @param settings - The settings to use for the two-way binding system.
+     */
+    configure(settings: TwoWaySettings): void;
+}>;
+/**
+ * Creates a default binding.
+ * @param expression - The binding to refresh when changed.
+ * @param optionsOrChangeEvent - The binding options or the name of the change event to use.
+ * @param isBindingVolatile - Indicates whether the binding is volatile or not.
+ * @returns A binding.
+ * @public
+ */
+export declare function twoWay<T = any>(expression: Expression<T>, optionsOrChangeEvent?: TwoWayBindingOptions | string, isBindingVolatile?: boolean): Binding<T>;

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

@@ -1,308 +1,50 @@
-import { Binding, BindingObserver, ExecutionContext } from "../observation/observable.js";
-import { AddViewBehaviorFactory, Aspect, Aspected, HTMLDirective, ViewBehavior, ViewBehaviorFactory, ViewBehaviorTargets } from "./html-directive.js";
-import type { CaptureType } from "./template.js";
+import { ExecutionContext, Expression, ExpressionObserver } from "../observation/observable.js";
+import { AddViewBehaviorFactory, Aspect, Aspected, Binding, HTMLDirective, ViewBehavior, ViewBehaviorFactory, ViewController } from "./html-directive.js";
 /**
- * Describes how aspects of an HTML element will be affected by bindings.
+ * A simple View that can be interpolated into HTML content.
  * @public
  */
-export declare type BindingMode = Record<Aspect, (directive: HTMLBindingDirective) => Pick<ViewBehaviorFactory, "createBehavior">>;
-/**
- * Describes how aspects of an HTML element will be affected by bindings.
- * @public
- */
-export declare const BindingMode: Readonly<{
-    /**
-     * Creates a binding mode based on the supplied behavior types.
-     * @param UpdateType - The base behavior type used to update aspects.
-     * @param EventType - The base behavior type used to respond to events.
-     * @returns A new binding mode.
-     */
-    define(UpdateType: typeof UpdateBinding, EventType?: typeof EventBinding): BindingMode;
-}>;
-/**
- * Describes the configuration for a binding expression.
- * @public
- */
-export interface BindingConfig<T = any> {
-    /**
-     * The binding mode to configure the binding with.
-     */
-    mode: BindingMode;
-    /**
-     * Options to be supplied to the binding behaviors.
-     */
-    options: T;
-}
-/**
- * Creates a new binding configuration based on the supplied options.
- * @public
- */
-export declare type BindingConfigResolver<T> = (options: T) => BindingConfig<T>;
-/**
- * Describes the configuration for a binding expression.
- * @public
- */
-export declare const BindingConfig: Readonly<{
-    /**
-     * Creates a binding configuration based on the provided mode and options.
-     * @param mode - The mode to use for the configuration.
-     * @param defaultOptions - The default options to use for the configuration.
-     * @returns A new binding configuration.
-     */
-    define<T>(mode: BindingMode, defaultOptions: T): BindingConfig<T> & BindingConfigResolver<T>;
-}>;
-/**
- * The "this" context for an update target function.
- * @public
- */
-export interface UpdateTargetThis {
-    /**
-     * The directive configuration for the update.
-     */
-    directive: HTMLBindingDirective;
-}
-/**
- * A target update function.
- * @param this - The "this" context for the update.
- * @param target - The node that is targeted by the update.
- * @param aspect - The aspect of the node that is being targeted.
- * @param value - The value to assign to the aspect.
- * @param source - The source object that the value was derived from.
- * @param context - The execution context that the binding is being run under.
- * @public
- */
-export declare type UpdateTarget = (this: UpdateTargetThis, target: Node, aspect: string, value: any, source: any, context: ExecutionContext) => void;
-/**
- * A base binding behavior for DOM updates.
- * @public
- */
-export declare class UpdateBinding implements ViewBehavior {
-    readonly directive: HTMLBindingDirective;
-    protected updateTarget: UpdateTarget;
-    /**
-     * Creates an instance of UpdateBinding.
-     * @param directive - The directive that has the configuration for this behavior.
-     * @param updateTarget - The function used to update the target with the latest value.
-     */
-    constructor(directive: HTMLBindingDirective, updateTarget: UpdateTarget);
-    /**
-     * 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, context: ExecutionContext, 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: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
-    /**
-     * Creates a behavior.
-     * @param targets - The targets available for behaviors to be attached to.
-     */
-    createBehavior(targets: ViewBehaviorTargets): ViewBehavior;
-}
-/**
- * A binding behavior for one-time bindings.
- * @public
- */
-export declare class OneTimeBinding extends UpdateBinding {
-    /**
-     * 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, context: ExecutionContext, targets: ViewBehaviorTargets): void;
-}
-/**
- * A binding behavior for signal bindings.
- * @public
- */
-export declare class SignalBinding extends UpdateBinding {
-    private handlerProperty;
-    /**
-     * 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, context: ExecutionContext, 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: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
-    private getSignal;
-    /**
-     * Sends the specified signal to signaled bindings.
-     * @param signal - The signal to send.
-     * @public
-     */
-    static send(signal: string): void;
-}
-/**
- * A binding behavior for bindings that change.
- * @public
- */
-export declare class ChangeBinding extends UpdateBinding {
-    private isBindingVolatile;
-    private observerProperty;
-    /**
-     * Creates an instance of ChangeBinding.
-     * @param directive - The directive that has the configuration for this behavior.
-     * @param updateTarget - The function used to update the target with the latest value.
-     */
-    constructor(directive: HTMLBindingDirective, updateTarget: UpdateTarget);
-    /**
-     * Returns the binding observer used to update the node.
-     * @param target - The target node.
-     * @returns A BindingObserver.
-     */
-    protected getObserver(target: Node): BindingObserver;
+export interface ContentView {
+    readonly context: ExecutionContext;
     /**
-     * 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.
+     * Binds a view's behaviors to its binding source.
+     * @param source - The binding source for the view's binding behaviors.
+     * @param context - The execution context to run the view within.
      */
-    bind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
+    bind(source: any, context?: ExecutionContext): 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.
+     * Unbinds a view's behaviors from its binding source and context.
      */
-    unbind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
-    /** @internal */
-    handleChange(binding: Binding, observer: BindingObserver): void;
-}
-/**
- * A binding behavior for handling events.
- * @public
- */
-export declare class EventBinding {
-    readonly directive: HTMLBindingDirective;
-    private contextProperty;
-    private sourceProperty;
-    /**
-     * Creates an instance of EventBinding.
-     * @param directive - The directive that has the configuration for this behavior.
-     */
-    constructor(directive: HTMLBindingDirective);
+    unbind(): 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.
+     * Inserts the view's DOM nodes before the referenced node.
+     * @param node - The node to insert the view's DOM before.
      */
-    bind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
+    insertBefore(node: Node): 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.
+     * Removes the view's DOM nodes.
+     * The nodes are not disposed and the view can later be re-inserted.
      */
-    unbind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
-    /**
-     * Creates a behavior.
-     * @param targets - The targets available for behaviors to be attached to.
-     */
-    createBehavior(targets: ViewBehaviorTargets): ViewBehavior;
-    /**
-     * @internal
-     */
-    handleEvent(event: Event): void;
+    remove(): void;
 }
 /**
- * The settings required to enable two-way binding.
+ * A simple template that can create ContentView instances.
  * @public
  */
-export interface TwoWaySettings {
+export interface ContentTemplate {
     /**
-     * Determines which event to listen to, to detect changes in the view.
-     * @param directive - The directive to determine the change event for.
-     * @param target - The target element to determine the change event for.
+     * Creates a simple content view instance.
      */
-    determineChangeEvent(directive: HTMLBindingDirective, target: HTMLElement): string;
+    create(): ContentView;
 }
-/**
- * A binding behavior for bindings that update in two directions.
- * @public
- */
-export declare class TwoWayBinding extends ChangeBinding {
-    private changeEvent;
-    /**
-     * 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, context: ExecutionContext, 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: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
-    /** @internal */
-    handleEvent(event: Event): void;
-    /**
-     * Configures two-way binding.
-     * @param settings - The settings to use for the two-way binding system.
-     */
-    static configure(settings: TwoWaySettings): void;
-}
-/**
- * The default binding options.
- * @public
- */
-export declare type DefaultBindingOptions = AddEventListenerOptions;
-/**
- * The default onChange binding configuration.
- * @public
- */
-export declare const onChange: BindingConfig<AddEventListenerOptions> & BindingConfigResolver<AddEventListenerOptions>;
-/**
- * The default twoWay binding options.
- * @public
- */
-export declare type DefaultTwoWayBindingOptions = DefaultBindingOptions & {
-    changeEvent?: string;
-    fromView?: (value: any) => any;
-};
-/**
- * The default twoWay binding configuration.
- * @public
- */
-export declare const twoWay: BindingConfig<DefaultTwoWayBindingOptions> & BindingConfigResolver<DefaultTwoWayBindingOptions>;
-/**
- * The default onTime binding configuration.
- * @public
- */
-export declare const oneTime: BindingConfig<AddEventListenerOptions> & BindingConfigResolver<AddEventListenerOptions>;
-/**
- * Creates a signal binding configuration with the supplied options.
- * @param options - The signal name or a binding to use to retrieve the signal name.
- * @returns A binding configuration.
- * @public
- */
-export declare const signal: <T = any>(options: string | Binding<T, any, ExecutionContext<any>>) => BindingConfig<string | Binding<T, any, ExecutionContext<any>>>;
 /**
  * A directive that applies bindings.
  * @public
  */
-export declare class HTMLBindingDirective implements HTMLDirective, ViewBehaviorFactory, Aspected {
-    binding: Binding;
-    mode: BindingMode;
-    options: any;
-    private factory;
+export declare class HTMLBindingDirective implements HTMLDirective, ViewBehaviorFactory, ViewBehavior, Aspected {
+    dataBinding: Binding;
+    private data;
+    private updateTarget;
     /**
      * The unique id of the factory.
      */
@@ -325,11 +67,9 @@ export declare class HTMLBindingDirective implements HTMLDirective, ViewBehavior
     aspectType: Aspect;
     /**
      * Creates an instance of HTMLBindingDirective.
-     * @param binding - The binding to apply.
-     * @param mode - The binding mode to use when applying the binding.
-     * @param options - The options to configure the binding with.
+     * @param dataBinding - The binding configuration to apply.
      */
-    constructor(binding: Binding, mode: BindingMode, options: any);
+    constructor(dataBinding: Binding);
     /**
      * Creates HTML to be used within a template.
      * @param add - Can be used to add  behavior factories to a template.
@@ -337,15 +77,50 @@ export declare class HTMLBindingDirective implements HTMLDirective, ViewBehavior
     createHTML(add: AddViewBehaviorFactory): string;
     /**
      * Creates a behavior.
-     * @param targets - The targets available for behaviors to be attached to.
      */
-    createBehavior(targets: ViewBehaviorTargets): ViewBehavior;
+    createBehavior(): ViewBehavior;
+    /** @internal */
+    bindDefault(controller: ViewController): void;
+    /** @internal */
+    bind: (controller: ViewController) => void;
+    /** @internal */
+    bindContent(controller: ViewController): void;
+    /** @internal */
+    bindEvent(controller: ViewController): void;
+    /** @internal */
+    unbind(controller: ViewController): void;
+    /** @internal */
+    handleEvent(event: Event): void;
+    /** @internal */
+    handleChange(binding: Expression, observer: ExpressionObserver): void;
 }
 /**
- * Creates a binding directive with the specified configuration.
- * @param binding - The binding expression.
- * @param config - The binding configuration.
- * @returns A binding directive.
+ * Creates an standard binding.
+ * @param binding - The binding to refresh when changed.
+ * @param isVolatile - Indicates whether the binding is volatile or not.
+ * @returns A binding configuration.
+ * @public
+ */
+export declare function bind<T = any>(binding: Expression<T>, isVolatile?: boolean): Binding<T>;
+/**
+ * Creates a one time binding
+ * @param binding - The binding to refresh when signaled.
+ * @returns A binding configuration.
+ * @public
+ */
+export declare function oneTime<T = any>(binding: Expression<T>): Binding<T>;
+/**
+ * Creates an event listener binding.
+ * @param binding - The binding to invoke when the event is raised.
+ * @param options - Event listener options.
+ * @returns A binding configuration.
+ * @public
+ */
+export declare function listener<T = any>(binding: Expression<T>, options?: AddEventListenerOptions): Binding<T>;
+/**
+ * Normalizes the input value into a binding.
+ * @param value - The value to create the default binding for.
+ * @returns A binding configuration for the provided value.
  * @public
  */
-export declare function bind<T = any>(binding: Binding<T>, config?: BindingConfig | DefaultBindingOptions): CaptureType<T>;
+export declare function normalizeBinding<TSource = any, TReturn = any, TParent = any>(value: Expression<TSource, TReturn, TParent> | Binding<TSource, TReturn, TParent> | {}): Binding<TSource, TReturn, TParent>;

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

@@ -60,4 +60,4 @@ export declare class ChildrenDirective extends NodeObservationDirective<Children
  * @param propertyOrOptions - The options used to configure child node observation.
  * @public
  */
-export declare function children<T = any>(propertyOrOptions: (keyof T & string) | ChildrenDirectiveOptions<keyof T & string>): CaptureType<T>;
+export declare function children<TSource = any, TParent = any>(propertyOrOptions: (keyof TSource & string) | ChildrenDirectiveOptions<keyof TSource & string>): CaptureType<TSource, TParent>;

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

@@ -1,5 +1,4 @@
 import { TrustedTypesPolicy } from "../interfaces.js";
-import type { ExecutionContext } from "../observation/observable.js";
 import { ViewBehaviorFactory } from "./html-directive.js";
 import type { HTMLTemplateCompilationResult as TemplateCompilationResult } from "./template.js";
 /**
@@ -40,7 +39,7 @@ export declare const Compiler: {
      * it is recommended that you clone the original and pass the clone to this API.
      * @public
      */
-    compile<TSource = any, TParent = any, TContext extends ExecutionContext<TParent> = ExecutionContext<TParent>>(html: string | HTMLTemplateElement, directives: Record<string, ViewBehaviorFactory>): TemplateCompilationResult<TSource, TParent, TContext>;
+    compile<TSource = any, TParent = any>(html: string | HTMLTemplateElement, directives: Record<string, ViewBehaviorFactory>): TemplateCompilationResult<TSource, TParent>;
     /**
      * 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.