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

package/dist/dts/templating/html-binding-directive.d.ts

@@ -0,0 +1,155 @@
+import type { Binding, BindingDirective } from "../binding/binding.js";
+import { DOMAspect } from "../dom.js";
+import type { DOMPolicy } from "../dom-policy.js";
+import { ExecutionContext, type Expression, type ExpressionObserver } from "../observation/observable.js";
+import { type AddViewBehaviorFactory, type Aspected, HTMLDirective, type ViewBehavior, type ViewBehaviorFactory, type ViewController } from "./html-directive.js";
+/**
+ * A simple View that can be interpolated into HTML content.
+ * @public
+ */
+export interface ContentView {
+    readonly context: ExecutionContext;
+    /**
+     * Binds a view's behaviors to its binding source.
+     * @param source - The binding source for the view's binding behaviors.
+     * @param context - The execution context to run the view within.
+     */
+    bind(source: any, context?: ExecutionContext): void;
+    /**
+     * Unbinds a view's behaviors from its binding source and context.
+     */
+    unbind(): void;
+    /**
+     * Inserts the view's DOM nodes before the referenced node.
+     * @param node - The node to insert the view's DOM before.
+     */
+    insertBefore(node: Node): void;
+    /**
+     * Removes the view's DOM nodes.
+     * The nodes are not disposed and the view can later be re-inserted.
+     */
+    remove(): void;
+}
+/**
+ * A simple template that can create ContentView instances.
+ * @public
+ */
+export interface ContentTemplate {
+    /**
+     * Creates a simple content view instance.
+     */
+    create(): ContentView;
+}
+/**
+ * A template capable of hydrating content from existing DOM nodes.
+ * @beta
+ */
+export interface HydratableContentTemplate extends ContentTemplate {
+    /**
+     * Hydrates a content view from first/last nodes.
+     */
+    hydrate(first: Node, last: Node): ContentView;
+}
+/**
+ * The central binding directive that bridges data expressions and DOM updates.
+ *
+ * HTMLBindingDirective fulfills three roles simultaneously:
+ * - **HTMLDirective**: Produces placeholder HTML via createHTML() during template authoring.
+ * - **ViewBehaviorFactory**: Creates behaviors (returns itself) during view creation.
+ * - **ViewBehavior / EventListener**: Attaches to a DOM node during bind, manages
+ *   expression observers for reactive updates, and handles DOM events directly.
+ *
+ * The aspectType (set by HTMLDirective.assignAspect during template processing)
+ * determines which DOM "sink" function is used to apply values — e.g.,
+ * setAttribute for attributes, addEventListener for events, textContent for content.
+ *
+ * @public
+ */
+export declare class HTMLBindingDirective implements HTMLDirective, ViewBehaviorFactory, ViewBehavior, Aspected, BindingDirective {
+    private data;
+    private updateTarget;
+    /**
+     * The unique id of the factory.
+     */
+    id: string;
+    /**
+     * The structural id of the DOM node to which the created behavior will apply.
+     */
+    targetNodeId: string;
+    /**
+     * The tagname associated with the target node.
+     */
+    targetTagName: string | null;
+    /**
+     * The policy that the created behavior must run under.
+     */
+    policy: DOMPolicy;
+    /**
+     * The original source aspect exactly as represented in markup.
+     */
+    sourceAspect: string;
+    /**
+     * The evaluated target aspect, determined after processing the source.
+     */
+    targetAspect: string;
+    /**
+     * The type of aspect to target.
+     */
+    aspectType: DOMAspect;
+    /**
+     * The binding configuration to apply.
+     */
+    dataBinding: Binding;
+    /**
+     * Creates an instance of HTMLBindingDirective.
+     * @param dataBinding - The binding configuration to apply.
+     */
+    constructor(dataBinding: Binding);
+    /**
+     * Creates HTML to be used within a template.
+     * @param add - Can be used to add  behavior factories to a template.
+     */
+    createHTML(add: AddViewBehaviorFactory): string;
+    /**
+     * Creates a behavior.
+     */
+    createBehavior(): ViewBehavior;
+    /**
+     * Attaches this binding to its target DOM node.
+     * - For events: stores the controller reference on the target element and registers
+     *   this directive as the EventListener via addEventListener. The directive's
+     *   handleEvent() method will be called when the event fires.
+     * - For content bindings: registers an unbind handler, then falls through to the
+     *   default path.
+     * - For all non-event bindings: creates (or reuses) an ExpressionObserver, evaluates
+     *   the binding expression, and applies the result to the DOM via the updateTarget
+     *   sink function. The observer will call handleChange() on future data changes.
+     * @internal
+     */
+    bind(controller: ViewController): void;
+    /** @internal */
+    unbind(controller: ViewController): void;
+    /**
+     * Implements the EventListener interface. When a DOM event fires on the target
+     * element, this method retrieves the ViewController stored on the element,
+     * sets the event on the ExecutionContext so `c.event` is available to the
+     * binding expression, and evaluates the expression. If the expression returns
+     * anything other than `true`, the event's default action is prevented.
+     * @internal
+     */
+    handleEvent(event: Event): void;
+    /**
+     * Called by the ExpressionObserver when a tracked dependency changes.
+     * Re-evaluates the binding expression via observer.bind() and pushes
+     * the new value to the DOM through the updateTarget sink function.
+     * This is the reactive update path that keeps the DOM in sync with data.
+     *
+     * Guards against stale notifications: when a view is unbound (e.g., after
+     * a parent `when` directive tears down a child element), coupled-lifetime
+     * observers may still hold active subscriptions. If a property change fires
+     * on the source element while the view is inactive, this guard prevents
+     * the binding expression from evaluating with a null source.
+     * @internal
+     */
+    handleChange(binding: Expression, observer: ExpressionObserver): void;
+}

