@lushly-dev/fast-element 3.0.1-preview.0 → 3.0.1-preview.2

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

@@ -0,0 +1,91 @@
+import { type Constructable } from "../interfaces.js";
+import type { TrustEmitOptions } from "../trust/types.js";
+import { ElementController } from "./element-controller.js";
+import { type FASTElementExtension, type PartialFASTElementDefinition } from "./fast-definitions.js";
+/**
+ * Represents a custom element based on the FASTElement infrastructure.
+ * @public
+ */
+export interface FASTElement extends HTMLElement {
+    /**
+     * The underlying controller that handles the lifecycle and rendering of
+     * this FASTElement.
+     */
+    readonly $fastController: ElementController;
+    /**
+     * Emits a custom HTML event.
+     * @param type - The type name of the event.
+     * @param detail - The event detail object to send with the event.
+     * @param options - The event options. By default bubbles and composed.
+     * @remarks
+     * Only emits events if the element is connected.
+     */
+    $emit(type: string, detail?: any, options?: TrustEmitOptions): boolean | void;
+    /**
+     * The connected callback for this FASTElement.
+     * @remarks
+     * This method is invoked by the platform whenever this FASTElement
+     * becomes connected to the document.
+     */
+    connectedCallback(): void;
+    /**
+     * The disconnected callback for this FASTElement.
+     * @remarks
+     * This method is invoked by the platform whenever this FASTElement
+     * becomes disconnected from the document.
+     */
+    disconnectedCallback(): void;
+    /**
+     * The attribute changed callback for this FASTElement.
+     * @param name - The name of the attribute that changed.
+     * @param oldValue - The previous value of the attribute.
+     * @param newValue - The new value of the attribute.
+     * @remarks
+     * This method is invoked by the platform whenever an observed
+     * attribute of FASTElement has a value change.
+     */
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+}
+/**
+ * The FASTElement constructor and static registration helpers.
+ * @public
+ */
+export interface FASTElementConstructor {
+    /**
+     * Creates a FASTElement instance.
+     */
+    new (): FASTElement;
+    /**
+     * Defines a platform custom element based on the provided type and definition.
+     * @param nameOrDef - The name of the element to define or a definition object.
+     * @param extensions - Optional callbacks to run before registration.
+     */
+    define<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(this: TType, nameOrDef: string | PartialFASTElementDefinition<TType>, extensions?: FASTElementExtension[]): Promise<TType>;
+    /**
+     * Defines a platform custom element based on the provided type and definition.
+     * @param type - The custom element type to define.
+     * @param nameOrDef - The name of the element to define or a definition object.
+     * @param extensions - Optional callbacks to run before registration.
+     */
+    define<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition<TType>, extensions?: FASTElementExtension[]): Promise<TType>;
+    /**
+     * Creates a new FASTElement base class inherited from the provided base type.
+     * @param BaseType - The base element type to inherit from.
+     */
+    from<TBase extends typeof HTMLElement>(BaseType: TBase): {
+        new (): InstanceType<TBase> & FASTElement;
+    };
+}
+/**
+ * A minimal base class for FASTElements that also provides
+ * static helpers for working with FASTElements.
+ * @public
+ */
+export declare const FASTElement: FASTElementConstructor;
+/**
+ * Decorator: Defines a platform custom element based on `FASTElement`.
+ * @param nameOrDef - The name of the element to define or a definition object
+ * that describes the element to define.
+ * @public
+ */
+export declare function customElement(nameOrDef: string | PartialFASTElementDefinition): (type: Constructable<HTMLElement>) => void;

package/dist/dts/components/hydration-tracker.d.ts

