@microsoft/fast-element 2.0.0-beta.3 → 2.0.0-beta.4

package/dist/dts/hooks.d.ts

@@ -1,4 +1,4 @@
-import { BindingObserver } from "./observation/observable.js";
+import { ExpressionNotifier } from "./observation/observable.js";
 /**
  * Functions used for getting and setting a stateful value.
  * @beta
@@ -17,4 +17,4 @@ export declare function useState<T>(value: T, deep?: boolean): State<T>;
  * @param action An action that is affected by state changes.
  * @returns A BindingObserver which can be used to dispose of the effect.
  */
-export declare function useEffect(action: () => void): BindingObserver;
+export declare function useEffect(action: () => void): ExpressionNotifier;

package/dist/dts/interfaces.d.ts

@@ -13,6 +13,20 @@ export declare type Callable = typeof Function.prototype.call | {
 export declare type Constructable<T = {}> = {
     new (...args: any[]): T;
 };
+/**
+ * Represents a class.
+ * @public
+ */
+export declare type Class<T, C = {}> = C & {
+    /**
+     * The class's prototype;
+     */
+    readonly prototype: T;
+    /**
+     * The class's constructor.
+     */
+    new (...args: any[]): T;
+};
 /**
  * Provides a mechanism for releasing resources.
  * @public
@@ -77,18 +91,21 @@ export interface FASTGlobal {
     /**
      * Sends a warning to the developer.
      * @param code - The warning code to send.
-     * @param args - Args relevant for the warning.
+     * @param values - Values relevant for the warning message.
      */
-    warn(code: number, ...args: any[]): void;
+    warn(code: number, values?: Record<string, any>): void;
     /**
      * Creates an error.
      * @param code - The error code to send.
-     * @param args - Args relevant for the error.
+     * @param values - Values relevant for the error message.
      */
-    error(code: number, ...args: any[]): Error;
+    error(code: number, values?: Record<string, any>): Error;
     /**
      * Adds debug messages for errors and warnings.
      * @param messages - The message dictionary to add.
+     * @remarks
+     * Message can include placeholders like $\{name\} which can be
+     * replaced by values passed at runtime.
      */
     addMessages(messages: Record<number, string>): void;
 }
@@ -101,8 +118,7 @@ export declare const enum KernelServiceId {
     observable = 2,
     contextEvent = 3,
     elementRegistry = 4,
-    styleSheetStrategy = 5,
-    developerChannel = 6
+    styleSheetStrategy = 5
 }
 /**
  * A node that can be targeted by styles.
@@ -155,7 +171,22 @@ export declare const enum Message {
     onlySetHTMLPolicyOnce = 1201,
     bindingInnerHTMLRequiresTrustedTypes = 1202,
     twoWayBindingRequiresObservables = 1203,
-    missingElementDefinition = 1401
+    hostBindingWithoutHost = 1204,
+    unsupportedBindingBehavior = 1205,
+    missingElementDefinition = 1401,
+    noRegistrationForContext = 1501,
+    noFactoryForResolver = 1502,
+    invalidResolverStrategy = 1503,
+    cannotAutoregisterDependency = 1504,
+    cannotResolveKey = 1505,
+    cannotConstructNativeFunction = 1506,
+    cannotJITRegisterNonConstructor = 1507,
+    cannotJITRegisterIntrinsic = 1508,
+    cannotJITRegisterInterface = 1509,
+    invalidResolver = 1510,
+    invalidKey = 1511,
+    noDefaultResolver = 1512,
+    cyclicDependency = 1513
 }
 /**
  * @internal

package/dist/dts/observation/observable.d.ts

@@ -23,10 +23,10 @@ export interface Accessor {
 }
 /**
  * The signature of an arrow function capable of being evaluated
- * as part of a template binding update.
+ * against source data and within an execution context.
  * @public
  */
-export declare type Binding<TSource = any, TReturn = any, TParent = any> = (source: TSource, context: ExecutionContext<TParent>) => TReturn;
+export declare type Expression<TSource = any, TReturn = any, TParent = any> = (source: TSource, context: ExecutionContext<TParent>) => TReturn;
 /**
  * A record of observable property access.
  * @public
@@ -42,19 +42,25 @@ export interface ObservationRecord {
     propertyName: string;
 }
 /**
- * Enables evaluation of and subscription to a binding.
+ * Observes a binding for changes.
+ *
  * @public
  */
