@microsoft/fast-element 3.0.0-rc.1 → 3.0.0-rc.2

package/dist/fast-element.untrimmed.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Core APIs for building standards-based Web Components with FAST Element.
+ * @packageDocumentation
+ */
+
 /**
  * A path discovered from an access expression.
  * @public
@@ -149,7 +154,7 @@ export declare const AttributeConfiguration: Readonly<{
 }>;
 
 /**
- * An implementation of `Accessor` that supports reactivity,
+ * An implementation of {@link Accessor} that supports reactivity,
  * change callbacks, attribute reflection, and type conversion for
  * custom elements.
  * @public
@@ -232,20 +237,29 @@ export declare type AttributeMode = "reflect" | "boolean" | "fromView";
  * @public
  */
 export declare abstract class Binding<TSource = any, TReturn = any, TParent = any> {
-    evaluate: Expression<TSource, TReturn, TParent>;
-    policy?: DOMPolicy_2 | undefined;
-    isVolatile: boolean;
     /**
      * Options associated with the binding.
      */
     options?: any;
+    /**
+     * Evaluates the binding.
+     */
+    evaluate: Expression<TSource, TReturn, TParent>;
+    /**
+     * The security policy to associate with this binding.
+     */
+    policy?: DOMPolicy;
+    /**
+     * Indicates whether the binding is volatile.
+     */
+    isVolatile: boolean;
     /**
      * 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>, policy?: DOMPolicy_2 | undefined, isVolatile?: boolean);
+    constructor(evaluate: Expression<TSource, TReturn, TParent>, policy?: DOMPolicy, isVolatile?: boolean);
     /**
      * Creates an observer capable of notifying a subscriber when the output of a binding changes.
      * @param subscriber - The subscriber to changes in the binding.
@@ -317,7 +331,7 @@ export declare type Callable = typeof Function.prototype.call | {
  * into templates.
  * @public
  */
-export declare interface CaptureType {
+export declare interface CaptureType<TSource = any, TParent = any> {
 }
 
 /**
@@ -333,7 +347,7 @@ export declare interface ChildListDirectiveOptions<T = any> extends NodeBehavior
  * @param propertyOrOptions - The options used to configure child node observation.
  * @public
  */
-export declare function children<TSource = any>(propertyOrOptions: (keyof TSource & string) | ChildrenDirectiveOptions<keyof TSource & string>): CaptureType;
+export declare function children<TSource = any, TParent = any>(propertyOrOptions: (keyof TSource & string) | ChildrenDirectiveOptions<keyof TSource & string>): CaptureType<TSource, TParent>;
 
 /**
  * The runtime behavior for child node observation.
@@ -406,7 +420,7 @@ factories: Record<string, ViewBehaviorFactory>,
 /**
  * The security policy to compile the html with.
  */
-policy: DOMPolicy_2) => HTMLTemplateCompilationResult;
+policy: DOMPolicy) => HTMLTemplateCompilationResult;
 
 /**
  * Represents a ViewBehaviorFactory after the compilation process has completed.
@@ -431,7 +445,7 @@ export declare const Compiler: {
      * it is recommended that you clone the original and pass the clone to this API.
      * @public
      */
-    compile<TSource = any, TParent = any>(html: string | HTMLTemplateElement, factories: Record<string, ViewBehaviorFactory>, policy?: DOMPolicy_2): 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.
@@ -445,7 +459,7 @@ export declare const Compiler: {
      * @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)[], policy?: DOMPolicy_2): ViewBehaviorFactory;
+    aggregate(parts: (string | ViewBehaviorFactory)[], policy?: DOMPolicy): ViewBehaviorFactory;
 };
 
 /**
@@ -454,10 +468,6 @@ export declare const Compiler: {
  */
 export declare type ComposableStyles = string | ElementStyles | CSSStyleSheet;
 
-declare function compose<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(this: TType, nameOrDef: string | PartialFASTElementDefinition<TType>): Promise<FASTElementDefinition<TType>>;
-
-declare function compose<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition<TType>): Promise<FASTElementDefinition<TType>>;
-
 /**
  * Determines if the reference element contains the test element in a "composed" DOM tree that
  * ignores shadow DOM boundaries.
@@ -766,10 +776,6 @@ export declare class DefaultExecutionContext<TParent> implements ExecutionContex
     eventTarget<TTarget extends EventTarget>(): TTarget;
 }
 
-declare function define<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(this: TType, nameOrDef: string | PartialFASTElementDefinition<TType>, extensions?: FASTElementExtension[]): Promise<TType>;
-
-declare function define<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition<TType>, extensions?: FASTElementExtension[]): Promise<TType>;
-
 /**
  * Provides a mechanism for releasing resources.
  * @public
@@ -789,7 +795,7 @@ export declare const DOM: Readonly<{
     /**
      * Gets the dom policy used by the templating system.
      */
