@microsoft/fast-element 2.0.0-beta.16 → 2.0.0-beta.18

package/CHANGELOG.json

@@ -1,6 +1,42 @@
 {
   "name": "@microsoft/fast-element",
   "entries": [
+    {
+      "date": "Tue, 15 Nov 2022 02:40:34 GMT",
+      "tag": "@microsoft/fast-element_v2.0.0-beta.18",
+      "version": "2.0.0-beta.18",
+      "comments": {
+        "prerelease": [
+          {
+            "author": "roeisenb@microsoft.com",
+            "package": "@microsoft/fast-element",
+            "commit": "1a1fc0b9e85f1e65c605e32f6724402291ffbcaa",
+            "comment": "chore: move ViewBehaviorOrchestrator to utilities"
+          },
+          {
+            "author": "roeisenb@microsoft.com",
+            "package": "@microsoft/fast-element",
+            "commit": "3c14603089495a7af8ed5b55122c418b47c45fd5",
+            "comment": "feat: add new DOM Policy protection throughout"
+          }
+        ]
+      }
+    },
+    {
+      "date": "Tue, 01 Nov 2022 23:26:26 GMT",
+      "tag": "@microsoft/fast-element_v2.0.0-beta.17",
+      "version": "2.0.0-beta.17",
+      "comments": {
+        "prerelease": [
+          {
+            "author": "roeisenb@microsoft.com",
+            "package": "@microsoft/fast-element",
+            "commit": "a4982f452702a8fee67397767b603d4a67702b10",
+            "comment": "fix: prevent circular reference errors when stringifying DOM nodes controlled by FAST's rendering engine"
+          }
+        ]
+      }
+    },
     {
       "date": "Fri, 28 Oct 2022 20:44:44 GMT",
       "tag": "@microsoft/fast-element_v2.0.0-beta.16",

package/CHANGELOG.md

@@ -1,9 +1,26 @@
 # Change Log - @microsoft/fast-element
 
-This log was last generated on Fri, 28 Oct 2022 20:44:44 GMT and should not be manually modified.
+This log was last generated on Tue, 15 Nov 2022 02:40:34 GMT and should not be manually modified.
 
 <!-- Start content -->
 
+## 2.0.0-beta.18
+
+Tue, 15 Nov 2022 02:40:34 GMT
+
+### Changes
+
+- chore: move ViewBehaviorOrchestrator to utilities (roeisenb@microsoft.com)
+- feat: add new DOM Policy protection throughout (roeisenb@microsoft.com)
+
+## 2.0.0-beta.17
+
+Tue, 01 Nov 2022 23:26:26 GMT
+
+### Changes
+
+- fix: prevent circular reference errors when stringifying DOM nodes controlled by FAST's rendering engine (roeisenb@microsoft.com)
+
 ## 2.0.0-beta.16
 
 Fri, 28 Oct 2022 20:44:44 GMT

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

@@ -125,6 +125,11 @@ export declare class ElementController<TElement extends HTMLElement = HTMLElemen
      * Only emits events if connected.
      */
     emit(type: string, detail?: any, options?: Omit<CustomEventInit, "detail">): void | boolean;
+    /**
+     * Opts out of JSON stringification.
+     * @internal
+     */
+    toJSON: () => undefined;
     private renderTemplate;
     /**
      * Locates or creates a controller for the specified element.

package/dist/dts/dom-policy.d.ts

@@ -0,0 +1,68 @@
+import { DOMAspect, DOMPolicy, DOMSink } from "./dom.js";
+import { TrustedTypesPolicy } from "./interfaces.js";
+/**
+ * A specific DOM sink guard for a node aspect.
+ */
+export declare type DOMSinkGuards = Record<string, (tagName: string | null, aspect: DOMAspect, aspectName: string, sink: DOMSink) => DOMSink>;
+/**
+ * Aspect-specific guards for a DOM Policy.
+ */
+export declare type DOMAspectGuards = {
+    /**
+     * Guards for attributes.
+     */
+    [DOMAspect.attribute]?: DOMSinkGuards;
+    /**
+     * Guards for boolean attributes.
+     */
+    [DOMAspect.booleanAttribute]?: DOMSinkGuards;
+    /**
+     * Guards for properties.
+     */
+    [DOMAspect.property]?: DOMSinkGuards;
+    /**
+     * Guards for content.
+     */
+    [DOMAspect.content]?: DOMSinkGuards;
+    /**
+     * Guards for token list manipulation.
+     */
+    [DOMAspect.tokenList]?: DOMSinkGuards;
+    /**
+     * Guards for events.
+     */
+    [DOMAspect.event]?: DOMSinkGuards;
+};
+/**
+ * Element-specific guards for a DOM Policy.
+ */
+export declare type DOMElementGuards = Record<string, DOMAspectGuards>;
+/**
+ * Guard configuration for a DOM Policy.
+ */
+export declare type DOMGuards = {
+    elements: DOMElementGuards;
+    aspects: DOMAspectGuards;
+};
+/**
+ * Options for creating a DOM Policy.
+ */
+export declare type DOMPolicyOptions = {
+    /**
+     * The trusted type to use for HTML creation.
+     */
+    trustedType?: TrustedTypesPolicy;
+    /**
+     * The DOM guards used to override or extend the defaults.
+     */
+    guards?: Partial<DOMGuards>;
+};
+declare const DOMPolicy: Readonly<{
+    /**
+     * Creates a new DOM Policy object.
+     * @param options The options to use in creating the policy.
+     * @returns The newly created DOMPolicy.
+     */
+    create(options?: DOMPolicyOptions): Readonly<DOMPolicy>;
+}>;
+export { DOMPolicy };

package/dist/dts/dom.d.ts

@@ -0,0 +1,116 @@
+import { Callable } from "./interfaces.js";
+/**
+ * The type of HTML aspect to target.
+ * @public
+ */
+export declare const DOMAspect: Readonly<{
+    /**
+     * Not aspected.
+     */
+    readonly none: 0;
+    /**
+     * An attribute.
+     */
+    readonly attribute: 1;
+    /**
+     * A boolean attribute.
+     */
+    readonly booleanAttribute: 2;
+    /**
+     * A property.
+     */
+    readonly property: 3;
+    /**
+     * Content
+     */
+    readonly content: 4;
+    /**
+     * A token list.
+     */
+    readonly tokenList: 5;
+    /**
+     * An event.
+     */
+    readonly event: 6;
+}>;
+/**
+ * The type of HTML aspect to target.
+ * @public
+ */
+export declare type DOMAspect = typeof DOMAspect[Exclude<keyof typeof DOMAspect, "none">];
+/**
+ * A function used to send values to a DOM sink.
+ * @public
+ */
+export declare type DOMSink = (target: Node, aspectName: string, value: any, ...args: any[]) => void;
+/**
+ * A security policy that FAST can use to interact with the DOM.
+ * @public
+ */
+export interface DOMPolicy {
+    /**
+     * Creates safe HTML from the provided value.
+     * @param value - The source to convert to safe HTML.
+     */
+    createHTML(value: string): string;
+    /**
+     * Protects a DOM sink that intends to write to the DOM.
+     * @param tagName - The tag name for the element to write to.
+     * @param aspect - The aspect of the DOM to write to.
+     * @param aspectName - The name of the aspect to write to.
+     * @param sink - The sink that is used to write to the DOM.
+     */
+    protect(tagName: string | null, aspect: DOMAspect, aspectName: string, sink: DOMSink): DOMSink;
+}
+/**
+ * Common DOM APIs.
+ * @public
+ */
+export declare const DOM: Readonly<{
+    /**
+     * @deprecated
+     * Use Updates.enqueue().
+     */
+    queueUpdate: (callable: Callable) => void;
+    /**
+     * @deprecated
+     * Use Updates.next()
+     */
+    nextUpdate: () => Promise<void>;
+    /**
+     * @deprecated
+     * Use Updates.process()
+     */
+    processUpdates: () => void;
+    /**
+     * Gets the dom policy used by the templating system.
+     */
+    readonly policy: DOMPolicy;
+    /**
+     * 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: DOMPolicy): void;
+    /**
+     * 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: HTMLElement, attributeName: string, value: any): void;
+    /**
+     * 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: HTMLElement, attributeName: string, value: boolean): void;
+}>;

package/dist/dts/index.d.ts

@@ -1,5 +1,6 @@
-export type { Callable, Constructable, Disposable, FASTGlobal, Mutable, StyleStrategy, StyleTarget, TrustedTypes, TrustedTypesPolicy, } from "./interfaces.js";
+export type { Callable, Constructable, Disposable, FASTGlobal, Mutable, StyleStrategy, StyleTarget, } from "./interfaces.js";
 export * from "./platform.js";
+export * from "./dom.js";
 export * from "./observation/observable.js";
 export * from "./observation/notifier.js";
 export * from "./observation/arrays.js";
@@ -8,7 +9,6 @@ export * from "./styles/element-styles.js";
 export * from "./styles/css.js";
 export * from "./styles/css-directive.js";
 export * from "./styles/host.js";
-export * from "./templating/dom.js";
 export * from "./templating/template.js";
 export * from "./templating/compiler.js";
 export { Markup, Parser } from "./templating/markup.js";
@@ -21,6 +21,7 @@ export * from "./templating/slotted.js";
 export * from "./templating/children.js";
 export * from "./templating/view.js";
 export * from "./templating/node-observation.js";
+export * from "./templating/dangerous-html.js";
 export * from "./components/fast-element.js";
 export * from "./components/fast-definitions.js";
 export * from "./components/attributes.js";

package/dist/dts/index.rollup.d.ts

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

package/dist/dts/index.rollup.debug.d.ts

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

package/dist/dts/interfaces.d.ts

@@ -44,29 +44,6 @@ export interface Disposable {
 export declare type Mutable<T> = {
     -readonly [P in keyof T]: T[P];
 };
-/**
- * A policy for use with the standard trustedTypes platform API.
- * @public
- */
-export declare type TrustedTypesPolicy = {
-    /**
-     * Creates trusted HTML.
-     * @param html - The HTML to clear as trustworthy.
-     */
-    createHTML(html: string): string;
-};
-/**
- * Enables working with trusted types.
- * @public
- */
-export declare type TrustedTypes = {
-    /**
-     * Creates a trusted types policy.
-     * @param name - The policy name.
-     * @param rules - The policy rules implementation.
-     */
-    createPolicy(name: string, rules: TrustedTypesPolicy): TrustedTypesPolicy;
-};
 /**
  * The FAST global.
  * @internal
@@ -162,11 +139,14 @@ export interface StyleStrategy {
  */
 export declare const enum Message {
     needsArrayObservation = 1101,
-    onlySetHTMLPolicyOnce = 1201,
+    onlySetDOMPolicyOnce = 1201,
     bindingInnerHTMLRequiresTrustedTypes = 1202,
     twoWayBindingRequiresObservables = 1203,
     hostBindingWithoutHost = 1204,
     unsupportedBindingBehavior = 1205,
+    directCallToHTMLTagNotAllowed = 1206,
+    onlySetTemplatePolicyOnce = 1207,
+    cannotSetTemplatePolicyAfterCompilation = 1208,
     missingElementDefinition = 1401,
     noRegistrationForContext = 1501,
     noFactoryForResolver = 1502,
@@ -195,3 +175,14 @@ export declare const isString: (object: any) => object is string;
  * @internal
  */
 export declare const noop: () => undefined;
+/**
+ * A policy for use with the standard trustedTypes platform API.
+ * @public
+ */
+export declare type TrustedTypesPolicy = {
+    /**
+     * Creates trusted HTML.
+     * @param html - The HTML to clear as trustworthy.
+     */
+    createHTML(html: string): string;
+};

package/dist/dts/polyfills.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/dts/templating/binding-signal.d.ts

@@ -1,5 +1,6 @@
 import type { Expression } from "../observation/observable.js";
 import type { Subscriber } from "../observation/notifier.js";
+import type { DOMPolicy } from "../dom.js";
 import { Binding } from "./html-directive.js";
 export declare const Signal: Readonly<{
     subscribe(signal: string, subscriber: Subscriber): void;
@@ -15,7 +16,8 @@ export declare const Signal: Readonly<{
  * Creates a signal binding configuration with the supplied options.
  * @param expression - The binding to refresh when signaled.
  * @param options - The signal name or a binding to use to retrieve the signal name.
+ * @param policy - The security policy to associate with th binding.
  * @returns A binding configuration.
  * @public
  */
-export declare function signal<T = any>(expression: Expression<T>, options: string | Expression<T>): Binding<T>;
+export declare function signal<T = any>(expression: Expression<T>, options: string | Expression<T>, policy?: DOMPolicy): Binding<T>;

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

@@ -1,3 +1,4 @@
+import type { DOMPolicy } from "../dom.js";
 import { Expression } from "../observation/observable.js";
 import type { HTMLBindingDirective } from "./binding.js";
 import { Binding } from "./html-directive.js";
@@ -32,8 +33,9 @@ export declare const TwoWaySettings: Readonly<{
  * Creates a default binding.
  * @param expression - The binding to refresh when changed.
  * @param optionsOrChangeEvent - The binding options or the name of the change event to use.
+ * @param policy - The security policy to associate with the binding.
  * @param isBindingVolatile - Indicates whether the binding is volatile or not.
  * @returns A binding.
  * @public
  */
-export declare function twoWay<T = any>(expression: Expression<T>, optionsOrChangeEvent?: TwoWayBindingOptions | string, isBindingVolatile?: boolean): Binding<T>;
+export declare function twoWay<T = any>(expression: Expression<T>, optionsOrChangeEvent?: TwoWayBindingOptions | string, policy?: DOMPolicy, isBindingVolatile?: boolean): Binding<T>;

package/dist/dts/templating/binding.d.ts

@@ -1,5 +1,6 @@
 import { ExecutionContext, Expression, ExpressionObserver } from "../observation/observable.js";
-import { AddViewBehaviorFactory, Aspect, Aspected, Binding, HTMLDirective, ViewBehavior, ViewBehaviorFactory, ViewController } from "./html-directive.js";
+import { DOMAspect, DOMPolicy } from "../dom.js";
+import { AddViewBehaviorFactory, Aspected, Binding, HTMLDirective, ViewBehavior, ViewBehaviorFactory, ViewController } from "./html-directive.js";
 /**
  * A simple View that can be interpolated into HTML content.
  * @public
@@ -52,7 +53,15 @@ export declare class HTMLBindingDirective implements HTMLDirective, ViewBehavior
     /**
      * The structural id of the DOM node to which the created behavior will apply.
      */
-    nodeId: string;
+    targetNodeId: string;
+    /**
+     * The tagname associated with the target node.
+     */
+    targetTagName: string | null;
+    /**
+     * The policy that the created behavior must run under.
+     */
+    policy: DOMPolicy;
     /**
      * The original source aspect exactly as represented in markup.
      */
@@ -64,7 +73,7 @@ export declare class HTMLBindingDirective implements HTMLDirective, ViewBehavior
     /**
      * The type of aspect to target.
      */
-    aspectType: Aspect;
+    aspectType: DOMAspect;
     /**
      * Creates an instance of HTMLBindingDirective.
      * @param dataBinding - The binding configuration to apply.
@@ -91,18 +100,20 @@ export declare class HTMLBindingDirective implements HTMLDirective, ViewBehavior
 /**
  * Creates an standard binding.
  * @param expression - The binding to refresh when changed.
+ * @param policy - The security policy to associate with th binding.
  * @param isVolatile - Indicates whether the binding is volatile or not.
  * @returns A binding configuration.
  * @public
  */
-export declare function bind<T = any>(expression: Expression<T>, isVolatile?: boolean): Binding<T>;
+export declare function bind<T = any>(expression: Expression<T>, policy?: DOMPolicy, isVolatile?: boolean): Binding<T>;
 /**
  * Creates a one time binding
  * @param expression - The binding to refresh when signaled.
+ * @param policy - The security policy to associate with th binding.
  * @returns A binding configuration.
  * @public
  */
-export declare function oneTime<T = any>(expression: Expression<T>): Binding<T>;
+export declare function oneTime<T = any>(expression: Expression<T>, policy?: DOMPolicy): Binding<T>;
 /**
  * Creates an event listener binding.
  * @param expression - The binding to invoke when the event is raised.

package/dist/dts/templating/compiler.d.ts

@@ -1,4 +1,4 @@
-import { TrustedTypesPolicy } from "../interfaces.js";
+import { DOMPolicy } from "../dom.js";
 import { ViewBehaviorFactory } from "./html-directive.js";
 import type { HTMLTemplateCompilationResult as TemplateCompilationResult } from "./template.js";
 /**
@@ -14,32 +14,29 @@ html: string | HTMLTemplateElement,
 /**
  * The behavior factories used within the html that is being compiled.
  */
-factories: Record<string, ViewBehaviorFactory>) => TemplateCompilationResult;
+factories: Record<string, ViewBehaviorFactory>, 
+/**
+ * The security policy to compile the html with.
+ */
+policy: DOMPolicy) => TemplateCompilationResult;
 /**
  * Common APIs related to compilation.
  * @public
  */
 export declare const Compiler: {
-    /**
-     * Sets the HTML trusted types policy used by the compiler.
-     * @param policy - The policy to set for HTML.
-     * @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.
-     */
-    setHTMLPolicy(policy: TrustedTypesPolicy): void;
     /**
      * Compiles a template and associated directives into a compilation
      * result which can be used to create views.
      * @param html - The html string or template element to compile.
-     * @param directives - The directives referenced by the template.
+     * @param factories - The behavior factories referenced by the template.
+     * @param policy - The security policy to compile the html with.
      * @remarks
      * The template that is provided for compilation is altered in-place
      * and cannot be compiled again. If the original template must be preserved,
      * it is recommended that you clone the original and pass the clone to this API.
      * @public
      */
-    compile<TSource = any, TParent = any>(html: string | HTMLTemplateElement, directives: Record<string, ViewBehaviorFactory>): TemplateCompilationResult<TSource, TParent>;
+    compile<TSource = any, TParent = any>(html: string | HTMLTemplateElement, factories: Record<string, ViewBehaviorFactory>, policy?: DOMPolicy): TemplateCompilationResult<TSource, TParent>;
     /**
      * Sets the default compilation strategy that will be used by the ViewTemplate whenever
      * it needs to compile a view preprocessed with the html template function.
@@ -50,7 +47,8 @@ export declare const Compiler: {
      * Aggregates an array of strings and directives into a single directive.
      * @param parts - A heterogeneous array of static strings interspersed with
      * directives.
+     * @param policy - The security policy to use with the aggregated bindings.
      * @returns A single inline directive that aggregates the behavior of all the parts.
      */
-    aggregate(parts: (string | ViewBehaviorFactory)[]): ViewBehaviorFactory;
+    aggregate(parts: (string | ViewBehaviorFactory)[], policy?: DOMPolicy): ViewBehaviorFactory;
 };

package/dist/dts/templating/dangerous-html.d.ts

@@ -0,0 +1,18 @@
+import { HTMLDirective } from "./html-directive.js";
+import type { CaptureType } from "./template.js";
+/**
+ * A directive capable of injecting static HTML platform runtime protection.
+ * @public
+ */
+export declare class DangerousHTMLDirective implements HTMLDirective {
+    private html;
+    constructor(html: string);
+    createHTML(): string;
+}
+/**
+ * Injects static HTML without platform protection.
+ * @param html - The html to injection.
+ * @returns A DangerousHTMLDirective.
+ * @public
+ */
+export declare function dangerousHTML<TSource = any, TParent = any>(html: string): CaptureType<TSource, TParent>;