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

package/CHANGELOG.json

@@ -1,6 +1,153 @@
 {
   "name": "@microsoft/fast-element",
   "entries": [
+    {
+      "date": "Mon, 18 Jul 2022 21:10:01 GMT",
+      "tag": "@microsoft/fast-element_v2.0.0-beta.4",
+      "version": "2.0.0-beta.4",
+      "comments": {
+        "prerelease": [
+          {
+            "author": "roeisenb@microsoft.com",
+            "package": "@microsoft/fast-element",
+            "commit": "f9fb9c88902bd81233fb927a7357d4bca7634f29",
+            "comment": "feat: extract all error messages from context and DI"
+          },
+          {
+            "author": "roeisenb@microsoft.com",
+            "package": "@microsoft/fast-element",
+            "commit": "27dc848327b25328e428f67505684d2171b58711",
+            "comment": "feat: introduce new binding API"
+          },
+          {
+            "author": "roeisenb@microsoft.com",
+            "package": "@microsoft/fast-element",
+            "commit": "7f4d6b5587f6eff52e5b7f414e27543bb4d7772d",
+            "comment": "Enabled DOM Container fallback functions when a container cannot be located."
+          },
+          {
+            "author": "roeisenb@microsoft.com",
+            "package": "@microsoft/fast-element",
+            "commit": "0f57d55822bbf97ab69f90efc0a0d100b27e10eb",
+            "comment": "feat: add render directive, renderWith decorator, and RenderInstruction"
+          },
+          {
+            "author": "prudepixie@users.noreply.github.com",
+            "package": "@microsoft/fast-element",
+            "commit": "94e6b0a0e7e1fd1167bd6453c3f7b27efdc91804",
+            "comment": "only store removed views if it can't be reused right away"
+          },
+          {
+            "author": "32497422+KingOfTac@users.noreply.github.com",
+            "package": "@microsoft/fast-element",
+            "commit": "11d5b4075118456b2e7c2a4f32a415eeea94ed7f",
+            "comment": "fix: enable createElementTemplate to have undefined attributes"
+          },
+          {
+            "author": "prudepixie@users.noreply.github.com",
+            "package": "@microsoft/fast-element",
+            "commit": "31296ea2be3981d25f5feb773b2895dbedfaf2c2",
+            "comment": "use index to track reusable views"
+          },
+          {
+            "author": "roeisenb@microsoft.com",
+            "package": "@microsoft/fast-element",
+            "commit": "4567188a47598b3d2589b05f039bea695f2b8875",
+            "comment": "feat: enable render, repeat, and when template helpers to handle static data in addition to the already supported dynamic bindings"
+          },
+          {
+            "author": "roeisenb@microsoft.com",
+            "package": "@microsoft/fast-element",
+            "commit": "f164aa75e62ed71c9386902051c021f1fdfba364",
+            "comment": "fix: FASTElementDefinition#isDefined should be true only after define"
+          },
+          {
+            "author": "roeisenb@microsoft.com",
+            "package": "@microsoft/fast-element",
+            "commit": "aacfde6d1f52a20af5511c5e792f730bd091d452",
+            "comment": "feat: move testing and dependency injection to fast-element"
+          },
+          {
+            "author": "roeisenb@microsoft.com",
+            "package": "@microsoft/fast-element",
+            "commit": "04c51a17dde6d03dc2e2a4de3666cbbec950d900",
+            "comment": "fix: warn when host bindings are accidentally applied on non CE views"
+          },
+          {
+            "author": "roeisenb@microsoft.com",
+            "package": "@microsoft/fast-element",
+            "commit": "b32eb1004960da95b74dba7f111ee859b6655896",
+            "comment": "feat: perf and safety improvements to fast element definition"
+          }
+        ]
+      }
+    },
+    {
+      "date": "Wed, 22 Jun 2022 20:17:50 GMT",
+      "tag": "@microsoft/fast-element_v2.0.0-beta.3",
+      "version": "2.0.0-beta.3",
+      "comments": {
+        "prerelease": [
+          {
+            "comment": "fix: correct aspect type for content that looks like an attribute",
+            "author": "nicholasrice@users.noreply.github.com",
+            "commit": "f28cdb9fdba9cb27904acfad7444de82d447f39e",
+            "package": "@microsoft/fast-element"
+          }
+        ]
+      }
+    },
+    {
+      "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,50 @@
 # 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 Mon, 18 Jul 2022 21:10:01 GMT and should not be manually modified.
 
 <!-- Start content -->
 
+## 2.0.0-beta.4
+
+Mon, 18 Jul 2022 21:10:01 GMT
+
+### Changes
+
+- feat: extract all error messages from context and DI (roeisenb@microsoft.com)
+- feat: introduce new binding API (roeisenb@microsoft.com)
+- Enabled DOM Container fallback functions when a container cannot be located. (roeisenb@microsoft.com)
+- feat: add render directive, renderWith decorator, and RenderInstruction (roeisenb@microsoft.com)
+- only store removed views if it can't be reused right away (prudepixie@users.noreply.github.com)
+- fix: enable createElementTemplate to have undefined attributes (32497422+KingOfTac@users.noreply.github.com)
+- use index to track reusable views (prudepixie@users.noreply.github.com)
+- feat: enable render, repeat, and when template helpers to handle static data in addition to the already supported dynamic bindings (roeisenb@microsoft.com)
+- fix: FASTElementDefinition#isDefined should be true only after define (roeisenb@microsoft.com)
+- feat: move testing and dependency injection to fast-element (roeisenb@microsoft.com)
+- fix: warn when host bindings are accidentally applied on non CE views (roeisenb@microsoft.com)
+- feat: perf and safety improvements to fast element definition (roeisenb@microsoft.com)
+
+## 2.0.0-beta.3
+
+Wed, 22 Jun 2022 20:17:50 GMT
+
+### Changes
+
+- fix: correct aspect type for content that looks like an attribute (nicholasrice@users.noreply.github.com)
+
+## 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

@@ -37,7 +37,7 @@ export interface PartialFASTElementDefinition {
  * @public
  */
 export declare class FASTElementDefinition<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>> {
-    private observedAttributes;
+    private platformDefined;
     /**
      * The type this element definition describes.
      */
@@ -78,18 +78,21 @@ export declare class FASTElementDefinition<TType extends Constructable<HTMLEleme
      * Options controlling how the custom element is defined with the platform.
      */
     readonly elementOptions?: ElementDefinitionOptions;
-    /**
-     * Creates an instance of FASTElementDefinition.
-     * @param type - The type this definition is being created for.
-     * @param nameOrConfig - The name of the element to define or a config object
-     * that describes the element to define.
-     */
-    constructor(type: TType, nameOrConfig?: PartialFASTElementDefinition | string);
+    private constructor();
     /**
      * 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;
+    /**
+     * Creates an instance of FASTElementDefinition.
+     * @param type - The type this definition is being created for.
+     * @param nameOrDef - The name of the element to define or a config object
+     * that describes the element to define.
+     */
+    static compose<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition): FASTElementDefinition<TType>;
     /**
      * Gets the element definition associated with the specified type.
      * @param type - The custom element type to retrieve the definition for.

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

@@ -1,6 +1,6 @@
-import type { Constructable } from "../interfaces.js";
+import { 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
@@ -45,6 +45,10 @@ export interface FASTElement extends HTMLElement {
      */
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
 }
+declare function compose<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(this: TType, nameOrDef: string | PartialFASTElementDefinition): FASTElementDefinition<TType>;
+declare function compose<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition): FASTElementDefinition<TType>;
+declare function define<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(this: TType, nameOrDef: string | PartialFASTElementDefinition): TType;
+declare function define<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition): TType;
 /**
  * A minimal base class for FASTElements that also provides
  * static helpers for working with FASTElements.
@@ -66,7 +70,12 @@ export declare const FASTElement: (new () => HTMLElement & FASTElement) & {
      * @param nameOrDef - The name of the element to define or a definition object
      * that describes the element to define.
      */
-    define<TType extends Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition): TType;
+    define: typeof define;
+    /**
+     * Defines metadata for a FASTElement which can be used to later define the element.
+     * @public
+     */
+    compose: typeof compose;
 };
 /**
  * Decorator: Defines a platform custom element based on `FASTElement`.
@@ -75,3 +84,4 @@ export declare const FASTElement: (new () => HTMLElement & FASTElement) & {
  * @public
  */
 export declare function customElement(nameOrDef: string | PartialFASTElementDefinition): (type: Constructable<HTMLElement>) => void;
+export {};

package/dist/dts/context.d.ts

@@ -0,0 +1,157 @@
+import { 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 {};