-    readonly policy: DOMPolicy_2;
+    readonly policy: DOMPolicy;
     /**
      * Sets the dom policy used by the templating system.
      * @param policy - The policy to set.
@@ -797,7 +803,7 @@ export declare const DOM: Readonly<{
      * 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_2): void;
+    setPolicy(value: DOMPolicy): void;
     /**
      * Sets an attribute value on an element.
      * @param element - The element to set the attribute value on.
@@ -913,23 +919,10 @@ export declare type DOMGuards = {
 };
 
 /**
- * A helper for creating DOM policies.
- * @public
- */
-export 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_2>;
-}>;
-
-/**
- * A security policy that FAST can use to interact with the DOM.
+ * A policy that controls whether values can be written to DOM sinks.
  * @public
  */
-declare interface DOMPolicy_2 {
+export declare interface DOMPolicy {
     /**
      * Creates safe HTML from the provided value.
      * @param value - The source to convert to safe HTML.
@@ -945,6 +938,19 @@ declare interface DOMPolicy_2 {
     protect(tagName: string | null, aspect: DOMAspect, aspectName: string, sink: DOMSink): DOMSink;
 }
 
+/**
+ * A helper for creating DOM policies.
+ * @public
+ */
+export 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>;
+}>;
+
 /**
  * Options for creating a DOM Policy.
  * @public
@@ -1457,7 +1463,7 @@ export declare const ExecutionContext: Readonly<{
     /**
      * A default execution context.
      */
-    default: ExecutionContext<any>;
+    default: ExecutionContext;
     /**
      * Gets the current event.
      * @returns An event object.
@@ -1621,12 +1627,49 @@ export declare interface FASTElement extends HTMLElement {
  * static helpers for working with FASTElements.
  * @public
  */
-export declare const FASTElement: {
+export declare const FASTElement: FASTElementConstructor;
+
+/**
+ * The FASTElement constructor and static registration helpers.
+ * @public
+ */
+export declare interface FASTElementConstructor {
+    /**
+     * Creates a FASTElement instance.
+     */
     new (): FASTElement;
-    define: typeof define;
-    compose: typeof compose;
-    from: typeof from;
-};
+    /**
+     * Defines a platform custom element based on the provided type and definition.
+     * @param nameOrDef - The name of the element to define or a definition object.
+     * @param extensions - Optional callbacks to run before registration.
+     */
+    define<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(this: TType, nameOrDef: string | PartialFASTElementDefinition<TType>, extensions?: FASTElementExtension[]): Promise<TType>;
+    /**
+     * Defines a platform custom element based on the provided type and definition.
+     * @param type - The custom element type to define.
+     * @param nameOrDef - The name of the element to define or a definition object.
+     * @param extensions - Optional callbacks to run before registration.
+     */
+    define<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition<TType>, extensions?: FASTElementExtension[]): Promise<TType>;
+    /**
+     * Composes FASTElement metadata without registering the element.
+     * @param nameOrDef - The name of the element to compose or a definition object.
+     */
+    compose<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(this: TType, nameOrDef: string | PartialFASTElementDefinition<TType>): Promise<FASTElementDefinition<TType>>;
+    /**
+     * Composes FASTElement metadata without registering the element.
+     * @param type - The custom element type to compose.
+     * @param nameOrDef - The name of the element to compose or a definition object.
+     */
+    compose<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition<TType>): Promise<FASTElementDefinition<TType>>;
+    /**
+     * Creates a new FASTElement base class inherited from the provided base type.
+     * @param BaseType - The base element type to inherit from.
+     */
+    from<TBase extends typeof HTMLElement>(BaseType: TBase): {
+        new (): InstanceType<TBase> & FASTElement;
+    };
+}
 
 /**
  * Defines metadata for a FASTElement.
@@ -1742,8 +1785,11 @@ export declare class FASTElementDefinition<TType extends Constructable<HTMLEleme
 export declare type FASTElementExtension = (definition: FASTElementDefinition) => void;
 
 /**
- * The FAST custom element registry
- * @internal
+ * The FAST custom element registry.
+ * @remarks
+ * This registry stores FAST element definitions by constructor so consumers can
+ * look up the `FASTElementDefinition` associated with an element type or instance.
+ * @public
  */
 export declare const fastElementRegistry: TypeRegistry<FASTElementDefinition>;
 
