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

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

@@ -0,0 +1,221 @@
+import { Binding } from "../binding/binding.js";
+import type { DOMPolicy } from "../dom-policy.js";
+import type { Expression } from "../observation/observable.js";
+import { type AddViewBehaviorFactory, type CompiledViewBehaviorFactory, HTMLDirective, type ViewBehaviorFactory } from "./html-directive.js";
+import type { ElementView, HTMLView, SyntheticView } from "./view.js";
+/**
+ * A template capable of creating views specifically for rendering custom elements.
+ * @public
+ */
+export interface ElementViewTemplate<TSource = any, TParent = any> {
+    /**
+     * Creates an ElementView instance based on this template definition.
+     * @param hostBindingTarget - The element that host behaviors will be bound to.
+     * @param scope - The shadow root whose scoped custom element registry child
+     * elements should be created against, when it has one.
+     */
+    create(hostBindingTarget: Element, scope?: ShadowRoot): ElementView<TSource, TParent>;
+    /**
+     * Creates an HTMLView from this template, binds it to the source, and then appends it to the host.
+     * @param source - The data source to bind the template to.
+     * @param host - The Element where the template will be rendered.
+     * @param hostBindingTarget - An HTML element to target the host bindings at if different from the
+     * host that the template is being attached to.
+     * @param scope - The shadow root whose scoped custom element registry child
+     * elements should be created against, when it has one.
+     */
+    render(source: TSource, host: Node, hostBindingTarget?: Element, scope?: ShadowRoot): ElementView<TSource, TParent>;
+}
+/**
+ * A template capable of hydrating an element view from existing DOM nodes.
+ * @beta
+ */
+export interface HydratableElementViewTemplate<TSource = any, TParent = any> extends ElementViewTemplate<TSource, TParent> {
+    hydrate(firstChild: Node, lastChild: Node, hostBindingTarget?: Element): ElementView<TSource, TParent>;
+}
+/**
+ * A marker interface used to capture types when interpolating Directive helpers
+ * into templates.
+ * @public
+ */
+export interface CaptureType<TSource = any, TParent = any> {
+}
+/**
+ * A template capable of rendering views not specifically connected to custom elements.
+ * @public
+ */
+export interface SyntheticViewTemplate<TSource = any, TParent = any> {
+    /**
+     * Creates a SyntheticView instance based on this template definition.
+     */
+    create(): SyntheticView<TSource, TParent>;
+    /**
+     * Returns a directive that can inline the template.
+     */
+    inline(): CaptureType<TSource, TParent>;
+}
+/**
+ * A template capable of hydrating a synthetic view from existing DOM nodes.
+ * @beta
+ */
+export interface HydratableSyntheticViewTemplate<TSource = any, TParent = any> extends SyntheticViewTemplate {
+    hydrate(firstChild: Node, lastChild: Node): SyntheticView<TSource, TParent>;
+}
+/**
+ * The result of a template compilation operation.
+ * @public
+ */
+export interface HTMLTemplateCompilationResult<TSource = any, TParent = any> {
+    /**
+     * Creates a view instance.
+     * @param hostBindingTarget - The host binding target for the view.
+     * @param scope - The shadow root whose scoped custom element registry the view's
+     * elements should be created against, when it has one.
+     */
+    createView(hostBindingTarget?: Element, scope?: ShadowRoot): HTMLView<TSource, TParent>;
+    readonly factories: CompiledViewBehaviorFactory[];
+}
+/**
+ * Represents the types of values that can be interpolated into a template.
+ * @public
+ */
+export type TemplateValue<TSource, TParent = any> = Expression<TSource, any, TParent> | Binding<TSource, any, TParent> | HTMLDirective | CaptureType<TSource, TParent>;
+/**
+ * Inlines a template into another template.
+ * @public
+ */
+export declare class InlineTemplateDirective implements HTMLDirective {
+    private html;
+    private factories;
+    /**
+     * An empty template partial.
+     */
+    static readonly empty: InlineTemplateDirective;
+    /**
+     * Creates an instance of InlineTemplateDirective.
+     * @param template - The template to inline.
+     */
+    constructor(html: string, factories?: Record<string, ViewBehaviorFactory>);
+    /**
+     * Creates HTML to be used within a template.
+     * @param add - Can be used to add  behavior factories to a template.
+     */
+    createHTML(add: AddViewBehaviorFactory): string;
+}
+/**
+ * A template capable of creating HTMLView instances or rendering directly to DOM.
+ * @public
+ */
+export declare class ViewTemplate<TSource = any, TParent = any> implements ElementViewTemplate<TSource, TParent>, SyntheticViewTemplate<TSource, TParent> {
+    private policy?;
+    private result;
+    /**
+     * The html representing what this template will
+     * instantiate, including placeholders for directives.
+     */
+    readonly html: string | HTMLTemplateElement;
+    /**
+     * The directives that will be connected to placeholders in the html.
+     */
+    readonly factories: Record<string, ViewBehaviorFactory>;
+    /**
+     * Creates an instance of ViewTemplate.
+     * @param html - The html representing what this template will instantiate, including placeholders for directives.
+     * @param factories - The directives that will be connected to placeholders in the html.
+     * @param policy - The security policy to use when compiling this template.
+     */
+    constructor(html: string | HTMLTemplateElement, factories?: Record<string, ViewBehaviorFactory>, policy?: DOMPolicy | undefined);
+    /**
+     * @internal
+     */
+    compile(): HTMLTemplateCompilationResult<TSource, TParent>;
+    /**
+     * Returns a directive that can inline the template.
+     */
+    inline(): CaptureType<TSource, TParent>;
+    /**
+     * Sets the DOMPolicy for this template.
+     * @param policy - The policy to associated with this template.
+     * @returns The modified template instance.
+     * @remarks
+     * The DOMPolicy can only be set once for a template and cannot be
+     * set after the template is compiled.
+     */
+    withPolicy(policy: DOMPolicy): this;
+    /**
+     * Creates an HTMLView from this template, binds it to the source, and then appends it to the host.
+     * @param source - The data source to bind the template to.
+     * @param host - The Element where the template will be rendered.
+     * @param hostBindingTarget - An HTML element to target the host bindings at if different from the
+     * host that the template is being attached to.
+     * @param scope - The shadow root whose scoped custom element registry child
+     * elements should be created against, when it has one.
+     */
+    render(source: TSource, host: Node, hostBindingTarget?: Element, scope?: ShadowRoot): HTMLView<TSource, TParent>;
+    /**
+     * Creates an HTMLView instance based on this template definition.
+     * @param hostBindingTarget - The element that host behaviors will be bound to.
+     * @param scope - The shadow root whose scoped custom element registry child
+     * elements should be created against, when it has one.
+     */
+    create(hostBindingTarget?: Element, scope?: ShadowRoot): HTMLView<TSource, TParent>;
+    /**
+     * Processes the tagged template literal's static strings and interpolated values and
+     * creates a ViewTemplate.
+     *
+     * For each interpolated value:
+     * 1. Functions (binding expressions, e.g., `x => x.name`) → wrapped in a one-way HTMLBindingDirective
+     * 2. Binding instances → wrapped in an HTMLBindingDirective
+     * 3. HTMLDirective instances → used as-is
+     * 4. Static values (strings, numbers) → wrapped in a one-time HTMLBindingDirective
+     *
+     * Each directive's createHTML() is called with an `add` callback that registers
+     * the factory in the factories record under a unique ID and returns that ID.
+     * The directive inserts a placeholder marker (e.g., `fast-abc123{0}fast-abc123`) into
+     * the HTML string so the compiler can later find and associate it with the factory.
+     *
+     * Aspect detection happens here too: the `lastAttributeNameRegex` checks whether
+     * the placeholder appears inside an attribute value, and if so, assignAspect()
+     * sets the correct DOMAspect (attribute, property, event, etc.) based on the
+     * attribute name prefix.
+     *
+     * @param strings - The static strings to create the template with.
+     * @param values - The dynamic values to create the template with.
+     * @param policy - The DOMPolicy to associated with the template.
+     * @returns A ViewTemplate.
+     * @remarks
+     * This API should not be used directly under normal circumstances because constructing
+     * a template in this way, if not done properly, can open up the application to XSS
+     * attacks. When using this API, provide a strong DOMPolicy that can properly sanitize
+     * and also be sure to manually sanitize all static strings particularly if they can
+     * come from user input.
+     */
+    static create<TSource = any, TParent = any>(strings: string[], values: TemplateValue<TSource, TParent>[], policy?: DOMPolicy): ViewTemplate<TSource, TParent>;
+}
+/**
+ * Transforms a template literal string into a ViewTemplate.
+ * @param strings - The string fragments that are interpolated with the values.
+ * @param values - The values that are interpolated with the string fragments.
+ * @remarks
+ * The html helper supports interpolation of strings, numbers, binding expressions,
+ * other template instances, and Directive instances.
+ * @public
+ */
+export type HTMLTemplateTag = (<TSource = any, TParent = any>(strings: TemplateStringsArray, ...values: TemplateValue<TSource, TParent>[]) => ViewTemplate<TSource, TParent>) & {
+    /**
+     * Transforms a template literal string into partial HTML.
+     * @param html - The HTML string fragment to interpolate.
+     * @public
+     */
+    partial(html: string): InlineTemplateDirective;
+};
+/**
+ * Transforms a template literal string into a ViewTemplate.
+ * @param strings - The string fragments that are interpolated with the values.
+ * @param values - The values that are interpolated with the string fragments.
+ * @remarks
+ * The html helper supports interpolation of strings, numbers, binding expressions,
+ * other template instances, and Directive instances.
+ * @public
+ */
+export declare const html: HTMLTemplateTag;

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

