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

package/dist/dts/pending-task.d.ts

@@ -0,0 +1,32 @@
+/**
+ * An implementation of the https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/pending-task.md proposal.
+ * @public
+ */
+export interface PendingTask extends Event {
+    /**
+     * A promise that resolves when the pending task is complete.
+     */
+    readonly complete: Promise<void>;
+}
+/**
+ * A concrete implementation of {@link PendingTask}
+ * @public
+ */
+export declare class PendingTaskEvent extends Event implements PendingTask {
+    readonly complete: Promise<void>;
+    /**
+     * The type of the pending task event.
+     */
+    static readonly type = "pending-task";
+    /**
+     * Creates an instance of PendingTaskEvent.
+     * @param complete - A promise that resolves when the pending task is complete.
+     */
+    constructor(complete: Promise<void>);
+    /**
+     * Determines whether a value is a PendingTaskEvent.
+     * @param value - The value to check.
+     * @returns True if the value is a PendingTaskEvent; false otherwise.
+     */
+    static isPendingTask<T extends Event>(value: T | PendingTask): value is PendingTask;
+}

package/dist/dts/platform.d.ts

@@ -1,7 +1,8 @@
 import type { FASTGlobal } from "./interfaces.js";
+import "./polyfills.js";
 /**
  * The FAST global.
- * @internal
+ * @public
  */
 export declare const FAST: FASTGlobal;
 /**
@@ -33,3 +34,9 @@ export interface TypeRegistry<TDefinition extends TypeDefinition> {
  * @internal
  */
 export declare function createTypeRegistry<TDefinition extends TypeDefinition>(): TypeRegistry<TDefinition>;
+/**
+ * Creates a function capable of locating metadata associated with a type.
+ * @returns A metadata locator function.
+ * @internal
+ */
+export declare function createMetadataLocator<TMetadata>(): (target: {}) => TMetadata[];

package/dist/dts/polyfills.d.ts

@@ -1,8 +0,0 @@
-import type { StyleStrategy, StyleTarget } from "./interfaces.js";
-export declare class StyleElementStrategy implements StyleStrategy {
-    private readonly styles;
-    private readonly styleClass;
-    constructor(styles: string[]);
-    addStylesTo(target: StyleTarget): void;
-    removeStylesFrom(target: StyleTarget): void;
-}

package/dist/dts/state/exports.d.ts

@@ -0,0 +1,3 @@
+export { reactive } from "./reactive.js";
+export { watch } from "./watch.js";
+export * from "./state.js";

package/dist/dts/state/reactive.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Converts a plain object to a reactive, observable object.
+ * @param object - The object to make reactive.
+ * @param deep - Indicates whether or not to deeply convert the oject.
+ * @returns The converted object.
+ * @beta
+ */
+export declare function reactive<T>(object: T, deep?: boolean): T;

package/dist/dts/state/state.d.ts

