@microsoft/fast-element 1.10.0 → 2.0.0-beta.1

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.
@@ -25,7 +26,7 @@ export interface Accessor {
  * as part of a template binding update.
  * @public
  */
-export declare type Binding<TSource = any, TReturn = any, TParent = any> = (source: TSource, context: ExecutionContext<TParent>) => TReturn;
+export declare type Binding<TSource = any, TReturn = any, TContext extends ExecutionContext = ExecutionContext> = (source: TSource, context: TContext) => TReturn;
 /**
  * A record of observable property access.
  * @public
@@ -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, ExecutionContext<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, ExecutionContext<any>>): boolean;
 }>;
 /**
  * Decorator: Defines an observable property on the target.
@@ -141,61 +147,112 @@ 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 RootContext {
     /**
-     * The index of the current item within a repeat context.
+     * The current event within an event handler.
      */
-    index: number;
+    readonly event: Event;
     /**
-     * The length of the current collection within a repeat context.
+     * Returns the typed event detail of a custom event.
+     */
+    eventDetail<TDetail = any>(): TDetail;
+    /**
+     * Returns the typed event target of the event.
      */
-    length: number;
+    eventTarget<TTarget extends EventTarget = EventTarget>(): TTarget;
     /**
-     * The parent data object within a repeat context.
+     * 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.
      */
-    parent: TParent;
+    createChildContext<TParentSource>(source: TParentSource): ChildContext<TParentSource>;
+}
+/**
+ * Provides additional contextual information when inside a child template.
+ * @public
+ */
+export interface ChildContext<TParentSource = any> extends RootContext {
+    /**
+     * The parent data source within a nested context.
+     */
+    readonly parent: TParentSource;
     /**
      * The parent execution context when in nested context scenarios.
      */
-    parentContext: ExecutionContext<TGrandparent>;
+    readonly parentContext: ChildContext<TParentSource>;
     /**
-     * The current event within an event handler.
+     * 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): ItemContext<TParentSource>;
+}
+/**
+ * Provides additional contextual information when inside a repeat item template.s
+ * @public
+ */
+export interface ItemContext<TParentSource = any> extends ChildContext<TParentSource> {
+    /**
+     * The index of the current item within a repeat context.
      */
-    get event(): Event;
+    readonly index: number;
+    /**
+     * The length of the current collection within a repeat context.
+     */
+    readonly length: number;
     /**
      * 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;
+    /**
+     * 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;
+}
+/**
+ * The common execution context APIs.
+ * @public
+ */
+export declare const ExecutionContext: Readonly<{
+    default: RootContext;
     /**
      * Sets the event for the current execution context.
      * @param event - The event to set.
      * @internal
      */
-    static setEvent(event: Event | null): void;
-}
+    setEvent(event: Event | null): void;
+    /**
+     * Creates a new root execution context.
+     * @returns A new execution context.
+     */
+    create(): RootContext;
+}>;
 /**
- * The default execution context used in binding expressions.
+ * Represents some sort of execution context.
  * @public
  */
-export declare const defaultExecutionContext: ExecutionContext<any, any>;
+export declare type ExecutionContext<TParentSource = any> = RootContext | ChildContext<TParentSource> | ItemContext<TParentSource>;

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;

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

@@ -6,13 +6,29 @@ import { ComposableStyles, ElementStyles } from "./element-styles.js";
  * @param values - The values that are interpolated with the string fragments.
  * @remarks
  * The css helper supports interpolation of strings and ElementStyle instances.
+ * Use the .partial method to create partial CSS fragments.
  * @public
  */
-export declare function css(strings: TemplateStringsArray, ...values: (ComposableStyles | CSSDirective)[]): ElementStyles;
+export declare type CSSTemplateTag = ((strings: TemplateStringsArray, ...values: (ComposableStyles | CSSDirective)[]) => 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;
+};
 /**
- * Transforms a template literal string into partial CSS.
+ * Transforms a template literal string into styles.
  * @param strings - The string fragments that are interpolated with the values.
  * @param values - The values that are interpolated with the string fragments.
+ * @remarks
+ * The css helper supports interpolation of strings and ElementStyle instances.
+ * @public
+ */
+export declare const css: CSSTemplateTag;
+/**
+ * @deprecated Use css.partial instead.
  * @public
  */
-export declare function cssPartial(strings: TemplateStringsArray, ...values: (ComposableStyles | CSSDirective)[]): CSSDirective;
+export declare const cssPartial: (strings: TemplateStringsArray, ...values: (ComposableStyles | CSSDirective)[]) => CSSDirective;

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

@@ -1,55 +1,42 @@
 import type { Behavior } from "../observation/behavior.js";
-/**
- * A node that can be targeted by styles.
- * @public
- */
-export interface StyleTarget {
-    /**
-     * 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;
-    /**
-     * Adds styles to the target by prepending the styles.
-     * @param styles - The styles element to add.
-     * @deprecated - use append()
-     */
-    prepend(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>;
-}
+import { StyleStrategy, StyleTarget } from "../interfaces.js";
 /**
  * Represents styles that can be composed into the ShadowDOM of a custom element.
  * @public
  */
 export declare type ComposableStyles = string | ElementStyles | CSSStyleSheet;
 /**
- * Creates an ElementStyles instance for an array of ComposableStyles.
+ * A type that instantiates a StyleStrategy.
  * @public
  */
-export declare type ElementStyleFactory = (styles: ReadonlyArray<ComposableStyles>) => ElementStyles;
+export declare type ConstructibleStyleStrategy = {
+    /**
+     * Creates an instance of the strategy.
+     * @param styles - The styles to initialize the strategy with.
+     */
+    new (styles: (string | CSSStyleSheet)[]): StyleStrategy;
+};
 /**
  * Represents styles that can be applied to a custom element.
  * @public
  */
-export declare abstract class ElementStyles {
+export declare class ElementStyles {
+    readonly styles: ReadonlyArray<ComposableStyles>;
     private targets;
-    /** @internal */
-    abstract readonly styles: ReadonlyArray<ComposableStyles>;
-    /** @internal */
-    abstract readonly behaviors: ReadonlyArray<Behavior> | null;
+    private _strategy;
+    /**
+     * The behaviors associated with this set of styles.
+     */
+    readonly behaviors: ReadonlyArray<Behavior<HTMLElement>> | null;
+    /**
+     * Gets the StyleStrategy associated with these element styles.
+     */
+    get strategy(): StyleStrategy;
+    /**
+     * Creates an instance of ElementStyles.
+     * @param styles - The styles that will be associated with elements.
+     */
+    constructor(styles: ReadonlyArray<ComposableStyles>);
     /** @internal */
     addStylesTo(target: StyleTarget): void;
     /** @internal */
@@ -60,11 +47,21 @@ export declare abstract class ElementStyles {
      * Associates behaviors with this set of styles.
      * @param behaviors - The behaviors to associate.
      */
-    withBehaviors(...behaviors: Behavior[]): this;
+    withBehaviors(...behaviors: Behavior<HTMLElement>[]): this;
+    /**
+     * Sets the strategy that handles adding/removing these styles for an element.
+     * @param strategy - The strategy to use.
+     */
+    withStrategy(Strategy: ConstructibleStyleStrategy): this;
+    /**
+     * Sets the default strategy type to use when creating style strategies.
+     * @param Strategy - The strategy type to construct.
+     */
+    static setDefaultStrategy(Strategy: ConstructibleStyleStrategy): void;
     /**
-     * Create ElementStyles from ComposableStyles.
+     * Indicates whether the DOM supports the adoptedStyleSheets feature.
      */
-    static readonly create: ElementStyleFactory;
+    static readonly supportsAdoptedStyleSheets: boolean;
 }
 /**
  * https://wicg.github.io/construct-stylesheets/
@@ -72,27 +69,10 @@ export declare abstract class ElementStyles {
  *
  * @internal
  */
-export declare class AdoptedStyleSheetsStyles extends ElementStyles {
-    styles: ComposableStyles[];
-    private styleSheetCache;
-    private _styleSheets;
-    private get styleSheets();
-    readonly behaviors: ReadonlyArray<Behavior> | null;
-    constructor(styles: ComposableStyles[], styleSheetCache: Map<string, CSSStyleSheet>);
-    addStylesTo(target: StyleTarget): void;
-    removeStylesFrom(target: StyleTarget): void;
-}
-/**
- * @internal
- */
-export declare class StyleElementStyles extends ElementStyles {
-    styles: ComposableStyles[];
-    private readonly styleSheets;
-    private readonly styleClass;
-    readonly behaviors: ReadonlyArray<Behavior> | null;
-    constructor(styles: ComposableStyles[]);
+export declare class AdoptedStyleSheetsStrategy implements StyleStrategy {
+    /** @internal */
+    readonly sheets: CSSStyleSheet[];
+    constructor(styles: (string | CSSStyleSheet)[]);
     addStylesTo(target: StyleTarget): void;
     removeStylesFrom(target: StyleTarget): void;
-    isAttachedTo(target: StyleTarget): boolean;
-    private normalizeTarget;
 }