@microsoft/fast-element 2.0.0-beta.9 → 2.0.1

package/dist/esm/context.js

@@ -1,17 +1,33 @@
 import "./interfaces.js";
 import { Metadata } from "./metadata.js";
 import { FAST } from "./platform.js";
+const contextsByName = new Map();
 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
+ * Enables using:
+ * {@link https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md | W3C Community Context protocol.}
+ * @public
  */
 export const Context = Object.freeze({
     /**
      * The event type used for W3C Context Protocol requests.
      */
     eventType: contextEventType,
+    /**
+     * Returns a FASTContext object from the global context registry matching the given name if found.
+     * Otherwise, returns a new FASTContext with this name.
+     * @param name - The name of the FASTContext to get or create.
+     * @returns A FASTContext object.
+     */
+    for(name) {
+        let c = contextsByName.get(name);
+        if (c === void 0) {
+            c = Context.create(name);
+            contextsByName.set(name, c);
+        }
+        return c;
+    },
     /**
      * Creates a W3C Community Protocol-based Context object to use in requesting/providing
      * context through the DOM.
@@ -94,8 +110,14 @@ export const Context = Object.freeze({
     dispatch(target, context, callback, multiple = false) {
         target.dispatchEvent(new ContextEvent(context, callback, multiple));
     },
+    /**
+     * Enables an event target to provide a context value.
+     * @param target The target to provide the context value for.
+     * @param context The context to provide the value for.
+     * @param value The value to provide for the context.
+     */
     provide(target, context, value) {
-        this.handle(target, (event) => {
+        Context.handle(target, (event) => {
             event.stopImmediatePropagation();
             event.callback(value);
         }, context);
@@ -132,7 +154,7 @@ export const Context = Object.freeze({
      * initialValue if the context isn't handled.
      */
     defineProperty(target, propertyName, context) {
-        const field = `$di_${propertyName}`;
+        const field = Symbol.for(`fast:di:${propertyName}`);
         Reflect.defineProperty(target, propertyName, {
             get: function () {
                 var _a;

package/dist/esm/debug.js

@@ -9,18 +9,24 @@ if (globalThis.FAST === void 0) {
 const FAST = globalThis.FAST;
 const debugMessages = {
     [1101 /* needsArrayObservation */]: "Must call enableArrayObservation before observing arrays.",
-    [1201 /* onlySetHTMLPolicyOnce */]: "The HTML policy can only be set once.",
+    [1201 /* onlySetDOMPolicyOnce */]: "The DOM 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.",
+    [1206 /* directCallToHTMLTagNotAllowed */]: "Calling html`` as a normal function invalidates the security guarantees provided by FAST.",
+    [1207 /* onlySetTemplatePolicyOnce */]: "The DOM Policy for an HTML template can only be set once.",
+    [1208 /* cannotSetTemplatePolicyAfterCompilation */]: "The DOM Policy cannot be set after a template is compiled.",
+    [1209 /* blockedByDOMPolicy */]: "'${aspectName}' on '${tagName}' is blocked by the current DOMPolicy.",
     [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.",
+    [1506 /* cannotConstructNativeFunction */]: 
+    /* eslint-disable-next-line max-len */
+    "'${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}'.",

package/dist/esm/di/di.js

@@ -292,7 +292,8 @@ export const DI = Object.freeze({
      * @returns An array of dependency keys.
      */
     getDependencies(Type) {
-        // Note: Every detail of this getDependencies method is pretty deliberate at the moment, and probably not yet 100% tested from every possible angle,
+        // Note: Every detail of this getDependencies method is pretty deliberate at the moment,
+        // and probably not yet 100% tested from every possible angle,
         // so be careful with making changes here as it can have a huge impact on complex end user apps.
         // Preferably, only make changes to the dependency resolution process via a RFC.
         let dependencies = dependencyLookup.get(Type);
@@ -371,16 +372,16 @@ export const DI = Object.freeze({
      * The respectConnection option is only applicable to elements that descend from FASTElement.
      */
     defineProperty(target, propertyName, key, respectConnection = false) {
-        const diPropertyKey = `$di_${propertyName}`;
+        const field = Symbol.for(`fast:di:${propertyName}`);
         Reflect.defineProperty(target, propertyName, {
             get: function () {
-                let value = this[diPropertyKey];
+                let value = this[field];
                 if (value === void 0) {
                     const container = this instanceof Node
                         ? DI.findResponsibleContainer(this)
                         : DI.getOrCreateDOMContainer();
                     value = container.get(key);
-                    this[diPropertyKey] = value;
+                    this[field] = value;
                     if (respectConnection) {
                         const notifier = this.$fastController;
                         if (!notifier) {
@@ -389,9 +390,9 @@ export const DI = Object.freeze({
                         const handleChange = () => {
                             const newContainer = DI.findResponsibleContainer(this);
                             const newValue = newContainer.get(key);
-                            const oldValue = this[diPropertyKey];
+                            const oldValue = this[field];
                             if (newValue !== oldValue) {
-                                this[diPropertyKey] = value;
+                                this[field] = value;
                                 notifier.notify(propertyName);
                             }
                         };
@@ -414,11 +415,6 @@ export const DI = Object.freeze({
      * in addition to its standard use in an inject array or through direct container APIs.
      */
     createContext,
-    /**
-     * @deprecated
-     * Use DI.createContext instead.
-     */
-    createInterface: createContext,
     /**
      * A decorator that specifies what to inject into its target.
      * @param dependencies - The dependencies to inject.
@@ -1384,7 +1380,8 @@ const isNativeFunction = (function () {
                     i <= 100 &&
                     // This whole heuristic *could* be tricked by a comment. Do we need to care about that?
                     sourceText.charCodeAt(i - 1) === 0x7d && // }
-                    // TODO: the spec is a little vague about the precise constraints, so we do need to test this across various browsers to make sure just one whitespace is a safe assumption.
+                    // TODO: the spec is a little vague about the precise constraints,
+                    // so we do need to test this across various browsers to make sure just one whitespace is a safe assumption.
                     sourceText.charCodeAt(i - 2) <= 0x20 && // whitespace
                     sourceText.charCodeAt(i - 3) === 0x5d && // ]
                     sourceText.charCodeAt(i - 4) === 0x65 && // e

package/dist/esm/dom-policy.js

@@ -0,0 +1,345 @@
+import { DOMAspect } from "./dom.js";
+import { isString } from "./interfaces.js";
+import { FAST } from "./platform.js";
+function safeURL(tagName, aspect, aspectName, sink) {
+    return (target, name, value, ...rest) => {
+        if (isString(value)) {
+            value = value.replace(/(javascript:|vbscript:|data:)/, "");
+        }
+        sink(target, name, value, ...rest);
+    };
+}
+function block(tagName, aspect, aspectName, sink) {
+    throw FAST.error(1209 /* Message.blockedByDOMPolicy */, {
+        aspectName,
+        tagName: tagName !== null && tagName !== void 0 ? tagName : "text",
+    });
+}
+const defaultDOMElementGuards = {
+    a: {
+        [DOMAspect.attribute]: {
+            href: safeURL,
+        },
+        [DOMAspect.property]: {
+            href: safeURL,
+        },
+    },
+    area: {
+        [DOMAspect.attribute]: {
+            href: safeURL,
+        },
+        [DOMAspect.property]: {
+            href: safeURL,
+        },
+    },
+    button: {
+        [DOMAspect.attribute]: {
+            formaction: safeURL,
+        },
+        [DOMAspect.property]: {
+            formAction: safeURL,
+        },
+    },
+    embed: {
+        [DOMAspect.attribute]: {
+            src: block,
+        },
+        [DOMAspect.property]: {
+            src: block,
+        },
+    },
+    form: {
+        [DOMAspect.attribute]: {
+            action: safeURL,
+        },
+        [DOMAspect.property]: {
+            action: safeURL,
+        },
+    },
+    frame: {
+        [DOMAspect.attribute]: {
+            src: safeURL,
+        },
+        [DOMAspect.property]: {
+            src: safeURL,
+        },
+    },
+    iframe: {
+        [DOMAspect.attribute]: {
+            src: safeURL,
+        },
+        [DOMAspect.property]: {
+            src: safeURL,
+            srcdoc: block,
+        },
+    },
+    input: {
+        [DOMAspect.attribute]: {
+            formaction: safeURL,
+        },
+        [DOMAspect.property]: {
+            formAction: safeURL,
+        },
+    },
+    link: {
+        [DOMAspect.attribute]: {
+            href: block,
+        },
+        [DOMAspect.property]: {
+            href: block,
+        },
+    },
+    object: {
+        [DOMAspect.attribute]: {
+            codebase: block,
+            data: block,
+        },
+        [DOMAspect.property]: {
+            codeBase: block,
+            data: block,
+        },
+    },
+    script: {
+        [DOMAspect.attribute]: {
+            src: block,
+            text: block,
+        },
+        [DOMAspect.property]: {
+            src: block,
+            text: block,
+            innerText: block,
+            textContent: block,
+        },
+    },
+    style: {
+        [DOMAspect.property]: {
+            innerText: block,
+            textContent: block,
+        },
+    },
+};
+const blockedEvents = {
+    onabort: block,
+    onauxclick: block,
+    onbeforeinput: block,
+    onbeforematch: block,
+    onblur: block,
+    oncancel: block,
+    oncanplay: block,
+    oncanplaythrough: block,
+    onchange: block,
+    onclick: block,
+    onclose: block,
+    oncontextlost: block,
+    oncontextmenu: block,
+    oncontextrestored: block,
+    oncopy: block,
+    oncuechange: block,
+    oncut: block,
+    ondblclick: block,
+    ondrag: block,
+    ondragend: block,
+    ondragenter: block,
+    ondragleave: block,
+    ondragover: block,
+    ondragstart: block,
+    ondrop: block,
+    ondurationchange: block,
+    onemptied: block,
+    onended: block,
+    onerror: block,
+    onfocus: block,
+    onformdata: block,
+    oninput: block,
+    oninvalid: block,
+    onkeydown: block,
+    onkeypress: block,
+    onkeyup: block,
+    onload: block,
+    onloadeddata: block,
+    onloadedmetadata: block,
+    onloadstart: block,
+    onmousedown: block,
+    onmouseenter: block,
+    onmouseleave: block,
+    onmousemove: block,
+    onmouseout: block,
+    onmouseover: block,
+    onmouseup: block,
+    onpaste: block,
+    onpause: block,
+    onplay: block,
+    onplaying: block,
+    onprogress: block,
+    onratechange: block,
+    onreset: block,
+    onresize: block,
+    onscroll: block,
+    onsecuritypolicyviolation: block,
+    onseeked: block,
+    onseeking: block,
+    onselect: block,
+    onslotchange: block,
+    onstalled: block,
+    onsubmit: block,
+    onsuspend: block,
+    ontimeupdate: block,
+    ontoggle: block,
+    onvolumechange: block,
+    onwaiting: block,
+    onwebkitanimationend: block,
+    onwebkitanimationiteration: block,
+    onwebkitanimationstart: block,
+    onwebkittransitionend: block,
+    onwheel: block,
+};
+const defaultDOMGuards = {
+    elements: defaultDOMElementGuards,
+    aspects: {
+        [DOMAspect.attribute]: Object.assign({}, blockedEvents),
+        [DOMAspect.property]: Object.assign({ innerHTML: block }, blockedEvents),
+        [DOMAspect.event]: Object.assign({}, blockedEvents),
+    },
+};
+function createDomSinkGuards(config, defaults) {
+    const result = {};
+    for (const name in defaults) {
+        const overrideValue = config[name];
+        const defaultValue = defaults[name];
+        switch (overrideValue) {
+            case null:
+                // remove the default
+                break;
+            case undefined:
+                // keep the default
+                result[name] = defaultValue;
+                break;
+            default:
+                // override the default
+                result[name] = overrideValue;
+                break;
+        }
+    }
+    // add any new sinks that were not overrides
+    for (const name in config) {
+        if (!(name in result)) {
+            result[name] = config[name];
+        }
+    }
+    return Object.freeze(result);
+}
+function createDOMAspectGuards(config, defaults) {
+    const result = {};
+    for (const aspect in defaults) {
+        const overrideValue = config[aspect];
+        const defaultValue = defaults[aspect];
+        switch (overrideValue) {
+            case null:
+                // remove the default
+                break;
+            case undefined:
+                // keep the default
+                result[aspect] = createDomSinkGuards(defaultValue, {});
+                break;
+            default:
+                // override the default
+                result[aspect] = createDomSinkGuards(overrideValue, defaultValue);
+                break;
+        }
+    }
+    // add any new aspect guards that were not overrides
+    for (const aspect in config) {
+        if (!(aspect in result)) {
+            result[aspect] = createDomSinkGuards(config[aspect], {});
+        }
+    }
+    return Object.freeze(result);
+}
+function createElementGuards(config, defaults) {
+    const result = {};
+    for (const tag in defaults) {
+        const overrideValue = config[tag];
+        const defaultValue = defaults[tag];
+        switch (overrideValue) {
+            case null:
+                // remove the default
+                break;
+            case undefined:
+                // keep the default
+                result[tag] = createDOMAspectGuards(overrideValue, {});
+                break;
+            default:
+                // override the default aspects
+                result[tag] = createDOMAspectGuards(overrideValue, defaultValue);
+                break;
+        }
+    }
+    // Add any new element guards that were not overrides
+    for (const tag in config) {
+        if (!(tag in result)) {
+            result[tag] = createDOMAspectGuards(config[tag], {});
+        }
+    }
+    return Object.freeze(result);
+}
+function createDOMGuards(config, defaults) {
+    return Object.freeze({
+        elements: config.elements
+            ? createElementGuards(config.elements, defaults.elements)
+            : defaults.elements,
+        aspects: config.aspects
+            ? createDOMAspectGuards(config.aspects, defaults.aspects)
+            : defaults.aspects,
+    });
+}
+function createTrustedType() {
+    const createHTML = html => html;
+    return globalThis.trustedTypes
+        ? globalThis.trustedTypes.createPolicy("fast-html", { createHTML })
+        : { createHTML };
+}
+function tryGuard(aspectGuards, tagName, aspect, aspectName, sink) {
+    const sinkGuards = aspectGuards[aspect];
+    if (sinkGuards) {
+        const guard = sinkGuards[aspectName];
+        if (guard) {
+            return guard(tagName, aspect, aspectName, sink);
+        }
+    }
+}
+/**
+ * A helper for creating DOM policies.
+ * @public
+ */
+const DOMPolicy = Object.freeze({
+    /**
+     * Creates a new DOM Policy object.
+     * @param options The options to use in creating the policy.
+     * @returns The newly created DOMPolicy.
+     */
+    create(options = {}) {
+        var _a, _b;
+        const trustedType = (_a = options.trustedType) !== null && _a !== void 0 ? _a : createTrustedType();
+        const guards = createDOMGuards((_b = options.guards) !== null && _b !== void 0 ? _b : {}, defaultDOMGuards);
+        return Object.freeze({
+            createHTML(value) {
+                return trustedType.createHTML(value);
+            },
+            protect(tagName, aspect, aspectName, sink) {
+                var _a;
+                // Check for element-specific guards.
+                const key = (tagName !== null && tagName !== void 0 ? tagName : "").toLowerCase();
+                const elementGuards = guards.elements[key];
+                if (elementGuards) {
+                    const guard = tryGuard(elementGuards, tagName, aspect, aspectName, sink);
+                    if (guard) {
+                        return guard;
+                    }
+                }
+                // Check for guards applicable to all nodes.
+                return ((_a = tryGuard(guards.aspects, tagName, aspect, aspectName, sink)) !== null && _a !== void 0 ? _a : sink);
+            },
+        });
+    },
+});
+export { DOMPolicy };

package/dist/esm/dom.js

@@ -0,0 +1,101 @@
+import "./interfaces.js";
+import { FAST } from "./platform.js";
+/**
+ * The type of HTML aspect to target.
+ * @public
+ */
+export const DOMAspect = Object.freeze({
+    /**
+     * Not aspected.
+     */
+    none: 0,
+    /**
+     * An attribute.
+     */
+    attribute: 1,
+    /**
+     * A boolean attribute.
+     */
+    booleanAttribute: 2,
+    /**
+     * A property.
+     */
+    property: 3,
+    /**
+     * Content
+     */
+    content: 4,
+    /**
+     * A token list.
+     */
+    tokenList: 5,
+    /**
+     * An event.
+     */
+    event: 6,
+});
+const createHTML = html => html;
+const fastTrustedType = globalThis.trustedTypes
+    ? globalThis.trustedTypes.createPolicy("fast-html", { createHTML })
+    : { createHTML };
+let defaultPolicy = Object.freeze({
+    createHTML(value) {
+        return fastTrustedType.createHTML(value);
+    },
+    protect(tagName, aspect, aspectName, sink) {
+        return sink;
+    },
+});
+const fastPolicy = defaultPolicy;
+/**
+ * Common DOM APIs.
+ * @public
+ */
+export const DOM = Object.freeze({
+    /**
+     * Gets the dom policy used by the templating system.
+     */
+    get policy() {
+        return defaultPolicy;
+    },
+    /**
+     * Sets the dom policy used by the templating system.
+     * @param policy - The policy to set.
+     * @remarks
+     * This API can only be called once, for security reasons. It should be
+     * called by the application developer at the start of their program.
+     */
+    setPolicy(value) {
+        if (defaultPolicy !== fastPolicy) {
+            throw FAST.error(1201 /* Message.onlySetDOMPolicyOnce */);
+        }
+        defaultPolicy = value;
+    },
+    /**
+     * Sets an attribute value on an element.
+     * @param element - The element to set the attribute value on.
+     * @param attributeName - The attribute name to set.
+     * @param value - The value of the attribute to set.
+     * @remarks
+     * If the value is `null` or `undefined`, the attribute is removed, otherwise
+     * it is set to the provided value using the standard `setAttribute` API.
+     */
+    setAttribute(element, attributeName, value) {
+        value === null || value === undefined
+            ? element.removeAttribute(attributeName)
+            : element.setAttribute(attributeName, value);
+    },
+    /**
+     * Sets a boolean attribute value.
+     * @param element - The element to set the boolean attribute value on.
+     * @param attributeName - The attribute name to set.
+     * @param value - The value of the attribute to set.
+     * @remarks
+     * If the value is true, the attribute is added; otherwise it is removed.
+     */
+    setBooleanAttribute(element, attributeName, value) {
+        value
+            ? element.setAttribute(attributeName, "")
+            : element.removeAttribute(attributeName);
+    },
+});