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

package/dist/dts/testing/fixture.d.ts

@@ -0,0 +1,90 @@
+import type { Constructable } from "../interfaces.js";
+import { ExecutionContext } from "../observation/observable.js";
+import { ViewTemplate } from "../templating/template.js";
+import type { HTMLView } from "../templating/view.js";
+/**
+ * Options used to customize the creation of the test fixture.
+ * @public
+ */
+export interface FixtureOptions {
+    /**
+     * The document to run the fixture in.
+     * @defaultValue `globalThis.document`
+     */
+    document?: Document;
+    /**
+     * The parent element to append the fixture to.
+     * @defaultValue An instance of `HTMLDivElement`.
+     */
+    parent?: HTMLElement;
+    /**
+     * The data source to bind the HTML to.
+     * @defaultValue An empty object.
+     */
+    source?: any;
+    /**
+     * The execution context to use during binding.
+     * @defaultValue {@link @microsoft/fast-element#ExecutionContext}
+     */
+    context?: ExecutionContext;
+}
+/**
+ * A test fixture.
+ * @public
+ */
+export interface Fixture<TElement = HTMLElement> {
+    /**
+     * The document the fixture is running in.
+     */
+    document: Document;
+    /**
+     * The template the fixture was created from.
+     */
+    template: ViewTemplate;
+    /**
+     * The view that was created from the fixture's template.
+     */
+    view: HTMLView;
+    /**
+     * The parent element that the view was appended to.
+     * @remarks
+     * This element will be appended to the DOM only
+     * after {@link Fixture.connect} has been called.
+     */
+    parent: HTMLElement;
+    /**
+     * The first element in the {@link Fixture.view}.
+     */
+    element: TElement;
+    /**
+     * Adds the {@link Fixture.parent} to the DOM, causing the
+     * connect lifecycle to begin.
+     * @remarks
+     * Yields control to the caller one Microtask later, in order to
+     * ensure that the DOM has settled.
+     */
+    connect: () => Promise<void>;
+    /**
+     * Removes the {@link Fixture.parent} from the DOM, causing the
+     * disconnect lifecycle to begin.
+     * @remarks
+     * Yields control to the caller one Microtask later, in order to
+     * ensure that the DOM has settled.
+     */
+    disconnect: () => Promise<void>;
+}
+/**
+ * Creates a random, unique name suitable for use as a Custom Element name.
+ * @public
+ */
+export declare function uniqueElementName(prefix?: string): string;
+/**
+ * Creates a test fixture suitable for testing custom elements, templates, and bindings.
+ * @param templateNameOrType An HTML template or single element name to create the fixture for.
+ * @param options Enables customizing fixture creation behavior.
+ * @remarks
+ * Yields control to the caller one Microtask later, in order to
+ * ensure that the DOM has settled.
+ * @public
+ */
+export declare function fixture<TElement = HTMLElement>(templateNameOrType: ViewTemplate | string | Constructable<TElement>, options?: FixtureOptions): Promise<Fixture<TElement>>;

package/dist/dts/testing/timeout.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A timeout helper for use in tests.
+ * @param timeout The length of the timeout.
+ * @returns A promise that resolves once the configured time has elapsed.
+ * @public
+ */
+export declare function timeout(timeout?: number): Promise<void>;

package/dist/esm/components/fast-definitions.js

@@ -11,19 +11,15 @@ const fastElementRegistry = FAST.getById(4 /* KernelServiceId.elementRegistry */
  * @public
  */
 export class FASTElementDefinition {
-    /**
-     * 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, nameOrConfig = type.definition) {
+        this.platformDefined = false;
         if (isString(nameOrConfig)) {
             nameOrConfig = { name: nameOrConfig };
         }
         this.type = type;
         this.name = nameOrConfig.name;
         this.template = nameOrConfig.template;
+        const proto = type.prototype;
         const attributes = AttributeDefinition.collect(type, nameOrConfig.attributes);
         const observedAttributes = new Array(attributes.length);
         const propertyLookup = {};
@@ -33,9 +29,13 @@ export class FASTElementDefinition {
             observedAttributes[i] = current.attribute;
             propertyLookup[current.name] = current;
             attributeLookup[current.attribute] = current;
+            Observable.defineProperty(proto, current);
         }
+        Reflect.defineProperty(type, "observedAttributes", {
+            value: observedAttributes,
+            enumerable: true,
+        });
         this.attributes = attributes;
-        this.observedAttributes = observedAttributes;
         this.propertyLookup = propertyLookup;
         this.attributeLookup = attributeLookup;
         this.shadowOptions =
@@ -48,43 +48,43 @@ export class FASTElementDefinition {
             nameOrConfig.elementOptions === void 0
                 ? defaultElementOptions
                 : Object.assign(Object.assign({}, defaultElementOptions), nameOrConfig.elementOptions);
-        this.styles =
-            nameOrConfig.styles === void 0
-                ? void 0
-                : Array.isArray(nameOrConfig.styles)
-                    ? new ElementStyles(nameOrConfig.styles)
-                    : nameOrConfig.styles instanceof ElementStyles
-                        ? nameOrConfig.styles
-                        : new ElementStyles([nameOrConfig.styles]);
+        this.styles = ElementStyles.normalize(nameOrConfig.styles);
+        fastElementRegistry.register(this);
     }
     /**
      * Indicates if this element has been defined in at least one registry.
      */
     get isDefined() {
-        return !!fastElementRegistry.getByType(this.type);
+        return this.platformDefined;
     }
     /**
      * 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 = customElements) {
         const type = this.type;
-        if (fastElementRegistry.register(this)) {
-            const attributes = this.attributes;
-            const proto = type.prototype;
-            for (let i = 0, ii = attributes.length; i < ii; ++i) {
-                Observable.defineProperty(proto, attributes[i]);
-            }
-            Reflect.defineProperty(type, "observedAttributes", {
-                value: this.observedAttributes,
-                enumerable: true,
-            });
-        }
         if (!registry.get(this.name)) {
+            this.platformDefined = true;
             registry.define(this.name, type, this.elementOptions);
         }
         return 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(type, nameOrDef) {
+        const found = fastElementRegistry.getByType(type);
+        if (found) {
+            return new FASTElementDefinition(class extends type {
+            }, nameOrDef);
+        }
+        return new FASTElementDefinition(type, nameOrDef);
+    }
 }
 /**
  * Gets the element definition associated with the specified type.

package/dist/esm/components/fast-element.js

@@ -1,3 +1,4 @@
+import { isFunction } from "../interfaces.js";
 import { Controller } from "./controller.js";
 import { FASTElementDefinition, } from "./fast-definitions.js";
 /* eslint-disable-next-line @typescript-eslint/explicit-function-return-type */
@@ -22,6 +23,18 @@ function createFASTElement(BaseType) {
         }
     };
 }