@@ -0,0 +1,110 @@
+import type { HydrationDebugger } from "../hydration/hydration-debugger.js";
+/**
+ * Describes when FAST should stop hydrating newly connected prerendered elements.
+ * @public
+ */
+export declare const StopHydration: Readonly<{
+    /**
+     * Stop hydrating new prerendered elements after the active hydration batch completes.
+     */
+    readonly hydrationComplete: "hydration-complete";
+    /**
+     * Keep the hydration hook active for later prerendered elements.
+     */
+    readonly never: "never";
+}>;
+/**
+ * Describes when FAST should stop hydrating newly connected prerendered elements.
+ * @public
+ */
+export type StopHydration = (typeof StopHydration)[keyof typeof StopHydration];
+/**
+ * Options for configuring hydration behavior.
+ * @public
+ */
+export interface HydrationOptions {
+    /**
+     * Indicates when the hydration hook should stop handling new
+     * prerendered elements.
+     *
+     * @defaultValue StopHydration.hydrationComplete
+     */
+    stopHydration?: StopHydration;
+    /**
+     * Optional opt-in debugger that swaps the default minimal hydration
+     * mismatch error message for a rich "Expected … / Received …" report
+     * including an HTML snippet of the SSR DOM and structured
+     * `expected`/`received` fields on `HydrationBindingError` /
+     * `HydrationTargetElementError`. Obtained via
+     * `hydrationDebugger()` from `@lushly-dev/fast-element/hydration.js`.
+     */
+    debugger?: HydrationDebugger;
+}
+/**
+ * The controller returned by `enableHydration()`.
+ * @public
+ */
+export interface HydrationController {
+    /**
+     * Resolves when the active hydration batch completes, or when hydration work
+     * for the specified tag name completes.
+     * @param tagName - The optional custom element tag name to observe.
+     * @remarks
+     * If hydration is configured with `stopHydration: StopHydration.never`, the
+     * global promise intentionally remains pending because hydration never
+     * reaches a global completion point.
+     */
+    whenHydrated(tagName?: string): Promise<void>;
+}
+/**
+ * Tracks prerendered elements through the hydration lifecycle and
+ * exposes the active global hydration completion promise.
+ *
+ * @public
+ */
+export declare class HydrationTracker implements HydrationController {
+    private elements;
+    private elementTags;
+    private tagHydrationStates;
+    private started;
+    private completed;
+    private checkTimer;
+    private stopHydration;
+    private _whenHydrated;
+    private resolveWhenHydrated;
+    constructor(options: HydrationOptions);
+    /**
+     * Resolves when the active hydration batch completes, or when hydration work
+     * for the specified tag name completes.
+     */
+    whenHydrated(tagName?: string): Promise<void>;
+    /**
+     * Indicates whether the hydration hook should attempt to hydrate
+     * prerendered elements.
+     */
+    get shouldHydrate(): boolean;
+    /**
+     * Registers an element as pending hydration.
+     */
+    add(element: HTMLElement): void;
+    /**
+     * Removes an element from the pending set and schedules
+     * a debounced completion check.
+     */
+    remove(element: HTMLElement): void;
+    /**
+     * Merges additional options into the tracker.
+     */
+    mergeOptions(incoming: HydrationOptions): void;
+    private prepareHydrationPromise;
+    private getTagHydrationPromise;
+    private addTagHydration;
+    private removeTagHydration;
+    private getTagHydrationState;
+    private createTagHydrationState;
+    private prepareTagHydrationState;
+    private resolveTagHydrationState;
+    private scheduleTagHydrationResolution;
+    private resolveTagHydrationPromises;
+    private resolveHydrationPromise;
+}

package/dist/dts/components/hydration.d.ts

@@ -0,0 +1,52 @@
+import type { ContentTemplate, HydratableContentTemplate } from "../templating/html-binding-directive.js";
+import type { ViewController } from "../templating/html-directive.js";
+import type { HydratableViewController } from "../templating/hydration-view.js";
+import type { ElementViewTemplate, HydratableElementViewTemplate, HydratableSyntheticViewTemplate, SyntheticViewTemplate } from "../templating/template.js";
+/**
+ * Markup utilities to aid in template hydration.
+ * @internal
+ */
+export declare const HydrationMarkup: Readonly<{
+    attributeMarkerName: "data-fe";
+    legacyAttributeMarkerName: "data-fe-b";
+    legacyCompactAttributeMarkerName: "data-fe-c";
+    contentBindingStartMarker(): string;
+    contentBindingEndMarker(): string;
+    repeatStartMarker(): string;
+    repeatEndMarker(): string;
+    elementBoundaryStartMarker(): string;
+    elementBoundaryEndMarker(): string;
+    isContentBindingStartMarker(data: string): boolean;
+    isContentBindingEndMarker(data: string): boolean;
+    isRepeatViewStartMarker(data: string): boolean;
+    isRepeatViewEndMarker(data: string): boolean;
+    isElementBoundaryStartMarker(node: Node): boolean;
+    isElementBoundaryEndMarker(node: Node): boolean;
+    /**
+     * Returns the count of attribute bindings on the element, or null
+     * if no attribute binding marker is present.
+     *
+     * Parses the `data-fe="N"` attribute format where N is the count
+     * of attribute binding factories targeting this element.
+     */
+    parseAttributeBindingCount(node: Element): number | null;
+    parseLegacyAttributeBindingIndices(node: Element): number[] | null;
+    removeLegacyAttributeBindingMarkers(node: Element): void;
+    parseLegacyContentBindingStartIndex(data: string): number | null;
+}>;
+/**
+ * @internal
+ */
+export declare const Hydratable: unique symbol;
+/**
+ * Tests if a template or ViewController is hydratable.
+ *
+ * @beta
+ */
+export declare function isHydratable(view: ViewController): view is HydratableViewController;
+/** @beta */
+export declare function isHydratable<TSource = any, TParent = any>(template: SyntheticViewTemplate<TSource, TParent>): template is HydratableSyntheticViewTemplate<TSource, TParent>;
+/** @beta */
+export declare function isHydratable<TSource = any, TParent = any>(template: ElementViewTemplate<TSource, TParent>): template is HydratableElementViewTemplate<TSource, TParent>;
+/** @beta */
+export declare function isHydratable(template: ContentTemplate): template is HydratableContentTemplate;