@@ -0,0 +1,268 @@
+import type { Disposable } from "../interfaces.js";
+import { ExecutionContext, SourceLifetime } from "../observation/observable.js";
+import type { CompiledViewBehaviorFactory, ViewBehaviorTargets, ViewController } from "./html-directive.js";
+/**
+ * Represents a collection of DOM nodes which can be bound to a data source.
+ * @public
+ */
+export interface View<TSource = any, TParent = any> extends Disposable {
+    /**
+     * The execution context the view is running within.
+     */
+    readonly context: ExecutionContext<TParent>;
+    /**
+     * The data that the view is bound to.
+     */
+    readonly source: TSource | null;
+    /**
+     * Indicates whether the controller is bound.
+     */
+    readonly isBound: boolean;
+    /**
+     * Binds a view's behaviors to its binding source.
+     * @param source - The binding source for the view's binding behaviors.
+     */
+    bind(source: TSource, context?: ExecutionContext<TParent>): void;
+    /**
+     * Unbinds a view's behaviors from its binding source and context.
+     */
+    unbind(): void;
+}
+/**
+ * A View representing DOM nodes specifically for rendering the view of a custom element.
+ * @public
+ */
+export interface ElementView<TSource = any, TParent = any> extends View<TSource, TParent> {
+    /**
+     * Indicates how the source's lifetime relates to the controller's lifetime.
+     */
+    readonly sourceLifetime?: SourceLifetime;
+    /**
+     * Registers an unbind handler with the controller.
+     * @param behavior - An object to call when the controller unbinds.
+     */
+    onUnbind(behavior: {
+        unbind(controller: ViewController<TSource, TParent>): any;
+    }): void;
+    /**
+     * Appends the view's DOM nodes to the referenced node.
+     * @param node - The parent node to append the view's DOM nodes to.
+     */
+    appendTo(node: Node): void;
+}
+/**
+ * A view representing a range of DOM nodes which can be added/removed ad hoc.
+ * @public
+ */
+export interface SyntheticView<TSource = any, TParent = any> extends View<TSource, TParent> {
+    /**
+     * The first DOM node in the range of nodes that make up the view.
+     */
+    readonly firstChild: Node;
+    /**
+     * The last DOM node in the range of nodes that make up the view.
+     */
+    readonly lastChild: Node;
+    /**
+     * 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;
+}
+/**
+ * Creates a child view from a template on behalf of a directive, carrying over the
+ * scoped custom element registry scope of the parent view (if it has one).
+ * For views without a scope this is exactly `template.create()`.
+ * @internal
+ */
+export declare function createChildView<TView>(template: {
+    create(): TView;
+}, controller: {
+    readonly _scope?: ShadowRoot;
+}): TView;
+export declare function removeNodeSequence(firstNode: Node, lastNode: Node): void;
+/**
+ * The default execution context for template views.
+ * @public
+ */
+export declare class DefaultExecutionContext<TParent> implements ExecutionContext<TParent> {
+    /**
+     * The index of the current item within a repeat context.
+     */
+    index: number;
+    /**
+     * The length of the current collection within a repeat context.
+     */
+    length: number;
+    /**
+     * The parent data source within a nested context.
+     */
+    readonly parent: TParent;
+    /**
+     * The parent execution context when in nested context scenarios.
+     */
+    readonly parentContext: ExecutionContext<TParent>;
+    /**
+     * The current event within an event handler.
+     */
+    get event(): Event;
+    /**
+     * Indicates whether the current item within a repeat context
+     * has an even index.
+     */
+    get isEven(): boolean;
+    /**
+     * Indicates whether the current item within a repeat context
+     * has an odd index.
+     */
+    get isOdd(): boolean;
+    /**
+     * Indicates whether the current item within a repeat context
+     * is the first item in the collection.
+     */
+    get isFirst(): boolean;
+    /**
+     * Indicates whether the current item within a repeat context
+     * is somewhere in the middle of the collection.
+     */
+    get isInMiddle(): boolean;
+    /**
+     * Indicates whether the current item within a repeat context
+     * is the last item in the collection.
+     */
+    get isLast(): boolean;
+    /**
+     * Returns the typed event detail of a custom event.
+     */
+    eventDetail<TDetail>(): TDetail;
+    /**
+     * Returns the typed event target of the event.
+     */
+    eventTarget<TTarget extends EventTarget>(): TTarget;
+}
+/**
+ * The standard View implementation, which also implements ElementView and SyntheticView.
+ * @public
+ */
+export declare class HTMLView<TSource = any, TParent = any> extends DefaultExecutionContext<TParent> implements ElementView<TSource, TParent>, SyntheticView<TSource, TParent>, ExecutionContext<TParent> {
+    private fragment;
+    private factories;
+    readonly targets: ViewBehaviorTargets;
+    /**
+     * The shadow root whose scoped custom element registry this view's
+     * elements were created against, if any. Child views inherit it.
+     * @internal
+     */
+    readonly _scope?: ShadowRoot | undefined;
+    private behaviors;
+    private unbindables;
+    /**
+     * The data that the view is bound to.
+     */
+    source: TSource | null;
+    /**
+     * Indicates whether the controller is bound.
+     */
+    isBound: boolean;
+    /**
+     * Indicates how the source's lifetime relates to the controller's lifetime.
+     */
+    readonly sourceLifetime: SourceLifetime;
+    /**
+     * When true, directives skip attribute/booleanAttribute DOM
+     * updates during bind(). Set only during the prerendered bind
+     * window and cleared immediately after.
+     * @internal
+     */
+    _skipAttrUpdates: boolean;
+    /**
+     * A promise that resolves with `true` after prerendered content
+     * has been hydrated, or `false` when the view is client-side
+     * rendered. Resolves once the first bind completes.
+     */
+    isPrerendered: Promise<boolean>;
+    /**
+     * Resolves `true` after prerendered content has been hydrated,
+     * `false` when client-side rendered or hydration not enabled.
+     */
+    isHydrated: Promise<boolean>;
+    /**
+     * The execution context the view is running within.
+     */
+    context: ExecutionContext<TParent>;
+    /**
+     * The first DOM node in the range of nodes that make up the view.
+     */
+    firstChild: Node;
+    /**
+     * The last DOM node in the range of nodes that make up the view.
+     */
+    lastChild: Node;
+    /**
+     * Constructs an instance of HTMLView.
+     * @param fragment - The html fragment that contains the nodes for this view.
+     * @param behaviors - The behaviors to be applied to this view.
+     */
+    constructor(fragment: DocumentFragment, factories: ReadonlyArray<CompiledViewBehaviorFactory>, targets: ViewBehaviorTargets, 
+    /**
+     * The shadow root whose scoped custom element registry this view's
+     * elements were created against, if any. Child views inherit it.
+     * @internal
+     */
+    _scope?: ShadowRoot | undefined);
+    /**
+     * Appends the view's DOM nodes to the referenced node.
+     * @param node - The parent node to append the view's DOM nodes to.
+     */
+    appendTo(node: Node): 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;
+    /**
+     * 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;
+    /**
+     * Binds a view's behaviors to its binding source.
+     *
+     * On the first call, this iterates through all compiled factories, calling
+     * createBehavior() on each to produce a ViewBehavior instance (e.g., an
+     * HTMLBindingDirective), and then immediately binds it. This is where event
+     * listeners are registered, expression observers are created, and initial
+     * DOM values are set.
+     *
+     * On subsequent calls with a new source, existing behaviors are re-bound
+     * to the new data source, which re-evaluates all binding expressions and
+     * updates the DOM accordingly.
+     *
+     * @param source - The binding source for the view's binding behaviors.
+     * @param context - The execution context to run the behaviors within.
+     */
+    bind(source: TSource, context?: ExecutionContext<TParent>): void;
+    /**
+     * Unbinds a view's behaviors from its binding source.
+     */
+    unbind(): void;
+    private evaluateUnbindables;
+    /**
+     * Efficiently disposes of a contiguous range of synthetic view instances.
+     * @param views - A contiguous range of views to be disposed.
+     */
+    static disposeContiguousBatch(views: SyntheticView[]): void;
+}

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

@@ -0,0 +1,12 @@
+import type { Expression } from "../observation/observable.js";
+import type { CaptureType, SyntheticViewTemplate } from "./template.js";
+/**
+ * A directive that enables basic conditional rendering in a template.
+ * @param condition - The condition to test for rendering.
+ * @param templateOrTemplateBinding - The template or a binding that gets
+ * the template to render when the condition is true.
+ * @param elseTemplateOrTemplateBinding - Optional template or binding that that
+ * gets the template to render when the conditional is false.
+ * @public
+ */
+export declare function when<TSource = any, TReturn = any, TParent = any>(condition: Expression<TSource, TReturn, TParent> | boolean, templateOrTemplateBinding: SyntheticViewTemplate<TSource, TParent> | Expression<TSource, SyntheticViewTemplate<TSource, TParent>, TParent>, elseTemplateOrTemplateBinding?: SyntheticViewTemplate<TSource, TParent> | Expression<TSource, SyntheticViewTemplate<TSource, TParent>, TParent>): CaptureType<TSource, TParent>;

package/dist/dts/testing/exports.d.ts

@@ -0,0 +1,3 @@
+export * from "./fakes.js";
+export * from "./fixture.js";
+export { timeout } from "./timeout.js";

package/dist/dts/testing/fakes.d.ts

@@ -0,0 +1,15 @@
+import { ExecutionContext } from "../observation/observable.js";
+import type { ViewBehavior, ViewBehaviorTargets } from "../templating/html-directive.js";
+export declare const Fake: Readonly<{
+    executionContext<TParent = any>(parent?: TParent, parentContext?: ExecutionContext<TParent>): ExecutionContext<TParent>;
+    viewController<TSource = any, TParent = any>(targets?: ViewBehaviorTargets, ...behaviors: ViewBehavior<TSource, TParent>[]): {
+        isBound: boolean;
+        context: ExecutionContext<TParent>;
+        onUnbind(object: any): void;
+        source: TSource;
+        targets: ViewBehaviorTargets;
+        toJSON: () => undefined;
+        bind(source: TSource, context?: ExecutionContext<TParent>): void;
+        unbind(): void;
+    };
+}>;

package/dist/dts/testing/fixture.d.ts

@@ -0,0 +1,84 @@
+import type { Constructable } from "../interfaces.js";
+import { ViewTemplate } from "../templating/template.js";
+import type { HTMLView } from "../templating/view.js";
+/**
+ * Options used to customize the creation of the test fixture.
+ * @public
+ */
+export interface FixtureOptions {
+    /**
+     * The document to run the fixture in.
+     * @defaultValue `globalThis.document`
+     */
+    document?: Document;
+    /**
+     * The parent element to append the fixture to.
+     * @defaultValue An instance of `HTMLDivElement`.
+     */
+    parent?: HTMLElement;
+    /**
+     * The data source to bind the HTML to.
+     * @defaultValue An empty object.
+     */
+    source?: any;
+}
+/**
+ * A test fixture.
+ * @public
+ */
+export interface Fixture<TElement = HTMLElement> {
+    /**
+     * The document the fixture is running in.
+     */
+    document: Document;
+    /**
+     * The template the fixture was created from.
+     */
+    template: ViewTemplate;
+    /**
+     * The view that was created from the fixture's template.
+     */
+    view: HTMLView;
+    /**
+     * The parent element that the view was appended to.
+     * @remarks
+     * This element will be appended to the DOM only
+     * after {@link Fixture.connect} has been called.
+     */
+    parent: HTMLElement;
+    /**
+     * The first element in the {@link Fixture.view}.
+     */
+    element: TElement;
+    /**
+     * Adds the {@link Fixture.parent} to the DOM, causing the
+     * connect lifecycle to begin.
+     * @remarks
+     * Yields control to the caller one Microtask later, in order to
+     * ensure that the DOM has settled.
+     */
+    connect: () => Promise<void>;
+    /**
+     * Removes the {@link Fixture.parent} from the DOM, causing the
+     * disconnect lifecycle to begin.
+     * @remarks
+     * Yields control to the caller one Microtask later, in order to
+     * ensure that the DOM has settled.
+     */
+    disconnect: () => Promise<void>;
+}
+/**
+ * Creates a random, unique name suitable for use as a Custom Element name.
+ * @public
+ */
+export declare function uniqueElementName(prefix?: string): string;
+/**
+ * Creates a test fixture suitable for testing custom elements, templates, and bindings.
+ * @param templateNameOrType An HTML template or single element name to create the fixture for.
+ * @param options Enables customizing fixture creation behavior.
+ * @remarks
+ * Yields control to the caller one Microtask later, in order to
+ * ensure that the DOM has settled.
+ * @public
+ */
+export declare function fixture<TElement = HTMLElement>(templateNameOrType: ViewTemplate | string | Constructable<TElement>, options?: FixtureOptions): Promise<Fixture<TElement>>;

package/dist/dts/testing/models.d.ts

@@ -0,0 +1,20 @@
+declare class ChildModel {
+    value: string;
+}
+declare class Model {
+    childChangedCalled: boolean;
+    trigger: number;
+    value: number;
+    child: ChildModel;
+    child2: ChildModel;
+    childChanged(): void;
+    incrementTrigger(): void;
+    decrementTrigger(): void;
+    get ifConditional(): number;
+}
+declare class DerivedModel extends Model {
+    child2ChangedCalled: boolean;
+    child2Changed(): void;
+    derivedChild: ChildModel;
+}
+export { ChildModel, DerivedModel, Model };

package/dist/dts/testing/timeout.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A timeout helper for use in tests.
+ * @param timeout The length of the timeout.
+ * @returns A promise that resolves once the configured time has elapsed.
+ * @public
+ */
+export declare function timeout(timeout?: number): Promise<void>;

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

@@ -0,0 +1,8 @@
+/**
+ * Trust Events - AFD trust signals for component events.
+ *
+ * @packageDocumentation
+ */
+export type { TrustEmitOptions, TrustSignals, Warning, WarningSeverity, } from "./types.js";
+export { TRUST_KEY } from "./types.js";
+export { getTrustSignals, hasTrustSignals } from "./utils.js";