@@ -1753,8 +1799,6 @@ export declare const fastElementRegistry: TypeRegistry<FASTElementDefinition>;
  */
 export declare type FASTElementTemplateResolver<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>> = (definition: FASTElementDefinition<TType>) => ElementViewTemplate<InstanceType<TType>> | Promise<ElementViewTemplate<InstanceType<TType>>>;
 
-declare function from<TBase extends typeof HTMLElement>(BaseType: TBase): new () => InstanceType<TBase> & FASTElement;
-
 /**
  * Represents an object that can contribute behavior to a host.
  * @public
@@ -1847,7 +1891,6 @@ export declare const html: HTMLTemplateTag;
  * @public
  */
 export declare class HTMLBindingDirective implements HTMLDirective, ViewBehaviorFactory, ViewBehavior, Aspected, BindingDirective {
-    dataBinding: Binding;
     private data;
     private updateTarget;
     /**
@@ -1865,7 +1908,7 @@ export declare class HTMLBindingDirective implements HTMLDirective, ViewBehavior
     /**
      * The policy that the created behavior must run under.
      */
-    policy: DOMPolicy_2;
+    policy: DOMPolicy;
     /**
      * The original source aspect exactly as represented in markup.
      */
@@ -1878,6 +1921,10 @@ export declare class HTMLBindingDirective implements HTMLDirective, ViewBehavior
      * The type of aspect to target.
      */
     aspectType: DOMAspect;
+    /**
+     * The binding configuration to apply.
+     */
+    dataBinding: Binding;
     /**
      * Creates an instance of HTMLBindingDirective.
      * @param dataBinding - The binding configuration to apply.
@@ -2458,13 +2505,13 @@ export declare const Observable: Readonly<{
      * @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>(expression: Expression<TSource, TReturn, any>, initialSubscriber?: Subscriber, isVolatileBinding?: boolean): ExpressionNotifier<TSource, TReturn, any>;
+    binding<TSource = any, TReturn = any>(expression: Expression<TSource, TReturn>, initialSubscriber?: Subscriber, isVolatileBinding?: boolean): ExpressionNotifier<TSource, TReturn>;
     /**
      * Determines whether a binding expression is volatile and needs to have its dependency list re-evaluated
      * on every evaluation of the value.
      * @param expression - The binding to inspect.
      */
-    isVolatileBinding<TSource_1 = any, TReturn_1 = any>(expression: Expression<TSource_1, TReturn_1, any>): boolean;
+    isVolatileBinding<TSource = any, TReturn = any>(expression: Expression<TSource, TReturn>): boolean;
 }>;
 
 /**
@@ -2497,7 +2544,7 @@ export declare interface ObservationRecord {
  * @returns A binding configuration.
  * @public
  */
-export declare function oneTime<T = any>(expression: Expression<T>, policy?: DOMPolicy_2): Binding<T>;
+export declare function oneTime<T = any>(expression: Expression<T>, policy?: DOMPolicy): Binding<T>;
 
 /**
  * Creates an standard binding.
@@ -2507,7 +2554,7 @@ export declare function oneTime<T = any>(expression: Expression<T>, policy?: DOM
  * @returns A binding configuration.
  * @public
  */
-export declare function oneWay<T = any>(expression: Expression<T>, policy?: DOMPolicy_2, isVolatile?: boolean): Binding<T>;
+export declare function oneWay<T = any>(expression: Expression<T>, policy?: DOMPolicy, isVolatile?: boolean): Binding<T>;
 
 /**
  * A read/write stateful value associated with an owner.
@@ -2689,7 +2736,7 @@ export declare type ReadonlyState<T> = {
  * @param propertyName - The name of the property to assign the reference to.
  * @public
  */
