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

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

@@ -1,3 +1,4 @@
+import { Constructable } from "../interfaces.js";
 import { ComposableStyles, ElementStyles } from "../styles/element-styles.js";
 import type { ElementViewTemplate } from "../templating/template.js";
 import { AttributeConfiguration, AttributeDefinition } from "./attributes.js";
@@ -35,7 +36,7 @@ export interface PartialFASTElementDefinition {
  * Defines metadata for a FASTElement.
  * @public
  */
-export declare class FASTElementDefinition<TType extends Function = Function> {
+export declare class FASTElementDefinition<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>> {
     private observedAttributes;
     /**
      * The type this element definition describes.
@@ -87,11 +88,18 @@ export declare class FASTElementDefinition<TType extends Function = Function> {
     /**
      * Defines a custom element based on this definition.
      * @param registry - The element registry to define the element in.
+     * @remarks
+     * This operation is idempotent per registry.
      */
     define(registry?: CustomElementRegistry): this;
     /**
      * Gets the element definition associated with the specified type.
      * @param type - The custom element type to retrieve the definition for.
      */
-    static readonly forType: <TType_1 extends Function>(key: TType_1) => FASTElementDefinition<Function> | undefined;
+    static readonly getByType: (key: Function) => FASTElementDefinition<Constructable<HTMLElement>> | undefined;
+    /**
+     * Gets the element definition associated with the instance.
+     * @param instance - The custom element instance to retrieve the definition for.
+     */
+    static readonly getForInstance: (object: any) => FASTElementDefinition<Constructable<HTMLElement>> | undefined;
 }

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";
+import { FASTElementDefinition, 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,13 @@ 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;
+    /**
+     * Defines metadata for a FASTElement which can be used to later define the element.
+     * IMPORTANT: This API will be renamed to "compose" in a future beta.
+     * @public
+     */
+    metadata<TType_1 extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType_1, nameOrDef?: string | PartialFASTElementDefinition): FASTElementDefinition<TType_1>;
 };
 /**
  * Decorator: Defines a platform custom element based on `FASTElement`.
@@ -73,4 +80,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/context.d.ts

@@ -0,0 +1,157 @@
+import type { Constructable } from "./interfaces.js";
+/**
+ * A Context object defines an optional initial value for a Context, as well as a name identifier for debugging purposes.
+ * @public
+ */
+export declare type Context<T> = {
+    readonly name: string;
+    readonly initialValue?: T;
+};
+/**
+ * A constant key that can be used to represent a Context dependency.
+ * The key can be used for context or DI but also doubles as a decorator for
+ * resolving the associated dependency.
+ * @beta
+ */
+export declare type ContextDecorator<T = any> = Readonly<Context<T>> & PropertyDecorator & ParameterDecorator;
+/**
+ * A Context object defines an optional initial value for a Context, as well as a name identifier for debugging purposes.
+ * The FASTContext can also be used as a decorator to declare context dependencies or as a key for DI.
+ * @beta
+ */
+export declare type FASTContext<T> = ContextDecorator<T> & {
+    get(target: EventTarget): T;
+    provide(target: EventTarget, value: T): void;
+    request(target: EventTarget, callback: ContextCallback<T>, multiple?: boolean): void;
+    handle(target: EventTarget, callback: (event: ContextEvent<FASTContext<T>>) => void): any;
+};
+/**
+ * A strategy that controls how all Context.request API calls are handled.
+ * @remarks
+ * By default this is handled via Context.dispatch, which dispatched a ContextEvent.
+ * @beta
+ */
+export declare type FASTContextRequestStrategy = <T extends UnknownContext>(target: EventTarget, context: T, callback: ContextCallback<ContextType<T>>, multiple: any) => void;
+declare const contextEventType = "context-request";
+/**
+ * Enables using the {@link https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md | W3C Community Context protocol.}
+ * @beta
+ */
+export declare const Context: Readonly<{
+    /**
+     * The event type used for W3C Context Protocol requests.
+     */
+    eventType: "context-request";
+    /**
+     * Creates a W3C Community Protocol-based Context object to use in requesting/providing
+     * context through the DOM.
+     * @param name - The name to use for the connext. Useful in debugging.
+     * @param initialValue - An optional initial value to use if a context handler isn't found.
+     */
+    create<T = unknown>(name: string, initialValue?: T | undefined): FASTContext<T>;
+    /**
+     * Sets the strategy used by all FAST-specific context requests made through the
+     * Context.request, Context.get, Context.defineProperty, and ContextDecorator APIs.
+     * @param strategy - The strategy to use. By default, the strategy is Context.dispatch.
+     */
+    setDefaultRequestStrategy(strategy: FASTContextRequestStrategy): void;
+    /**
+     * Gets the context value for the target node or returns the initial value if
+     * a context handler is not found.
+     * @param target - The target to get the context for.
+     * @param context - The context to locate.
+     * @returns The context value.
+     * @remarks
+     * Uses the default request strategy to locate the context. If no context is found
+     * then the initial value of the context is returned.
+     */
+    get<T_1 extends UnknownContext>(target: EventTarget, context: T_1): ContextType<T_1>;
+    /**
+     * Requests the context value for the target node.
+     * @param target - The target to request the context for.
+     * @param context - The context to locate.
+     * @param callback - A callback to invoke with the context value.
+     * @param multiple - Whether the context requestor expects to handle updates
+     * to the context value after the initial request.
+     * @remarks
+     * Uses the default request strategy to locate the context.
+     */
+    request<T_2 extends UnknownContext>(target: EventTarget, context: T_2, callback: ContextCallback<ContextType<T_2>>, multiple?: boolean): void;
+    /**
+     *
+     * @param target - The target to dispatch the context event on.
+     * @param context - The context to locate.
+     * @param callback - The callback to invoke with the context value.
+     * @param multiple - Whether the context requestor expects to handle updates
+     * to the context value after the initial request.
+     * @remarks
+     * This API does NOT use the default request strategy. It always dispatches
+     * an event through the DOM.
+     */
+    dispatch<T_3 extends UnknownContext>(target: EventTarget, context: T_3, callback: ContextCallback<ContextType<T_3>>, multiple?: boolean): void;
+    provide<T_4 extends UnknownContext>(target: EventTarget, context: T_4, value: ContextType<T_4>): void;
+    /**
+     *
+     * @param target - The target on which to handle context requests.
+     * @param callback - The callback to invoke when a context request is received.
+     * @param context - The context to handle requests for.
+     * @remarks
+     * If a context is not provided then the callback will be invoked for all context
+     * requests that are received on the target.
+     */
+    handle<T_5 extends UnknownContext>(target: EventTarget, callback: (event: ContextEvent<T_5>) => void, context?: T_5 | undefined): void;
+    /**
+     * Defines a getter-only property on the target that will return the context
+     * value for the target.
+     * @param target The target to define the property on.
+     * @param propertyName The name of the property to define.
+     * @param context The context that will be used to retrieve the property value.
+     * @remarks
+     * Uses the default request strategy to locate the context and will return the
+     * initialValue if the context isn't handled.
+     */
+    defineProperty<T_6 extends UnknownContext>(target: Constructable<EventTarget> | EventTarget, propertyName: string, context: T_6): void;
+}>;
+/**
+ * An unknown context type.
+ * @public
+ */
+export declare type UnknownContext = Context<unknown>;
+/**
+ * A helper type which can extract a Context value type from a Context type
+ * @public
+ */
+export declare type ContextType<T extends UnknownContext> = T extends Context<infer Y> ? Y : never;
+/**
+ * A callback which is provided by a context requester and is called with the value satisfying the request.
+ * This callback can be called multiple times by context providers as the requested value is changed.
+ * @public
+ */
+export declare type ContextCallback<ValueType> = (value: ValueType, dispose?: () => void) => void;
+/**
+ * An event fired by a context requester to signal it desires a named context.
+ *
+ * A provider should inspect the `context` property of the event to determine if it has a value that can
+ * satisfy the request, calling the `callback` with the requested value if so.
+ *
+ * If the requested context event contains a truthy `multiple` value, then a provider can call the callback
+ * multiple times if the value is changed, if this is the case the provider should pass a `dispose`
+ * method to the callback which requesters can invoke to indicate they no longer wish to receive these updates.
+ * @public
+ */
+export declare class ContextEvent<T extends UnknownContext> extends Event {
+    readonly context: T;
+    readonly callback: ContextCallback<ContextType<T>>;
+    readonly multiple?: boolean | undefined;
+    constructor(context: T, callback: ContextCallback<ContextType<T>>, multiple?: boolean | undefined);
+}
+declare global {
+    interface HTMLElementEventMap {
+        /**
+         * A 'context-request' event can be emitted by any element which desires
+         * a context value to be injected by an external provider.
+         */
+        [contextEventType]: ContextEvent<UnknownContext>;
+    }
+}
+export {};

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,138 @@ 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,
+    twoWayBindingRequiresObservables = 1203,
+    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/metadata.d.ts

@@ -0,0 +1,25 @@
+import type { Constructable } from "./interfaces.js";
+/**
+ * Provides basic metadata capabilities used by Context and Dependency Injection.
+ */
+export declare const Metadata: Readonly<{
+    /**
+     * Gets the "design:paramtypes" metadata for the specified type.
+     * @param Type - The type to get the metadata for.
+     * @returns The metadata array or a frozen empty array if no metadata is found.
+     */
+    getDesignParamTypes: (Type: any) => any;
+    /**
+     * Gets the "annotation:paramtypes" metadata for the specified type.
+     * @param Type - The type to get the metadata for.
+     * @returns The metadata array or a frozen empty array if no metadata is found.
+     */
+    getAnnotationParamTypes: (Type: any) => any;
+    /**
+     *
+     * @param Type - Gets the "annotation:paramtypes" metadata for the specified type. If none is found,
+     * an empty, mutable metadata array is created and added.
+     * @returns The metadata array.
+     */
+    getOrCreateAnnotationParamTypes(Type: Constructable): any[];
+}>;