@microsoft/fast-element 2.0.0-beta.2 → 2.0.0-beta.21

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

@@ -0,0 +1,83 @@
+import { DOMAspect, DOMPolicy, DOMSink } from "./dom.js";
+import { TrustedTypesPolicy } from "./interfaces.js";
+/**
+ * A specific DOM sink guard for a node aspect.
+ * @public
+ */
+export declare type DOMSinkGuards = Record<string, (tagName: string | null, aspect: DOMAspect, aspectName: string, sink: DOMSink) => DOMSink>;
+/**
+ * Aspect-specific guards for a DOM Policy.
+ * @public
+ */
+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.
+ * @public
+ */
+export declare type DOMElementGuards = Record<string, DOMAspectGuards>;
+/**
+ * Guard configuration for a DOM Policy.
+ * @public
+ */
+export declare type DOMGuards = {
+    /**
+     * Guards for specific elements.
+     */
+    elements: DOMElementGuards;
+    /**
+     * General aspect guards independent of the element type.
+     */
+    aspects: DOMAspectGuards;
+};
+/**
+ * Options for creating a DOM Policy.
+ * @public
+ */
+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>;
+};
+/**
+ * A helper for creating DOM policies.
+ * @public
+ */
+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,100 @@
+/**
+ * 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<{
+    /**
+     * 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,14 +1,15 @@
-export type { Callable, Constructable, Disposable, FASTGlobal, Mutable, StyleStrategy, StyleTarget, TrustedTypes, TrustedTypesPolicy, } from "./interfaces.js";
+export type { Callable, Constructable, Class, Disposable, FASTGlobal, TrustedTypesPolicy, } 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";
 export * from "./observation/update-queue.js";
-export type { Behavior } from "./observation/behavior.js";
 export * from "./styles/element-styles.js";
 export * from "./styles/css.js";
 export * from "./styles/css-directive.js";
-export * from "./templating/dom.js";
+export * from "./styles/host.js";
+export * from "./styles/style-strategy.js";
 export * from "./templating/template.js";
 export * from "./templating/compiler.js";
 export { Markup, Parser } from "./templating/markup.js";
@@ -24,4 +25,4 @@ export * from "./templating/node-observation.js";
 export * from "./components/fast-element.js";
 export * from "./components/fast-definitions.js";
 export * from "./components/attributes.js";
-export * from "./components/controller.js";
+export { ElementController, ElementControllerStrategy, } from "./components/element-controller.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

@@ -6,13 +6,23 @@ export declare type Callable = typeof Function.prototype.call | {
     call(): void;
 };
 /**
- * Allows for the creation of Constructable mixin classes.
+ * Represents a type which can be constructed with the new operator.
  *
  * @public
  */
 export declare type Constructable<T = {}> = {
     new (...args: any[]): T;
 };
+/**
+ * Represents a constructable class with a prototype.
+ * @public
+ */
+export declare type Class<T, C = {}> = C & Constructable<T> & {
+    /**
+     * The class's prototype;
+     */
+    readonly prototype: T;
+};
 /**
  * Provides a mechanism for releasing resources.
  * @public
@@ -23,18 +33,6 @@ export interface Disposable {
      */
     dispose(): void;
 }
-/**
- * Reverses all readonly members, making them mutable.
- * @internal
- */
-export declare type Mutable<T> = {
-    -readonly [P in keyof T]: T[P];
-};
-/**
- * Extracts the item type from an array.
- * @public
- */
-export declare type ArrayItem<T> = T extends ReadonlyArray<infer TItem> ? TItem : T extends Array<infer TItem> ? TItem : any;
 /**
  * A policy for use with the standard trustedTypes platform API.
  * @public
@@ -47,20 +45,15 @@ export declare type TrustedTypesPolicy = {
     createHTML(html: string): string;
 };
 /**
- * Enables working with trusted types.
- * @public
+ * Reverses all readonly members, making them mutable.
+ * @internal
  */
-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;
+export declare type Mutable<T> = {
+    -readonly [P in keyof T]: T[P];
 };
 /**
  * The FAST global.
- * @internal
+ * @public
  */
 export interface FASTGlobal {
     /**
@@ -77,90 +70,79 @@ export interface FASTGlobal {
     /**
      * Sends a warning to the developer.
      * @param code - The warning code to send.
-     * @param args - Args relevant for the warning.
+     * @param values - Values relevant for the warning message.
      */
-    warn(code: number, ...args: any[]): void;
+    warn(code: number, values?: Record<string, any>): void;
     /**
      * Creates an error.
      * @param code - The error code to send.
-     * @param args - Args relevant for the error.
+     * @param values - Values relevant for the error message.
      */
-    error(code: number, ...args: any[]): Error;
+    error(code: number, values?: Record<string, any>): Error;
     /**
      * Adds debug messages for errors and warnings.
      * @param messages - The message dictionary to add.
+     * @remarks
+     * Message can include placeholders like $\{name\} which can be
+     * replaced by values passed at runtime.
      */
     addMessages(messages: Record<number, string>): void;
 }
 /**
- * Core services shared across FAST instances.
+ * Core services that can be shared across FAST instances.
  * @internal
  */