package/dist/dts/components/schema.d.ts

@@ -0,0 +1,205 @@
+type FastContextMetaData = "$fast_context";
+type FastContextsMetaData = "$fast_parent_contexts";
+/**
+ * Describes a child custom element binding referenced by a schema path.
+ * @public
+ */
+export interface ChildrenMap {
+    customElementName: string;
+    attributeName: string;
+}
+/**
+ * A reusable JSON schema definition.
+ * @public
+ */
+export interface JSONSchemaDefinition extends JSONSchemaCommon {
+    $fast_context: string;
+    $fast_parent_contexts: Array<string>;
+}
+/**
+ * Common properties shared by schema nodes.
+ * @public
+ */
+export interface JSONSchemaCommon {
+    type?: string;
+    properties?: any;
+    items?: any;
+    anyOf?: Array<any>;
+    $ref?: string;
+    /**
+     * Stamped by `applyConfigToSchema` when an `ObserverMapConfig` excludes
+     * this path. When `false`, the proxy system skips observation for this
+     * node and (if all descendants are also `false`) its subtree.
+     */
+    $observe?: boolean;
+}
+/**
+ * A JSON schema describing a root property.
+ * @public
+ */
+export interface JSONSchema extends JSONSchemaCommon {
+    $schema: string;
+    $id: string;
+    $defs?: Record<string, JSONSchemaDefinition>;
+}
+/**
+ * Common metadata for paths cached while parsing a template.
+ * @public
+ */
+export interface CachedPathCommon {
+    parentContext: string | null;
+    currentContext: string | null;
+    path: string;
+}
+/**
+ * A path discovered from an access expression.
+ * @public
+ */
+export interface AccessCachedPath extends CachedPathCommon {
+    type: "access";
+}
+/**
+ * A path discovered from a default binding.
+ * @public
+ */
+export interface DefaultCachedPath extends CachedPathCommon {
+    type: "default";
+}
+/**
+ * A path discovered from an event binding.
+ * @public
+ */
+export interface EventCachedPath extends CachedPathCommon {
+    type: "event";
+}
+/**
+ * A path discovered from a repeat directive.
+ * @public
+ */
+export interface RepeatCachedPath extends CachedPathCommon {
+    type: "repeat";
+}
+/**
+ * A path discovered while parsing a template.
+ * @public
+ */
+export type CachedPath = DefaultCachedPath | RepeatCachedPath | AccessCachedPath | EventCachedPath;
+/**
+ * A map from element names and root properties to JSON schemas.
+ * @public
+ */
+export type CachedPathMap = Map<string, Map<string, JSONSchema>>;
+/**
+ * Configuration for registering a path with a schema.
+ * @public
+ */
+export interface RegisterPathConfig {
+    rootPropertyName: string;
+    pathConfig: CachedPath;
+    childrenMap: ChildrenMap | null;
+}
+export declare const fastContextMetaData: FastContextMetaData;
+export declare const fastContextsMetaData: FastContextsMetaData;
+export declare const defsPropertyName = "$defs";
+export declare const refPropertyName = "$ref";
+/**
+ * Module-level registry that maps custom element names to their schema maps.
+ * Used for cross-element `$ref` resolution (e.g. nested element schemas).
+ * Each Schema instance registers itself here on construction.
+ * @public
+ */
+export declare const schemaRegistry: CachedPathMap;
+/**
+ * A constructed JSON schema from a template
+ * @public
+ */
+export declare class Schema {
+    /**
+     * The name of the custom element
+     */
+    private customElementName;
+    /**
+     * Instance-level JSON schema map describing each root property
+     */
+    private schemaMap;
+    constructor(name: string);
+    /**
+     * Add a path to a schema
+     * @param config - The path registration configuration.
+     */
+    addPath(config: RegisterPathConfig): void;
+    /**
+     * Gets the JSON schema for a property name
+     * @param rootPropertyName - the root property the JSON schema is mapped to
+     * @returns The JSON schema for the root property
+     */
+    getSchema(rootPropertyName: string): JSONSchema | null;
+    /**
+     * Gets root properties
+     * @returns IterableIterator<string>
+     */
+    getRootProperties(): IterableIterator<string>;
+    /**
+     * Get a path split into property names
+     * @param path - The dot syntax path, e.g. `a.b.c`.
+     * @returns An array of items in the path
+     */
+    private getSplitPath;
+    /**
+     * Gets the path to the $def
+     * @param context - The context name. For example, `item in items` creates the `item` context.
+     * @returns A string to use as a $ref
+     */
+    private getDefsPath;
+    /**
+     * Get the schema $id
+     * @param customElementName - The custom element name
+     * @param propertyName - The property name
+     * @returns The ID that can be used in the JSON schema as $id
+     */
+    private getSchemaId;
+    /**
+     * Add a new JSON schema to the JSON schema map
+     * @param propertyName - The name of the property to assign this JSON schema to.
+     */
+    private addNewSchema;
+    /**
+     * Add properties to a context
+     * @param schema - The schema to add the properties to.
+     * @param splitPath - The path split into property/context names.
+     * @param context - The path context.
+     */
+    private addPropertiesToAContext;
+    /**
+     * Add properties to an object
+     * @param schema - The schema to add the properties to.
+     * @param splitPath - The path split into property/context names.
+     * @param context - The path context.
+     * @param type - The data type (see JSON schema for details).
+     */
+    private addPropertiesToAnObject;
+    /**
+     * Add an array to an object property
+     * @param schema - The schema to add the properties to.
+     * @param context - The name of the context.
+     */
+    private addArrayToAnObject;
+    /**
+     * Add a context to the $defs property
+     * @param schema - The schema to use.
+     * @param propertyName - The name of the property the context belongs to.
+     * @param currentContext - The current context.
+     * @param parentContext - The parent context.
+     * @returns
+     */
+    private addContext;
+    /**
+     * Get parent contexts
+     * @param schema - The schema to use.
+     * @param parentContext - The parent context.
+     * @param contexts - A list of parent contexts.
+     * @returns
+     */
+    private getParentContexts;
+}
+export {};