@@ -0,0 +1,141 @@
+import { Disposable } from "../interfaces.js";
+import type { Subscriber } from "../observation/notifier.js";
+/**
+ * Options for creating state.
+ * @beta
+ */
+export declare type StateOptions = {
+    /**
+     * Indicates whether to deeply make the state value observable.
+     */
+    deep?: boolean;
+    /**
+     * A friendly name for the state.
+     */
+    name?: string;
+};
+/**
+ * A readonly stateful value.
+ * @beta
+ */
+export declare type ReadonlyState<T> = {
+    /**
+     * Gets the current state value.
+     */
+    (): T;
+    /**
+     * Gets the current state value.
+     */
+    readonly current: T;
+};
+/**
+ * A read/write stateful value.
+ * @beta
+ */
+export declare type State<T> = ReadonlyState<T> & {
+    /**
+     * Gets or sets the current state value.
+     */
+    current: T;
+    /**
+     * Sets the current state value.
+     * @param value The new state value.
+     */
+    set(value: T): void;
+    /**
+     * Creates a readonly version of the state.
+     */
+    asReadonly(): ReadonlyState<T>;
+};
+/**
+ * Creates a reactive state value.
+ * @param value - The initial state value.
+ * @param options - Options to customize the state or a friendly name.
+ * @returns A State instance.
+ * @beta
+ */
+export declare function state<T>(value: T, options?: string | StateOptions): State<T>;
+/**
+ * A readonly stateful value associated with an object owner.
+ * @beta
+ */
+export declare type ReadonlyOwnedState<T> = {
+    /**
+     * Gets the current stateful value for the owner.
+     */
+    (owner: any): T;
+};
+/**
+ * A read/write stateful value associated with an owner.
+ * @beta
+ */
+export declare type OwnedState<T> = ReadonlyOwnedState<T> & {
+    /**
+     * Sets
+     * @param owner - The object to set the state for the owner.
+     * @param value - The new state value.
+     */
+    set(owner: any, value: T): void;
+    /**
+     * Creates a readonly version of the state.
+     */
+    asReadonly(): ReadonlyOwnedState<T>;
+};
+/**
+ * Creates a reactive state that has its value associated with a specific owner.
+ * @param value - The initial value or a factory that provides an initial value for each owner.
+ * @param options - Options to customize the state or a friendly name.
+ * @returns An OwnedState instance.
+ * @beta
+ */
+export declare function ownedState<T>(value: T | (() => T), options?: string | StateOptions): OwnedState<T>;
+/**
+ * State whose value is computed from other dependencies.
+ * @beta
+ */
+export declare type ComputedState<T> = ReadonlyState<T> & Disposable & {
+    /**
+     * Subscribes to notification of changes in the state.
+     * @param subscriber - The object that is subscribing for change notification.
+     */
+    subscribe(subscriber: Subscriber): void;
+    /**
+     * Unsubscribes from notification of changes in the state.
+     * @param subscriber - The object that is unsubscribing from change notification.
+     */
+    unsubscribe(subscriber: Subscriber): void;
+};
+/**
+ * A callback that enables computation setup.
+ * @beta
+ */
+export declare type ComputedSetupCallback = () => (() => void) | void;
+/**
+ * Provides computed state capabilities.
+ * @beta
+ */
+export declare type ComputedBuilder = {
+    /**
+     * Callbacks related to computed state.
+     */
+    on: {
+        /**
+         * Provides a setup callback for the computation.
+         * @param callback The callback to run to setup the computation.
+         */
+        setup(callback: ComputedSetupCallback): void;
+    };
+};
+/**
+ * A callback that initializes the computation.
+ * @beta
+ */
+export declare type ComputedInitializer<T> = (builder: ComputedBuilder) => () => T;
+/**
+ * Creates a ComputedState.
+ * @param initialize - The initialization callback.
+ * @param name - A friendly name for this computation.
+ * @returns A ComputedState
+ * @beta
+ */
+export declare function computedState<T>(initialize: ComputedInitializer<T>, name?: string): ComputedState<T>;

package/dist/dts/state/visitor.d.ts

@@ -0,0 +1,6 @@
+export interface ObjectVisitor<TVisitorData> {
+    visitObject(object: any, data: TVisitorData): void;
+    visitArray(array: any[], data: TVisitorData): void;
+    visitProperty(object: any, key: PropertyKey, value: any, data: TVisitorData): void;
+}
+export declare function visitObject<TVisitorData>(object: any, deep: boolean, visitor: ObjectVisitor<TVisitorData>, data: TVisitorData, traversed: WeakSet<any> | Set<any>): void;

package/dist/dts/state/watch.d.ts