-export interface BindingObserver<TSource = any, TReturn = any, TParent = any> extends Notifier, Disposable {
+export interface ExpressionObserver<TSource = any, TReturn = any, TParent = any> extends Disposable {
     /**
-     * Begins observing the binding for the source and returns the current value.
-     * @param source - The source that the binding is based on.
-     * @param context - The execution context to execute the binding within.
-     * @returns The value of the binding.
+     * Begins observing the binding.
+     * @param source - The source to pass to the binding.
+     * @param context - The context to pass to the binding.
      */
     observe(source: TSource, context?: ExecutionContext<TParent>): TReturn;
+}
+/**
+ * Enables evaluation of and subscription to a binding.
+ * @public
+ */
+export interface ExpressionNotifier<TSource = any, TReturn = any, TParent = any> extends Notifier, ExpressionObserver<TSource, TReturn, TParent> {
     /**
-     * Gets {@link ObservationRecord|ObservationRecords} that the {@link BindingObserver}
+     * Gets {@link ObservationRecord|ObservationRecords} that the {@link ExpressionNotifier}
      * is observing.
      */
     records(): IterableIterator<ObservationRecord>;
@@ -114,19 +120,19 @@ export declare const Observable: Readonly<{
      */
     getAccessors: (target: {}) => Accessor[];
     /**
-     * Creates a {@link BindingObserver} that can watch the
-     * provided {@link Binding} for changes.
+     * Creates a {@link ExpressionNotifier} that can watch the
+     * provided {@link Expression} for changes.
      * @param binding - The binding to observe.
      * @param initialSubscriber - An initial subscriber to changes in the binding value.
      * @param isVolatileBinding - Indicates whether the binding's dependency list must be re-evaluated on every value evaluation.
      */
-    binding<TSource = any, TReturn = any>(binding: Binding<TSource, TReturn, any>, initialSubscriber?: Subscriber, isVolatileBinding?: boolean): BindingObserver<TSource, TReturn, any>;
+    binding<TSource = any, TReturn = any>(binding: Expression<TSource, TReturn, any>, initialSubscriber?: Subscriber, isVolatileBinding?: boolean): ExpressionNotifier<TSource, TReturn, any>;
     /**
      * Determines whether a binding expression is volatile and needs to have its dependency list re-evaluated
      * on every evaluation of the value.
      * @param binding - The binding to inspect.
      */
-    isVolatileBinding<TSource_1 = any, TReturn_1 = any>(binding: Binding<TSource_1, TReturn_1, any>): boolean;
+    isVolatileBinding<TSource_1 = any, TReturn_1 = any>(binding: Expression<TSource_1, TReturn_1, any>): boolean;
 }>;
 /**
  * Decorator: Defines an observable property on the target.

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

@@ -58,6 +58,12 @@ 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.
      */

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

@@ -1,38 +1,21 @@
-import type { Binding, ExecutionContext } from "../observation/observable.js";
-import { BindingConfig, UpdateBinding } from "./binding.js";
-import type { ViewBehaviorTargets } from "./html-directive.js";
-/**
- * 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;
+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
      */
-    static send(signal: string): void;
-}
+    send(signal: string): void;
+}>;
 /**
  * Creates a signal binding configuration with the supplied options.
+ * @param binding - 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 const signal: <T = any>(options: string | Binding<T, any, any>) => BindingConfig<string | Binding<T, any, any>>;
+export declare function signal<T = any>(binding: Expression<T>, options: string | Expression<T>): Binding<T>;

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

@@ -1,6 +1,14 @@
-import type { ExecutionContext } from "../observation/observable.js";
-import { BindingConfig, ChangeBinding, DefaultBindingOptions, HTMLBindingDirective } from "./binding.js";
-import type { ViewBehaviorTargets } from "./html-directive.js";
+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
@@ -14,43 +22,10 @@ export interface TwoWaySettings {
     determineChangeEvent(directive: HTMLBindingDirective, target: HTMLElement): string;
 }
 /**
- * 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 twoWay binding options.
- * @public
- */
-export declare type DefaultTwoWayBindingOptions = DefaultBindingOptions & {
-    changeEvent?: string;
-    fromView?: (value: any) => any;
-};
-/**
- * The default twoWay binding configuration.
+ * Creates a default binding.
+ * @param binding - The binding to refresh when changed.
+ * @param isBindingVolatile - Indicates whether the binding is volatile or not.
+ * @returns A binding configuration.
  * @public
  */
-export declare const twoWay: BindingConfig<DefaultTwoWayBindingOptions> & import("./binding.js").BindingConfigResolver<DefaultTwoWayBindingOptions>;
+export declare function twoWay<T = any>(binding: Expression<T>, optionsOrChangeEvent?: TwoWayBindingOptions | string, isBindingVolatile?: boolean): Binding<T>;

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

@@ -1,56 +1,5 @@
-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";
-/**
- * Describes how aspects of an HTML element will be affected by bindings.
- * @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>;
-}>;
+import { ExecutionContext, Expression, ExpressionObserver } from "../observation/observable.js";
+import { AddViewBehaviorFactory, Aspect, Aspected, Binding, HTMLDirective, ViewBehavior, ViewBehaviorFactory, ViewBehaviorTargets } from "./html-directive.js";
 /**
  * The "this" context for an update target function.
  * @public
@@ -73,57 +22,48 @@ export interface UpdateTargetThis {
  */
 export declare type UpdateTarget = (this: UpdateTargetThis, target: Node, aspect: string, value: any, source: any, context: ExecutionContext) => void;
 /**
- * A base binding behavior for DOM updates.
+ * A simple View that can be interpolated into HTML content.
  * @public
  */
