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

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

@@ -0,0 +1,349 @@
+import type { Notifier, Subscriber } from "../observation/notifier.js";
+import { ExecutionContext, type ExpressionController, SourceLifetime } from "../observation/observable.js";
+import { ElementStyles } from "../styles/element-styles.js";
+import type { HostBehavior, HostController } from "../styles/host.js";
+import type { StyleStrategy, StyleTarget } from "../styles/style-strategy.js";
+import type { ElementViewTemplate } from "../templating/template.js";
+import type { ElementView } from "../templating/view.js";
+import type { TrustEmitOptions } from "../trust/types.js";
+import { FASTElementDefinition, type ShadowRootOptions } from "./fast-definitions.js";
+/**
+ * Creates an optional behavior for a newly constructed element controller.
+ * @internal
+ */
+export type ElementControllerBehaviorFactory = (element: HTMLElement) => HostBehavior<HTMLElement> | undefined;
+/**
+ * Registers a focused integration hook for optional element behaviors.
+ * @param factory - Factory invoked for each new element controller.
+ * @returns A callback that removes the factory.
+ * @internal
+ */
+export declare function registerElementControllerBehaviorFactory(factory: ElementControllerBehaviorFactory): () => void;
+/**
+ * A type that instantiates an ElementController
+ * @public
+ */
+export interface ElementControllerStrategy {
+    new (element: HTMLElement, definition: FASTElementDefinition): ElementController;
+}
+/**
+ * The various lifecycle stages of an ElementController.
+ * @public
+ */
+export declare const enum Stages {
+    /** The element is in the process of connecting. */
+    connecting = 0,
+    /** The element is connected. */
+    connected = 1,
+    /** The element is in the process of disconnecting. */
+    disconnecting = 2,
+    /** The element is disconnected. */
+    disconnected = 3
+}
+/**
+ * Controls the lifecycle and rendering of a `FASTElement`.
+ * @public
+ */
+export declare class ElementController<TElement extends HTMLElement = HTMLElement> implements Notifier, HostController<TElement> {
+    /**
+     * Internal notifier used to delegate subscriber management.
+     */
+    private _notifier;
+    /**
+     * A map of observable properties that were set on the element before upgrade.
+     */
+    private boundObservables;
+    /**
+     * Indicates whether the controller needs to perform initial rendering.
+     */
+    protected needsInitialization: boolean;
+    /**
+     * Indicates whether the element has an existing shadow root (e.g. from declarative shadow DOM).
+     */
+    protected hasExistingShadowRoot: boolean;
+    /**
+     * Resolves the isPrerendered promise.
+     */
+    private _resolvePrerendered;
+    /**
+     * Resolves the isHydrated promise.
+     */
+    private _resolveHydrated;
+    /**
+     * Resolves `true` when the element had an existing shadow root
+     * (from SSR or declarative shadow DOM) at connect time, `false`
+     * otherwise.
+     */
+    readonly isPrerendered: Promise<boolean>;
+    /**
+     * Resolves `true` after prerendered content has been successfully
+     * hydrated, or `false` when the component is client-side rendered
+     * or hydration is not enabled.
+     */
+    readonly isHydrated: Promise<boolean>;
+    /**
+     * The template used to render the component.
+     */
+    private _template;
+    /**
+     * The shadow root options for the component.
+     */
+    private _shadowRootOptions;
+    /**
+     * The current lifecycle stage of the controller.
+     */
+    protected stage: Stages;
+    /**
+     * A guard against connecting behaviors multiple times
+     * during connect in scenarios where a behavior adds
+     * another behavior during it's connectedCallback
+     */
+    private guardBehaviorConnection;
+    /**
+     * The behaviors associated with the component.
+     */
+    protected behaviors: Map<HostBehavior<TElement>, number> | null;
+    /**
+     * Tracks whether behaviors are connected so that
+     * behaviors cant be connected multiple times
+     */
+    private behaviorsConnected;
+    /**
+     * The main set of styles used for the component, independent of any
+     * dynamically added styles.
+     */
+    private _mainStyles;
+    /**
+     * This allows Observable.getNotifier(...) to return the Controller
+     * when the notifier for the Controller itself is being requested. The
+     * result is that the Observable system does not need to create a separate
+     * instance of Notifier for observables on the Controller. The component and
+     * the controller will now share the same notifier, removing one-object construct
+     * per web component instance.
+     */
+    private readonly $fastController;
+    /**
+     * The element being controlled by this controller.
+     */
+    readonly source: TElement;
+    /**
+     * The element definition that instructs this controller
+     * in how to handle rendering and other platform integrations.
+     */
+    readonly definition: FASTElementDefinition;
+    /**
+     * The view associated with the custom element.
+     * @remarks
+     * If `null` then the element is managing its own rendering.
+     */
+    readonly view: ElementView<TElement> | null;
+    /**
+     * Indicates whether or not the custom element has been
+     * connected to the document.
+     */
+    get isConnected(): boolean;
+    /**
+     * The context the expression is evaluated against.
+     */
+    get context(): ExecutionContext;
+    /**
+     * Indicates whether the controller is bound.
+     */
+    get isBound(): boolean;
+    /**
+     * Indicates how the source's lifetime relates to the controller's lifetime.
+     */
+    get sourceLifetime(): SourceLifetime | undefined;
+    /**
+     * Gets/sets the template used to render the component.
+     * @remarks
+     * This value can only be accurately read after connect but can be set at any time.
+     */
+    get template(): ElementViewTemplate<TElement> | null;
+    set template(value: ElementViewTemplate<TElement> | null);
+    /**
+     * The shadow root options for the component.
+     */
+    get shadowOptions(): ShadowRootOptions | undefined;
+    set shadowOptions(value: ShadowRootOptions | undefined);
+    /**
+     * The main set of styles used for the component, independent
+     * of any dynamically added styles.
+     */
+    get mainStyles(): ElementStyles | null;
+    set mainStyles(value: ElementStyles | null);
+    /**
+     * Creates a Controller to control the specified element.
+     * @param element - The element to be controlled by this controller.
+     * @param definition - The element definition metadata that instructs this
+     * controller in how to handle rendering and other platform integrations.
+     * @internal
+     */
+    constructor(element: TElement, definition: FASTElementDefinition);
+    /**
+     * The subject that subscribers will receive notifications for.
+     */
+    get subject(): TElement;
+    /**
+     * Notifies all subscribers of a property change.
+     * @param args - The property name that changed.
+     */
+    notify(args: any): void;
+    /**
+     * Subscribes to notification of changes in the element's state.
+     * @param subscriber - The object that is subscribing for change notification.
+     * @param propertyToWatch - The name of the property to watch for changes.
+     */
+    subscribe(subscriber: Subscriber, propertyToWatch?: any): void;
+    /**
+     * Unsubscribes from notification of changes in the element's state.
+     * @param subscriber - The object that is unsubscribing from change notification.
+     * @param propertyToUnwatch - The name of the property to unsubscribe from.
+     */
+    unsubscribe(subscriber: Subscriber, propertyToUnwatch?: any): void;
+    /**
+     * Registers an unbind handler with the controller.
+     * @param behavior - An object to call when the controller unbinds.
+     */
+    onUnbind(behavior: {
+        unbind(controller: ExpressionController<TElement>): any;
+    }): void;
+    /**
+     * Adds the behavior to the component.
+     * @param behavior - The behavior to add.
+     */
+    addBehavior(behavior: HostBehavior<TElement>): void;
+    /**
+     * Removes the behavior from the component.
+     * @param behavior - The behavior to remove.
+     * @param force - Forces removal even if this behavior was added more than once.
+     */
+    removeBehavior(behavior: HostBehavior<TElement>, force?: boolean): void;
+    /**
+     * Adds styles to this element. Providing an HTMLStyleElement will attach the element instance to the shadowRoot.
+     * @param styles - The styles to add.
+     */
+    addStyles(styles: ElementStyles | HTMLStyleElement | null | undefined): void;
+    /**
+     * Removes styles from this element. Providing an HTMLStyleElement will detach the element instance from the shadowRoot.
+     * @param styles - the styles to remove.
+     */
+    removeStyles(styles: ElementStyles | HTMLStyleElement | null | undefined): void;
+    /**
+     * Runs connected lifecycle behavior on the associated element.
+     */
+    connect(): void;
+    /**
+     * Binds any observables that were set before upgrade.
+     */
+    protected bindObservables(): void;
+    /**
+     * Captures public own-properties that shadow observable accessors on the
+     * prototype so they can be rebound through the accessor before rendering.
+     */
+    protected captureBoundObservables(): void;
+    /**
+     * Synchronizes late-defined attribute-map attributes from the live DOM to the
+     * associated property values before the initial render occurs.
+     */
+    protected syncLateAttributes(): void;
+    /**
+     * Observes late-defined attribute-map attributes that the platform does not
+     * surface through attributeChangedCallback because they were added after
+     * customElements.define() completed.
+     */
+    protected observeLateAttributes(): void;
+    /**
+     * Connects any existing behaviors on the associated element.
+     */
+    protected connectBehaviors(): void;
+    /**
+     * Disconnects any behaviors on the associated element.
+     */
+    protected disconnectBehaviors(): void;
+    /**
+     * Runs disconnected lifecycle behavior on the associated element.
+     */
+    disconnect(): void;
+    /**
+     * Runs the attribute changed callback for the associated element.
+     * @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.
+     */
+    onAttributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    /**
+     * 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 connected.
+     */
+    emit(type: string, detail?: any, options?: TrustEmitOptions): void | boolean;
+    /**
+     * Renders the provided template to the element.
+     *
+     * @param template - The template to render.
+     * @remarks
+     * If `null` is provided, any existing view will be removed.
+     */
+    protected renderTemplate(template: ElementViewTemplate | null | undefined): void;
+    /**
+     * Standard client-side render: clears any stale content, clones the
+     * compiled fragment, binds, and appends to the host.
+     */
+    private renderClientSide;
+    /**
+     * Locates or creates a controller for the specified element.
+     * @param element - The element to return the controller for.
+     * @param override - Reset the controller even if one has been defined.
+     * @remarks
+     * The specified element must have a {@link FASTElementDefinition}
+     * registered either through the use of the {@link customElement}
+     * decorator or a call to `FASTElement.define`.
+     */
+    static forCustomElement(element: HTMLElement, override?: boolean): ElementController;
+    /**
+     * Sets the strategy that ElementController.forCustomElement uses to construct
+     * ElementController instances for an element.
+     * @param strategy - The strategy to use.
+     */
+    static setStrategy(strategy: ElementControllerStrategy): void;
+    /**
+     * A hook that, when set, handles prerendered content hydration.
+     * Called by renderTemplate when an existing shadow root is detected.
+     * Returns true if hydration was performed, false to fall back to client-side.
+     * @internal
+     */
+    private static hydrationHook;
+    /**
+     * Installs the hydration hook. Called by enableHydration().
+     * @internal
+     */
+    static installHydrationHook(hook: (controller: ElementController, template: ElementViewTemplate, element: HTMLElement, host: Node) => boolean): void;
+}
+/**
+ * https://wicg.github.io/construct-stylesheets/
+ * https://developers.google.com/web/updates/2019/02/constructable-stylesheets
+ *
+ * @internal
+ */
+export declare class AdoptedStyleSheetsStrategy implements StyleStrategy {
+    private static styleSheetCache;
+    /** @internal */
+    readonly sheets: CSSStyleSheet[];
+    constructor(styles: (string | CSSStyleSheet)[]);
+    addStylesTo(target: StyleTarget): void;
+    removeStylesFrom(target: StyleTarget): void;
+}
+/**
+ * @internal
+ */
+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/components/element-hydration.d.ts