@@ -0,0 +1,10 @@
+import { Disposable } from "../interfaces.js";
+import type { Subscriber } from "../observation/notifier.js";
+/**
+ * Deeply subscribes to changes in existing observable objects.
+ * @param object - The observable object to watch.
+ * @param subscriber - The handler to call when changes are made to the object.
+ * @returns A disposable that can be used to unsubscribe from change updates.
+ * @beta
+ */
+export declare function watch(object: any, subscriber: Subscriber | ((subject: any, args: any) => void)): Disposable;

package/dist/dts/styles/css-directive.d.ts

@@ -1,11 +1,11 @@
 import type { Constructable } from "../interfaces.js";
-import type { Behavior } from "../observation/behavior.js";
+import type { HostBehavior } from "./host.js";
 import type { ComposableStyles } from "./element-styles.js";
 /**
  * Used to add behaviors when constructing styles.
  * @public
  */
-export declare type AddBehavior = (behavior: Behavior<HTMLElement>) => void;
+export declare type AddBehavior = (behavior: HostBehavior<HTMLElement>) => void;
 /**
  * Directive for use in {@link css}.
  *

package/dist/dts/styles/css.d.ts

@@ -27,8 +27,3 @@ export declare type CSSTemplateTag = ((strings: TemplateStringsArray, ...values:
  * @public
  */
 export declare const css: CSSTemplateTag;
-/**
- * @deprecated Use css.partial instead.
- * @public
- */
-export declare const cssPartial: (strings: TemplateStringsArray, ...values: (ComposableStyles | CSSDirective)[]) => CSSDirective;

package/dist/dts/styles/element-styles.d.ts

@@ -1,5 +1,5 @@
-import type { Behavior } from "../observation/behavior.js";
-import { StyleStrategy, StyleTarget } from "../interfaces.js";
+import type { StyleStrategy, StyleTarget } from "./style-strategy.js";
+import type { HostBehavior } from "./host.js";
 /**
  * Represents styles that can be composed into the ShadowDOM of a custom element.
  * @public
@@ -27,7 +27,7 @@ export declare class ElementStyles {
     /**
      * The behaviors associated with this set of styles.
      */
-    readonly behaviors: ReadonlyArray<Behavior<HTMLElement>> | null;
+    readonly behaviors: ReadonlyArray<HostBehavior<HTMLElement>> | null;
     /**
      * Gets the StyleStrategy associated with these element styles.
      */
@@ -47,7 +47,7 @@ export declare class ElementStyles {
      * Associates behaviors with this set of styles.
      * @param behaviors - The behaviors to associate.
      */
-    withBehaviors(...behaviors: Behavior<HTMLElement>[]): this;
+    withBehaviors(...behaviors: HostBehavior<HTMLElement>[]): this;
     /**
      * Sets the strategy that handles adding/removing these styles for an element.
      * @param strategy - The strategy to use.
@@ -58,21 +58,14 @@ export declare class ElementStyles {
      * @param Strategy - The strategy type to construct.
      */
     static setDefaultStrategy(Strategy: ConstructibleStyleStrategy): void;
+    /**
+     * Normalizes a set of composable style options.
+     * @param styles - The style options to normalize.
+     * @returns A singular ElementStyles instance or undefined.
+     */
+    static normalize(styles: ComposableStyles | ComposableStyles[] | undefined): ElementStyles | undefined;
     /**
      * Indicates whether the DOM supports the adoptedStyleSheets feature.
      */
     static readonly supportsAdoptedStyleSheets: boolean;
 }
-/**
- * https://wicg.github.io/construct-stylesheets/
- * https://developers.google.com/web/updates/2019/02/constructable-stylesheets
- *
- * @internal
- */
-export declare class AdoptedStyleSheetsStrategy implements StyleStrategy {
-    /** @internal */
-    readonly sheets: CSSStyleSheet[];
-    constructor(styles: (string | CSSStyleSheet)[]);
-    addStylesTo(target: StyleTarget): void;
-    removeStylesFrom(target: StyleTarget): void;
-}

package/dist/dts/styles/host.d.ts