+function compose(type, nameOrDef) {
+    if (isFunction(type)) {
+        return FASTElementDefinition.compose(type, nameOrDef);
+    }
+    return FASTElementDefinition.compose(this, type);
+}
+function define(type, nameOrDef) {
+    if (isFunction(type)) {
+        return FASTElementDefinition.compose(type, nameOrDef).define().type;
+    }
+    return FASTElementDefinition.compose(this, type).define().type;
+}
 /**
  * A minimal base class for FASTElements that also provides
  * static helpers for working with FASTElements.
@@ -42,9 +55,12 @@ export const FASTElement = Object.assign(createFASTElement(HTMLElement), {
      * @param nameOrDef - The name of the element to define or a definition object
      * that describes the element to define.
      */
-    define(type, nameOrDef) {
-        return new FASTElementDefinition(type, nameOrDef).define().type;
-    },
+    define,
+    /**
+     * Defines metadata for a FASTElement which can be used to later define the element.
+     * @public
+     */
+    compose,
 });
 /**
  * Decorator: Defines a platform custom element based on `FASTElement`.
@@ -55,6 +71,6 @@ export const FASTElement = Object.assign(createFASTElement(HTMLElement), {
 export function customElement(nameOrDef) {
     /* eslint-disable-next-line @typescript-eslint/explicit-function-return-type */
     return function (type) {
-        new FASTElementDefinition(type, nameOrDef).define();
+        define(type, nameOrDef);
     };
 }

package/dist/esm/context.js

@@ -0,0 +1,163 @@
+import "./interfaces.js";
+import { Metadata } from "./metadata.js";
+import { FAST } from "./platform.js";
+const contextEventType = "context-request";
+let requestStrategy;
+/**
+ * Enables using the {@link https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md | W3C Community Context protocol.}
+ * @beta
+ */
+export const Context = Object.freeze({
+    /**
+     * The event type used for W3C Context Protocol requests.
+     */
+    eventType: contextEventType,
+    /**
+     * 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(name, initialValue) {
+        const Interface = function (target, property, index) {
+            if (target == null || new.target !== undefined) {
+                throw FAST.error(1501 /* Message.noRegistrationForContext */, {
+                    name: Interface.name,
+                });
+            }
+            if (property) {
+                Context.defineProperty(target, property, Interface);
+            }
+            else {
+                const types = Metadata.getOrCreateAnnotationParamTypes(target);
+                types[index] = Interface;
+            }
+        };
+        Interface.$isInterface = true;
+        Interface.initialValue = initialValue;
+        Reflect.defineProperty(Interface, "name", { value: name });
+        Interface.handle = (target, callback) => Context.handle(target, callback, Interface);
+        Interface.provide = (target, value) => Context.provide(target, Interface, value);
+        Interface.get = (target) => Context.get(target, Interface);
+        Interface.request = (target, callback, multiple) => Context.request(target, Interface, callback, multiple);
+        Interface.toString = () => `Context<${Interface.name}>`;
+        return Interface;
+    },
+    /**
+     * 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) {
+        requestStrategy = strategy;
+    },
+    /**
+     * 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(target, context) {
+        var _a;
+        let value;
+        requestStrategy(target, context, found => (value = found), false);
+        return (_a = value) !== null && _a !== void 0 ? _a : context.initialValue;
+    },
+    /**
+     * 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(target, context, callback, multiple = false) {
+        requestStrategy(target, context, callback, multiple);
+    },
+    /**
+     *
+     * @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(target, context, callback, multiple = false) {
+        target.dispatchEvent(new ContextEvent(context, callback, multiple));
+    },
+    provide(target, context, value) {
+        this.handle(target, (event) => {
+            event.stopImmediatePropagation();
+            event.callback(value);
+        }, context);
+    },
+    /**
+     *
+     * @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(target, callback, context) {
+        if (context) {
+            target.addEventListener(contextEventType, (event) => {
+                if (event.context === context) {
+                    callback(event);
+                }
+            });
+        }
+        else {
+            target.addEventListener(contextEventType, callback);
+        }
+    },
+    /**
+     * 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(target, propertyName, context) {
+        const field = `$di_${propertyName}`;
+        Reflect.defineProperty(target, propertyName, {
+            get: function () {
+                var _a;
+                return (_a = this[field]) !== null && _a !== void 0 ? _a : (this[field] = Context.get(this, context));
+            },
+        });
+    },
+});
+Context.setDefaultRequestStrategy(Context.dispatch);
+/**
+ * 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 class ContextEvent extends Event {
+    constructor(context, callback, multiple) {
+        super(contextEventType, { bubbles: true, composed: true });
+        this.context = context;
+        this.callback = callback;
+        this.multiple = multiple;
+    }
+}

package/dist/esm/debug.js

@@ -11,19 +11,50 @@ const debugMessages = {
     [1101 /* needsArrayObservation */]: "Must call enableArrayObservation before observing arrays.",
     [1201 /* onlySetHTMLPolicyOnce */]: "The HTML policy can only be set once.",
     [1202 /* bindingInnerHTMLRequiresTrustedTypes */]: "To bind innerHTML, you must use a TrustedTypesPolicy.",
