@microsoft/fast-element 2.0.0-beta.17 → 2.0.0-beta.19

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

@@ -1,7 +1,7 @@
-import type { HostBehavior } from "../index.js";
+import { DOMAspect, DOMPolicy } from "../dom.js";
 import { Constructable } from "../interfaces.js";
 import type { Subscriber } from "../observation/notifier.js";
-import { Expression, ExpressionController, ExpressionObserver } from "../observation/observable.js";
+import type { Expression, ExpressionController, ExpressionObserver } from "../observation/observable.js";
 /**
  * The target nodes available to a behavior.
  * @public
@@ -19,43 +19,6 @@ export interface ViewController<TSource = any, TParent = any> extends Expression
      */
     readonly targets: ViewBehaviorTargets;
 }
-/**
- * Bridges between ViewBehaviors and HostBehaviors, enabling a host to
- * control ViewBehaviors.
- * @public
- */
-export 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;
-    /**
-     * Adds a behavior.
-     * @param behavior - The behavior to add.
-     */
-    addBehavior(behavior: ViewBehavior): void;
-    /**
-     * Adds a behavior factory.
-     * @param factory - The behavior factory to add.
-     * @param target - The target the factory will create behaviors for.
-     */
-    addBehaviorFactory(factory: ViewBehaviorFactory, target: Node): void;
-}
-/**
- * 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>;
-}>;
 /**
  * Represents an object that can contribute behavior to a view.
  * @public
@@ -76,16 +39,29 @@ export 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;
+    /**
+     * The tag name of the DOM node to which the created behavior will apply.
+     */
+    targetTagName?: string | null;
+    /**
+     * The policy that the created behavior must run under.
+     */
+    policy?: DOMPolicy;
     /**
      * Creates a behavior.
      */
     createBehavior(): ViewBehavior;
 }
+/**
+ * Represents a ViewBehaviorFactory after the compilation process has completed.
+ * @public
+ */
+export declare type CompiledViewBehaviorFactory = Required<ViewBehaviorFactory>;
 /**
  * Used to add behavior factories when constructing templates.
  * @public
@@ -102,6 +78,28 @@ export interface HTMLDirective {
      */
     createHTML(add: AddViewBehaviorFactory): string;
 }
+/**
+ * Represents something that applies to a specific aspect of the DOM.
+ * @public
+ */
+export interface Aspected {
+    /**
+     * The original source aspect exactly as represented in markup.
+     */
+    sourceAspect: string;
+    /**
+     * The evaluated target aspect, determined after processing the source.
+     */
+    targetAspect: string;
+    /**
+     * The type of aspect to target.
+     */
+    aspectType: DOMAspect;
+    /**
+     * A binding if one is associated with the aspect.
+     */
+    dataBinding?: Binding;
+}
 /**
  * Represents metadata configuration for an HTMLDirective.
  * @public
@@ -144,6 +142,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;
 }>;
 /**
  * Decorator: Defines an HTMLDirective.
@@ -158,6 +164,7 @@ export declare function htmlDirective(options?: PartialHTMLDirectiveDefinition):
  */
 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.
@@ -166,9 +173,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.
@@ -176,89 +184,12 @@ export declare abstract class Binding<TSource = any, TReturn = any, TParent = an
      */
     abstract createObserver(directive: HTMLDirective, subscriber: Subscriber): ExpressionObserver<TSource, TReturn, TParent>;
 }
