@microsoft/fast-element 2.0.0-beta.20 → 2.0.0-beta.22

package/dist/fast-element.d.ts

@@ -207,16 +207,6 @@ export declare class AttributeDefinition implements Accessor {
  */
 export declare type AttributeMode = typeof reflectMode | typeof booleanMode | "fromView";
 
-/**
- * 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>, policy?: DOMPolicy, isVolatile?: boolean): Binding<T>;
-
 /**
  * Captures a binding expression along with related information and capabilities.
  *
@@ -239,10 +229,30 @@ export declare abstract class Binding<TSource = any, TReturn = any, TParent = an
     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.
      * @param subscriber - The subscriber to changes in the binding.
+     * @param directive - The Binding directive to create the observer for.
      */
-    abstract createObserver(directive: HTMLDirective, subscriber: Subscriber): ExpressionObserver<TSource, TReturn, TParent>;
+    abstract createObserver(subscriber: Subscriber, directive: BindingDirective): ExpressionObserver<TSource, TReturn, TParent>;
+}
+
+/**
+ * The directive from which a binding originates.
+ *
+ * @public
+ */
+export declare interface BindingDirective {
+    /**
+     * The binding.
+     */
+    readonly dataBinding: Binding;
+    /**
+     * The evaluated target aspect.
+     */
+    readonly targetAspect?: string;
+    /**
+     * The type of aspect to target.
+     */
+    readonly aspectType?: DOMAspect;
 }
 
 /**
@@ -461,10 +471,6 @@ export declare interface ContentView {
     remove(): void;
 }
 
-/* Excluded from this release type: createMetadataLocator */
-
-/* Excluded from this release type: createTypeRegistry */
-
 /**
  * Transforms a template literal string into styles.
  * @param strings - The string fragments that are interpolated with the values.
@@ -475,6 +481,54 @@ export declare interface ContentView {
  */
 export declare const css: CSSTemplateTag;
 
+/**
+ * Enables bindings in CSS.
+ *
+ * @public
+ */
+export declare class CSSBindingDirective implements HostBehavior, Subscriber, CSSDirective, BindingDirective {
+    readonly dataBinding: Binding;
+    readonly targetAspect: string;
+    /**
+     * Creates an instance of CSSBindingDirective.
+     * @param dataBinding - The binding to use in CSS.
+     * @param targetAspect - The CSS property to target.
+     */
+    constructor(dataBinding: Binding, targetAspect: string);
+    /**
+     * Creates a CSS fragment to interpolate into the CSS document.
+     * @returns - the string to interpolate into CSS
+     */
+    createCSS(add: AddBehavior): ComposableStyles;
+    /**
+     * Executed when this behavior is attached to a controller.
+     * @param controller - Controls the behavior lifecycle.
+     */
+    addedCallback(controller: HostController<HTMLElement & {
+        $cssBindings: Map<CSSBindingDirective, CSSBindingEntry>;
+    }>): void;
+    /**
+     * Executed when this behavior's host is connected.
+     * @param controller - Controls the behavior lifecycle.
+     */
+    connectedCallback(controller: HostController<HTMLElement & {
+        $cssBindings: Map<CSSBindingDirective, CSSBindingEntry>;
+    }>): void;
+    /**
+     * Executed when this behavior is detached from a controller.
+     * @param controller - Controls the behavior lifecycle.
+     */
+    removedCallback(controller: HostController<HTMLElement & {
+        $cssBindings: Map<CSSBindingDirective, CSSBindingEntry>;
+    }>): void;
+    /* Excluded from this release type: handleChange */
+}
+
+declare type CSSBindingEntry = {
+    observer: ExpressionObserver;
+    controller: HostController;
+};
+
 /**
  * Directive for use in {@link css}.
  *
@@ -537,16 +591,22 @@ export declare interface CSSDirectiveDefinition<TType extends Constructable<CSSD
  * Use the .partial method to create partial CSS fragments.
  * @public
  */
