@microsoft/fast-element 1.10.5 → 2.0.0-beta.10

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

@@ -1,3 +1,4 @@
+import { Disposable } from "../interfaces.js";
 import type { Notifier, Subscriber } from "./notifier.js";
 /**
  * Represents a getter/setter property accessor on an object.
@@ -22,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,26 +42,91 @@ export interface ObservationRecord {
     propertyName: string;
 }
 /**
- * Enables evaluation of and subscription to a binding.
+ * 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 BindingObserver<TSource = any, TReturn = any, TParent = any> extends Notifier {
+export interface ExpressionObserver<TSource = any, TReturn = any, TParent = any> {
     /**
-     * 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.
+     * Binds the expression to the source.
+     * @param controller - The controller that manages the lifecycle and related
+     * context for the expression.
      */
-    observe(source: TSource, context: ExecutionContext<TParent>): TReturn;
+    bind(controller: ExpressionController<TSource, TParent>): TReturn;
+}
+/**
+ * Enables evaluation of and subscription to a binding.
+ * @public
+ */
+export interface ExpressionNotifier<TSource = any, TReturn = any, TParent = any> extends Notifier, ExpressionObserver<TSource, TReturn, TParent>, Disposable {
     /**
-     * Unsubscribe from all dependent observables of the binding.
+     * Observes the expression.
+     * @param source - The source for the expression.
+     * @param context - The context for the expression.
      */
-    disconnect(): void;
+    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>;
+    /**
+     * Sets the update mode used by the observer.
+     * @param isAsync - Indicates whether updates should be asynchronous.
+     * @remarks
+     * By default, the update mode is asynchronous, since that provides the best
+     * performance for template rendering scenarios. Passing false to setMode will
+     * instead cause the observer to notify subscribers immediately when changes occur.
+     */
+    setMode(isAsync: boolean): void;
 }
 /**
  * Common Observable APIs.
@@ -76,7 +142,7 @@ export declare const Observable: Readonly<{
      * Gets a notifier for an object or Array.
      * @param source - The object or Array to get the notifier for.
      */
-    getNotifier: (source: any) => Notifier;
+    getNotifier: <T extends Notifier = Notifier>(source: any) => T;
     /**
      * Records a property change for a source object.
      * @param source - The object to record the change against.
@@ -108,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, TParent = any>(binding: Binding<TSource, TReturn, TParent>, initialSubscriber?: Subscriber | undefined, isVolatileBinding?: boolean): BindingObserver<TSource, TReturn, TParent>;
+    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, TParent_1 = any>(binding: Binding<TSource_1, TReturn_1, TParent_1>): boolean;
+    isVolatileBinding<TSource_1 = any, TReturn_1 = any>(expression: Expression<TSource_1, TReturn_1, any>): boolean;
 }>;
 /**
  * Decorator: Defines an observable property on the target.
@@ -141,7 +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<TParent = any, TGrandparent = any> {
+export interface ExecutionContext<TParent = any> {
     /**
      * The index of the current item within a repeat context.
      */
@@ -151,51 +217,68 @@ export declare class ExecutionContext<TParent = any, TGrandparent = any> {
      */
     length: number;
     /**
-     * The parent data object within a repeat context.
+     * The parent data source within a nested context.
      */
     parent: TParent;
     /**
      * The parent execution context when in nested context scenarios.
      */
-    parentContext: ExecutionContext<TGrandparent>;
+    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;
     /**
-     * Sets the event for the current execution context.
-     * @param event - The event to set.
-     * @internal
+     * Returns the typed event detail of a custom event.
+     */
+    eventDetail<TDetail>(): TDetail;
+    /**
+     * Returns the typed event target of the event.
      */
-    static setEvent(event: Event | null): void;
+    eventTarget<TTarget extends EventTarget>(): TTarget;
 }
 /**
- * The default execution context used in binding expressions.
+ * Provides additional contextual information available to behaviors and expressions.
  * @public
  */
-export declare const defaultExecutionContext: ExecutionContext<any, any>;
+export declare const ExecutionContext: Readonly<{
+    /**
+     * A default execution context.
+     */
+    default: ExecutionContext<any>;
+    /**
+     * Gets the current event.
+     * @returns An event object.
+     */
+    getEvent(): Event | null;
+    /**
+     * Sets the current event.
+     * @param event - An event object.
+     */
+    setEvent(event: Event | null): void;
+}>;

package/dist/dts/observation/update-queue.d.ts

@@ -0,0 +1,40 @@
+import { Callable } from "../interfaces.js";
+/**
+ * A work queue used to synchronize writes to the DOM.
+ * @public
+ */
+export interface UpdateQueue {
+    /**
+     * Schedules DOM update work in the next batch.
+     * @param callable - The callable function or object to queue.
+     */
+    enqueue(callable: Callable): void;
+    /**
+     * Resolves with the next DOM update.
+     */
+    next(): Promise<void>;
+    /**
+     * Immediately processes all work previously scheduled
+     * through enqueue.
+     * @remarks
+     * This also forces next() promises
+     * to resolve.
+     */
+    process(): void;
+    /**
+     * Sets the update mode used by enqueue.
+     * @param isAsync - Indicates whether DOM updates should be asynchronous.
+     * @remarks
+     * By default, the update mode is asynchronous, since that provides the best
+     * performance in the browser. Passing false to setMode will instead cause
+     * the queue to be immediately processed for each call to enqueue. However,
+     * ordering will still be preserved so that nested tasks do not run until
+     * after parent tasks complete.
+     */
+    setMode(isAsync: boolean): void;
+}
+/**
+ * The default UpdateQueue.
+ * @public
+ */
+export declare const Updates: UpdateQueue;

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