-export declare const enum KernelServiceId {
-    updateQueue = 1,
-    observable = 2,
-    contextEvent = 3,
-    elementRegistry = 4,
-    styleSheetStrategy = 5,
-    developerChannel = 6
-}
-/**
- * A node that can be targeted by styles.
- * @public
- */
-export interface StyleTarget {
-    /**
-     * Stylesheets to be adopted by the node.
-     */
-    adoptedStyleSheets?: CSSStyleSheet[];
-    /**
-     * Adds styles to the target by appending the styles.
-     * @param styles - The styles element to add.
-     */
-    append(styles: HTMLStyleElement): void;
-    /**
-     * Removes styles from the target.
-     * @param styles - The styles element to remove.
-     */
-    removeChild(styles: HTMLStyleElement): void;
-    /**
-     * Returns all element descendants of node that match selectors.
-     * @param selectors - The CSS selector to use for the query.
-     */
-    querySelectorAll<E extends Element = Element>(selectors: string): NodeListOf<E>;
-}
-/**
- * Implemented to provide specific behavior when adding/removing styles
- * for elements.
- * @public
- */
-export interface StyleStrategy {
-    /**
-     * Adds styles to the target.
-     * @param target - The target to add the styles to.
-     */
-    addStylesTo(target: StyleTarget): void;
-    /**
-     * Removes styles from the target.
-     * @param target - The target to remove the styles from.
-     */
-    removeStylesFrom(target: StyleTarget): void;
-}
+declare type KernelServiceId = {
+    readonly updateQueue: string | number;
+    readonly observable: string | number;
+    readonly contextEvent: string | number;
+    readonly elementRegistry: string | number;
+};
+declare let KernelServiceId: KernelServiceId;
+export { KernelServiceId };
 /**
  * Warning and error messages.
  * @internal
  */
 export declare const enum Message {
     needsArrayObservation = 1101,
-    onlySetHTMLPolicyOnce = 1201,
+    onlySetDOMPolicyOnce = 1201,
     bindingInnerHTMLRequiresTrustedTypes = 1202,
-    missingElementDefinition = 1401
+    twoWayBindingRequiresObservables = 1203,
+    hostBindingWithoutHost = 1204,
+    unsupportedBindingBehavior = 1205,
+    directCallToHTMLTagNotAllowed = 1206,
+    onlySetTemplatePolicyOnce = 1207,
+    cannotSetTemplatePolicyAfterCompilation = 1208,
+    blockedByDOMPolicy = 1209,
+    missingElementDefinition = 1401,
+    noRegistrationForContext = 1501,
+    noFactoryForResolver = 1502,
+    invalidResolverStrategy = 1503,
+    cannotAutoregisterDependency = 1504,
+    cannotResolveKey = 1505,
+    cannotConstructNativeFunction = 1506,
+    cannotJITRegisterNonConstructor = 1507,
+    cannotJITRegisterIntrinsic = 1508,
+    cannotJITRegisterInterface = 1509,
+    invalidResolver = 1510,
+    invalidKey = 1511,
+    noDefaultResolver = 1512,
+    cyclicDependency = 1513,
+    connectUpdateRequiresController = 1514
 }
 /**
+ * Determines whether or not an object is a function.
  * @internal
  */
 export declare const isFunction: (object: any) => object is Function;
 /**
+ * Determines whether or not an object is a string.
  * @internal
  */
 export declare const isString: (object: any) => object is string;
+/**
+ * A function which does nothing.
+ * @internal
+ */
+export declare const noop: () => undefined;

package/dist/dts/metadata.d.ts

@@ -8,18 +8,18 @@ export declare const Metadata: Readonly<{
      * @param Type - The type to get the metadata for.
      * @returns The metadata array or a frozen empty array if no metadata is found.
      */
-    getDesignParamTypes: (Type: any) => any;
+    getDesignParamTypes: (Type: Constructable) => readonly any[];
     /**
      * Gets the "annotation:paramtypes" metadata for the specified type.
      * @param Type - The type to get the metadata for.
      * @returns The metadata array or a frozen empty array if no metadata is found.
      */
-    getAnnotationParamTypes: (Type: any) => any;
+    getAnnotationParamTypes: (Type: Constructable) => readonly any[];
     /**
-     *
-     * @param Type - Gets the "annotation:paramtypes" metadata for the specified type. If none is found,
+     * Gets the "annotation:paramtypes" metadata for the specified type. If none is found,
      * an empty, mutable metadata array is created and added.
-     * @returns The metadata array.
+     * @param Type - The type to get or create the metadata for.
+     * @returns A mutable metadata array.
      */
     getOrCreateAnnotationParamTypes(Type: Constructable): any[];
 }>;