@@ -0,0 +1,68 @@
+import type { ElementStyles } from "./element-styles.js";
+/**
+ * Controls the lifecycle and context of behaviors and styles
+ * associated with a component host.
+ * @public
+ */
+export interface HostController<TSource = any> {
+    /**
+     * The component source.
+     */
+    readonly source: TSource;
+    /**
+     * Indicates whether the host is connected or not.
+     */
+    readonly isConnected: boolean;
+    /**
+     * The main set of styles used for the component, independent
+     * of any behavior-specific styles.
+     */
+    mainStyles: ElementStyles | null;
+    /**
+     * Adds the behavior to the component.
+     * @param behavior - The behavior to add.
+     */
+    addBehavior(behavior: HostBehavior<TSource>): void;
+    /**
+     * Removes the behavior from the component.
+     * @param behavior - The behavior to remove.
+     * @param force - Forces removal even if this behavior was added more than once.
+     */
+    removeBehavior(behavior: HostBehavior<TSource>, force?: boolean): void;
+    /**
+     * Adds styles to this element. Providing an HTMLStyleElement will attach the element instance to the shadowRoot.
+     * @param styles - The styles to add.
+     */
+    addStyles(styles: ElementStyles | HTMLStyleElement | null | undefined): void;
+    /**
+     * Removes styles from this element. Providing an HTMLStyleElement will detach the element instance from the shadowRoot.
+     * @param styles - the styles to remove.
+     */
+    removeStyles(styles: ElementStyles | HTMLStyleElement | null | undefined): void;
+}
+/**
+ * Represents an object that can contribute behavior to a host.
+ * @public
+ */
+export interface HostBehavior<TSource = any> {
+    /**
+     * Executed when this behavior is attached to a controller.
+     * @param controller - Controls the behavior lifecycle.
+     */
+    addedCallback?(controller: HostController<TSource>): void;
+    /**
+     * Executed when this behavior is detached from a controller.
+     * @param controller - Controls the behavior lifecycle.
+     */
+    removedCallback?(controller: HostController<TSource>): void;
+    /**
+     * Executed when this behavior's host is connected.
+     * @param controller - Controls the behavior lifecycle.
+     */
+    connectedCallback?(controller: HostController<TSource>): void;
+    /**
+     * Executed when this behavior's host is disconnected.
+     * @param controller - Controls the behavior lifecycle.
+     */
+    disconnectedCallback?(controller: HostController<TSource>): void;
+}

package/dist/dts/styles/style-strategy.d.ts

