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

package/CHANGELOG.json

@@ -1,6 +1,57 @@
 {
   "name": "@microsoft/fast-element",
   "entries": [
+    {
+      "date": "Wed, 15 Jun 2022 17:41:10 GMT",
+      "tag": "@microsoft/fast-element_v2.0.0-beta.2",
+      "version": "2.0.0-beta.2",
+      "comments": {
+        "prerelease": [
+          {
+            "comment": "doc: add note to FASTElement.metadata API",
+            "author": "roeisenb@microsoft.com",
+            "commit": "359467f9ae67c46a33dfc28ce86dfd908072695d",
+            "package": "@microsoft/fast-element"
+          },
+          {
+            "comment": "when recycle is set to false while itemBinding stays the same, views should be recreated",
+            "author": "wendy.hsu@microsoft.com",
+            "commit": "9c92b9bb5bc9bf221b439c0a776b3621fdd9d9aa",
+            "package": "@microsoft/fast-element"
+          },
+          {
+            "comment": "feat: simplify execution context to align closer with v1",
+            "author": "roeisenb@microsoft.com",
+            "commit": "488d051999c43b93a0beef4db30a2bddd6bbdc64",
+            "package": "@microsoft/fast-element"
+          },
+          {
+            "comment": "feat: ergo improvements to context, array length, and metadata",
+            "author": "roeisenb@microsoft.com",
+            "commit": "12f5671e215ebd2b95c9cc83f856e233e01e9c4a",
+            "package": "@microsoft/fast-element"
+          },
+          {
+            "comment": "feat: move optional bindings out of rollup and list as exports",
+            "author": "roeisenb@microsoft.com",
+            "commit": "e86a638b9e84cbf36d950025889742944e68e512",
+            "package": "@microsoft/fast-element"
+          },
+          {
+            "comment": "fix: make SyntheticViewTemplate type a string so it is generally usable",
+            "author": "roeisenb@microsoft.com",
+            "commit": "de7f234ef871204fcac2b5df59433d919809341d",
+            "package": "@microsoft/fast-element"
+          },
+          {
+            "comment": "feat: implement W3C WC community context protocol and integrate with DI",
+            "author": "roeisenb@microsoft.com",
+            "commit": "c45297c0ca48b7e5f4343ba48e5183f2bccdb946",
+            "package": "@microsoft/fast-element"
+          }
+        ]
+      }
+    },
     {
       "date": "Wed, 01 Jun 2022 17:53:14 GMT",
       "tag": "@microsoft/fast-element_v2.0.0-beta.1",

package/CHANGELOG.md

@@ -1,9 +1,23 @@
 # Change Log - @microsoft/fast-element
 
-This log was last generated on Wed, 01 Jun 2022 17:53:14 GMT and should not be manually modified.
+This log was last generated on Wed, 15 Jun 2022 17:41:10 GMT and should not be manually modified.
 
 <!-- Start content -->
 
+## 2.0.0-beta.2
+
+Wed, 15 Jun 2022 17:41:10 GMT
+
+### Changes
+
+- doc: add note to FASTElement.metadata API (roeisenb@microsoft.com)
+- when recycle is set to false while itemBinding stays the same, views should be recreated (wendy.hsu@microsoft.com)
+- feat: simplify execution context to align closer with v1 (roeisenb@microsoft.com)
+- feat: ergo improvements to context, array length, and metadata (roeisenb@microsoft.com)
+- feat: move optional bindings out of rollup and list as exports (roeisenb@microsoft.com)
+- fix: make SyntheticViewTemplate type a string so it is generally usable (roeisenb@microsoft.com)
+- feat: implement W3C WC community context protocol and integrate with DI (roeisenb@microsoft.com)
+
 ## 2.0.0-beta.1
 
 Wed, 01 Jun 2022 17:53:14 GMT

package/dist/dts/components/fast-definitions.d.ts

@@ -88,6 +88,8 @@ export declare class FASTElementDefinition<TType extends Constructable<HTMLEleme
     /**
      * Defines a custom element based on this definition.
      * @param registry - The element registry to define the element in.
+     * @remarks
+     * This operation is idempotent per registry.
      */
     define(registry?: CustomElementRegistry): this;
     /**

package/dist/dts/components/fast-element.d.ts

@@ -1,6 +1,6 @@
 import type { Constructable } from "../interfaces.js";
 import { Controller } from "./controller.js";
-import { PartialFASTElementDefinition } from "./fast-definitions.js";
+import { FASTElementDefinition, PartialFASTElementDefinition } from "./fast-definitions.js";
 /**
  * Represents a custom element based on the FASTElement infrastructure.
  * @public
@@ -67,6 +67,12 @@ export declare const FASTElement: (new () => HTMLElement & FASTElement) & {
      * that describes the element to define.
      */
     define<TType extends Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition): TType;
+    /**
+     * Defines metadata for a FASTElement which can be used to later define the element.
+     * IMPORTANT: This API will be renamed to "compose" in a future beta.
+     * @public
+     */
+    metadata<TType_1 extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType_1, nameOrDef?: string | PartialFASTElementDefinition): FASTElementDefinition<TType_1>;
 };
 /**
  * Decorator: Defines a platform custom element based on `FASTElement`.

package/dist/dts/context.d.ts

@@ -0,0 +1,157 @@
+import type { Constructable } from "./interfaces.js";
+/**
+ * A Context object defines an optional initial value for a Context, as well as a name identifier for debugging purposes.
+ * @public
+ */
+export declare type Context<T> = {
+    readonly name: string;
+    readonly initialValue?: T;
+};
+/**
+ * A constant key that can be used to represent a Context dependency.
+ * The key can be used for context or DI but also doubles as a decorator for
+ * resolving the associated dependency.
+ * @beta
+ */
+export declare type ContextDecorator<T = any> = Readonly<Context<T>> & PropertyDecorator & ParameterDecorator;
+/**
+ * A Context object defines an optional initial value for a Context, as well as a name identifier for debugging purposes.
+ * The FASTContext can also be used as a decorator to declare context dependencies or as a key for DI.
+ * @beta
+ */
+export declare type FASTContext<T> = ContextDecorator<T> & {
+    get(target: EventTarget): T;
+    provide(target: EventTarget, value: T): void;
+    request(target: EventTarget, callback: ContextCallback<T>, multiple?: boolean): void;
+    handle(target: EventTarget, callback: (event: ContextEvent<FASTContext<T>>) => void): any;
+};
+/**
+ * A strategy that controls how all Context.request API calls are handled.
+ * @remarks
+ * By default this is handled via Context.dispatch, which dispatched a ContextEvent.
+ * @beta
+ */
+export declare type FASTContextRequestStrategy = <T extends UnknownContext>(target: EventTarget, context: T, callback: ContextCallback<ContextType<T>>, multiple: any) => void;
+declare const contextEventType = "context-request";
+/**
+ * Enables using the {@link https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md | W3C Community Context protocol.}
+ * @beta
+ */
+export declare const Context: Readonly<{
+    /**
+     * The event type used for W3C Context Protocol requests.
+     */
+    eventType: "context-request";
+    /**
+     * Creates a W3C Community Protocol-based Context object to use in requesting/providing
+     * context through the DOM.
+     * @param name - The name to use for the connext. Useful in debugging.
+     * @param initialValue - An optional initial value to use if a context handler isn't found.
+     */
+    create<T = unknown>(name: string, initialValue?: T | undefined): FASTContext<T>;
+    /**
+     * Sets the strategy used by all FAST-specific context requests made through the
+     * Context.request, Context.get, Context.defineProperty, and ContextDecorator APIs.
+     * @param strategy - The strategy to use. By default, the strategy is Context.dispatch.
+     */
+    setDefaultRequestStrategy(strategy: FASTContextRequestStrategy): void;
+    /**
+     * Gets the context value for the target node or returns the initial value if
+     * a context handler is not found.
+     * @param target - The target to get the context for.
+     * @param context - The context to locate.
+     * @returns The context value.
+     * @remarks
+     * Uses the default request strategy to locate the context. If no context is found
+     * then the initial value of the context is returned.
+     */
+    get<T_1 extends UnknownContext>(target: EventTarget, context: T_1): ContextType<T_1>;
+    /**
+     * Requests the context value for the target node.
+     * @param target - The target to request the context for.
+     * @param context - The context to locate.
+     * @param callback - A callback to invoke with the context value.
+     * @param multiple - Whether the context requestor expects to handle updates
+     * to the context value after the initial request.
+     * @remarks
+     * Uses the default request strategy to locate the context.
+     */
+    request<T_2 extends UnknownContext>(target: EventTarget, context: T_2, callback: ContextCallback<ContextType<T_2>>, multiple?: boolean): void;
+    /**
+     *
+     * @param target - The target to dispatch the context event on.
+     * @param context - The context to locate.
+     * @param callback - The callback to invoke with the context value.
+     * @param multiple - Whether the context requestor expects to handle updates
+     * to the context value after the initial request.
+     * @remarks
+     * This API does NOT use the default request strategy. It always dispatches
+     * an event through the DOM.
+     */
+    dispatch<T_3 extends UnknownContext>(target: EventTarget, context: T_3, callback: ContextCallback<ContextType<T_3>>, multiple?: boolean): void;
+    provide<T_4 extends UnknownContext>(target: EventTarget, context: T_4, value: ContextType<T_4>): void;
+    /**
+     *
+     * @param target - The target on which to handle context requests.
+     * @param callback - The callback to invoke when a context request is received.
+     * @param context - The context to handle requests for.
+     * @remarks
+     * If a context is not provided then the callback will be invoked for all context
+     * requests that are received on the target.
+     */
+    handle<T_5 extends UnknownContext>(target: EventTarget, callback: (event: ContextEvent<T_5>) => void, context?: T_5 | undefined): void;
+    /**
+     * Defines a getter-only property on the target that will return the context
+     * value for the target.
+     * @param target The target to define the property on.
+     * @param propertyName The name of the property to define.
+     * @param context The context that will be used to retrieve the property value.
+     * @remarks
+     * Uses the default request strategy to locate the context and will return the
+     * initialValue if the context isn't handled.
+     */
+    defineProperty<T_6 extends UnknownContext>(target: Constructable<EventTarget> | EventTarget, propertyName: string, context: T_6): void;
+}>;
+/**
+ * An unknown context type.
+ * @public
+ */
+export declare type UnknownContext = Context<unknown>;
+/**
+ * A helper type which can extract a Context value type from a Context type
+ * @public
+ */
+export declare type ContextType<T extends UnknownContext> = T extends Context<infer Y> ? Y : never;
+/**
+ * A callback which is provided by a context requester and is called with the value satisfying the request.
+ * This callback can be called multiple times by context providers as the requested value is changed.
+ * @public
+ */
+export declare type ContextCallback<ValueType> = (value: ValueType, dispose?: () => void) => void;
+/**
+ * An event fired by a context requester to signal it desires a named context.
+ *
+ * A provider should inspect the `context` property of the event to determine if it has a value that can
+ * satisfy the request, calling the `callback` with the requested value if so.
+ *
+ * If the requested context event contains a truthy `multiple` value, then a provider can call the callback
+ * multiple times if the value is changed, if this is the case the provider should pass a `dispose`
+ * method to the callback which requesters can invoke to indicate they no longer wish to receive these updates.
+ * @public
+ */
+export declare class ContextEvent<T extends UnknownContext> extends Event {
+    readonly context: T;
+    readonly callback: ContextCallback<ContextType<T>>;
+    readonly multiple?: boolean | undefined;
+    constructor(context: T, callback: ContextCallback<ContextType<T>>, multiple?: boolean | undefined);
+}
+declare global {
+    interface HTMLElementEventMap {
+        /**
+         * A 'context-request' event can be emitted by any element which desires
+         * a context value to be injected by an external provider.
+         */
+        [contextEventType]: ContextEvent<UnknownContext>;
+    }
+}
+export {};

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