package/dist/dts/observation/observable.d.ts

@@ -23,10 +23,10 @@ export interface Accessor {
 }
 /**
  * The signature of an arrow function capable of being evaluated
- * as part of a template binding update.
+ * against source data and within an execution context.
  * @public
  */
-export declare type Binding<TSource = any, TReturn = any, TParent = any> = (source: TSource, context: ExecutionContext<TParent>) => TReturn;
+export declare type Expression<TSource = any, TReturn = any, TParent = any> = (source: TSource, context: ExecutionContext<TParent>) => TReturn;
 /**
  * A record of observable property access.
  * @public
@@ -41,20 +41,80 @@ export interface ObservationRecord {
      */
     propertyName: string;
 }
+/**
+ * Describes how the source's lifetime relates to its controller's lifetime.
+ * @public
+ */
+export declare const SourceLifetime: Readonly<{
+    /**
+     * The source to controller lifetime relationship is unknown.
+     */
+    readonly unknown: undefined;
+    /**
+     * The source and controller lifetimes are coupled to one another.
+     * They can/will be GC'd together.
+     */
+    readonly coupled: 1;
+}>;
+/**
+ * Describes how the source's lifetime relates to its controller's lifetime.
+ * @public
+ */
+export declare type SourceLifetime = typeof SourceLifetime[keyof typeof SourceLifetime];
+/**
+ * Controls the lifecycle of an expression and provides relevant context.
+ * @public
+ */
+export interface ExpressionController<TSource = any, TParent = any> {
+    /**
+     * The source the expression is evaluated against.
+     */
+    readonly source: TSource;
+    /**
+     * Indicates how the source's lifetime relates to the controller's lifetime.
+     */
+    readonly sourceLifetime?: SourceLifetime;
+    /**
+     * The context the expression is evaluated against.
+     */
+    readonly context: ExecutionContext<TParent>;
+    /**
+     * Indicates whether the controller is bound.
+     */
+    readonly isBound: boolean;
+    /**
+     * Registers an unbind handler with the controller.
+     * @param behavior - An object to call when the controller unbinds.
+     */
+    onUnbind(behavior: {
+        unbind(controller: ExpressionController<TSource, TParent>): any;
+    }): void;
+}
+/**
+ * Observes an expression for changes.
+ * @public
+ */
+export interface ExpressionObserver<TSource = any, TReturn = any, TParent = any> {
+    /**
+     * Binds the expression to the source.
+     * @param controller - The controller that manages the lifecycle and related
+     * context for the expression.
+     */
+    bind(controller: ExpressionController<TSource, TParent>): TReturn;
+}
 /**
  * Enables evaluation of and subscription to a binding.
  * @public
  */