-export declare const ref: <TSource = any>(propertyName: keyof TSource & string) => CaptureType;
+export declare const ref: <TSource = any, TParent = any>(propertyName: keyof TSource & string) => CaptureType<TSource, TParent>;
 
 /**
  * The runtime behavior for template references.
@@ -2733,7 +2780,7 @@ export declare interface RegisterPathConfig {
  * RenderInstruction to determine the view.
  * @public
  */
-export declare function render<TSource = any, TItem = any, TParent = any>(value?: Expression<TSource, TItem> | Binding<TSource, TItem> | {}, template?: ContentTemplate | string | Expression<TSource, ContentTemplate | string | Node, TParent> | Binding<TSource, ContentTemplate | string | Node, TParent>): CaptureType;
+export declare function render<TSource = any, TItem = any, TParent = any>(value?: Expression<TSource, TItem> | Binding<TSource, TItem> | {}, template?: ContentTemplate | string | Expression<TSource, ContentTemplate | string | Node, TParent> | Binding<TSource, ContentTemplate | string | Node, TParent>): CaptureType<TSource, TParent>;
 
 /**
  * A Behavior that enables advanced rendering.
@@ -2813,7 +2860,7 @@ export declare class RenderDirective<TSource = any> implements HTMLDirective, Vi
  * @param options - Options used to turn on special repeat features.
  * @public
  */
-export declare function repeat<TSource = any, TArray extends ReadonlyArray<any> = ReadonlyArray<any>, TParent = any>(items: Expression<TSource, TArray, TParent> | Binding<TSource, TArray, TParent> | ReadonlyArray<any>, template: Expression<TSource, ViewTemplate<any, TSource>> | Binding<TSource, ViewTemplate<any, TSource>> | ViewTemplate<any, TSource>, options?: RepeatOptions): CaptureType;
+export declare function repeat<TSource = any, TArray extends ReadonlyArray<any> = ReadonlyArray<any>, TParent = any>(items: Expression<TSource, TArray, TParent> | Binding<TSource, TArray, TParent> | ReadonlyArray<any>, template: Expression<TSource, ViewTemplate<any, TSource>> | Binding<TSource, ViewTemplate<any, TSource>> | ViewTemplate<any, TSource>, options?: RepeatOptions): CaptureType<TSource, TParent>;
 
 /**
  * A behavior that renders a template for each item in an array.
@@ -3065,7 +3112,7 @@ export declare const Signal: Readonly<{
  * @returns A binding configuration.
  * @public
  */
-export declare function signal<T = any>(expression: Expression<T>, options: string | Expression<T>, policy?: DOMPolicy_2): Binding<T>;
+export declare function signal<T = any>(expression: Expression<T>, options: string | Expression<T>, policy?: DOMPolicy): Binding<T>;
 
 /**
  * A directive that observes the `assignedNodes()` of a slot and updates a property
@@ -3073,7 +3120,7 @@ export declare function signal<T = any>(expression: Expression<T>, options: stri
  * @param propertyOrOptions - The options used to configure slotted node observation.
  * @public
  */
-export declare function slotted<TSource = any>(propertyOrOptions: (keyof TSource & string) | SlottedDirectiveOptions<keyof TSource & string>): CaptureType;
+export declare function slotted<TSource = any, TParent = any>(propertyOrOptions: (keyof TSource & string) | SlottedDirectiveOptions<keyof TSource & string>): CaptureType<TSource, TParent>;
 
 /**
  * The runtime behavior for slotted node observation.
@@ -3559,7 +3606,7 @@ export declare interface SyntheticViewTemplate<TSource = any, TParent = any> {
     /**
      * Returns a directive that can inline the template.
      */
-    inline(): CaptureType;
+    inline(): CaptureType<TSource, TParent>;
 }
 
 /**
@@ -3597,7 +3644,7 @@ export declare interface TemplateLifecycleCallbacks {
  * 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;
+export declare type TemplateValue<TSource, TParent = any> = Expression<TSource, any, TParent> | Binding<TSource, any, TParent> | HTMLDirective | CaptureType<TSource, TParent>;
 
 /**
  * A policy for use with the standard trustedTypes platform API.
@@ -3620,7 +3667,7 @@ export declare type TrustedTypesPolicy = {
  * @returns A binding.
  * @public
  */