-/**
- * 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
- */
-export interface Aspected {
-    /**
-     * The original source aspect exactly as represented in markup.
-     */
-    sourceAspect: string;
-    /**
-     * The evaluated target aspect, determined after processing the source.
-     */
-    targetAspect: string;
-    /**
-     * The type of aspect to target.
-     */
-    aspectType: Aspect;
-    /**
-     * A binding if one is associated with the aspect.
-     */
-    dataBinding?: Binding;
-}
 /**
  * A base class used for attribute directives that don't need internal state.
  * @public
  */
 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;
     /**
      * Opts out of JSON stringification.
      * @internal

package/dist/dts/templating/node-observation.d.ts

@@ -36,7 +36,17 @@ export declare const elements: (selector?: string) => ElementsFilter;
  * Internally used by the SlottedDirective and the ChildrenDirective.
  */
 export declare abstract class NodeObservationDirective<T extends NodeBehaviorOptions> extends StatelessAttachedAttributeDirective<T> {
-    private controllerProperty;
+    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.

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

@@ -5,6 +5,10 @@ import type { CaptureType } from "./template.js";
  * @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.

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

@@ -1,4 +1,5 @@
 import type { FASTElement } from "../components/fast-element.js";
+import type { DOMPolicy } from "../dom.js";
 import { Constructable } from "../interfaces.js";
 import type { Subscriber } from "../observation/notifier.js";
 import type { ExecutionContext, Expression, ExpressionObserver } from "../observation/observable.js";
@@ -45,14 +46,10 @@ export declare class RenderDirective<TSource = any> implements HTMLDirective, Vi
     readonly dataBinding: Binding<TSource>;
     readonly templateBinding: Binding<TSource, ContentTemplate>;
     readonly templateBindingDependsOnData: boolean;
-    /**
-     * 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 an instance of RenderDirective.
      * @param dataBinding - A binding expression that returns the data to render.
@@ -123,12 +120,28 @@ export declare type TemplateRenderOptions = CommonRenderOptions & {
 export declare type BaseElementRenderOptions<TSource = any, TParent = any> = CommonRenderOptions & {
     /**
      * Attributes to use when creating the element template.
+     * @remarks
+     * This API should be used with caution. When providing attributes, if not done properly,
+     * you 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 attribute
+     * values particularly if they can come from user input.
      */
     attributes?: Record<string, string | TemplateValue<TSource, TParent>>;
     /**
      * Content to use when creating the element template.
+     * @remarks
+     * This API should be used with caution. When providing content, if not done properly,
+     * you 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 content
+     * particularly if it can come from user input. Prefer passing a template
+     * created by the the html tag helper rather than passing a raw string, as that will
+     * enable the JS runtime to help secure the static strings.
      */
     content?: string | SyntheticViewTemplate;
+    /**
+     * The DOMPolicy to create the render instruction with.
+     */
+    policy?: DOMPolicy;
 };
 /**
  * Render options used to specify an element.
@@ -150,7 +163,7 @@ export declare type TagNameRenderOptions<TSource = any, TParent = any> = BaseEle
      */
     tagName: string;
 };
-declare function createElementTemplate<TSource = any, TParent = any>(tagName: string, attributes?: Record<string, string | TemplateValue<TSource, TParent>>, content?: string | ContentTemplate): ViewTemplate<TSource, TParent>;
+declare function createElementTemplate<TSource = any, TParent = any>(tagName: string, attributes?: Record<string, string | TemplateValue<TSource, TParent>>, content?: string | ContentTemplate, policy?: DOMPolicy): ViewTemplate<TSource, TParent>;
 declare function create(options: TagNameRenderOptions): RenderInstruction;
 declare function create(options: ElementConstructorRenderOptions): RenderInstruction;
 declare function create(options: TemplateRenderOptions): RenderInstruction;
@@ -175,6 +188,11 @@ export declare const RenderInstruction: Readonly<{
     /**
      * Creates a RenderInstruction for a set of options.
      * @param options - The options to use when creating the RenderInstruction.
+     * @remarks
+     * This API should be used with caution. When providing attributes or content,
+     * if not done properly, you 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
+     * content and attribute values particularly if they can come from user input.
      */
     create: typeof create;
     /**
@@ -182,7 +200,13 @@ export declare const RenderInstruction: Readonly<{
      * @param tagName - The tag name to use when creating the template.
      * @param attributes - The attributes to apply to the element.
      * @param content - The content to insert into the element.
+     * @param policy - The DOMPolicy to create the template with.
      * @returns A template based on the provided specifications.
+     * @remarks
+     * This API should be used with caution. When providing attributes or content,
+     * if not done properly, you 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
+     * content and attribute values particularly if they can come from user input.
      */
     createElementTemplate: typeof createElementTemplate;
     /**

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

@@ -72,14 +72,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.

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

@@ -1,3 +1,4 @@
+import type { DOMPolicy } from "../dom.js";
 import type { Expression } from "../observation/observable.js";
 import { Binding, HTMLDirective, ViewBehaviorFactory } from "./html-directive.js";
 import type { ElementView, HTMLView, SyntheticView } from "./view.js";
@@ -41,11 +42,24 @@ export interface HTMLTemplateCompilationResult<TSource = any, TParent = any> {
      */
     createView(hostBindingTarget?: Element): HTMLView<TSource, TParent>;
 }