-export interface BindingObserver<TSource = any, TReturn = any, TParent = any> extends Notifier, Disposable {
+export interface ExpressionNotifier<TSource = any, TReturn = any, TParent = any> extends Notifier, ExpressionObserver<TSource, TReturn, TParent>, Disposable {
     /**
-     * Begins observing the binding for the source and returns the current value.
-     * @param source - The source that the binding is based on.
-     * @param context - The execution context to execute the binding within.
-     * @returns The value of the binding.
+     * Observes the expression.
+     * @param source - The source for the expression.
+     * @param context - The context for the expression.
      */
-    observe(source: TSource, context?: ExecutionContext<TParent>): TReturn;
+    observe(source: TSource, context?: ExecutionContext): TReturn;
     /**
-     * Gets {@link ObservationRecord|ObservationRecords} that the {@link BindingObserver}
+     * Gets {@link ObservationRecord|ObservationRecords} that the {@link ExpressionNotifier}
      * is observing.
      */
     records(): IterableIterator<ObservationRecord>;
@@ -114,19 +174,19 @@ export declare const Observable: Readonly<{
      */
     getAccessors: (target: {}) => Accessor[];
     /**
-     * Creates a {@link BindingObserver} that can watch the
-     * provided {@link Binding} for changes.
-     * @param binding - The binding to observe.
+     * Creates a {@link ExpressionNotifier} that can watch the
+     * provided {@link Expression} for changes.
+     * @param expression - The binding to observe.
      * @param initialSubscriber - An initial subscriber to changes in the binding value.
      * @param isVolatileBinding - Indicates whether the binding's dependency list must be re-evaluated on every value evaluation.
      */
-    binding<TSource = any, TReturn = any>(binding: Binding<TSource, TReturn, any>, initialSubscriber?: Subscriber, isVolatileBinding?: boolean): BindingObserver<TSource, TReturn, any>;
+    binding<TSource = any, TReturn = any>(expression: Expression<TSource, TReturn, any>, initialSubscriber?: Subscriber, isVolatileBinding?: boolean): ExpressionNotifier<TSource, TReturn, any>;
     /**
      * Determines whether a binding expression is volatile and needs to have its dependency list re-evaluated
      * on every evaluation of the value.
-     * @param binding - The binding to inspect.
+     * @param expression - The binding to inspect.
      */
-    isVolatileBinding<TSource_1 = any, TReturn_1 = any>(binding: Binding<TSource_1, TReturn_1, any>): boolean;
+    isVolatileBinding<TSource_1 = any, TReturn_1 = any>(expression: Expression<TSource_1, TReturn_1, any>): boolean;
 }>;
 /**
  * Decorator: Defines an observable property on the target.
@@ -147,11 +207,7 @@ export declare function volatile(target: {}, name: string | Accessor, descriptor
  * Provides additional contextual information available to behaviors and expressions.
  * @public
  */
-export declare class ExecutionContext<TParentSource = any> {
-    /**
-     * The default execution context.
-     */
-    static readonly default: ExecutionContext<any>;
+export interface ExecutionContext<TParent = any> {
     /**
      * The index of the current item within a repeat context.
      */
@@ -163,41 +219,40 @@ export declare class ExecutionContext<TParentSource = any> {
     /**
      * The parent data source within a nested context.
      */
-    readonly parent: TParentSource;
+    parent: TParent;
     /**
      * The parent execution context when in nested context scenarios.
      */
-    readonly parentContext: ExecutionContext<TParentSource>;
-    private constructor();
+    parentContext: ExecutionContext<TParent>;
     /**
      * The current event within an event handler.
      */
-    get event(): Event;
+    readonly event: Event;
     /**
      * Indicates whether the current item within a repeat context
      * has an even index.
      */
-    get isEven(): boolean;
+    readonly isEven: boolean;
     /**
      * Indicates whether the current item within a repeat context
      * has an odd index.
      */
-    get isOdd(): boolean;
+    readonly isOdd: boolean;
     /**
      * Indicates whether the current item within a repeat context
      * is the first item in the collection.
      */
-    get isFirst(): boolean;
+    readonly isFirst: boolean;
     /**
      * Indicates whether the current item within a repeat context
      * is somewhere in the middle of the collection.
      */
-    get isInMiddle(): boolean;
+    readonly isInMiddle: boolean;
     /**
      * Indicates whether the current item within a repeat context
      * is the last item in the collection.
      */
-    get isLast(): boolean;
+    readonly isLast: boolean;
     /**
      * Returns the typed event detail of a custom event.
      */
@@ -206,34 +261,24 @@ export declare class ExecutionContext<TParentSource = any> {
      * Returns the typed event target of the event.
      */
     eventTarget<TTarget extends EventTarget>(): TTarget;
+}
+/**
+ * Provides additional contextual information available to behaviors and expressions.
+ * @public
+ */
+export declare const ExecutionContext: Readonly<{
     /**
-     * Updates the position/size on a context associated with a list item.
-     * @param index - The new index of the item.
-     * @param length - The new length of the list.
-     */
-    updatePosition(index: number, length: number): void;
-    /**
-     * Creates a new execution context descendent from the current context.
-     * @param source - The source for the context if different than the parent.
-     * @returns A child execution context.
-     */
-    createChildContext<TParentSource>(parentSource: TParentSource): ExecutionContext<TParentSource>;
-    /**
-     * Creates a new execution context descent suitable for use in list rendering.
-     * @param item - The list item to serve as the source.
-     * @param index - The index of the item in the list.
-     * @param length - The length of the list.
+     * A default execution context.
      */
-    createItemContext(index: number, length: number): ExecutionContext<TParentSource>;
+    default: ExecutionContext<any>;
     /**
-     * Sets the event for the current execution context.
-     * @param event - The event to set.
-     * @internal
+     * Gets the current event.
+     * @returns An event object.
      */
-    static setEvent(event: Event | null): void;
+    getEvent(): Event | null;
     /**
-     * Creates a new root execution context.
-     * @returns A new execution context.
+     * Sets the current event.
+     * @param event - An event object.
      */
-    static create(): ExecutionContext;
-}
+    setEvent(event: Event | null): void;
+}>;