@@ -0,0 +1,2 @@
+export { ElementController } from "./element-controller.js";
+export * from "./hydration.js";

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

@@ -0,0 +1,66 @@
+import { type HydrationController, type HydrationOptions } from "./hydration-tracker.js";
+export { StopHydration } from "./hydration-tracker.js";
+export type { HydrationController, HydrationOptions };
+/**
+ * Enables hydration support for prerendered FAST elements.
+ *
+ * @remarks
+ * Call this before any FAST elements connect to the DOM. Hydration
+ * logic is not active unless this function is called, keeping
+ * `FASTElement` lightweight for client-side-only applications.
+ *
+ * Safe to call multiple times — the hydration hook is installed once
+ * and subsequent calls merge their options into the shared tracker.
+ * By default, the hook stops hydrating new prerendered elements after
+ * the initial hydration batch completes. Await the returned controller's
+ * `whenHydrated()` promise to run code after the active hydration batch
+ * completes.
+ *
+ * Set `stopHydration` to `StopHydration.never` for streaming scenarios
+ * that append hydratable Declarative Shadow DOM after the initial batch.
+ * In this mode, `whenHydrated` intentionally remains pending because
+ * hydration never reaches a global completion point.
+ *
+ * Pass `debugger: hydrationDebugger()` to swap the default minimal
+ * hydration mismatch error message for a rich "Expected / Received"
+ * report including the SSR HTML snippet and structured
+ * `expected`/`received` fields on `HydrationBindingError` /
+ * `HydrationTargetElementError`. The debugger module is tree-shaken
+ * out of production hydration bundles unless explicitly imported.
+ *
+ * @example
+ * ```ts
+ * import { enableHydration } from "@lushly-dev/fast-element/hydration.js";
+ *
+ * const hydration = enableHydration();
+ *
+ * await hydration.whenHydrated();
+ * console.log("hydration complete");
+ * ```
+ *
+ * @example Streaming Declarative Shadow DOM
+ * ```ts
+ * import { enableHydration, StopHydration } from "@lushly-dev/fast-element/hydration.js";
+ *
+ * enableHydration({
+ *     stopHydration: StopHydration.never,
+ * });
+ * ```
+ *
+ * @example Rich hydration mismatch diagnostics
+ * ```ts
+ * import { enableHydration, hydrationDebugger } from "@lushly-dev/fast-element/hydration.js";
+ *
+ * enableHydration({ debugger: hydrationDebugger() });
+ * ```
+ *
+ * @param options - Optional hydration behavior.
+ * @public
+ */
+export declare function enableHydration(options?: HydrationOptions): HydrationController;
+/**
+ * The attribute used to defer hydration of an element.
+ * Retained for intersection observer viewport hydration rendering.
+ * @beta
+ */
+export declare const deferHydrationAttribute = "defer-hydration";

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