@@ -0,0 +1,42 @@
+/**
+ * A node that can be targeted by styles.
+ * @public
+ */
+export interface StyleTarget extends Pick<Node, "getRootNode"> {
+    /**
+     * 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;
+}

package/dist/dts/templating/binding-signal.d.ts

@@ -1,38 +1,23 @@
-import type { Binding, ExecutionContext } from "../observation/observable.js";
-import { BindingConfig, UpdateBinding } from "./binding.js";
-import type { ViewBehaviorTargets } from "./html-directive.js";
-/**
- * A binding behavior for signal bindings.
- * @public
- */
-export declare class SignalBinding extends UpdateBinding {
-    private handlerProperty;
-    /**
-     * Bind this behavior to the source.
-     * @param source - The source to bind to.
-     * @param context - The execution context that the binding is operating within.
-     * @param targets - The targets that behaviors in a view can attach to.
-     */
-    bind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
-    /**
-     * Unbinds this behavior from the source.
-     * @param source - The source to unbind from.
-     * @param context - The execution context that the binding is operating within.
-     * @param targets - The targets that behaviors in a view can attach to.
-     */
-    unbind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
-    private getSignal;
+import type { Expression } from "../observation/observable.js";
+import type { Subscriber } from "../observation/notifier.js";
+import type { DOMPolicy } from "../dom.js";
+import { Binding } from "./html-directive.js";
+export declare const Signal: Readonly<{
+    subscribe(signal: string, subscriber: Subscriber): void;
+    unsubscribe(signal: string, subscriber: Subscriber): void;
     /**
      * Sends the specified signal to signaled bindings.
      * @param signal - The signal to send.
      * @public
      */
-    static send(signal: string): void;
-}
+    send(signal: string): void;
+}>;
 /**
  * Creates a signal binding configuration with the supplied options.
+ * @param expression - The binding to refresh when signaled.
  * @param options - The signal name or a binding to use to retrieve the signal name.
+ * @param policy - The security policy to associate with th binding.
  * @returns A binding configuration.
  * @public
  */
-export declare const signal: <T = any>(options: string | Binding<T, any, any>) => BindingConfig<string | Binding<T, any, any>>;
+export declare function signal<T = any>(expression: Expression<T>, options: string | Expression<T>, policy?: DOMPolicy): Binding<T>;

package/dist/dts/templating/binding-two-way.d.ts

@@ -1,6 +1,15 @@
-import type { ExecutionContext } from "../observation/observable.js";
-import { BindingConfig, ChangeBinding, DefaultBindingOptions, HTMLBindingDirective } from "./binding.js";
-import type { ViewBehaviorTargets } from "./html-directive.js";
+import type { DOMPolicy } from "../dom.js";
+import { Expression } from "../observation/observable.js";
+import type { HTMLBindingDirective } from "./binding.js";
+import { Binding } from "./html-directive.js";
+/**
+ * The twoWay binding options.
+ * @public
+ */
+export declare type TwoWayBindingOptions = {
+    changeEvent?: string;
+    fromView?: (value: any) => any;
+};
 /**
  * The settings required to enable two-way binding.
  * @public
@@ -13,44 +22,20 @@ export interface TwoWaySettings {
      */
     determineChangeEvent(directive: HTMLBindingDirective, target: HTMLElement): string;
 }
-/**
- * A binding behavior for bindings that update in two directions.
- * @public
- */
-export declare class TwoWayBinding extends ChangeBinding {
-    private changeEvent;
-    /**
-     * Bind this behavior to the source.
-     * @param source - The source to bind to.
-     * @param context - The execution context that the binding is operating within.
-     * @param targets - The targets that behaviors in a view can attach to.
-     */
-    bind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
-    /**
-     * Unbinds this behavior from the source.
-     * @param source - The source to unbind from.
-     * @param context - The execution context that the binding is operating within.
-     * @param targets - The targets that behaviors in a view can attach to.
-     */
-    unbind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
-    /** @internal */
-    handleEvent(event: Event): void;
+export declare const TwoWaySettings: Readonly<{
     /**
      * Configures two-way binding.
      * @param settings - The settings to use for the two-way binding system.
      */
-    static configure(settings: TwoWaySettings): void;
-}
-/**
- * The default twoWay binding options.
- * @public
- */
-export declare type DefaultTwoWayBindingOptions = DefaultBindingOptions & {
-    changeEvent?: string;
-    fromView?: (value: any) => any;
-};
+    configure(settings: TwoWaySettings): void;
+}>;
 /**
- * The default twoWay binding configuration.
+ * Creates a default binding.
+ * @param expression - The binding to refresh when changed.
+ * @param optionsOrChangeEvent - The binding options or the name of the change event to use.
+ * @param policy - The security policy to associate with the binding.
+ * @param isBindingVolatile - Indicates whether the binding is volatile or not.
+ * @returns A binding.
  * @public
  */
-export declare const twoWay: BindingConfig<DefaultTwoWayBindingOptions> & import("./binding.js").BindingConfigResolver<DefaultTwoWayBindingOptions>;
+export declare function twoWay<T = any>(expression: Expression<T>, optionsOrChangeEvent?: TwoWayBindingOptions | string, policy?: DOMPolicy, isBindingVolatile?: boolean): Binding<T>;