package/dist/dts/templating/html-directive.d.ts

@@ -0,0 +1,218 @@
+import type { Binding } from "../binding/binding.js";
+import { DOMAspect } from "../dom.js";
+import type { DOMPolicy } from "../dom-policy.js";
+import type { Constructable } from "../interfaces.js";
+import type { ExpressionController } from "../observation/observable.js";
+/**
+ * The target nodes available to a behavior.
+ * @public
+ */
+export type ViewBehaviorTargets = {
+    [id: string]: Node;
+};
+/**
+ * Controls the lifecycle of a view and provides relevant context.
+ * @public
+ */
+export interface ViewController<TSource = any, TParent = any> extends ExpressionController<TSource, TParent> {
+    /**
+     * The parts of the view that are targeted by view behaviors.
+     */
+    readonly targets: ViewBehaviorTargets;
+    /**
+     * When true, directives skip attribute/booleanAttribute DOM
+     * updates during bind(). This is an internal flag set only
+     * during the prerendered bind window.
+     * @internal
+     */
+    readonly _skipAttrUpdates?: boolean;
+    /**
+     * The shadow root whose scoped custom element registry the view's elements
+     * were created against. Directives pass it on when they create child views.
+     * @internal
+     */
+    readonly _scope?: ShadowRoot;
+    /**
+     * Resolves `true` when the view's host element had prerendered
+     * content (existing shadow root).
+     */
+    readonly isPrerendered?: Promise<boolean>;
+    /**
+     * Resolves `true` after prerendered content has been hydrated,
+     * `false` when client-side rendered or hydration not enabled.
+     */
+    readonly isHydrated?: Promise<boolean>;
+}
+/**
+ * Represents an object that can contribute behavior to a view.
+ * @public
+ */
+export interface ViewBehavior<TSource = any, TParent = any> {
+    /**
+     * Bind this behavior.
+     * @param controller - The view controller that manages the lifecycle of this behavior.
+     */
+    bind(controller: ViewController<TSource, TParent>): void;
+}
+/**
+ * A factory that can create a {@link ViewBehavior} associated with a particular
+ * location within a DOM fragment.
+ * @public
+ */
+export interface ViewBehaviorFactory {
+    /**
+     * The unique id of the factory.
+     */
+    id?: string;
+    /**
+     * The structural id of the DOM node to which the created behavior will apply.
+     */
+    targetNodeId?: string;
+    /**
+     * The tag name of the DOM node to which the created behavior will apply.
+     */
+    targetTagName?: string | null;
+    /**
+     * The policy that the created behavior must run under.
+     */
+    policy?: DOMPolicy;
+    /**
+     * Creates a behavior.
+     */
+    createBehavior(): ViewBehavior;
+}
+/**
+ * Represents a ViewBehaviorFactory after the compilation process has completed.
+ * @public
+ */
+export type CompiledViewBehaviorFactory = Required<ViewBehaviorFactory>;
+/**
+ * Used to add behavior factories when constructing templates.
+ * @public
+ */
+export type AddViewBehaviorFactory = (factory: ViewBehaviorFactory) => string;
+/**
+ * Instructs the template engine to apply behavior to a node.
+ * @public
+ */
+export interface HTMLDirective {
+    /**
+     * Creates HTML to be used within a template.
+     * @param add - Can be used to add  behavior factories to a template.
+     */
+    createHTML(add: AddViewBehaviorFactory): string;
+}
+/**
+ * Represents something that applies to a specific aspect of the DOM.
+ * @public
+ */
+export interface Aspected {
+    /**
+     * The original source aspect exactly as represented in markup.
+     */
+    sourceAspect: string;
+    /**
+     * The evaluated target aspect, determined after processing the source.
+     */
+    targetAspect: string;
+    /**
+     * The type of aspect to target.
+     */
+    aspectType: DOMAspect;
+    /**
+     * A binding if one is associated with the aspect.
+     */
+    dataBinding?: Binding;
+}
+/**
+ * Represents metadata configuration for an HTMLDirective.
+ * @public
+ */
+export interface PartialHTMLDirectiveDefinition {
+    /**
+     * Indicates whether the directive needs access to template contextual information
+     * such as the sourceAspect, targetAspect, and aspectType.
+     */
+    aspected?: boolean;
+}
+/**
+ * Defines metadata for an HTMLDirective.
+ * @public
+ */
+export interface HTMLDirectiveDefinition<TType extends Constructable<HTMLDirective> = Constructable<HTMLDirective>> extends Required<PartialHTMLDirectiveDefinition> {
+    /**
+     * The type that the definition provides metadata for.
+     */
+    readonly type: TType;
+}
+/**
+ * Instructs the template engine to apply behavior to a node.
+ * @public
+ */
+export declare const HTMLDirective: Readonly<{
+    /**
+     * Gets the directive definition associated with the instance.
+     * @param instance - The directive instance to retrieve the definition for.
+     */
+    getForInstance: (object: any) => HTMLDirectiveDefinition<Constructable<HTMLDirective>> | undefined;
+    /**
+     * Gets the directive definition associated with the specified type.
+     * @param type - The directive type to retrieve the definition for.
+     */
+    getByType: (key: Function) => HTMLDirectiveDefinition<Constructable<HTMLDirective>> | undefined;
+    /**
+     * Defines an HTMLDirective based on the options.
+     * @param type - The type to define as a directive.
+     * @param options - Options that specify the directive's application.
+     */
+    define<TType extends Constructable<HTMLDirective>>(type: TType, options?: PartialHTMLDirectiveDefinition): TType;
+    /**
+     * Determines the DOM aspect type for a directive based on attribute name prefix.
+     * The prefix convention maps to aspect types as follows:
+     *   - No prefix (e.g. "class")  → DOMAspect.attribute
+     *   - ":" prefix (e.g. ":value") → DOMAspect.property (":classList" → DOMAspect.tokenList)
+     *   - "?" prefix (e.g. "?disabled") → DOMAspect.booleanAttribute
+     *   - `@` prefix (e.g. `@click`) → DOMAspect.event
+     *   - Falsy or absent value → DOMAspect.content (see remarks)
+     * @param directive - The directive to assign the aspect to.
+     * @param value - The value to base the aspect determination on.
+     * @remarks
+     * If a falsy value is provided, then the content aspect will be assigned.
+     */
+    assignAspect(directive: Aspected, value?: string): void;
+}>;
+/**
+ * Decorator: Defines an HTMLDirective.
+ * @param options - Provides options that specify the directive's application.
+ * @public
+ */
+export declare function htmlDirective(options?: PartialHTMLDirectiveDefinition): (type: Constructable<HTMLDirective>) => void;
+/**
+ * A base class used for attribute directives that don't need internal state.
+ * @public
+ */
+export declare abstract class StatelessAttachedAttributeDirective<TOptions> implements HTMLDirective, ViewBehaviorFactory, ViewBehavior {
+    protected options: TOptions;
+    /**
+     * Creates an instance of RefDirective.
+     * @param options - The options to use in configuring the directive.
+     */
+    constructor(options: TOptions);
+    /**
+     * Creates a placeholder string based on the directive's index within the template.
+     * @param index - The index of the directive within the template.
+     * @remarks
+     * Creates a custom attribute placeholder.
+     */
+    createHTML(add: AddViewBehaviorFactory): string;
+    /**
+     * Creates a behavior.
+     * @param targets - The targets available for behaviors to be attached to.
+     */
+    createBehavior(): ViewBehavior;
+    /**
+     * Bind this behavior.
+     * @param controller - The view controller that manages the lifecycle of this behavior.
+     */
+    abstract bind(controller: ViewController): void;
+}

