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

package/dist/dts/components/fast-element.d.ts

@@ -1,10 +1,11 @@
+import type { Constructable } from "../interfaces.js";
 import { Controller } from "./controller.js";
 import { PartialFASTElementDefinition } from "./fast-definitions.js";
 /**
  * Represents a custom element based on the FASTElement infrastructure.
  * @public
  */
-export interface FASTElement {
+export interface FASTElement extends HTMLElement {
     /**
      * The underlying controller that handles the lifecycle and rendering of
      * this FASTElement.
@@ -42,7 +43,7 @@ export interface FASTElement {
      * This method is invoked by the platform whenever an observed
      * attribute of FASTElement has a value change.
      */
-    attributeChangedCallback(name: string, oldValue: string, newValue: string): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
 }
 /**
  * A minimal base class for FASTElements that also provides
@@ -65,7 +66,7 @@ export declare const FASTElement: (new () => HTMLElement & FASTElement) & {
      * @param nameOrDef - The name of the element to define or a definition object
      * that describes the element to define.
      */
-    define<TType extends Function>(type: TType, nameOrDef?: string | PartialFASTElementDefinition | undefined): TType;
+    define<TType extends Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition): TType;
 };
 /**
  * Decorator: Defines a platform custom element based on `FASTElement`.
@@ -73,4 +74,4 @@ export declare const FASTElement: (new () => HTMLElement & FASTElement) & {
  * that describes the element to define.
  * @public
  */
-export declare function customElement(nameOrDef: string | PartialFASTElementDefinition): (type: Function) => void;
+export declare function customElement(nameOrDef: string | PartialFASTElementDefinition): (type: Constructable<HTMLElement>) => void;

package/dist/dts/debug.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dts/hooks.d.ts

@@ -0,0 +1,20 @@
+import { BindingObserver } from "./observation/observable.js";
+/**
+ * Functions used for getting and setting a stateful value.
+ * @beta
+ */
+export declare type State<T> = [() => T, (newValue: T) => T];
+/**
+ * Creates an observable state value.
+ * @param value The initial state value.
+ * @param deep Whether or not to convert the state value to an observable.
+ * @returns The state accessor functions.
+ * @beta
+ */
+export declare function useState<T>(value: T, deep?: boolean): State<T>;
+/**
+ * Executes an action once, and then whenever any of its dependent state changes.
+ * @param action An action that is affected by state changes.
+ * @returns A BindingObserver which can be used to dispose of the effect.
+ */
+export declare function useEffect(action: () => void): BindingObserver;

package/dist/dts/index.d.ts

@@ -1,21 +1,17 @@
+export type { Callable, Constructable, Disposable, FASTGlobal, Mutable, StyleStrategy, StyleTarget, TrustedTypes, TrustedTypesPolicy, } from "./interfaces.js";
 export * from "./platform.js";
-export * from "./templating/template.js";
-export * from "./components/fast-element.js";
-export { FASTElementDefinition, PartialFASTElementDefinition, } from "./components/fast-definitions.js";
-export * from "./components/attributes.js";
-export * from "./components/controller.js";
-export type { Callable, Constructable, Mutable } from "./interfaces.js";
-export * from "./templating/compiler.js";
-export { ElementStyles, ElementStyleFactory, ComposableStyles, StyleTarget, } from "./styles/element-styles.js";
-export { css, cssPartial } from "./styles/css.js";
-export { CSSDirective } from "./styles/css-directive.js";
-export * from "./templating/view.js";
 export * from "./observation/observable.js";
 export * from "./observation/notifier.js";
-export { Splice } from "./observation/array-change-records.js";
-export { enableArrayObservation } from "./observation/array-observer.js";
-export { DOM } from "./dom.js";
+export * from "./observation/arrays.js";
+export * from "./observation/update-queue.js";
 export type { Behavior } from "./observation/behavior.js";