+    [1203 /* twoWayBindingRequiresObservables */]: "View=>Model update skipped. To use twoWay binding, the target property must be observable.",
+    [1204 /* hostBindingWithoutHost */]: "No host element is present. Cannot bind host with ${name}.",
+    [1205 /* unsupportedBindingBehavior */]: "The requested binding behavior is not supported by the binding engine.",
     [1401 /* missingElementDefinition */]: "Missing FASTElement definition.",
+    [1501 /* noRegistrationForContext */]: "No registration for Context/Interface '${name}'.",
+    [1502 /* noFactoryForResolver */]: "Dependency injection resolver for '${key}' returned a null factory.",
+    [1503 /* invalidResolverStrategy */]: "Invalid dependency injection resolver strategy specified '${strategy}'.",
+    [1504 /* cannotAutoregisterDependency */]: "Unable to autoregister dependency.",
+    [1505 /* cannotResolveKey */]: "Unable to resolve dependency injection key '${key}'.",
+    [1506 /* cannotConstructNativeFunction */]: "'${name}' is a native function and therefore cannot be safely constructed by DI. If this is intentional, please use a callback or cachedCallback resolver.",
+    [1507 /* cannotJITRegisterNonConstructor */]: "Attempted to jitRegister something that is not a constructor '${value}'. Did you forget to register this dependency?",
+    [1508 /* cannotJITRegisterIntrinsic */]: "Attempted to jitRegister an intrinsic type '${value}'. Did you forget to add @inject(Key)?",
+    [1509 /* cannotJITRegisterInterface */]: "Attempted to jitRegister an interface '${value}'.",
+    [1510 /* invalidResolver */]: "A valid resolver was not returned from the register method.",
+    [1511 /* invalidKey */]: "Key/value cannot be null or undefined. Are you trying to inject/register something that doesn't exist with DI?",
+    [1512 /* noDefaultResolver */]: "'${key}' not registered. Did you forget to add @singleton()?",
+    [1513 /* cyclicDependency */]: "Cyclic dependency found '${name}'.",
 };
+const allPlaceholders = /(\$\{\w+?})/g;
+const placeholder = /\$\{(\w+?)}/g;
+const noValues = Object.freeze({});
+function formatMessage(message, values) {
+    return message
+        .split(allPlaceholders)
+        .map(v => {
+        var _a;
+        const replaced = v.replace(placeholder, "$1");
+        return String((_a = values[replaced]) !== null && _a !== void 0 ? _a : v);
+    })
+        .join("");
+}
 Object.assign(FAST, {
     addMessages(messages) {
         Object.assign(debugMessages, messages);
     },
-    warn(code, ...args) {
+    warn(code, values = noValues) {
         var _a;
-        console.warn((_a = debugMessages[code]) !== null && _a !== void 0 ? _a : "Unknown Warning");
+        const message = (_a = debugMessages[code]) !== null && _a !== void 0 ? _a : "Unknown Warning";
+        console.warn(formatMessage(message, values));
     },
-    error(code, ...args) {
+    error(code, values = noValues) {
         var _a;
-        return new Error((_a = debugMessages[code]) !== null && _a !== void 0 ? _a : "Unknown Error");
+        const message = (_a = debugMessages[code]) !== null && _a !== void 0 ? _a : "Unknown Error";
+        return new Error(formatMessage(message, values));
     },
 });
 export {};