-export declare class UpdateBinding implements ViewBehavior {
-    readonly directive: HTMLBindingDirective;
-    protected updateTarget: UpdateTarget;
+export interface ContentView {
     /**
-     * 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.
+     * 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.
      */
-    constructor(directive: HTMLBindingDirective, updateTarget: UpdateTarget);
+    bind(source: any, context: ExecutionContext): 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.
+     * Unbinds a view's behaviors from its binding source and context.
      */
-    bind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
+    unbind(): 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.
+     * Inserts the view's DOM nodes before the referenced node.
+     * @param node - The node to insert the view's DOM before.
      */
-    unbind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
+    insertBefore(node: Node): void;
     /**
-     * Creates a behavior.
-     * @param targets - The targets available for behaviors to be attached to.
+     * Removes the view's DOM nodes.
+     * The nodes are not disposed and the view can later be re-inserted.
      */
-    createBehavior(targets: ViewBehaviorTargets): ViewBehavior;
+    remove(): void;
 }
 /**
- * A binding behavior for one-time bindings.
+ * A simple template that can create ContentView instances.
  * @public
  */
-export declare class OneTimeBinding extends UpdateBinding {
+export interface ContentTemplate {
     /**
-     * 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 simple content view instance.
      */
-    bind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
+    create(): ContentView;
 }
 /**
  * A binding behavior for bindings that change.
  * @public
  */
-export declare class ChangeBinding extends UpdateBinding {
-    private isBindingVolatile;
+export declare class BindingBehavior implements ViewBehavior {
+    readonly directive: HTMLBindingDirective;
+    protected updateTarget: UpdateTarget;
     private observerProperty;
     /**
      * Creates an instance of ChangeBinding.
@@ -131,12 +71,6 @@ export declare class ChangeBinding extends UpdateBinding {
      * @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;
     /**
      * Bind this behavior to the source.
      * @param source - The source to bind to.
@@ -152,13 +86,37 @@ export declare class ChangeBinding extends UpdateBinding {
      */
     unbind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
     /** @internal */
-    handleChange(binding: Binding, observer: BindingObserver): void;
+    handleChange(binding: Expression, observer: ExpressionObserver): void;
+    /**
+     * Returns the binding observer used to update the node.
+     * @param target - The target node.
+     * @returns A BindingObserver.
+     */
+    protected getObserver(target: Node): ExpressionObserver;
+    /**
+     * Creates a behavior.
+     * @param targets - The targets available for behaviors to be attached to.
+     */
+    createBehavior(targets: ViewBehaviorTargets): ViewBehavior;
+}
+/**
+ * A special binding behavior that can bind node content.
+ * @public
+ */
+export declare class ContentBehavior extends BindingBehavior {
+    /**
+     * 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;
 }
 /**
  * A binding behavior for handling events.
  * @public
  */
-export declare class EventBinding {
+export declare class EventBehavior {
     readonly directive: HTMLBindingDirective;
     private contextProperty;
     private sourceProperty;
@@ -191,29 +149,12 @@ export declare class EventBinding {
      */
     handleEvent(event: Event): 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 onTime binding configuration.
- * @public
- */
-export declare const oneTime: BindingConfig<AddEventListenerOptions> & BindingConfigResolver<AddEventListenerOptions>;
 /**
  * A directive that applies bindings.
  * @public
  */
 export declare class HTMLBindingDirective implements HTMLDirective, ViewBehaviorFactory, Aspected {
-    binding: Binding;
-    mode: BindingMode;
-    options: any;
+    dataBinding: Binding;
     private factory;
     /**
      * The unique id of the factory.
@@ -237,11 +178,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.
@@ -254,10 +193,32 @@ export declare class HTMLBindingDirective implements HTMLDirective, ViewBehavior
     createBehavior(targets: ViewBehaviorTargets): ViewBehavior;
 }
 /**
- * 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/html-directive.d.ts

@@ -1,6 +1,7 @@
 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 type { ExecutionContext, Expression, ExpressionObserver } from "../observation/observable.js";
 /**
  * The target nodes available to a behavior.
  * @public
@@ -113,6 +114,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> {
+    /**
+     * Options associated with the binding.
+     */
+    options?: any;
+    /**
+     * Whether or not the binding is volatile.
+     */
+    isVolatile?: boolean;
+    /**
+     * Evaluates the binding expression.
+     */
+    evaluate: Expression<TSource, TReturn, TParent>;
+    /**
+     * 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
@@ -180,7 +206,7 @@ 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.