@microsoft/fast-element 1.10.2 → 2.0.0-beta.3

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

@@ -0,0 +1,207 @@
+import { Subscriber, SubscriberSet } from "./notifier.js";
+/**
+ * A splice map is a representation of how a previous array of items
+ * was transformed into a new array of items. Conceptually it is a list of
+ * tuples of
+ *
+ *   (index, removed, addedCount)
+ *
+ * which are kept in ascending index order of. The tuple represents that at
+ * the |index|, |removed| sequence of items were removed, and counting forward
+ * from |index|, |addedCount| items were added.
+ * @public
+ */
+export declare class Splice {
+    index: number;
+    removed: any[];
+    addedCount: number;
+    /**
+     * Indicates that this splice represents a complete array reset.
+     */
+    reset?: boolean;
+    /**
+     * Creates a splice.
+     * @param index - The index that the splice occurs at.
+     * @param removed - The items that were removed.
+     * @param addedCount - The  number of items that were added.
+     */
+    constructor(index: number, removed: any[], addedCount: number);
+    /**
+     * Adjusts the splice index based on the provided array.
+     * @param array - The array to adjust to.
+     * @returns The same splice, mutated based on the reference array.
+     */
+    adjustTo(array: any[]): this;
+}
+/**
+ * Indicates what level of feature support the splice
+ * strategy provides.
+ * @public
+ */
+export declare const SpliceStrategySupport: Readonly<{
+    /**
+     * Only supports resets.
+     */
+    readonly reset: 1;
+    /**
+     * Supports tracking splices and resets.
+     */
+    readonly splice: 2;
+    /**
+     * Supports tracking splices and resets, while applying some form
+     * of optimization, such as merging, to the splices.
+     */
+    readonly optimized: 3;
+}>;
+/**
+ * The available values for SpliceStrategySupport.
+ * @public
+ */
+export declare type SpliceStrategySupport = typeof SpliceStrategySupport[keyof typeof SpliceStrategySupport];
+/**
+ * An approach to tracking changes in an array.
+ * @public
+ */
+export interface SpliceStrategy {
+    /**
+     * The level of feature support the splice strategy provides.
+     */
+    readonly support: SpliceStrategySupport;
+    /**
+     * Normalizes the splices before delivery to array change subscribers.
+     * @param previous - The previous version of the array if a reset has taken place.
+     * @param current - The current version of the array.
+     * @param changes - The set of changes tracked against the array.
+     */
+    normalize(previous: unknown[] | undefined, current: unknown[], changes: Splice[] | undefined): readonly Splice[];
+    /**
+     * Performs and tracks a pop operation on an array.
+     * @param array - The array to track the change for.
+     * @param observer - The observer to register the change with.
+     * @param pop - The operation to perform.
+     * @param args - The arguments for the operation.
+     */
+    pop(array: any[], observer: ArrayObserver, pop: typeof Array.prototype.pop, args: any[]): any;
+    /**
+     * Performs and tracks a push operation on an array.
+     * @param array - The array to track the change for.
+     * @param observer - The observer to register the change with.
+     * @param push - The operation to perform.
+     * @param args - The arguments for the operation.
+     */
+    push(array: any[], observer: ArrayObserver, push: typeof Array.prototype.push, args: any[]): any;
+    /**
+     * Performs and tracks a reverse operation on an array.
+     * @param array - The array to track the change for.
+     * @param observer - The observer to register the change with.
+     * @param reverse - The operation to perform.
+     * @param args - The arguments for the operation.
+     */
+    reverse(array: any[], observer: ArrayObserver, reverse: typeof Array.prototype.reverse, args: any[]): any;
+    /**
+     * Performs and tracks a shift operation on an array.
+     * @param array - The array to track the change for.
+     * @param observer - The observer to register the change with.
+     * @param shift - The operation to perform.
+     * @param args - The arguments for the operation.
+     */
+    shift(array: any[], observer: ArrayObserver, shift: typeof Array.prototype.shift, args: any[]): any;
+    /**
+     * Performs and tracks a sort operation on an array.
+     * @param array - The array to track the change for.
+     * @param observer - The observer to register the change with.
+     * @param sort - The operation to perform.
+     * @param args - The arguments for the operation.
+     */
+    sort(array: any[], observer: ArrayObserver, sort: typeof Array.prototype.sort, args: any[]): any[];
+    /**
+     * Performs and tracks a splice operation on an array.
+     * @param array - The array to track the change for.
+     * @param observer - The observer to register the change with.
+     * @param splice - The operation to perform.
+     * @param args - The arguments for the operation.
+     */
+    splice(array: any[], observer: ArrayObserver, splice: typeof Array.prototype.splice, args: any[]): any;
+    /**
+     * Performs and tracks an unshift operation on an array.
+     * @param array - The array to track the change for.
+     * @param observer - The observer to register the change with.
+     * @param unshift - The operation to perform.
+     * @param args - The arguments for the operation.
+     */
+    unshift(array: any[], observer: ArrayObserver, unshift: typeof Array.prototype.unshift, args: any[]): any[];
+}
+/**
+ * Functionality related to tracking changes in arrays.
+ * @public
+ */
+export declare const SpliceStrategy: Readonly<{
+    /**
+     * A set of changes that represent a full array reset.
+     */
+    readonly reset: Splice[];
+    /**
+     * Sets the default strategy to use for array observers.
+     * @param strategy - The splice strategy to use.
+     */
+    readonly setDefaultStrategy: (strategy: SpliceStrategy) => void;
+}>;
+/**
+ * Observes array lengths.
+ * @public
+ */
+export interface LengthObserver extends Subscriber {
+    /**
+     * The length of the observed array.
+     */
+    length: number;
+}
+/**
+ * An observer for arrays.
+ * @public
+ */
+export interface ArrayObserver extends SubscriberSet {
+    /**
+     * The strategy to use for tracking changes.
+     */
+    strategy: SpliceStrategy | null;
+    /**
+     * The length observer for the array.
+     */
+    readonly lengthObserver: LengthObserver;
+    /**
+     * Adds a splice to the list of changes.
+     * @param splice - The splice to add.
+     */
+    addSplice(splice: Splice): void;
+    /**
+     * Indicates that a reset change has occurred.
+     * @param oldCollection - The collection as it was before the reset.
+     */
+    reset(oldCollection: any[] | undefined): void;
+    /**
+     * Flushes the changes to subscribers.
+     */
+    flush(): void;
+}
+/**
+ * An observer for arrays.
+ * @public
+ */
+export declare const ArrayObserver: Readonly<{
+    /**
+     * Enables the array observation mechanism.
+     * @remarks
+     * Array observation is enabled automatically when using the
+     * {@link RepeatDirective}, so calling this API manually is
+     * not typically necessary.
+     */
+    readonly enable: () => void;
+}>;
+/**
+ * Enables observing the length of an array.
+ * @param array - The array to observe the length of.
+ * @returns The length of the array.
+ * @public
+ */
+export declare function lengthOf<T>(array: readonly T[]): number;

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