package/dist/dts/templating/html.d.ts

@@ -0,0 +1 @@
+export { html } from "./template.js";

package/dist/dts/templating/hydration-view.d.ts

@@ -0,0 +1,130 @@
+import { Hydratable } from "../components/hydration.js";
+import { type HydrationMismatchActual, type HydrationMismatchExpectation } from "../hydration/diagnostics.js";
+import { type ViewBehaviorBoundaries } from "../hydration/target-builder.js";
+import { type ExecutionContext, SourceLifetime } from "../observation/observable.js";
+import type { ViewTemplate } from "../templating/template.js";
+import type { ViewBehaviorFactory, ViewBehaviorTargets, ViewController } from "./html-directive.js";
+import { DefaultExecutionContext, type ElementView, type SyntheticView } from "./view.js";
+/** @public */
+export interface HydratableView<TSource = any, TParent = any> extends ElementView<TSource, TParent>, SyntheticView<TSource, TParent>, DefaultExecutionContext<TParent> {
+    [Hydratable]: symbol;
+    readonly bindingViewBoundaries: Record<string, ViewNodes>;
+    readonly hydrationStage: keyof typeof HydrationStage;
+}
+/**
+ * A view controller that can hydrate existing DOM nodes.
+ * @beta
+ */
+export type HydratableViewController<TSource = any, TParent = any> = HydratableView<TSource, TParent> & ViewController<TSource, TParent>;
+/** @public */
+export interface ViewNodes {
+    first: Node;
+    last: Node;
+}
+/** @public */
+export declare const HydrationStage: {
+    readonly unhydrated: "unhydrated";
+    readonly hydrating: "hydrating";
+    readonly hydrated: "hydrated";
+};
+/** @public */
+export declare class HydrationBindingError extends Error {
+    /**
+     * The factory that was unable to be bound
+     */
+    readonly factory: ViewBehaviorFactory;
+    /**
+     * A DocumentFragment containing a clone of the
+     * view's Nodes.
+     */
+    readonly fragment: DocumentFragment;
+    /**
+     * String representation of the HTML in the template that
+     * threw the binding error.
+     */
+    readonly templateString: string;
+    /**
+     * Structured description of the binding the hydration walk was
+     * attempting to apply when the mismatch was detected.
+     */
+    readonly expected?: HydrationMismatchExpectation | undefined;
+    /**
+     * Structured description of the server-rendered DOM that was
+     * encountered at the mismatch point.
+     */
+    readonly received?: HydrationMismatchActual | undefined;
+    constructor(
+    /**
+     * The error message
+     */
+    message: string | undefined, 
+    /**
+     * The factory that was unable to be bound
+     */
+    factory: ViewBehaviorFactory, 
+    /**
+     * A DocumentFragment containing a clone of the
+     * view's Nodes.
+     */
+    fragment: DocumentFragment, 
+    /**
+     * String representation of the HTML in the template that
+     * threw the binding error.
+     */
+    templateString: string, 
+    /**
+     * Structured description of the binding the hydration walk was
+     * attempting to apply when the mismatch was detected.
+     */
+    expected?: HydrationMismatchExpectation | undefined, 
+    /**
+     * Structured description of the server-rendered DOM that was
+     * encountered at the mismatch point.
+     */
+    received?: HydrationMismatchActual | undefined);
+}
+export declare class HydrationView<TSource = any, TParent = any> extends DefaultExecutionContext<TParent> implements HydratableView {
+    readonly firstChild: Node;
+    readonly lastChild: Node;
+    private sourceTemplate;
+    private hostBindingTarget?;
+    [Hydratable]: symbol;
+    context: ExecutionContext<any>;
+    source: TSource | null;
+    isBound: boolean;
+    get hydrationStage(): "hydrated" | "hydrating" | "unhydrated";
+    get targets(): ViewBehaviorTargets;
+    get bindingViewBoundaries(): ViewBehaviorBoundaries;
+    readonly sourceLifetime: SourceLifetime;
+    private unbindables;
+    private fragment;
+    private behaviors;
+    private factories;
+    private _hydrationStage;
+    private _bindingViewBoundaries;
+    private _targets;
+    constructor(firstChild: Node, lastChild: Node, sourceTemplate: ViewTemplate, hostBindingTarget?: Element | undefined);
+    /**
+     * no-op. Hydrated views are don't need to be moved from a documentFragment
+     * to the target node.
+     */
+    insertBefore(node: Node): void;
+    /**
+     * Appends the view to a node. In cases where this is called before the
+     * view has been removed, the method will no-op.
+     * @param node - the node to append the view to.
+     */
+    appendTo(node: Node): void;
+    remove(): void;
+    bind(source: TSource, context?: ExecutionContext<any>): void;
+    unbind(): void;
+    /**
+     * Removes the view and unbinds its behaviors, disposing of DOM nodes afterward.
+     * Once a view has been disposed, it cannot be inserted or bound again.
+     */
+    dispose(): void;
+    onUnbind(behavior: {
+        unbind(controller: ViewController<TSource, TParent>): void;
+    }): void;
+    private evaluateUnbindables;
+}