-export declare function twoWay<T = any>(expression: Expression<T>, optionsOrChangeEvent?: TwoWayBindingOptions | string, policy?: DOMPolicy_2, isBindingVolatile?: boolean): Binding<T>;
+export declare function twoWay<T = any>(expression: Expression<T>, optionsOrChangeEvent?: TwoWayBindingOptions | string, policy?: DOMPolicy, isBindingVolatile?: boolean): Binding<T>;
 
 /**
  * The twoWay binding options.
@@ -3657,20 +3704,36 @@ export declare const TwoWaySettings: Readonly<{
 }>;
 
 /**
- * Do not change. Part of shared kernel contract.
- * @internal
+ * A type that can be registered with a `TypeRegistry`.
+ * @public
  */
-declare interface TypeDefinition {
+export declare interface TypeDefinition {
+    /**
+     * The registered type constructor.
+     */
     type: Function;
 }
 
 /**
- * Do not change. Part of shared kernel contract.
- * @internal
+ * A registry that stores definitions by type.
+ * @public
  */
 export declare interface TypeRegistry<TDefinition extends TypeDefinition> {
+    /**
+     * Registers a type definition.
+     * @param definition - The type definition to register.
+     * @returns `true` when the definition was registered, otherwise `false`.
+     */
     register(definition: TDefinition): boolean;
+    /**
+     * Gets a definition by type.
+     * @param key - The type to retrieve the definition for.
+     */
     getByType(key: Function): TDefinition | undefined;
+    /**
+     * Gets a definition by instance.
+     * @param object - The instance to retrieve the definition for.
+     */
     getForInstance(object: any): TDefinition | undefined;
 }
 
@@ -3810,7 +3873,7 @@ export declare interface ViewBehaviorFactory {
     /**
      * The policy that the created behavior must run under.
      */
-    policy?: DOMPolicy_2;
+    policy?: DOMPolicy;
     /**
      * Creates a behavior.
      */
@@ -3914,7 +3977,7 @@ export declare class ViewTemplate<TSource = any, TParent = any> implements Eleme
      * @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>, policy?: DOMPolicy_2 | undefined);
+    constructor(html: string | HTMLTemplateElement, factories?: Record<string, ViewBehaviorFactory>, policy?: DOMPolicy | undefined);
     /**
      * @internal
      */
@@ -3922,7 +3985,7 @@ export declare class ViewTemplate<TSource = any, TParent = any> implements Eleme
     /**
      * Returns a directive that can inline the template.
      */
-    inline(): CaptureType;
+    inline(): CaptureType<TSource, TParent>;
     /**
      * Sets the DOMPolicy for this template.
      * @param policy - The policy to associated with this template.
@@ -3931,7 +3994,7 @@ export declare class ViewTemplate<TSource = any, TParent = any> implements Eleme
      * The DOMPolicy can only be set once for a template and cannot be
      * set after the template is compiled.
      */
-    withPolicy(policy: DOMPolicy_2): this;
+    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.
@@ -3976,7 +4039,7 @@ export declare class ViewTemplate<TSource = any, TParent = any> implements Eleme
      * 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_2): ViewTemplate<TSource, TParent>;
+    static create<TSource = any, TParent = any>(strings: string[], values: TemplateValue<TSource, TParent>[], policy?: DOMPolicy): ViewTemplate<TSource, TParent>;
 }
 
 /**
@@ -4006,6 +4069,6 @@ export declare function watch(object: any, subscriber: Subscriber | ((subject: a
  * gets the template to render when the conditional is false.
  * @public
  */
-export declare function when<TSource = any, TReturn = any, TParent = any>(condition: Expression<TSource, TReturn, TParent> | boolean, templateOrTemplateBinding: SyntheticViewTemplate<TSource, TParent> | Expression<TSource, SyntheticViewTemplate<TSource, TParent>, TParent>, elseTemplateOrTemplateBinding?: SyntheticViewTemplate<TSource, TParent> | Expression<TSource, SyntheticViewTemplate<TSource, TParent>, TParent>): CaptureType;
+export declare function when<TSource = any, TReturn = any, TParent = any>(condition: Expression<TSource, TReturn, TParent> | boolean, templateOrTemplateBinding: SyntheticViewTemplate<TSource, TParent> | Expression<TSource, SyntheticViewTemplate<TSource, TParent>, TParent>, elseTemplateOrTemplateBinding?: SyntheticViewTemplate<TSource, TParent> | Expression<TSource, SyntheticViewTemplate<TSource, TParent>, TParent>): CaptureType<TSource, TParent>;
 
 export { }