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

package/dist/fast-element.d.ts

@@ -76,55 +76,6 @@ export declare const ArrayObserver: Readonly<{
     readonly enable: () => void;
 }>;
 
-/**
- * The type of HTML aspect to target.
- * @public
- */
-export declare const Aspect: 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;
-    /**
-     *
-     * @param directive - The directive to assign the aspect to.
-     * @param value - The value to base the aspect determination on.
-     * @remarks
-     * If a falsy value is provided, then the content aspect will be assigned.
-     */
-    readonly assign: (directive: Aspected, value?: string) => void;
-}>;
-
-/**
- * The type of HTML aspect to target.
- * @public
- */
-export declare type Aspect = typeof Aspect[Exclude<keyof typeof Aspect, "assign" | "none">];
-
 /**
  * Represents something that applies to a specific aspect of the DOM.
  * @public
@@ -141,7 +92,7 @@ export declare interface Aspected {
     /**
      * The type of aspect to target.
      */
-    aspectType: Aspect;
+    aspectType: DOMAspect;
     /**
      * A binding if one is associated with the aspect.
      */
@@ -259,11 +210,12 @@ export declare type AttributeMode = typeof reflectMode | typeof booleanMode | "f
 /**
  * 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>;
 
 /**
  * Captures a binding expression along with related information and capabilities.
@@ -272,6 +224,7 @@ export declare function bind<T = any>(expression: Expression<T>, isVolatile?: bo
  */
 export declare abstract class Binding<TSource = any, TReturn = any, TParent = any> {
     evaluate: Expression<TSource, TReturn, TParent>;
+    policy?: DOMPolicy | undefined;
     isVolatile: boolean;
     /**
      * Options associated with the binding.
@@ -280,9 +233,10 @@ export declare abstract class Binding<TSource = any, TReturn = any, TParent = an
     /**
      * Creates a binding.
      * @param evaluate - Evaluates the binding.
+     * @param policy - The security policy to associate with this binding.
      * @param isVolatile - Indicates whether the binding is volatile.
      */
-    constructor(evaluate: Expression<TSource, TReturn, TParent>, isVolatile?: boolean);
+    constructor(evaluate: Expression<TSource, TReturn, TParent>, policy?: DOMPolicy | undefined, isVolatile?: boolean);
     /**
      * Creates an observer capable of notifying a subscriber when the output of a binding changes.
      * @param directive - The HTML Directive to create the observer for.
@@ -380,33 +334,36 @@ html: string | HTMLTemplateElement,
 /**
  * The behavior factories used within the html that is being compiled.
  */
-factories: Record<string, ViewBehaviorFactory>) => HTMLTemplateCompilationResult;
+factories: Record<string, ViewBehaviorFactory>, 
+/**
+ * The security policy to compile the html with.
+ */
+policy: DOMPolicy) => HTMLTemplateCompilationResult;
+
+/**
+ * Represents a ViewBehaviorFactory after the compilation process has completed.
+ * @public
+ */
+export declare type CompiledViewBehaviorFactory = Required<ViewBehaviorFactory>;
 
 /**
  * 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>): HTMLTemplateCompilationResult<TSource, TParent>;
+    compile<TSource = any, TParent = any>(html: string | HTMLTemplateElement, factories: Record<string, ViewBehaviorFactory>, policy?: DOMPolicy): HTMLTemplateCompilationResult<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.
@@ -417,9 +374,10 @@ 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;
 };
 
 /**
@@ -592,6 +550,24 @@ export declare type CSSTemplateTag = ((strings: TemplateStringsArray, ...values:
  */
 export declare function customElement(nameOrDef: string | PartialFASTElementDefinition): (type: Constructable<HTMLElement>) => void;
 
+/**
+ * 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>;
+
+/**
+ * A directive capable of injecting static HTML platform runtime protection.
+ * @public
+ */
+export declare class DangerousHTMLDirective implements HTMLDirective {
+    private html;
+    constructor(html: string);
+    createHTML(): string;
+}
+
 /**
  * Metadata used to configure a custom attribute's behavior through a decorator.
  * @public
@@ -633,6 +609,18 @@ export declare const DOM: Readonly<{
      * 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.
@@ -654,6 +642,73 @@ export declare const DOM: Readonly<{
     setBooleanAttribute(element: HTMLElement, attributeName: string, value: boolean): void;
 }>;
 
+/**
+ * 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 security policy that FAST can use to interact with the DOM.
+ * @public
+ */
+export declare 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;
+}
+
+/**
+ * A function used to send values to a DOM sink.
+ * @public
+ */
+export declare type DOMSink = (target: Node, aspectName: string, value: any, ...args: any[]) => void;
+
 /**
  * Controls the lifecycle and rendering of a `FASTElement`.
  * @public
@@ -760,6 +815,7 @@ export declare class ElementController<TElement extends HTMLElement = HTMLElemen
      * Only emits events if connected.
      */
     emit(type: string, detail?: any, options?: Omit<CustomEventInit, "detail">): void | boolean;