@@ -0,0 +1,211 @@
+import { type Constructable } from "../interfaces.js";
+import type { TypeDefinition, TypeRegistry } from "../platform.js";
+import { type ComposableStyles, ElementStyles } from "../styles/element-styles.js";
+import type { ElementViewTemplate } from "../templating/template.js";
+import { type AttributeConfiguration, AttributeDefinition } from "./attributes.js";
+import type { Schema } from "./schema.js";
+export type { TypeDefinition, TypeRegistry };
+/**
+ * Shadow root initialization options.
+ * @public
+ */
+export interface ShadowRootOptions extends ShadowRootInit {
+    /**
+     * A registry that provides the custom elements visible
+     * from within this shadow root.
+     * @beta
+     */
+    registry?: CustomElementRegistry;
+}
+/**
+ * A callback that receives a FASTElementDefinition during element registration.
+ * Extensions are invoked before the element is registered with the platform,
+ * allowing plugins to inspect or act on the resolved definition.
+ * @public
+ */
+export type FASTElementExtension = (definition: FASTElementDefinition, registry: CustomElementRegistry) => void;
+/**
+ * Resolves an element template from a composed definition.
+ * @public
+ */
+export type FASTElementTemplateResolver<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>> = (definition: FASTElementDefinition<TType>) => ElementViewTemplate<InstanceType<TType>> | Promise<ElementViewTemplate<InstanceType<TType>>>;
+/**
+ * Applies extension callbacks to a FAST element definition.
+ * @internal
+ */
+export declare function applyFASTElementExtensions(definition: FASTElementDefinition, registry?: CustomElementRegistry, extensions?: FASTElementExtension[]): void;
+/**
+ * Registers an extension that applies to every subsequently defined FAST element.
+ * @param extension - The extension to register.
+ * @returns A callback that removes the extension registration.
+ * @internal
+ */
+export declare function registerFASTElementExtension(extension: FASTElementExtension): () => void;
+/**
+ * Tracks attribute definitions that were added after the element was already
+ * registered with the platform and therefore are not covered by the browser's
+ * static observedAttributes snapshot.
+ * @internal
+ */
+export declare function trackLateAttributeDefinition(definition: FASTElementDefinition, attribute: AttributeDefinition): void;
+/**
+ * Gets the attribute definitions that were added after platform registration.
+ * @internal
+ */
+export declare function getLateAttributeLookup(definition: FASTElementDefinition): Readonly<Record<string, AttributeDefinition>> | null;
+/**
+ * Resolves the concrete template for a FAST element definition when the
+ * definition was composed with a template resolver.
+ * @internal
+ */
+export declare function resolveFASTElementTemplate<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(definition: FASTElementDefinition<TType>): ElementViewTemplate<InstanceType<TType>> | Promise<ElementViewTemplate<InstanceType<TType>> | undefined> | undefined;
+/**
+ * Indicates whether a definition still has a pending template resolver.
+ * @internal
+ */
+export declare function hasFASTElementTemplateResolver<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(definition: FASTElementDefinition<TType>): boolean;
+/**
+ * Gets any pending template resolution error for a FAST element definition.
+ * @internal
+ */
+export declare function getFASTElementTemplateError<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(definition: FASTElementDefinition<TType>): unknown;
+/**
+ * Sets or clears the template resolution error for a FAST element definition.
+ * @internal
+ */
+export declare function setFASTElementTemplateError<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(definition: FASTElementDefinition<TType>, error?: unknown): void;
+/**
+ * Represents metadata configuration for a custom element.
+ * @public
+ */
+export interface PartialFASTElementDefinition<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>> {
+    /**
+     * The name of the custom element.
+     */
+    readonly name: string;
+    /**
+     * The template, or template resolver, for the custom element.
+     */
+    readonly template?: ElementViewTemplate<InstanceType<TType>> | FASTElementTemplateResolver<TType>;
+    /**
+     * The styles to associate with the custom element.
+     */
+    readonly styles?: ComposableStyles | ComposableStyles[];
+    /**
+     * The custom attributes of the custom element.
+     */
+    readonly attributes?: (AttributeConfiguration | string)[];
+    /**
+     * Options controlling the creation of the custom element's shadow DOM.
+     * @remarks
+     * If not provided, defaults to an open shadow root. Provide null
+     * to render to the associated template to the light DOM instead.
+     */
+    readonly shadowOptions?: Partial<ShadowRootOptions> | null;
+    /**
+     * Options controlling how the custom element is defined with the platform.
+     */
+    readonly elementOptions?: ElementDefinitionOptions;
+    /**
+     * The registry to register this component in by default.
+     * @remarks
+     * If not provided, defaults to the global registry.
+     */
+    readonly registry?: CustomElementRegistry;
+    /**
+     * The optional schema associated with the custom element definition.
+     * Declarative templates assign this automatically during template resolution.
+     * Non-declarative callers can provide one for schema-driven extensions.
+     */
+    readonly schema?: Schema;
+}
+/**
+ * Defines metadata for a FASTElement.
+ * @public
+ */
+export declare class FASTElementDefinition<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>> {
+    private platformDefined;
+    /**
+     * The type this element definition describes.
+     */
+    readonly type: TType;
+    /**
+     * Indicates if this element has been defined in at least one registry.
+     */
+    get isDefined(): boolean;
+    /**
+     * The name of the custom element.
+     */
+    readonly name: string;
+    /**
+     * The custom attributes of the custom element.
+     */
+    readonly attributes: ReadonlyArray<AttributeDefinition>;
+    /**
+     * A map enabling lookup of attribute by associated property name.
+     */
+    readonly propertyLookup: Record<string, AttributeDefinition>;
+    /**
+     * A map enabling lookup of property by associated attribute name.
+     */
+    readonly attributeLookup: Record<string, AttributeDefinition>;
+    /**
+     * The template to render for the custom element.
+     */
+    template?: ElementViewTemplate<InstanceType<TType>>;
+    /**
+     * The styles to associate with the custom element.
+     */
+    readonly styles?: ElementStyles;
+    /**
+     * Options controlling the creation of the custom element's shadow DOM.
+     */
+    shadowOptions?: ShadowRootOptions;
+    /**
+     * Options controlling how the custom element is defined with the platform.
+     */
+    readonly elementOptions: ElementDefinitionOptions;
+    /**
+     * The registry to register this component in by default.
+     */
+    readonly registry: CustomElementRegistry;
+    /**
+     * The optional schema associated with the custom element definition.
+     * Declarative templates assign this automatically during template resolution.
+     * Non-declarative callers can provide one for schema-driven extensions.
+     */
+    schema?: Schema;
+    private constructor();
+    /**
+     * Defines a custom element based on this definition.
+     * @param registry - The element registry to define the element in.
+     * @param extensions - An optional array of extension callbacks to invoke
+     * with this definition before platform registration.
+     * @remarks
+     * This operation is idempotent per registry.
+     */
+    define(registry?: CustomElementRegistry, extensions?: FASTElementExtension[]): this;
+    /**
+     * Creates an instance of FASTElementDefinition.
+     * @param type - The type this definition is being created for.
+     * @param nameOrDef - The name of the element to define or a config object
+     * that describes the element to define.
+     */
+    static compose<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition<TType>): Promise<FASTElementDefinition<TType>>;
+    /**
+     * Registers a FASTElement base type.
+     * @param type - The type to register as a base type.
+     * @internal
+     */
+    static registerBaseType(type: Function): void;
+    /**
+     * Gets the element definition associated with the specified type.
+     * @param type - The custom element type to retrieve the definition for.
+     */
+    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-registry.d.ts

@@ -0,0 +1,23 @@
+import { type TypeRegistry } from "../platform.js";
+import type { FASTElementDefinition } from "./fast-definitions.js";
+/**
+ * The FAST custom element registry.
+ * @public
+ */
+export interface FASTElementRegistry extends TypeRegistry<FASTElementDefinition> {
+    /**
+     * Resolves when a FAST element definition has been registered for the tag name.
+     * @param name - The custom element tag name.
+     * @param registry - The custom element registry to observe.
+     */
+    whenRegistered(name: string, registry?: CustomElementRegistry): Promise<FASTElementDefinition>;
+}
+/**
+ * The FAST custom element registry.
+ * @remarks
+ * This registry stores FAST element definitions by constructor so consumers can
+ * look up the `FASTElementDefinition` associated with an element type, instance,
+ * or registered tag name.
+ * @public
+ */
+export declare const fastElementRegistry: FASTElementRegistry;