package/dist/dts/context.d.ts

@@ -0,0 +1,171 @@
+import { type Constructable, type ParameterDecorator } 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 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.
+ * @public
+ */
+export 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.
+ * @public
+ */
+export 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): void;
+};
+/**
+ * A strategy that controls how all Context.request API calls are handled.
+ * @remarks
+ * By default this is handled via Context.dispatch, which dispatches a ContextEvent.
+ * @public
+ */
+export type FASTContextRequestStrategy = <T extends UnknownContext>(target: EventTarget, context: T, callback: ContextCallback<ContextType<T>>, multiple: any) => void;
+declare const contextEventType = "context-request";
+/**
+ * Enables using:
+ * {@link https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md | W3C Community Context protocol.}
+ * @public
+ */
+export declare const Context: Readonly<{
+    /**
+     * The event type used for W3C Context Protocol requests.
+     */
+    eventType: "context-request";
+    /**
+     * Returns a FASTContext object from the global context registry matching the given name if found.
+     * Otherwise, returns a new FASTContext with this name.
+     * @param name - The name of the FASTContext to get or create.
+     * @returns A FASTContext object.
+     */
+    for<T = unknown>(name: string): FASTContext<T>;
+    /**
+     * 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): 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 extends UnknownContext>(target: EventTarget, context: T): ContextType<T>;
+    /**
+     * 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 extends UnknownContext>(target: EventTarget, context: T, callback: ContextCallback<ContextType<T>>, 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 extends UnknownContext>(target: EventTarget, context: T, callback: ContextCallback<ContextType<T>>, multiple?: boolean): void;
+    /**
+     * Enables an event target to provide a context value.
+     * @param target - The target to provide the context value for.
+     * @param context - The context to provide the value for.
+     * @param value - The value to provide for the context.
+     */
+    provide<T extends UnknownContext>(target: EventTarget, context: T, value: ContextType<T>): 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 extends UnknownContext>(target: EventTarget, callback: (event: ContextEvent<T>) => void, context?: T): 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 extends UnknownContext>(target: Constructable<EventTarget> | EventTarget, propertyName: string, context: T): void;
+}>;
+/**
+ * An unknown context type.
+ * @public
+ */
+export type UnknownContext = Context<unknown>;
+/**
+ * A helper type which can extract a Context value type from a Context type
+ * @public
+ */
+export 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 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,5 @@
+/**
+ * Enables human-readable FAST debug messages.
+ * @public
+ */
+export declare function enableDebug(): void;