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

package/dist/esm/components/controller.js

@@ -1,6 +1,7 @@
-import { DOM } from "../dom.js";
+import "../interfaces.js";
 import { PropertyChangeNotifier } from "../observation/notifier.js";
-import { defaultExecutionContext, Observable } from "../observation/observable.js";
+import { ExecutionContext, Observable } from "../observation/observable.js";
+import { FAST } from "../platform.js";
 import { FASTElementDefinition } from "./fast-definitions.js";
 const shadowRoots = new WeakMap();
 const defaultEventOptions = {
@@ -9,8 +10,10 @@ const defaultEventOptions = {
     cancelable: true,
 };
 function getShadowRoot(element) {
-    return element.shadowRoot || shadowRoots.get(element) || null;
+    var _a, _b;
+    return (_b = (_a = element.shadowRoot) !== null && _a !== void 0 ? _a : shadowRoots.get(element)) !== null && _b !== void 0 ? _b : null;
 }
+const isConnectedPropertyName = "isConnected";
 /**
  * Controls the lifecycle and rendering of a `FASTElement`.
  * @public
@@ -28,6 +31,7 @@ export class Controller extends PropertyChangeNotifier {
         this.boundObservables = null;
         this.behaviors = null;
         this.needsInitialization = true;
+        this.hasExistingShadowRoot = false;
         this._template = null;
         this._styles = null;
         this._isConnected = false;
@@ -50,9 +54,15 @@ export class Controller extends PropertyChangeNotifier {
         this.definition = definition;
         const shadowOptions = definition.shadowOptions;
         if (shadowOptions !== void 0) {
-            const shadowRoot = element.attachShadow(shadowOptions);
-            if (shadowOptions.mode === "closed") {
-                shadowRoots.set(element, shadowRoot);
+            let shadowRoot = element.shadowRoot;
+            if (shadowRoot) {
+                this.hasExistingShadowRoot = true;
+            }
+            else {
+                shadowRoot = element.attachShadow(shadowOptions);
+                if (shadowOptions.mode === "closed") {
+                    shadowRoots.set(element, shadowRoot);
+                }
             }
         }
         // Capture any observable values that were set by the binding engine before
@@ -77,12 +87,12 @@ export class Controller extends PropertyChangeNotifier {
      * connected to the document.
      */
     get isConnected() {
-        Observable.track(this, "isConnected");
+        Observable.track(this, isConnectedPropertyName);
         return this._isConnected;
     }
     setIsConnected(value) {
         this._isConnected = value;
-        Observable.notify(this, "isConnected");
+        Observable.notify(this, isConnectedPropertyName);
     }
     /**
      * Gets/sets the template used to render the component.
@@ -90,6 +100,19 @@ export class Controller extends PropertyChangeNotifier {
      * This value can only be accurately read after connect but can be set at any time.
      */
     get template() {
+        var _a;
+        // 1. Template overrides take top precedence.
+        if (this._template === null) {
+            const definition = this.definition;
+            if (this.element.resolveTemplate) {
+                // 2. Allow for element instance overrides next.
+                this._template = this.element.resolveTemplate();
+            }
+            else if (definition.template) {
+                // 3. Default to the static definition.
+                this._template = (_a = definition.template) !== null && _a !== void 0 ? _a : null;
+            }
+        }
         return this._template;
     }
     set template(value) {
@@ -107,6 +130,19 @@ export class Controller extends PropertyChangeNotifier {
      * This value can only be accurately read after connect but can be set at any time.
      */
     get styles() {
+        var _a;
+        // 1. Styles overrides take top precedence.
+        if (this._styles === null) {
+            const definition = this.definition;
+            if (this.element.resolveStyles) {
+                // 2. Allow for element instance overrides next.
+                this._styles = this.element.resolveStyles();
+            }
+            else if (definition.styles) {
+                // 3. Default to the static definition.
+                this._styles = (_a = definition.styles) !== null && _a !== void 0 ? _a : null;
+            }
+        }
         return this._styles;
     }
     set styles(value) {
@@ -117,7 +153,7 @@ export class Controller extends PropertyChangeNotifier {
             this.removeStyles(this._styles);
         }
         this._styles = value;
-        if (!this.needsInitialization && value !== null) {
+        if (!this.needsInitialization) {
             this.addStyles(value);
         }
     }
@@ -126,9 +162,12 @@ export class Controller extends PropertyChangeNotifier {
      * @param styles - The styles to add.
      */
     addStyles(styles) {
+        if (!styles) {
+            return;
+        }
         const target = getShadowRoot(this.element) ||
             this.element.getRootNode();
-        if (styles instanceof HTMLStyleElement) {
+        if (styles instanceof HTMLElement) {
             target.append(styles);
         }
         else if (!styles.isAttachedTo(target)) {
@@ -144,9 +183,12 @@ export class Controller extends PropertyChangeNotifier {
      * @param styles - the styles to remove.
      */
     removeStyles(styles) {
+        if (!styles) {
+            return;
+        }
         const target = getShadowRoot(this.element) ||
             this.element.getRootNode();
-        if (styles instanceof HTMLStyleElement) {
+        if (styles instanceof HTMLElement) {
             target.removeChild(styles);
         }
         else if (styles.isAttachedTo(target)) {
@@ -162,7 +204,8 @@ export class Controller extends PropertyChangeNotifier {
      * @param behaviors - The behaviors to add.
      */
     addBehaviors(behaviors) {
-        const targetBehaviors = this.behaviors || (this.behaviors = new Map());
+        var _a;
+        const targetBehaviors = (_a = this.behaviors) !== null && _a !== void 0 ? _a : (this.behaviors = new Map());
         const length = behaviors.length;
         const behaviorsToBind = [];
         for (let i = 0; i < length; ++i) {
@@ -177,8 +220,9 @@ export class Controller extends PropertyChangeNotifier {
         }
         if (this._isConnected) {
             const element = this.element;
+            const context = ExecutionContext.default;
             for (let i = 0; i < behaviorsToBind.length; ++i) {
-                behaviorsToBind[i].bind(element, defaultExecutionContext);
+                behaviorsToBind[i].bind(element, context);
             }
         }
     }
@@ -205,8 +249,9 @@ export class Controller extends PropertyChangeNotifier {
         }
         if (this._isConnected) {
             const element = this.element;
+            const context = ExecutionContext.default;
             for (let i = 0; i < behaviorsToUnbind.length; ++i) {
-                behaviorsToUnbind[i].unbind(element);
+                behaviorsToUnbind[i].unbind(element, context);
             }
         }
     }
@@ -218,16 +263,17 @@ export class Controller extends PropertyChangeNotifier {
             return;
         }
         const element = this.element;
+        const context = ExecutionContext.default;
         if (this.needsInitialization) {
             this.finishInitialization();
         }
         else if (this.view !== null) {
-            this.view.bind(element, defaultExecutionContext);
+            this.view.bind(element, context);
         }
         const behaviors = this.behaviors;
         if (behaviors !== null) {
-            for (const [behavior] of behaviors) {
-                behavior.bind(element, defaultExecutionContext);
+            for (const behavior of behaviors.keys()) {
+                behavior.bind(element, context);
             }
         }
         this.setIsConnected(true);
@@ -247,8 +293,9 @@ export class Controller extends PropertyChangeNotifier {
         const behaviors = this.behaviors;
         if (behaviors !== null) {
             const element = this.element;
-            for (const [behavior] of behaviors) {
-                behavior.unbind(element);
+            const context = ExecutionContext.default;
+            for (const behavior of behaviors.keys()) {
+                behavior.unbind(element, context);
             }
         }
     }
@@ -290,55 +337,28 @@ export class Controller extends PropertyChangeNotifier {
             }
             this.boundObservables = null;
         }
-        const definition = this.definition;
-        // 1. Template overrides take top precedence.
-        if (this._template === null) {
-            if (this.element.resolveTemplate) {
-                // 2. Allow for element instance overrides next.
-                this._template = this.element.resolveTemplate();
-            }
-            else if (definition.template) {
-                // 3. Default to the static definition.
-                this._template = definition.template || null;
-            }
-        }
-        // If we have a template after the above process, render it.
-        // If there's no template, then the element author has opted into
-        // custom rendering and they will managed the shadow root's content themselves.
-        if (this._template !== null) {
-            this.renderTemplate(this._template);
-        }
-        // 1. Styles overrides take top precedence.
-        if (this._styles === null) {
-            if (this.element.resolveStyles) {
-                // 2. Allow for element instance overrides next.
-                this._styles = this.element.resolveStyles();
-            }
-            else if (definition.styles) {
-                // 3. Default to the static definition.
-                this._styles = definition.styles || null;
-            }
-        }
-        // If we have styles after the above process, add them.
-        if (this._styles !== null) {
-            this.addStyles(this._styles);
-        }
+        this.renderTemplate(this.template);
+        this.addStyles(this.styles);
         this.needsInitialization = false;
     }
     renderTemplate(template) {
+        var _a;
         const element = this.element;
         // When getting the host to render to, we start by looking
         // up the shadow root. If there isn't one, then that means
         // we're doing a Light DOM render to the element's direct children.
-        const host = getShadowRoot(element) || element;
+        const host = (_a = getShadowRoot(element)) !== null && _a !== void 0 ? _a : element;
         if (this.view !== null) {
             // If there's already a view, we need to unbind and remove through dispose.
             this.view.dispose();
             this.view = null;
         }
-        else if (!this.needsInitialization) {
+        else if (!this.needsInitialization || this.hasExistingShadowRoot) {
+            this.hasExistingShadowRoot = false;
             // If there was previous custom rendering, we need to clear out the host.
-            DOM.removeChildNodes(host);
+            for (let child = host.firstChild; child !== null; child = host.firstChild) {
+                host.removeChild(child);
+            }
         }
         if (template) {
             // If a new template was provided, render it.
@@ -358,9 +378,9 @@ export class Controller extends PropertyChangeNotifier {
         if (controller !== void 0) {
             return controller;
         }
-        const definition = FASTElementDefinition.forType(element.constructor);
+        const definition = FASTElementDefinition.getForInstance(element);
         if (definition === void 0) {
-            throw new Error("Missing FASTElement definition.");
+            throw FAST.error(1401 /* Message.missingElementDefinition */);
         }
         return (element.$fastController = new Controller(element, definition));
     }

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

@@ -1,24 +1,11 @@
-import { FAST } from "../platform.js";
+import { isString } from "../interfaces.js";
 import { Observable } from "../observation/observable.js";
+import { createTypeRegistry, FAST } from "../platform.js";
 import { ElementStyles } from "../styles/element-styles.js";
 import { AttributeDefinition } from "./attributes.js";
 const defaultShadowOptions = { mode: "open" };
 const defaultElementOptions = {};
-const fastRegistry = FAST.getById(4 /* elementRegistry */, () => {
-    const typeToDefinition = new Map();
-    return Object.freeze({
-        register(definition) {
-            if (typeToDefinition.has(definition.type)) {
-                return false;
-            }
-            typeToDefinition.set(definition.type, definition);
-            return true;
-        },
-        getByType(key) {
-            return typeToDefinition.get(key);
-        },
-    });
-});
+const fastElementRegistry = FAST.getById(4 /* KernelServiceId.elementRegistry */, () => createTypeRegistry());
 /**
  * Defines metadata for a FASTElement.
  * @public
@@ -31,7 +18,7 @@ export class FASTElementDefinition {
      * that describes the element to define.
      */
     constructor(type, nameOrConfig = type.definition) {
-        if (typeof nameOrConfig === "string") {
+        if (isString(nameOrConfig)) {
             nameOrConfig = { name: nameOrConfig };
         }
         this.type = type;
@@ -65,24 +52,26 @@ export class FASTElementDefinition {
             nameOrConfig.styles === void 0
                 ? void 0
                 : Array.isArray(nameOrConfig.styles)
-                    ? ElementStyles.create(nameOrConfig.styles)
+                    ? new ElementStyles(nameOrConfig.styles)
                     : nameOrConfig.styles instanceof ElementStyles
                         ? nameOrConfig.styles
-                        : ElementStyles.create([nameOrConfig.styles]);
+                        : new ElementStyles([nameOrConfig.styles]);
     }
     /**
      * Indicates if this element has been defined in at least one registry.
      */
     get isDefined() {
-        return !!fastRegistry.getByType(this.type);
+        return !!fastElementRegistry.getByType(this.type);
     }
     /**
      * 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 (fastRegistry.register(this)) {
+        if (fastElementRegistry.register(this)) {
             const attributes = this.attributes;
             const proto = type.prototype;
             for (let i = 0, ii = attributes.length; i < ii; ++i) {
@@ -103,4 +92,9 @@ export class FASTElementDefinition {
  * Gets the element definition associated with the specified type.
  * @param type - The custom element type to retrieve the definition for.
  */
-FASTElementDefinition.forType = fastRegistry.getByType;
+FASTElementDefinition.getByType = fastElementRegistry.getByType;
+/**
+ * Gets the element definition associated with the instance.
+ * @param instance - The custom element instance to retrieve the definition for.
+ */
+FASTElementDefinition.getForInstance = fastElementRegistry.getForInstance;

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

@@ -43,7 +43,15 @@ export const FASTElement = Object.assign(createFASTElement(HTMLElement), {
      * that describes the element to define.
      */
     define(type, nameOrDef) {
-        return new FASTElementDefinition(type, nameOrDef).define().type;
+        return this.metadata(type, nameOrDef).define().type;
+    },
+    /**
+     * 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(type, nameOrDef) {
+        return new FASTElementDefinition(type, nameOrDef);
     },
 });
 /**
@@ -55,6 +63,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();
+        FASTElement.define(type, nameOrDef);
     };
 }

package/dist/esm/context.js

@@ -0,0 +1,159 @@
+import { Metadata } from "./metadata.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 new Error(`No registration for context: '${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

@@ -0,0 +1,30 @@
+if (globalThis.FAST === void 0) {
+    Reflect.defineProperty(globalThis, "FAST", {
+        value: Object.create(null),
+        configurable: false,
+        enumerable: false,
+        writable: false,
+    });
+}
+const FAST = globalThis.FAST;
+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.",
+    [1401 /* missingElementDefinition */]: "Missing FASTElement definition.",
+};
+Object.assign(FAST, {
+    addMessages(messages) {
+        Object.assign(debugMessages, messages);
+    },
+    warn(code, ...args) {
+        var _a;
+        console.warn((_a = debugMessages[code]) !== null && _a !== void 0 ? _a : "Unknown Warning");
+    },
+    error(code, ...args) {
+        var _a;
+        return new Error((_a = debugMessages[code]) !== null && _a !== void 0 ? _a : "Unknown Error");
+    },
+});
+export {};

package/dist/esm/hooks.js

@@ -0,0 +1,32 @@
+import { Observable } from "./observation/observable.js";
+import { makeObservable } from "./utilities.js";
+/**
+ * Creates an observable state value.
+ * @param value The initial state value.
+ * @param deep Whether or not to convert the state value to an observable.
+ * @returns The state accessor functions.
+ * @beta
+ */
+export function useState(value, deep = false) {
+    const host = makeObservable({ value }, deep);
+    return [() => host.value, newValue => (host.value = newValue)];
+}
+const effectModel = Object.freeze({});
+/**
+ * Executes an action once, and then whenever any of its dependent state changes.
+ * @param action An action that is affected by state changes.
+ * @returns A BindingObserver which can be used to dispose of the effect.
+ */
+export function useEffect(action) {
+    /* eslint prefer-const: 0 */
+    let observer;
+    const subscriber = {
+        handleChange() {
+            observer.observe(effectModel);
+        },
+    };
+    observer = Observable.binding(action, subscriber);
+    observer.setMode(false);
+    subscriber.handleChange();
+    return observer;
+}

package/dist/esm/index.debug.js

@@ -0,0 +1,2 @@
+import "./debug.js";
+export * from "./index.js";

package/dist/esm/index.js

@@ -1,19 +1,18 @@
 export * from "./platform.js";
-export * from "./templating/template.js";
-export * from "./components/fast-element.js";
-export { FASTElementDefinition, } from "./components/fast-definitions.js";
-export * from "./components/attributes.js";
-export * from "./components/controller.js";
-export * from "./templating/compiler.js";
-export { ElementStyles, } from "./styles/element-styles.js";
-export { css, cssPartial } from "./styles/css.js";
-export { CSSDirective } from "./styles/css-directive.js";
-export * from "./templating/view.js";
+// Observation
 export * from "./observation/observable.js";
 export * from "./observation/notifier.js";
-export {} from "./observation/array-change-records.js";
-export { enableArrayObservation } from "./observation/array-observer.js";
-export { DOM } from "./dom.js";
+export * from "./observation/arrays.js";
+export * from "./observation/update-queue.js";
+// Styles
+export * from "./styles/element-styles.js";
+export * from "./styles/css.js";
+export * from "./styles/css-directive.js";
+// Templating
+export * from "./templating/dom.js";
+export * from "./templating/template.js";
+export * from "./templating/compiler.js";
+export { Markup, Parser } from "./templating/markup.js";
 export * from "./templating/binding.js";
 export * from "./templating/html-directive.js";
 export * from "./templating/ref.js";
@@ -21,4 +20,10 @@ export * from "./templating/when.js";
 export * from "./templating/repeat.js";
 export * from "./templating/slotted.js";
 export * from "./templating/children.js";
-export { elements, } from "./templating/node-observation.js";
+export * from "./templating/view.js";
+export * from "./templating/node-observation.js";
+// Components
+export * from "./components/fast-element.js";
+export * from "./components/fast-definitions.js";
+export * from "./components/attributes.js";
+export * from "./components/controller.js";

package/dist/esm/index.rollup.debug.js

@@ -0,0 +1,3 @@
+import "./polyfills.js";
+import "./debug.js";
+export * from "./index.js";

package/dist/esm/index.rollup.js

@@ -0,0 +1,2 @@
+import "./polyfills.js";
+export * from "./index.js";

package/dist/esm/interfaces.js

@@ -1 +1,8 @@
-export {};
+/**
+ * @internal
+ */
+export const isFunction = (object) => typeof object === "function";
+/**
+ * @internal
+ */
+export const isString = (object) => typeof object === "string";