@@ -26,7 +26,7 @@ export interface Accessor {
  * as part of a template binding update.
  * @public
  */
-export declare type Binding<TSource = any, TReturn = any, TContext extends ExecutionContext = ExecutionContext> = (source: TSource, context: TContext) => TReturn;
+export declare type Binding<TSource = any, TReturn = any, TParent = any> = (source: TSource, context: ExecutionContext<TParent>) => TReturn;
 /**
  * A record of observable property access.
  * @public
@@ -120,13 +120,13 @@ export declare const Observable: Readonly<{
      * @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: Binding<TSource, TReturn, any>, initialSubscriber?: Subscriber, isVolatileBinding?: boolean): BindingObserver<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: Binding<TSource_1, TReturn_1, any>): boolean;
 }>;
 /**
  * Decorator: Defines an observable property on the target.
@@ -147,31 +147,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.
-     */
-    readonly event: Event;
-    /**
-     * Returns the typed event detail of a custom event.
+     * The default execution context.
      */
-    eventDetail<TDetail = any>(): TDetail;
+    static readonly default: ExecutionContext<any>;
     /**
-     * Returns the typed event target of the event.
+     * The index of the current item within a repeat context.
      */
-    eventTarget<TTarget extends EventTarget = EventTarget>(): TTarget;
+    index: number;
     /**
-     * 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.
+     * The length of the current collection within a repeat 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 +167,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/templating/binding-signal.d.ts

@@ -0,0 +1,38 @@
+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;
+    /**
+     * Sends the specified signal to signaled bindings.
+     * @param signal - The signal to send.
+     * @public
+     */
+    static send(signal: string): void;
+}
+/**
+ * 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, any>) => BindingConfig<string | Binding<T, any, any>>;

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

@@ -0,0 +1,56 @@
+import type { ExecutionContext } from "../observation/observable.js";
+import { BindingConfig, ChangeBinding, DefaultBindingOptions, HTMLBindingDirective } from "./binding.js";
+import type { ViewBehaviorTargets } from "./html-directive.js";
+/**
+ * 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;
+}
+/**
+ * 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.
+ * @public
+ */
+export declare const twoWay: BindingConfig<DefaultTwoWayBindingOptions> & import("./binding.js").BindingConfigResolver<DefaultTwoWayBindingOptions>;