package/dist/dts/templating/markup.d.ts

@@ -0,0 +1,48 @@
+import type { ViewBehaviorFactory } from "./html-directive.js";
+/** @internal */
+export declare const nextId: () => string;
+/**
+ * Common APIs related to markup generation.
+ * @public
+ */
+export declare const Markup: Readonly<{
+    /**
+     * Creates a placeholder string suitable for marking out a location *within*
+     * an attribute value or HTML content.
+     * @param index - The directive index to create the placeholder for.
+     * @remarks
+     * Used internally by binding directives.
+     */
+    interpolation: (id: string) => string;
+    /**
+     * Creates a placeholder that manifests itself as an attribute on an
+     * element.
+     * @param attributeName - The name of the custom attribute.
+     * @param index - The directive index to create the placeholder for.
+     * @remarks
+     * Used internally by attribute directives such as `ref`, `slotted`, and `children`.
+     */
+    attribute: (id: string) => string;
+    /**
+     * Creates a placeholder that manifests itself as a marker within the DOM structure.
+     * @param index - The directive index to create the placeholder for.
+     * @remarks
+     * Used internally by structural directives such as `repeat`.
+     */
+    comment: (id: string) => string;
+}>;
+/**
+ * Common APIs related to content parsing.
+ * @public
+ */
+export declare const Parser: Readonly<{
+    /**
+     * Parses text content or HTML attribute content, separating out the static strings
+     * from the directives.
+     * @param value - The content or attribute string to parse.
+     * @param factories - A list of directives to search for in the string.
+     * @returns A heterogeneous array of static strings interspersed with
+     * directives or null if no directives are found in the string.
+     */
+    parse(value: string, factories: Record<string, ViewBehaviorFactory>): (string | ViewBehaviorFactory)[] | null;
+}>;