+export * from "./styles/element-styles.js";
+export * from "./styles/css.js";
+export * from "./styles/css-directive.js";
+export * from "./templating/dom.js";
+export * from "./templating/template.js";
+export * from "./templating/compiler.js";
+export { Markup, Parser } from "./templating/markup.js";
 export * from "./templating/binding.js";
 export * from "./templating/html-directive.js";
 export * from "./templating/ref.js";
@@ -23,4 +19,9 @@ export * from "./templating/when.js";
 export * from "./templating/repeat.js";
 export * from "./templating/slotted.js";
 export * from "./templating/children.js";
-export { elements, ElementsFilter, NodeBehaviorOptions, } from "./templating/node-observation.js";
+export * from "./templating/view.js";
+export * from "./templating/node-observation.js";
+export * from "./components/fast-element.js";
+export * from "./components/fast-definitions.js";
+export * from "./components/attributes.js";
+export * from "./components/controller.js";

package/dist/dts/index.debug.d.ts

@@ -0,0 +1,2 @@
+import "./debug.js";
+export * from "./index.js";

package/dist/dts/index.rollup.d.ts

@@ -0,0 +1,2 @@
+import "./polyfills.js";
+export * from "./index.js";

package/dist/dts/index.rollup.debug.d.ts

@@ -0,0 +1,3 @@
+import "./polyfills.js";
+import "./debug.js";
+export * from "./index.js";

package/dist/dts/interfaces.d.ts

@@ -13,6 +13,16 @@ export declare type Callable = typeof Function.prototype.call | {
 export declare type Constructable<T = {}> = {
     new (...args: any[]): T;
 };
+/**
+ * Provides a mechanism for releasing resources.
+ * @public
+ */
+export interface Disposable {
+    /**
+     * Disposes the resources.
+     */
+    dispose(): void;
+}
 /**
  * Reverses all readonly members, making them mutable.
  * @internal
@@ -20,3 +30,137 @@ export declare type Constructable<T = {}> = {
 export declare type Mutable<T> = {
     -readonly [P in keyof T]: T[P];
 };
+/**
+ * Extracts the item type from an array.
+ * @public
+ */
+export declare type ArrayItem<T> = T extends ReadonlyArray<infer TItem> ? TItem : T extends Array<infer TItem> ? TItem : any;
+/**
+ * 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;
+};
+/**
+ * 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;
+    /**
+     * Sends a warning to the developer.
+     * @param code - The warning code to send.
+     * @param args - Args relevant for the warning.
+     */
+    warn(code: number, ...args: any[]): void;
+    /**
+     * Creates an error.
+     * @param code - The error code to send.
+     * @param args - Args relevant for the error.
+     */
+    error(code: number, ...args: any[]): Error;
+    /**
+     * Adds debug messages for errors and warnings.
+     * @param messages - The message dictionary to add.
+     */
+    addMessages(messages: Record<number, string>): void;
+}
+/**
+ * Core services shared across FAST instances.
+ * @internal
+ */
+export declare const enum KernelServiceId {
+    updateQueue = 1,
+    observable = 2,
+    contextEvent = 3,
+    elementRegistry = 4,
+    styleSheetStrategy = 5,
+    developerChannel = 6
+}
+/**
+ * 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;
+    /**
+     * 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;
+}
+/**
+ * Warning and error messages.
+ * @internal
+ */
+export declare const enum Message {
+    needsArrayObservation = 1101,
+    onlySetHTMLPolicyOnce = 1201,
+    bindingInnerHTMLRequiresTrustedTypes = 1202,
+    missingElementDefinition = 1401
+}
+/**
+ * @internal
+ */
+export declare const isFunction: (object: any) => object is Function;
+/**
+ * @internal
+ */
+export declare const isString: (object: any) => object is string;

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 length<T>(array: readonly T[]): number;

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

@@ -1,19 +1,19 @@
-import type { ExecutionContext } from "./observable.js";
+import type { ExecutionContext, RootContext } 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, TContext extends ExecutionContext<TParent> = RootContext> {
     /**
      * 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: TContext): void;
     /**
      * Unbinds this behavior from the source.
      * @param source - The source to unbind from.
      */
-    unbind(source: unknown): void;
+    unbind(source: TSource, context: TContext): 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.