+/**
+ * A marker interface used to capture types when interpolating Directive helpers
+ * into templates.
+ * @public
+ */
+export interface CaptureType<TSource, TParent> {
+}
+/**
+ * Represents the types of values that can be interpolated into a template.
+ * @public
+ */
+export declare type TemplateValue<TSource, TParent = any> = Expression<TSource, any, TParent> | Binding<TSource, any, TParent> | HTMLDirective | CaptureType<TSource, TParent>;
 /**
  * A template capable of creating HTMLView instances or rendering directly to DOM.
  * @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
@@ -60,13 +74,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.
@@ -80,19 +104,21 @@ export declare class ViewTemplate<TSource = any, TParent = any> implements Eleme
      * @internal
      */
     toJSON: () => undefined;
+    /**
+     * 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>;
 }
-/**
- * A marker interface used to capture types when interpolating Directive helpers
- * into templates.
- * @public
- */
-export interface CaptureType<TSource, TParent> {
-}
-/**
- * Represents the types of values that can be interpolated into a template.
- * @public
- */
-export declare type TemplateValue<TSource, TParent = any> = Expression<TSource, any, TParent> | Binding<TSource, any, TParent> | HTMLDirective | CaptureType<TSource, TParent>;
 /**
  * Transforms a template literal string into a ViewTemplate.
  * @param strings - The string fragments that are interpolated with the values.

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

@@ -1,6 +1,6 @@
 import { Disposable } from "../interfaces.js";
 import { ExecutionContext, SourceLifetime } from "../observation/observable.js";
-import type { ViewBehaviorFactory, ViewBehaviorTargets, ViewController } from "./html-directive.js";
+import type { CompiledViewBehaviorFactory, ViewBehaviorTargets, ViewController } from "./html-directive.js";
 /**
  * Represents a collection of DOM nodes which can be bound to a data source.
  * @public
@@ -151,7 +151,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.

package/dist/dts/utilities.d.ts

@@ -1,3 +1,5 @@
+import type { HostBehavior } from "./styles/host.js";
+import type { ViewBehavior, ViewBehaviorFactory, ViewController } from "./templating/html-directive.js";
 /**
  * Retrieves the "composed parent" element of a node, ignoring DOM tree boundaries.
  * When the parent of a node is a shadow-root, it will return the host
@@ -34,3 +36,40 @@ export declare class UnobservableMutationObserver extends MutationObserver {
     observe(target: Node, options?: MutationObserverInit | undefined): void;
     unobserve(target: Node): void;
 }
+/**
+ * Bridges between ViewBehaviors and HostBehaviors, enabling a host to
+ * control ViewBehaviors.
+ * @public
+ */
+export 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;
+    /**
+     * Adds a behavior.
+     * @param behavior - The behavior to add.
+     */
+    addBehavior(behavior: ViewBehavior): void;
+    /**
+     * Adds a behavior factory.
+     * @param factory - The behavior factory to add.
+     * @param target - The target the factory will create behaviors for.
+     */
+    addBehaviorFactory(factory: ViewBehaviorFactory, target: Node): void;
+}
+/**
+ * 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>;
+}>;

package/dist/esm/components/attributes.js

@@ -1,7 +1,7 @@
 import { Observable } from "../observation/observable.js";
 import { isString } from "../interfaces.js";
 import { Updates } from "../observation/update-queue.js";
-import { DOM } from "../templating/dom.js";
+import { DOM } from "../dom.js";
 import { createMetadataLocator } from "../platform.js";
 const booleanMode = "boolean";
 const reflectMode = "reflect";

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

@@ -1,4 +1,4 @@
-import { isString } from "../interfaces.js";
+import { isString, KernelServiceId } from "../interfaces.js";
 import { Observable } from "../observation/observable.js";
 import { createTypeRegistry, FAST } from "../platform.js";
 import { ElementStyles } from "../styles/element-styles.js";
@@ -6,7 +6,7 @@ import { AttributeDefinition } from "./attributes.js";
 const defaultShadowOptions = { mode: "open" };
 const defaultElementOptions = {};
 const fastElementBaseTypes = new Set();
-const fastElementRegistry = FAST.getById(4 /* KernelServiceId.elementRegistry */, () => createTypeRegistry());
+const fastElementRegistry = FAST.getById(KernelServiceId.elementRegistry, () => createTypeRegistry());
 /**
  * Defines metadata for a FASTElement.
  * @public

package/dist/esm/debug.js

@@ -9,11 +9,14 @@ 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.",
     [1401 /* missingElementDefinition */]: "Missing FASTElement definition.",
     [1501 /* noRegistrationForContext */]: "No registration for Context/Interface '${name}'.",
     [1502 /* noFactoryForResolver */]: "Dependency injection resolver for '${key}' returned a null factory.",