package/dist/dts/templating/node-observation.d.ts

@@ -0,0 +1,99 @@
+import { StatelessAttachedAttributeDirective, type ViewController } from "./html-directive.js";
+/**
+ * Options for configuring node observation behavior.
+ * @public
+ */
+export interface NodeBehaviorOptions<T = any> {
+    /**
+     * The property to assign the observed nodes to.
+     */
+    property: T;
+    /**
+     * Filters nodes that are synced with the property.
+     * Called one time for each element in the array.
+     * @param value - The Node that is being inspected.
+     * @param index - The index of the node within the array.
+     * @param array - The Node array that is being filtered.
+     */
+    filter?: ElementsFilter;
+}
+/**
+ * Elements filter function type.
+ *
+ * @public
+ */
+export type ElementsFilter = (value: Node, index?: number, array?: Node[]) => boolean;
+/**
+ * Creates a function that can be used to filter a Node array, selecting only elements.
+ * @param selector - An optional selector to restrict the filter to.
+ * @public
+ */
+export declare const elements: (selector?: string) => ElementsFilter;
+/**
+ * A base class for node observation.
+ * @public
+ * @remarks
+ * Internally used by the SlottedDirective and the ChildrenDirective.
+ */
+export declare abstract class NodeObservationDirective<T extends NodeBehaviorOptions> extends StatelessAttachedAttributeDirective<T> {
+    private _id;
+    private _controllerProperty;
+    /**
+     * The unique id of the factory.
+     */
+    get id(): string;
+    set id(value: string);
+    /**
+     * The structural id of the DOM node to which the created behavior will apply.
+     */
+    targetNodeId: string;
+    /**
+     * Bind this behavior to the source.
+     * @param source - The source to bind to.
+     * @param context - The execution context that the binding is operating within.
+     * @param targets - The targets that behaviors in a view can attach to.
+     */
+    bind(controller: ViewController): void;
+    /**
+     * Unbinds this behavior from the source.
+     * @param source - The source to unbind from.
+     * @param context - The execution context that the binding is operating within.
+     * @param targets - The targets that behaviors in a view can attach to.
+     */
+    unbind(controller: ViewController): void;
+    /**
+     * Gets the data source for the target.
+     * @param target - The target to get the source for.
+     * @returns The source.
+     */
+    protected getSource(target: Node): any;
+    /**
+     * Updates the source property with the computed nodes.
+     * @param source - The source object to assign the nodes property to.
+     * @param value - The nodes to assign to the source object property.
+     */
+    protected updateTarget(source: any, value: ReadonlyArray<any>): void;
+    /**
+     * Computes the set of nodes that should be assigned to the source property.
+     * @param target - The target to compute the nodes for.
+     * @returns The computed nodes.
+     * @remarks
+     * Applies filters if provided.
+     */
+    protected computeNodes(target: any): Node[];
+    /**
+     * Begins observation of the nodes.
+     * @param target - The target to observe.
+     */
+    protected abstract observe(target: any): void;
+    /**
+     * Disconnects observation of the nodes.
+     * @param target - The target to unobserve.
+     */
+    protected abstract disconnect(target: any): void;
+    /**
+     * Retrieves the raw nodes that should be assigned to the source property.
+     * @param target - The target to get the node to.
+     */
+    protected abstract getNodes(target: any): Node[];
+}

package/dist/dts/templating/ref.d.ts

@@ -0,0 +1,23 @@
+import { StatelessAttachedAttributeDirective, type ViewController } from "./html-directive.js";
+import type { CaptureType } from "./template.js";
+/**
+ * The runtime behavior for template references.
+ * @public
+ */
+export declare class RefDirective extends StatelessAttachedAttributeDirective<string> {
+    /**
+     * The structural id of the DOM node to which the created behavior will apply.
+     */
+    targetNodeId: string;
+    /**
+     * Bind this behavior.
+     * @param controller - The view controller that manages the lifecycle of this behavior.
+     */
+    bind(controller: ViewController): void;
+}
+/**
+ * A directive that observes the updates a property with a reference to the element.
+ * @param propertyName - The name of the property to assign the reference to.
+ * @public
+ */
+export declare const ref: <TSource = any, TParent = any>(propertyName: keyof TSource & string) => CaptureType<TSource, TParent>;