@@ -1,19 +1,19 @@
 import type { ExecutionContext } from "./observable.js";
 /**
- * Represents and object that can contribute behavior to a view or
+ * Represents an object that can contribute behavior to a view or
  * element's bind/unbind operations.
  * @public
  */
-export interface Behavior {
+export interface Behavior<TSource = any, TParent = any> {
     /**
      * Bind this behavior to the source.
      * @param source - The source to bind to.
      * @param context - The execution context that the binding is operating within.
      */
-    bind(source: unknown, context: ExecutionContext): void;
+    bind(source: TSource, context: ExecutionContext<TParent>): void;
     /**
      * Unbinds this behavior from the source.
      * @param source - The source to unbind from.
      */
-    unbind(source: unknown): void;
+    unbind(source: TSource, context: ExecutionContext<TParent>): void;
 }

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

@@ -4,21 +4,21 @@
  */
 export interface Subscriber {
     /**
-     * Called when a source this instance has subscribed to changes.
-     * @param source - The source of the change.
+     * Called when a subject this instance has subscribed to changes.
+     * @param subject - The subject of the change.
      * @param args - The event args detailing the change that occurred.
      */
-    handleChange(source: any, args: any): void;
+    handleChange(subject: any, args: any): void;
 }
 /**
- * Provides change notification for a source object.
+ * Provides change notifications for an observed subject.
  * @public
  */
 export interface Notifier {
     /**
-     * The source object that this notifier provides change notification for.
+     * The object that subscribers will receive notifications for.
      */
-    readonly source: any;
+    readonly subject: any;
     /**
      * Notifies all subscribers, based on the args.
      * @param args - Data passed along to subscribers during notification.
@@ -47,7 +47,7 @@ export interface Notifier {
 /**
  * An implementation of {@link Notifier} that efficiently keeps track of
  * subscribers interested in a specific change notification on an
- * observable source.
+ * observable subject.
  *
  * @remarks
  * This set is optimized for the most common scenario of 1 or 2 subscribers.
@@ -60,15 +60,15 @@ export declare class SubscriberSet implements Notifier {
     private sub2;
     private spillover;
     /**
-     * The source that this subscriber set is reporting changes for.
+     * The object that subscribers will receive notifications for.
      */
-    readonly source: any;
+    readonly subject: any;
     /**
-     * Creates an instance of SubscriberSet for the specified source.
-     * @param source - The object source that subscribers will receive notifications from.
+     * Creates an instance of SubscriberSet for the specified subject.
+     * @param subject - The subject that subscribers will receive notifications from.
      * @param initialSubscriber - An initial subscriber to changes.
      */
-    constructor(source: any, initialSubscriber?: Subscriber);
+    constructor(subject: any, initialSubscriber?: Subscriber);
     /**
      * Checks whether the provided subscriber has been added to this set.
      * @param subscriber - The subscriber to test for inclusion in this set.
@@ -97,16 +97,16 @@ export declare class SubscriberSet implements Notifier {
  */
 export declare class PropertyChangeNotifier implements Notifier {
     private subscribers;
-    private sourceSubscribers;
+    private subjectSubscribers;
     /**
-     * The source that property changes are being notified for.
+     * The subject that property changes are being notified for.
      */
-    readonly source: any;
+    readonly subject: any;
     /**
-     * Creates an instance of PropertyChangeNotifier for the specified source.
-     * @param source - The object source that subscribers will receive notifications from.
+     * Creates an instance of PropertyChangeNotifier for the specified subject.
+     * @param subject - The object that subscribers will receive notifications for.
      */
-    constructor(source: any);
+    constructor(subject: any);
     /**
      * Notifies all subscribers, based on the specified property.
      * @param propertyName - The property name, passed along to subscribers during notification.

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.
@@ -44,23 +45,28 @@ export interface ObservationRecord {
  * Enables evaluation of and subscription to a binding.
  * @public
  */
-export interface BindingObserver<TSource = any, TReturn = any, TParent = any> extends Notifier {
+export interface BindingObserver<TSource = any, TReturn = any, TParent = any> extends Notifier, 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.
      */
-    observe(source: TSource, context: ExecutionContext<TParent>): TReturn;
-    /**
-     * Unsubscribe from all dependent observables of the binding.
-     */
-    disconnect(): void;
+    observe(source: TSource, context?: ExecutionContext<TParent>): TReturn;
     /**
      * Gets {@link ObservationRecord|ObservationRecords} that the {@link BindingObserver}
      * 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 +82,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.
@@ -114,13 +120,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, TParent = any>(binding: Binding<TSource, TReturn, TParent>, initialSubscriber?: Subscriber | undefined, isVolatileBinding?: boolean): BindingObserver<TSource, TReturn, TParent>;
+    binding<TSource = any, TReturn = any>(binding: Binding<TSource, TReturn, any>, initialSubscriber?: Subscriber, isVolatileBinding?: boolean): BindingObserver<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.
      */
-    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>(binding: Binding<TSource_1, TReturn_1, any>): boolean;
 }>;
 /**
  * Decorator: Defines an observable property on the target.
@@ -141,7 +147,11 @@ 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 declare class ExecutionContext<TParentSource = any> {
+    /**
+     * The default execution context.
+     */
+    static readonly default: ExecutionContext<any>;
     /**
      * The index of the current item within a repeat context.
      */
@@ -151,13 +161,14 @@ 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;
+    readonly parent: TParentSource;
     /**
      * The parent execution context when in nested context scenarios.
      */
-    parentContext: ExecutionContext<TGrandparent>;
+    readonly parentContext: ExecutionContext<TParentSource>;
+    private constructor();
     /**
      * The current event within an event handler.
      */
@@ -187,15 +198,42 @@ export declare class ExecutionContext<TParent = any, TGrandparent = any> {
      * is the last item in the collection.
      */
     get isLast(): boolean;
+    /**
+     * Returns the typed event detail of a custom event.
+     */
+    eventDetail<TDetail>(): TDetail;
+    /**
+     * Returns the typed event target of the event.
+     */
+    eventTarget<TTarget extends EventTarget>(): TTarget;
+    /**
+     * 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.
+     */
+    createItemContext(index: number, length: number): ExecutionContext<TParentSource>;
     /**
      * Sets the event for the current execution context.
      * @param event - The event to set.
      * @internal
      */
     static setEvent(event: Event | null): void;
+    /**
+     * Creates a new root execution context.
+     * @returns A new execution context.
+     */
+    static create(): ExecutionContext;
 }
-/**
- * The default execution context used in binding expressions.
- * @public
- */
-export declare const defaultExecutionContext: ExecutionContext<any, any>;

package/dist/dts/observation/splice-strategies.d.ts

@@ -0,0 +1,13 @@
+import { SpliceStrategy } from "./arrays.js";
+/**
+ * A SpliceStrategy that attempts to merge all splices into the minimal set of
+ * splices needed to represent the change from the old array to the new array.
+ * @public
+ */
+export declare const mergeSpliceStrategy: SpliceStrategy;
+/**
+ * A splice strategy that doesn't create splices, but instead
+ * tracks every change as a full array reset.
+ * @public
+ */
+export declare const resetSpliceStrategy: SpliceStrategy;

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/platform.d.ts

@@ -1,84 +1,35 @@
-/**
- * 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;
-}
-/**
- * The platform global type.
- * @public
- */
-export declare type Global = typeof globalThis & {
-    /**
-     * Enables working with trusted types.
-     */
-    trustedTypes: TrustedTypes;
-    /**
-     * The FAST global.
-     * @internal
-     */
-    readonly FAST: FASTGlobal;
-};
+export declare const FAST: FASTGlobal;
 /**
- * A reference to globalThis, with support
- * for browsers that don't yet support the spec.
+ * A readonly, empty array.
+ * @remarks
+ * Typically returned by APIs that return arrays when there are
+ * no actual items to return.
  * @public
  */
-export declare const $global: Global;
+export declare const emptyArray: readonly never[];
 /**
- * The FAST global.
+ * Do not change. Part of shared kernel contract.
  * @internal
  */
-export declare const FAST: FASTGlobal;
+export interface TypeDefinition {
+    type: Function;
+}
 /**
- * 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 interface TypeRegistry<TDefinition extends TypeDefinition> {
+    register(definition: TDefinition): boolean;
+    getByType(key: Function): TDefinition | undefined;
+    getForInstance(object: any): TDefinition | undefined;
 }
 /**
- * A readonly, empty array.
- * @remarks
- * Typically returned by APIs that return arrays when there are
- * no actual items to return.
+ * Do not change. Part of shared kernel contract.
  * @internal
  */
-export declare const emptyArray: readonly never[];
+export declare function createTypeRegistry<TDefinition extends TypeDefinition>(): TypeRegistry<TDefinition>;

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/styles/css-directive.d.ts

@@ -1,19 +1,57 @@
+import type { Constructable } from "../interfaces.js";
 import type { Behavior } from "../observation/behavior.js";
 import type { ComposableStyles } from "./element-styles.js";
+/**
+ * Used to add behaviors when constructing styles.
+ * @public
+ */
+export declare type AddBehavior = (behavior: Behavior<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;