+    /* Excluded from this release type: toJSON */
     private renderTemplate;
     /**
      * Locates or creates a controller for the specified element.
@@ -1286,7 +1342,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.
      */
@@ -1298,7 +1362,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.
@@ -1352,6 +1416,14 @@ export declare const HTMLDirective: Readonly<{
      * @param options - Options that specify the directive's application.
      */
     define<TType extends Constructable<HTMLDirective>>(type: TType, options?: PartialHTMLDirectiveDefinition): TType;
+    /**
+     *
+     * @param directive - The directive to assign the aspect to.
+     * @param value - The value to base the aspect determination on.
+     * @remarks
+     * If a falsy value is provided, then the content aspect will be assigned.
+     */
+    assignAspect(directive: Aspected, value?: string): void;
 }>;
 
 /**
@@ -1476,7 +1548,7 @@ export declare class HTMLView<TSource = any, TParent = any> implements ElementVi
      * @param fragment - The html fragment that contains the nodes for this view.
      * @param behaviors - The behaviors to be applied to this view.
      */
-    constructor(fragment: DocumentFragment, factories: ReadonlyArray<ViewBehaviorFactory>, targets: ViewBehaviorTargets);
+    constructor(fragment: DocumentFragment, factories: ReadonlyArray<CompiledViewBehaviorFactory>, targets: ViewBehaviorTargets);
     /**
      * Appends the view's DOM nodes to the referenced node.
      * @param node - The parent node to append the view's DOM nodes to.
@@ -1510,6 +1582,7 @@ export declare class HTMLView<TSource = any, TParent = any> implements ElementVi
      * Unbinds a view's behaviors from its binding source.
      */
     unbind(): void;
