@microsoft/fast-element 2.0.0-beta.1 → 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.
@@ -154,7 +170,23 @@ export declare const enum Message {
     needsArrayObservation = 1101,
     onlySetHTMLPolicyOnce = 1201,
     bindingInnerHTMLRequiresTrustedTypes = 1202,
-    missingElementDefinition = 1401
+    twoWayBindingRequiresObservables = 1203,
+    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/metadata.d.ts

@@ -0,0 +1,25 @@
+import type { Constructable } from "./interfaces.js";
+/**
+ * Provides basic metadata capabilities used by Context and Dependency Injection.
+ */
+export declare const Metadata: Readonly<{
+    /**
+     * Gets the "design:paramtypes" metadata for the specified type.
+     * @param Type - The type to get the metadata for.
+     * @returns The metadata array or a frozen empty array if no metadata is found.
+     */
+    getDesignParamTypes: (Type: any) => any;
+    /**
+     * Gets the "annotation:paramtypes" metadata for the specified type.
+     * @param Type - The type to get the metadata for.
+     * @returns The metadata array or a frozen empty array if no metadata is found.
+     */
+    getAnnotationParamTypes: (Type: any) => any;
+    /**
+     *
+     * @param Type - Gets the "annotation:paramtypes" metadata for the specified type. If none is found,
+     * an empty, mutable metadata array is created and added.
+     * @returns The metadata array.
+     */
+    getOrCreateAnnotationParamTypes(Type: Constructable): any[];
+}>;

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

@@ -204,4 +204,4 @@ export declare const ArrayObserver: Readonly<{
  * @returns The length of the array.
  * @public
  */
-export declare function length<T>(array: readonly T[]): number;
+export declare function lengthOf<T>(array: readonly T[]): number;

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

@@ -1,19 +1,19 @@
-import type { ExecutionContext, RootContext } from "./observable.js";
+import type { ExecutionContext } from "./observable.js";
 /**
  * Represents an object that can contribute behavior to a view or
  * element's bind/unbind operations.
  * @public
  */
-export interface Behavior<TSource = any, TParent = any, TContext extends ExecutionContext<TParent> = RootContext> {
+export interface Behavior<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.
      */
-    bind(source: TSource, context: TContext): void;
+    bind(source: TSource, context: ExecutionContext<TParent>): void;
     /**
      * Unbinds this behavior from the source.
      * @param source - The source to unbind from.
      */
-    unbind(source: TSource, context: TContext): void;
+    unbind(source: TSource, context: ExecutionContext<TParent>): void;
 }

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, TContext extends ExecutionContext = ExecutionContext> = (source: TSource, context: TContext) => 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, ExecutionContext<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, ExecutionContext<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.
@@ -147,31 +153,19 @@ export declare function volatile(target: {}, name: string | Accessor, descriptor
  * Provides additional contextual information available to behaviors and expressions.
  * @public
  */
-export interface RootContext {
+export declare class ExecutionContext<TParentSource = any> {
     /**
-     * The current event within an event handler.
+     * The default execution context.
      */
-    readonly event: Event;
+    static readonly default: ExecutionContext<any>;
     /**
-     * Returns the typed event detail of a custom event.
+     * The index of the current item within a repeat context.
      */
-    eventDetail<TDetail = any>(): TDetail;
+    index: number;
     /**
-     * Returns the typed event target of the event.
+     * The length of the current collection within a repeat context.
      */
-    eventTarget<TTarget extends EventTarget = EventTarget>(): TTarget;
-    /**
-     * Creates a new execution context descendent from the current context.
-     * @param source - The source for the context if different than the parent.
-     * @returns A child execution context.
-     */
-    createChildContext<TParentSource>(source: TParentSource): ChildContext<TParentSource>;
-}
-/**
- * Provides additional contextual information when inside a child template.
- * @public
- */
-export interface ChildContext<TParentSource = any> extends RootContext {
+    length: number;
     /**
      * The parent data source within a nested context.
      */
@@ -179,80 +173,73 @@ export interface ChildContext<TParentSource = any> extends RootContext {
     /**
      * The parent execution context when in nested context scenarios.
      */
-    readonly parentContext: ChildContext<TParentSource>;
+    readonly parentContext: ExecutionContext<TParentSource>;
+    private constructor();
     /**
-     * Creates a new execution context descent suitable for use in list rendering.
-     * @param item - The list item to serve as the source.
-     * @param index - The index of the item in the list.
-     * @param length - The length of the list.
-     */
-    createItemContext(index: number, length: number): ItemContext<TParentSource>;
-}
-/**
- * Provides additional contextual information when inside a repeat item template.s
- * @public
- */
-export interface ItemContext<TParentSource = any> extends ChildContext<TParentSource> {
-    /**
-     * The index of the current item within a repeat context.
-     */
-    readonly index: number;
-    /**
-     * The length of the current collection within a repeat context.
+     * The current event within an event handler.
      */
-    readonly length: number;
+    get event(): Event;
     /**
      * Indicates whether the current item within a repeat context
      * has an even index.
      */
-    readonly isEven: boolean;
+    get isEven(): boolean;
     /**
      * Indicates whether the current item within a repeat context
      * has an odd index.
      */
-    readonly isOdd: boolean;
+    get isOdd(): boolean;
     /**
      * Indicates whether the current item within a repeat context
      * is the first item in the collection.
      */
-    readonly isFirst: boolean;
+    get isFirst(): boolean;
     /**
      * Indicates whether the current item within a repeat context
      * is somewhere in the middle of the collection.
      */
-    readonly isInMiddle: boolean;
+    get isInMiddle(): boolean;
     /**
      * Indicates whether the current item within a repeat context
      * is the last item in the collection.
      */
-    readonly isLast: boolean;
+    get isLast(): boolean;
+    /**
+     * Returns the typed event detail of a custom event.
+     */
+    eventDetail<TDetail>(): TDetail;
+    /**
+     * Returns the typed event target of the event.
+     */
+    eventTarget<TTarget extends EventTarget>(): TTarget;
     /**
      * Updates the position/size on a context associated with a list item.
      * @param index - The new index of the item.
      * @param length - The new length of the list.
      */
     updatePosition(index: number, length: number): void;
-}
-/**
- * The common execution context APIs.
- * @public
- */
-export declare const ExecutionContext: Readonly<{
-    default: RootContext;
+    /**
+     * Creates a new execution context descendent from the current context.
+     * @param source - The source for the context if different than the parent.
+     * @returns A child execution context.
+     */
+    createChildContext<TParentSource>(parentSource: TParentSource): ExecutionContext<TParentSource>;
+    /**
+     * Creates a new execution context descent suitable for use in list rendering.
+     * @param item - The list item to serve as the source.
+     * @param index - The index of the item in the list.
+     * @param length - The length of the list.
+     */
+    createItemContext(index: number, length: number): ExecutionContext<TParentSource>;
     /**
      * Sets the event for the current execution context.
      * @param event - The event to set.
      * @internal
      */
-    setEvent(event: Event | null): void;
+    static setEvent(event: Event | null): void;
     /**
      * Creates a new root execution context.
      * @returns A new execution context.
      */
-    create(): RootContext;
-}>;
-/**
- * Represents some sort of execution context.
- * @public
- */
-export declare type ExecutionContext<TParentSource = any> = RootContext | ChildContext<TParentSource> | ItemContext<TParentSource>;
+    static create(): ExecutionContext;
+}

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

@@ -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 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 function signal<T = any>(binding: Expression<T>, options: string | Expression<T>): Binding<T>;

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

@@ -0,0 +1,31 @@
+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;
+}
+/**
+ * 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 function twoWay<T = any>(binding: Expression<T>, optionsOrChangeEvent?: TwoWayBindingOptions | string, isBindingVolatile?: boolean): Binding<T>;