-export declare type CSSTemplateTag = ((strings: TemplateStringsArray, ...values: (ComposableStyles | CSSDirective)[]) => ElementStyles) & {
+export declare type CSSTemplateTag = (<TSource = any, TParent = any>(strings: TemplateStringsArray, ...values: CSSValue<TSource, TParent>[]) => ElementStyles) & {
     /**
      * Transforms a template literal string into partial CSS.
      * @param strings - The string fragments that are interpolated with the values.
      * @param values - The values that are interpolated with the string fragments.
      * @public
      */
-    partial(strings: TemplateStringsArray, ...values: (ComposableStyles | CSSDirective)[]): CSSDirective;
+    partial<TSource = any, TParent = any>(strings: TemplateStringsArray, ...values: CSSValue<TSource, TParent>[]): CSSDirective;
 };
 
+/**
+ * Represents the types of values that can be interpolated into a template.
+ * @public
+ */
+export declare type CSSValue<TSource, TParent = any> = Expression<TSource, any, TParent> | Binding<TSource, any, TParent> | ComposableStyles | CSSDirective;
+
 /**
  * Decorator: Defines a platform custom element based on `FASTElement`.
  * @param nameOrDef - The name of the element to define or a definition object
@@ -728,6 +788,18 @@ export declare class ElementController<TElement extends HTMLElement = HTMLElemen
      * connected to the document.
      */
     get isConnected(): boolean;
+    /**
+     * The context the expression is evaluated against.
+     */
+    get context(): ExecutionContext;
+    /**
+     * Indicates whether the controller is bound.
+     */
+    get isBound(): boolean;
+    /**
+     * Indicates how the source's lifetime relates to the controller's lifetime.
+     */
+    get sourceLifetime(): SourceLifetime | undefined;
     /**
      * Gets/sets the template used to render the component.
      * @remarks
@@ -742,6 +814,13 @@ export declare class ElementController<TElement extends HTMLElement = HTMLElemen
     get mainStyles(): ElementStyles | null;
     set mainStyles(value: ElementStyles | null);
     /* Excluded from this release type: __constructor */
+    /**
+     * Registers an unbind handler with the controller.
+     * @param behavior - An object to call when the controller unbinds.
+     */
+    onUnbind(behavior: {
+        unbind(controller: ExpressionController<TElement>): any;
+    }): void;
     /**
      * Adds the behavior to the component.
      * @param behavior - The behavior to add.
@@ -787,7 +866,6 @@ 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.
@@ -884,6 +962,17 @@ export declare class ElementStyles {
  * @public
  */
 export declare interface ElementView<TSource = any, TParent = any> extends View<TSource, TParent> {
+    /**
+     * Indicates how the source's lifetime relates to the controller's lifetime.
+     */
+    readonly sourceLifetime?: SourceLifetime;
+    /**
+     * Registers an unbind handler with the controller.
+     * @param behavior - An object to call when the controller unbinds.
+     */
+    onUnbind(behavior: {
+        unbind(controller: ViewController<TSource, TParent>): any;
+    }): void;
     /**
      * Appends the view's DOM nodes to the referenced node.
      * @param node - The parent node to append the view's DOM nodes to.
@@ -1078,7 +1167,11 @@ export declare interface ExpressionObserver<TSource = any, TReturn = any, TParen
     bind(controller: ExpressionController<TSource, TParent>): TReturn;
 }
 
-/* Excluded from this release type: FAST */
+/**
+ * The FAST global.
+ * @public
+ */
+export declare const FAST: FASTGlobal;
 
 /**
  * Represents a custom element based on the FASTElement infrastructure.
@@ -1215,7 +1308,43 @@ export declare class FASTElementDefinition<TType extends Constructable<HTMLEleme
     static readonly getForInstance: (object: any) => FASTElementDefinition<Constructable<HTMLElement>> | undefined;
 }
 
-/* Excluded from this release type: FASTGlobal */
+/**
+ * The FAST global.
+ * @public
+ */
+export declare interface FASTGlobal {
+    /**
+     * The list of loaded versions.
+     */
+    readonly versions: string[];
+    /**
+     * Gets a kernel value.
+     * @param id - The id to get the value for.
+     * @param initialize - Creates the initial value for the id if not already existing.
+     */
+    getById<T>(id: string | number): T | null;
+    getById<T>(id: string | number, initialize: () => T): T;
+    /**
+     * Sends a warning to the developer.
+     * @param code - The warning code to send.
+     * @param values - Values relevant for the warning message.
+     */
+    warn(code: number, values?: Record<string, any>): void;
+    /**
+     * Creates an error.
+     * @param code - The error code to send.
+     * @param values - Values relevant for the error message.
+     */
+    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;
+}
 
 declare function from<TBase extends typeof HTMLElement>(BaseType: TBase): new () => InstanceType<TBase> & FASTElement;
 
@@ -1251,11 +1380,7 @@ export declare interface HostBehavior<TSource = any> {
  * associated with a component host.
  * @public
  */
-export declare interface HostController<TSource = any> {
-    /**
-     * The component source.
-     */
-    readonly source: TSource;
+export declare interface HostController<TSource = any> extends ExpressionController<TSource> {
     /**
      * Indicates whether the host is connected or not.
      */
@@ -1303,7 +1428,7 @@ export declare const html: HTMLTemplateTag;
  * A directive that applies bindings.
  * @public
  */
-export declare class HTMLBindingDirective implements HTMLDirective, ViewBehaviorFactory, ViewBehavior, Aspected {
+export declare class HTMLBindingDirective implements HTMLDirective, ViewBehaviorFactory, ViewBehavior, Aspected, BindingDirective {
     dataBinding: Binding;
     private data;
     private updateTarget;
@@ -1572,7 +1697,6 @@ 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.
@@ -1751,14 +1875,6 @@ export declare abstract class NodeObservationDirective<T extends NodeBehaviorOpt
     protected abstract getNodes(target: any): Node[];
 }
 
-/**
- * Normalizes the input value into a binding.
- * @param value - The value to create the default binding for.
- * @returns A binding configuration for the provided value.
- * @public
- */
-export declare function normalizeBinding<TSource = any, TReturn = any, TParent = any>(value: Expression<TSource, TReturn, TParent> | Binding<TSource, TReturn, TParent> | {}): Binding<TSource, TReturn, TParent>;
-
 /**
  * Provides change notifications for an observed subject.
  * @public
@@ -1898,6 +2014,16 @@ export declare interface ObservationRecord {
  */
 export declare function oneTime<T = any>(expression: Expression<T>, policy?: DOMPolicy): Binding<T>;
 
+/**
+ * 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 oneWay<T = any>(expression: Expression<T>, policy?: DOMPolicy, isVolatile?: boolean): Binding<T>;
+
 /**
  * Common APIs related to content parsing.
  * @public
@@ -2087,7 +2213,7 @@ export declare class RepeatBehavior<TSource = any> implements ViewBehavior, Subs
  * A directive that configures list rendering.
  * @public
  */
-export declare class RepeatDirective<TSource = any> implements HTMLDirective, ViewBehaviorFactory {
+export declare class RepeatDirective<TSource = any> implements HTMLDirective, ViewBehaviorFactory, BindingDirective {
     readonly dataBinding: Binding<TSource>;
     readonly templateBinding: Binding<TSource, SyntheticViewTemplate>;
     readonly options: RepeatOptions;
@@ -2360,7 +2486,6 @@ export declare type SpliceStrategySupport = typeof SpliceStrategySupport[keyof t
  */
 export declare abstract class StatelessAttachedAttributeDirective<TOptions> implements HTMLDirective, ViewBehaviorFactory, ViewBehavior {
     protected options: TOptions;
-    /* Excluded from this release type: toJSON */
     /**
      * Creates an instance of RefDirective.
      * @param options - The options to use in configuring the directive.
@@ -2563,10 +2688,6 @@ export declare type TrustedTypesPolicy = {
     createHTML(html: string): string;
 };
 
-/* Excluded from this release type: TypeDefinition */
-
-/* Excluded from this release type: TypeRegistry */
-
 /**
  * A work queue used to synchronize writes to the DOM.
  * @public
@@ -2639,6 +2760,10 @@ export declare interface View<TSource = any, TParent = any> extends Disposable {
      * The data that the view is bound to.
      */
     readonly source: TSource | null;
+    /**
+     * Indicates whether the controller is bound.
+     */
+    readonly isBound: boolean;
     /**
      * Binds a view's behaviors to its binding source.
      * @param source - The binding source for the view's binding behaviors.
@@ -2758,7 +2883,6 @@ 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.