+    /* Excluded from this release type: toJSON */
     private evaluateUnbindables;
     /**
      * Efficiently disposes of a contiguous range of synthetic view instances.
@@ -1605,7 +1678,17 @@ export declare interface NodeBehaviorOptions<T = any> {
  * Internally used by the SlottedDirective and the ChildrenDirective.
  */
 export declare abstract class NodeObservationDirective<T extends NodeBehaviorOptions> extends StatelessAttachedAttributeDirective<T> {
-    private sourceProperty;
+    private _id;
+    private _controllerProperty;
+    /**
+     * The unique id of the factory.
+     */
+    get id(): string;
+    set id(value: string);
+    /**
+     * The structural id of the DOM node to which the created behavior will apply.
+     */
+    targetNodeId: string;
     /**
      * Bind this behavior to the source.
      * @param source - The source to bind to.
@@ -1792,10 +1875,11 @@ export declare interface ObservationRecord {
 /**
  * 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>;
 
 /**
  * Common APIs related to content parsing.
@@ -1913,6 +1997,10 @@ export declare const ref: <TSource = any, TParent = any>(propertyName: keyof TSo
  * @public
  */
 export declare class RefDirective extends StatelessAttachedAttributeDirective<string> {
+    /**
+     * The structural id of the DOM node to which the created behavior will apply.
+     */
+    targetNodeId: string;
     /**
      * Bind this behavior.
      * @param controller - The view controller that manages the lifecycle of this behavior.
@@ -1986,14 +2074,10 @@ export declare class RepeatDirective<TSource = any> implements HTMLDirective, Vi
     readonly dataBinding: Binding<TSource>;
     readonly templateBinding: Binding<TSource, SyntheticViewTemplate>;
     readonly options: RepeatOptions;
-    /**
-     * The unique id of the factory.
-     */
-    id: string;
     /**
      * The structural id of the DOM node to which the created behavior will apply.
      */
-    nodeId: string;
+    targetNodeId: string;
     /**
      * Creates a placeholder string based on the directive's index within the template.
      * @param index - The index of the directive within the template.
@@ -2259,14 +2343,7 @@ export declare type SpliceStrategySupport = typeof SpliceStrategySupport[keyof t
  */
 export declare abstract class StatelessAttachedAttributeDirective<TOptions> implements HTMLDirective, ViewBehaviorFactory, ViewBehavior {
     protected options: TOptions;
-    /**
-     * The unique id of the factory.
-     */
-    id: string;
-    /**
-     * The structural id of the DOM node to which the created behavior will apply.
-     */
-    nodeId: string;
+    /* Excluded from this release type: toJSON */
     /**
      * Creates an instance of RefDirective.
      * @param options - The options to use in configuring the directive.
@@ -2453,31 +2530,6 @@ export declare interface SyntheticViewTemplate<TSource = any, TParent = any> {
  */
 export declare type TemplateValue<TSource, TParent = any> = Expression<TSource, any, TParent> | Binding<TSource, any, TParent> | HTMLDirective | CaptureType<TSource, TParent>;
 
-/**
- * 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;
-};
-
-/**
- * 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;
-};
-
 /* Excluded from this release type: TypeDefinition */
 
 /* Excluded from this release type: TypeRegistry */
@@ -2586,56 +2638,25 @@ export declare interface ViewBehaviorFactory {
     /**
      * The unique id of the factory.
      */
-    id: string;
+    id?: string;
     /**
      * The structural id of the DOM node to which the created behavior will apply.
      */
-    nodeId: string;
+    targetNodeId?: string;
     /**
-     * Creates a behavior.
+     * The tag name of the DOM node to which the created behavior will apply.
      */
-    createBehavior(): ViewBehavior;
-}
-
-/**
- * Bridges between ViewBehaviors and HostBehaviors, enabling a host to
- * control ViewBehaviors.
- * @public
- */
-export declare interface ViewBehaviorOrchestrator<TSource = any, TParent = any> extends ViewController<TSource, TParent>, HostBehavior<TSource> {
-    /**
-     *
-     * @param nodeId - The structural id of the DOM node to which a behavior will apply.
-     * @param target - The DOM node associated with the id.
-     */
-    addTarget(nodeId: string, target: Node): void;
+    targetTagName?: string | null;
     /**
-     * Adds a behavior.
-     * @param behavior - The behavior to add.
+     * The policy that the created behavior must run under.
      */
-    addBehavior(behavior: ViewBehavior): void;
+    policy?: DOMPolicy;
     /**
-     * Adds a behavior factory.
-     * @param factory - The behavior factory to add.
-     * @param target - The target the factory will create behaviors for.
+     * Creates a behavior.
      */
-    addBehaviorFactory(factory: ViewBehaviorFactory, target: Node): void;
+    createBehavior(): ViewBehavior;
 }
 
-/**
- * Bridges between ViewBehaviors and HostBehaviors, enabling a host to
- * control ViewBehaviors.
- * @public
- */
-export declare const ViewBehaviorOrchestrator: Readonly<{
-    /**
-     * Creates a ViewBehaviorOrchestrator.
-     * @param source - The source to to associate behaviors with.
-     * @returns A ViewBehaviorOrchestrator.
-     */
-    create<TSource = any, TParent = any>(source: TSource): ViewBehaviorOrchestrator<TSource, TParent>;
-}>;
-
 /**
  * The target nodes available to a behavior.
  * @public
@@ -2660,6 +2681,7 @@ export declare interface ViewController<TSource = any, TParent = any> extends Ex
  * @public
  */
 export declare class ViewTemplate<TSource = any, TParent = any> implements ElementViewTemplate<TSource, TParent>, SyntheticViewTemplate<TSource, TParent> {
+    private policy?;
     private result;
     /**
      * The html representing what this template will
@@ -2674,13 +2696,23 @@ export declare class ViewTemplate<TSource = any, TParent = any> implements Eleme
      * Creates an instance of ViewTemplate.
      * @param html - The html representing what this template will instantiate, including placeholders for directives.
      * @param factories - The directives that will be connected to placeholders in the html.
+     * @param policy - The security policy to use when compiling this template.
      */
-    constructor(html: string | HTMLTemplateElement, factories: Record<string, ViewBehaviorFactory>);
+    constructor(html: string | HTMLTemplateElement, factories?: Record<string, ViewBehaviorFactory>, policy?: DOMPolicy | undefined);
     /**
      * Creates an HTMLView instance based on this template definition.
      * @param hostBindingTarget - The element that host behaviors will be bound to.
      */
     create(hostBindingTarget?: Element): HTMLView<TSource, TParent>;
+    /**
+     * Sets the DOMPolicy for this template.
+     * @param policy - The policy to associated with this template.
+     * @returns The modified template instance.
+     * @remarks
+     * The DOMPolicy can only be set once for a template and cannot be
+     * set after the template is compiled.
+     */
+    withPolicy(policy: DOMPolicy): this;
     /**
      * Creates an HTMLView from this template, binds it to the source, and then appends it to the host.
      * @param source - The data source to bind the template to.
@@ -2689,6 +2721,21 @@ export declare class ViewTemplate<TSource = any, TParent = any> implements Eleme
      * host that the template is being attached to.
      */
     render(source: TSource, host: Node, hostBindingTarget?: Element): HTMLView<TSource, TParent>;
+    /* Excluded from this release type: toJSON */
+    /**
+     * Creates a template based on a set of static strings and dynamic values.
+     * @param strings - The static strings to create the template with.
+     * @param values - The dynamic values to create the template with.
+     * @param policy - The DOMPolicy to associated with the template.
+     * @returns A ViewTemplate.
+     * @remarks
+     * This API should not be used directly under normal circumstances because constructing
+     * a template in this way, if not done properly, can open up the application to XSS
+     * attacks. When using this API, provide a strong DOMPolicy that can properly sanitize
+     * and also be sure to manually sanitize all static strings particularly if they can
+     * come from user input.
+     */
+    static create<TSource = any, TParent = any>(strings: string[], values: TemplateValue<TSource, TParent>[], policy?: DOMPolicy): ViewTemplate<TSource, TParent>;
 }
 
 /**