@@ -0,0 +1,20 @@
+/**
+ * This module provides
+ */
+/**
+ * An implementation of the https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/pending-task.md proposal.
+ * @beta
+ */
+export interface PendingTask extends Event {
+    complete: Promise<void>;
+}
+/**
+ * A concrete implementation of {@link PendingTask}
+ * @beta
+ */
+export declare class PendingTaskEvent extends Event implements PendingTask {
+    complete: Promise<void>;
+    static readonly type = "pending-task";
+    constructor(complete: Promise<void>);
+    static isPendingTask<T extends Event>(value: T | PendingTask): value is PendingTask;
+}

package/dist/dts/platform.d.ts

@@ -1,84 +1,41 @@
-/**
- * A policy for use with the standard trustedTypes platform API.
- * @public
- */
-export declare type TrustedTypesPolicy = {
-    /**
-     * Creates trusted HTML.
-     * @param html - The HTML to clear as trustworthy.
-     */
-    createHTML(html: string): string;
-};
-/**
- * Enables working with trusted types.
- * @public
- */
-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;
-};
+import type { FASTGlobal } from "./interfaces.js";
 /**
  * The FAST global.
  * @internal
  */
-export 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;
-}
+export declare const FAST: FASTGlobal;
 /**
- * The platform global type.
+ * A readonly, empty array.
+ * @remarks
+ * Typically returned by APIs that return arrays when there are
+ * no actual items to return.
  * @public
  */
-export declare type Global = typeof globalThis & {
-    /**
-     * Enables working with trusted types.
-     */
-    trustedTypes: TrustedTypes;
-    /**
-     * The FAST global.
-     * @internal
-     */
-    readonly FAST: FASTGlobal;
-};
+export declare const emptyArray: readonly never[];
 /**
- * A reference to globalThis, with support
- * for browsers that don't yet support the spec.
- * @public
+ * Do not change. Part of shared kernel contract.
+ * @internal
  */
-export declare const $global: Global;
+export interface TypeDefinition {
+    type: Function;
+}
 /**
- * The FAST global.
+ * Do not change. Part of shared kernel contract.
  * @internal
  */
-export declare const FAST: FASTGlobal;
+export interface TypeRegistry<TDefinition extends TypeDefinition> {
+    register(definition: TDefinition): boolean;
+    getByType(key: Function): TDefinition | undefined;
+    getForInstance(object: any): TDefinition | undefined;
+}
 /**
- * Core services shared across FAST instances.
+ * Do not change. Part of shared kernel contract.
  * @internal
  */
-export declare const enum KernelServiceId {
-    updateQueue = 1,
-    observable = 2,
-    contextEvent = 3,
-    elementRegistry = 4
-}
+export declare function createTypeRegistry<TDefinition extends TypeDefinition>(): TypeRegistry<TDefinition>;
 /**
- * A readonly, empty array.
- * @remarks
- * Typically returned by APIs that return arrays when there are
- * no actual items to return.
+ * Creates a function capable of locating metadata associated with a type.
+ * @returns A metadata locator function.
  * @internal
  */
-export declare const emptyArray: readonly never[];
+export declare function createMetadataLocator<TMetadata>(): (target: {}) => TMetadata[];

package/dist/dts/polyfills.d.ts

@@ -0,0 +1,8 @@
+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,19 +1,57 @@
-import type { Behavior } from "../observation/behavior.js";
+import type { Constructable } from "../interfaces.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: HostBehavior<HTMLElement>) => void;
 /**
  * Directive for use in {@link css}.
  *
  * @public
  */
-export declare class CSSDirective {
+export interface CSSDirective {
     /**
      * Creates a CSS fragment to interpolate into the CSS document.
      * @returns - the string to interpolate into CSS
      */
-    createCSS(): ComposableStyles;
+    createCSS(add: AddBehavior): ComposableStyles;
+}
+/**
+ * Defines metadata for a CSSDirective.
+ * @public
+ */
+export interface CSSDirectiveDefinition<TType extends Constructable<CSSDirective> = Constructable<CSSDirective>> {
     /**
-     * Creates a behavior to bind to the host element.
-     * @returns - the behavior to bind to the host element, or undefined.
+     * The type that the definition provides metadata for.
      */
-    createBehavior(): Behavior | undefined;
+    readonly type: TType;
 }
+/**
+ * Instructs the css engine to provide dynamic styles or
+ * associate behaviors with styles.
+ * @public
+ */
+export declare const CSSDirective: Readonly<{
+    /**
+     * Gets the directive definition associated with the instance.
+     * @param instance - The directive instance to retrieve the definition for.
+     */
+    getForInstance: (object: any) => CSSDirectiveDefinition<Constructable<CSSDirective>> | undefined;
+    /**
+     * Gets the directive definition associated with the specified type.
+     * @param type - The directive type to retrieve the definition for.
+     */
+    getByType: (key: Function) => CSSDirectiveDefinition<Constructable<CSSDirective>> | undefined;
+    /**
+     * Defines a CSSDirective.
+     * @param type - The type to define as a directive.
+     */
+    define<TType extends Constructable<CSSDirective>>(type: any): TType;
+}>;
+/**
+ * Decorator: Defines a CSSDirective.
+ * @public
+ */
+export declare function cssDirective(): (type: Constructable<CSSDirective>) => void;