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

package/dist/dts/scoped/registry.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Registry builder utilities for Scoped Custom Element Registries.
+ */
+import type { CreateRegistryOptions, ElementDefinition } from "./types.js";
+/**
+ * Creates a scoped custom element registry with the provided element definitions.
+ *
+ * @remarks
+ * When scoped registries are supported, creates a new CustomElementRegistry
+ * and defines all provided elements in it. When not supported, falls back to
+ * registering elements on the global `customElements` registry (with a dev warning).
+ *
+ * In strict mode, throws an error if scoped registries are not supported
+ * instead of falling back to the global registry.
+ *
+ * @param definitions - Array of [Constructor, tagName] tuples to register
+ * @param options - Configuration options
+ * @returns The created registry, or undefined if fallback to global occurred
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const registry = createRegistry([
+ *   [MyButton, 'my-button'],
+ *   [MyInput, 'my-input'],
+ * ]);
+ *
+ * if (registry) {
+ *   element.attachShadow({ mode: 'open', customElementRegistry: registry });
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Strict mode - throws if not supported
+ * const registry = createRegistry(
+ *   [[MyButton, 'my-button']],
+ *   { strict: true }
+ * );
+ * ```
+ *
+ * @public
+ */
+export declare function createRegistry(definitions: ElementDefinition[], options?: CreateRegistryOptions): CustomElementRegistry | undefined;
+/**
+ * Creates a scoped custom element registry with automatic polyfill loading.
+ *
+ * @remarks
+ * This async version first ensures scoped registry support is available
+ * (loading the polyfill if necessary), then creates the registry.
+ *
+ * Unlike `createRegistry()`, this function always operates in strict mode
+ * after polyfill loading, as the polyfill should provide support. If the
+ * polyfill fails to load, the underlying `ensureScopedRegistrySupport()`
+ * will throw.
+ *
+ * @param definitions - Array of [Constructor, tagName] tuples to register
+ * @param options - Configuration options (strict is always true after polyfill)
+ * @returns Promise resolving to the created registry
+ *
+ * @throws Error if polyfill loading fails
+ *
+ * @example
+ * ```typescript
+ * // Automatically loads polyfill if needed
+ * const registry = await createRegistryAsync([
+ *   [MyButton, 'my-button'],
+ *   [MyInput, 'my-input'],
+ * ]);
+ *
+ * element.attachShadow({ mode: 'open', customElementRegistry: registry });
+ * ```
+ *
+ * @public
+ */
+export declare function createRegistryAsync(definitions: ElementDefinition[], options?: CreateRegistryOptions): Promise<CustomElementRegistry>;

package/dist/dts/scoped/types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Type definitions for Scoped Custom Element Registries.
+ */
+/**
+ * Extended ShadowRootInit with registry support.
+ *
+ * @remarks
+ * Extends the standard ShadowRootInit to support scoped custom element registries.
+ * The `customElementRegistry` property is the native spec key (Safari 26+, Chrome 133+ OT).
+ * The `registry` property is deprecated and will be removed in a future version.
+ *
+ * @public
+ */
+export interface ScopedShadowRootInit extends ShadowRootInit {
+    /** @deprecated Use customElementRegistry instead */
+    registry?: CustomElementRegistry;
+    /** Native spec key - preferred (Safari 26+, Chrome 133+ Origin Trial) */
+    customElementRegistry?: CustomElementRegistry;
+}
+/**
+ * Element definition tuple: [Constructor, tag-name]
+ *
+ * @remarks
+ * Used with createRegistry() to define elements in a scoped registry.
+ *
+ * @example
+ * ```typescript
+ * const definitions: ElementDefinition[] = [
+ *   [MyButton, 'my-button'],
+ *   [MyInput, 'my-input'],
+ * ];
+ * ```
+ *
+ * @public
+ */
+export type ElementDefinition = [CustomElementConstructor, string];
+/**
+ * Options for createRegistry helper.
+ *
+ * @public
+ */
+export interface CreateRegistryOptions {
+    /**
+     * If true, throw when unsupported instead of falling back to global registry.
+     * Default: false (uses global registry fallback)
+     */
+    strict?: boolean;
+}

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

@@ -0,0 +1,3 @@
+export { reactive } from "./reactive.js";
+export { type ComputedBuilder, type ComputedInitializer, type ComputedSetupCallback, type ComputedState, computedState, type OwnedState, ownedState, type ReadonlyOwnedState, type ReadonlyState, type State, type StateOptions, state, } from "./state.js";
+export { watch } from "./watch.js";

package/dist/dts/state/reactive.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Converts a plain object to a reactive, observable object.
+ * @param object - The object to make reactive.
+ * @param deep - Indicates whether or not to deeply convert the oject.
+ * @returns The converted object.
+ * @beta
+ */
+export declare function reactive<T>(object: T, deep?: boolean): T;

package/dist/dts/state/state.d.ts

@@ -0,0 +1,141 @@
+import { type Disposable } from "../interfaces.js";
+import type { Subscriber } from "../observation/notifier.js";
+/**
+ * Options for creating state.
+ * @beta
+ */
+export type StateOptions = {
+    /**
+     * Indicates whether to deeply make the state value observable.
+     */
+    deep?: boolean;
+    /**
+     * A friendly name for the state.
+     */
+    name?: string;
+};
+/**
+ * A readonly stateful value.
+ * @beta
+ */
+export type ReadonlyState<T> = {
+    /**
+     * Gets the current state value.
+     */
+    (): T;
+    /**
+     * Gets the current state value.
+     */
+    readonly current: T;
+};
+/**
+ * A read/write stateful value.
+ * @beta
+ */
+export type State<T> = ReadonlyState<T> & {
+    /**
+     * Gets or sets the current state value.
+     */
+    current: T;
+    /**
+     * Sets the current state value.
+     * @param value - The new state value.
+     */
+    set(value: T): void;
+    /**
+     * Creates a readonly version of the state.
+     */
+    asReadonly(): ReadonlyState<T>;
+};
+/**
+ * Creates a reactive state value.
+ * @param value - The initial state value.
+ * @param options - Options to customize the state or a friendly name.
+ * @returns A State instance.
+ * @beta
+ */
+export declare function state<T>(value: T, options?: string | StateOptions): State<T>;
+/**
+ * A readonly stateful value associated with an object owner.
+ * @beta
+ */
+export type ReadonlyOwnedState<T> = {
+    /**
+     * Gets the current stateful value for the owner.
+     */
+    (owner: any): T;
+};
+/**
+ * A read/write stateful value associated with an owner.
+ * @beta
+ */
+export type OwnedState<T> = ReadonlyOwnedState<T> & {
+    /**
+     * Sets
+     * @param owner - The object to set the state for the owner.
+     * @param value - The new state value.
+     */
+    set(owner: any, value: T): void;
+    /**
+     * Creates a readonly version of the state.
+     */
+    asReadonly(): ReadonlyOwnedState<T>;
+};
+/**
+ * Creates a reactive state that has its value associated with a specific owner.
+ * @param value - The initial value or a factory that provides an initial value for each owner.
+ * @param options - Options to customize the state or a friendly name.
+ * @returns An OwnedState instance.
+ * @beta
+ */
+export declare function ownedState<T>(value: T | (() => T), options?: string | StateOptions): OwnedState<T>;
+/**
+ * State whose value is computed from other dependencies.
+ * @beta
+ */
+export type ComputedState<T> = ReadonlyState<T> & Disposable & {
+    /**
+     * Subscribes to notification of changes in the state.
+     * @param subscriber - The object that is subscribing for change notification.
+     */
+    subscribe(subscriber: Subscriber): void;
+    /**
+     * Unsubscribes from notification of changes in the state.
+     * @param subscriber - The object that is unsubscribing from change notification.
+     */
+    unsubscribe(subscriber: Subscriber): void;
+};
+/**
+ * A callback that enables computation setup.
+ * @beta
+ */
+export type ComputedSetupCallback = () => (() => void) | void;
+/**
+ * Provides computed state capabilities.
+ * @beta
+ */
+export type ComputedBuilder = {
+    /**
+     * Callbacks related to computed state.
+     */
+    on: {
+        /**
+         * Provides a setup callback for the computation.
+         * @param callback - The callback to run to setup the computation.
+         */
+        setup(callback: ComputedSetupCallback): void;
+    };
+};
+/**
+ * A callback that initializes the computation.
+ * @beta
+ */
+export type ComputedInitializer<T> = (builder: ComputedBuilder) => () => T;
+/**
+ * Creates a ComputedState.
+ * @param initialize - The initialization callback.
+ * @param name - A friendly name for this computation.
+ * @returns A ComputedState
+ * @beta
+ */
+export declare function computedState<T>(initialize: ComputedInitializer<T>, name?: string): ComputedState<T>;

package/dist/dts/state/visitor.d.ts

@@ -0,0 +1,6 @@
+export interface ObjectVisitor<TVisitorData> {
+    visitObject(object: any, data: TVisitorData): void;
+    visitArray(array: any[], data: TVisitorData): void;
+    visitProperty(object: any, key: PropertyKey, value: any, data: TVisitorData): void;
+}
+export declare function visitObject<TVisitorData>(object: any, deep: boolean, visitor: ObjectVisitor<TVisitorData>, data: TVisitorData, traversed: WeakSet<any> | Set<any>): void;

package/dist/dts/state/watch.d.ts

@@ -0,0 +1,10 @@
+import { type Disposable } from "../interfaces.js";
+import type { Subscriber } from "../observation/notifier.js";
+/**
+ * Deeply subscribes to changes in existing observable objects.
+ * @param object - The observable object to watch.
+ * @param subscriber - The handler to call when changes are made to the object.
+ * @returns A disposable that can be used to unsubscribe from change updates.
+ * @beta
+ */
+export declare function watch(object: any, subscriber: Subscriber | ((subject: any, args: any) => void)): Disposable;

package/dist/dts/styles/css-directive.d.ts

@@ -0,0 +1,50 @@
+import type { Constructable } from "../interfaces.js";
+import type { ComposableStyles } from "./element-styles.js";
+/**
+ * Directive for use in CSS templates.
+ *
+ * @public
+ */
+export interface CSSDirective {
+    /**
+     * Creates static styles to interpolate into the CSS document.
+     * @returns - the styles to interpolate into CSS
+     */
+    createCSS(): ComposableStyles;
+}
+/**
+ * Defines metadata for a CSSDirective.
+ * @public
+ */
+export interface CSSDirectiveDefinition<TType extends Constructable<CSSDirective> = Constructable<CSSDirective>> {
+    /**
+     * The type that the definition provides metadata for.
+     */
+    readonly type: TType;
+}
+/**
+ * Instructs the css engine to provide styles during CSS template composition.
+ * @public
+ */
+export declare const CSSDirective: Readonly<{
+    /**
+     * Gets the directive definition associated with the instance.
+     * @param instance - The directive instance to retrieve the definition for.
+     */
+    getForInstance: (object: any) => CSSDirectiveDefinition<Constructable<CSSDirective>> | undefined;
+    /**
+     * Gets the directive definition associated with the specified type.
+     * @param type - The directive type to retrieve the definition for.
+     */
+    getByType: (key: Function) => CSSDirectiveDefinition<Constructable<CSSDirective>> | undefined;
+    /**
+     * Defines a CSSDirective.
+     * @param type - The type to define as a directive.
+     */
+    define<TType extends Constructable<CSSDirective>>(type: any): TType;
+}>;
+/**
+ * Decorator: Defines a CSSDirective.
+ * @public
+ */
+export declare function cssDirective(): (type: Constructable<CSSDirective>) => void;

package/dist/dts/styles/css.d.ts

@@ -0,0 +1,34 @@
+import { CSSDirective } from "./css-directive.js";
+import { type ComposableStyles, ElementStyles } from "./element-styles.js";
+/**
+ * Represents the types of values that can be interpolated into a template.
+ * @public
+ */
+export type CSSValue = ComposableStyles | CSSDirective;
+/**
+ * Transforms a template literal string into styles.
+ * @param strings - The string fragments that are interpolated with the values.
+ * @param values - The values that are interpolated with the string fragments.
+ * @remarks
+ * The css helper supports interpolation of static composable styles and CSS directives.
+ * Use the .partial method to create partial CSS fragments.
+ * @public
+ */
+export type CSSTemplateTag = ((strings: TemplateStringsArray, ...values: CSSValue[]) => ElementStyles) & {
+    /**
+     * Transforms a template literal string into partial CSS.
+     * @param strings - The string fragments that are interpolated with the values.
+     * @param values - The values that are interpolated with the string fragments.
+     * @public
+     */
+    partial(strings: TemplateStringsArray, ...values: CSSValue[]): CSSDirective;
+};
+/**
+ * Transforms a template literal string into styles.
+ * @param strings - The string fragments that are interpolated with the values.
+ * @param values - The values that are interpolated with the string fragments.
+ * @remarks
+ * The css helper supports interpolation of static composable styles and CSS directives.
+ * @public
+ */
+export declare const css: CSSTemplateTag;

package/dist/dts/styles/element-styles.d.ts

@@ -0,0 +1,61 @@
+import type { StyleStrategy, StyleTarget } from "./style-strategy.js";
+/**
+ * Represents styles that can be composed into the ShadowDOM of a custom element.
+ * @public
+ */
+export type ComposableStyles = string | ElementStyles | CSSStyleSheet;
+/**
+ * A type that instantiates a StyleStrategy.
+ * @public
+ */
+export type ConstructibleStyleStrategy = {
+    /**
+     * Creates an instance of the strategy.
+     * @param styles - The styles to initialize the strategy with.
+     */
+    new (styles: (string | CSSStyleSheet)[]): StyleStrategy;
+};
+/**
+ * Represents styles that can be applied to a custom element.
+ * @public
+ */
+export declare class ElementStyles {
+    readonly styles: ReadonlyArray<ComposableStyles>;
+    private targets;
+    private _strategy;
+    /**
+     * Gets the StyleStrategy associated with these element styles.
+     */
+    get strategy(): StyleStrategy;
+    /**
+     * Creates an instance of ElementStyles.
+     * @param styles - The styles that will be associated with elements.
+     */
+    constructor(styles: ReadonlyArray<ComposableStyles>);
+    /** @internal */
+    addStylesTo(target: StyleTarget): void;
+    /** @internal */
+    removeStylesFrom(target: StyleTarget): void;
+    /** @internal */
+    isAttachedTo(target: StyleTarget): boolean;
+    /**
+     * Sets the strategy that handles adding/removing these styles for an element.
+     * @param strategy - The strategy to use.
+     */
+    withStrategy(Strategy: ConstructibleStyleStrategy): this;
+    /**
+     * Sets the default strategy type to use when creating style strategies.
+     * @param Strategy - The strategy type to construct.
+     */
+    static setDefaultStrategy(Strategy: ConstructibleStyleStrategy): void;
+    /**
+     * Normalizes a set of composable style options.
+     * @param styles - The style options to normalize.
+     * @returns A singular ElementStyles instance or undefined.
+     */
+    static normalize(styles: ComposableStyles | ComposableStyles[] | undefined): ElementStyles | undefined;
+    /**
+     * Indicates whether the DOM supports the adoptedStyleSheets feature.
+     */
+    static readonly supportsAdoptedStyleSheets: boolean;
+}

package/dist/dts/styles/host.d.ts

@@ -0,0 +1,65 @@
+import type { ExpressionController } from "../observation/observable.js";
+import type { ElementStyles } from "./element-styles.js";
+/**
+ * Controls the lifecycle and context of behaviors and styles
+ * associated with a component host.
+ * @public
+ */
+export interface HostController<TSource = any> extends ExpressionController<TSource> {
+    /**
+     * Indicates whether the host is connected or not.
+     */
+    readonly isConnected: boolean;
+    /**
+     * The main set of styles used for the component, independent
+     * of any behavior-specific styles.
+     */
+    mainStyles: ElementStyles | null;
+    /**
+     * Adds the behavior to the component.
+     * @param behavior - The behavior to add.
+     */
+    addBehavior(behavior: HostBehavior<TSource>): 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<TSource>, 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;
+}
+/**
+ * Represents an object that can contribute behavior to a host.
+ * @public
+ */
+export interface HostBehavior<TSource = any> {
+    /**
+     * Executed when this behavior is attached to a controller.
+     * @param controller - Controls the behavior lifecycle.
+     */
+    addedCallback?(controller: HostController<TSource>): void;
+    /**
+     * Executed when this behavior is detached from a controller.
+     * @param controller - Controls the behavior lifecycle.
+     */
+    removedCallback?(controller: HostController<TSource>): void;
+    /**
+     * Executed when this behavior's host is connected.
+     * @param controller - Controls the behavior lifecycle.
+     */
+    connectedCallback?(controller: HostController<TSource>): void;
+    /**
+     * Executed when this behavior's host is disconnected.
+     * @param controller - Controls the behavior lifecycle.
+     */
+    disconnectedCallback?(controller: HostController<TSource>): void;
+}

package/dist/dts/styles/style-strategy.d.ts

@@ -0,0 +1,42 @@
+/**
+ * A node that can be targeted by styles.
+ * @public
+ */
+export interface StyleTarget extends Pick<Node, "getRootNode"> {
+    /**
+     * Stylesheets to be adopted by the node.
+     */
+    adoptedStyleSheets?: CSSStyleSheet[];
+    /**
+     * Adds styles to the target by appending the styles.
+     * @param styles - The styles element to add.
+     */
+    append(styles: HTMLStyleElement): void;
+    /**
+     * Removes styles from the target.
+     * @param styles - The styles element to remove.
+     */
+    removeChild(styles: HTMLStyleElement): void;
+    /**
+     * Returns all element descendants of node that match selectors.
+     * @param selectors - The CSS selector to use for the query.
+     */
+    querySelectorAll<E extends Element = Element>(selectors: string): NodeListOf<E>;
+}
+/**
+ * Implemented to provide specific behavior when adding/removing styles
+ * for elements.
+ * @public
+ */
+export interface StyleStrategy {
+    /**
+     * Adds styles to the target.
+     * @param target - The target to add the styles to.
+     */
+    addStylesTo(target: StyleTarget): void;
+    /**
+     * Removes styles from the target.
+     * @param target - The target to remove the styles from.
+     */
+    removeStylesFrom(target: StyleTarget): void;
+}

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

@@ -0,0 +1,62 @@
+import { type NodeBehaviorOptions, NodeObservationDirective } from "./node-observation.js";
+import type { CaptureType } from "./template.js";
+/**
+ * The options used to configure child list observation.
+ * @public
+ */
+export interface ChildListDirectiveOptions<T = any> extends NodeBehaviorOptions<T>, Omit<MutationObserverInit, "subtree" | "childList"> {
+}
+/**
+ * The options used to configure subtree observation.
+ * @public
+ */
+export interface SubtreeDirectiveOptions<T = any> extends NodeBehaviorOptions<T>, Omit<MutationObserverInit, "subtree" | "childList"> {
+    /**
+     * Indicates that child subtrees should be observed for changes.
+     */
+    subtree: boolean;
+    /**
+     * When subtrees are observed, a query selector is required to indicate
+     * which of potentially many nodes should be assigned to the property.
+     */
+    selector: string;
+}
+/**
+ * The options used to configure child/subtree node observation.
+ * @public
+ */
+export type ChildrenDirectiveOptions<T = any> = ChildListDirectiveOptions<T> | SubtreeDirectiveOptions<T>;
+/**
+ * The runtime behavior for child node observation.
+ * @public
+ */
+export declare class ChildrenDirective extends NodeObservationDirective<ChildrenDirectiveOptions> {
+    private observerProperty;
+    /**
+     * Creates an instance of ChildrenDirective.
+     * @param options - The options to use in configuring the child observation behavior.
+     */
+    constructor(options: ChildrenDirectiveOptions);
+    /**
+     * Begins observation of the nodes.
+     * @param target - The target to observe.
+     */
+    observe(target: any): void;
+    /**
+     * Disconnects observation of the nodes.
+     * @param target - The target to unobserve.
+     */
+    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.
+     */
+    getNodes(target: Element): Node[];
+}
+/**
+ * A directive that observes the `childNodes` of an element and updates a property
+ * whenever they change.
+ * @param propertyOrOptions - The options used to configure child node observation.
+ * @public
+ */
+export declare function children<TSource = any, TParent = any>(propertyOrOptions: (keyof TSource & string) | ChildrenDirectiveOptions<keyof TSource & string>): CaptureType<TSource, TParent>;

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

@@ -0,0 +1,54 @@
+import type { DOMPolicy } from "../dom-policy.js";
+import { type ViewBehaviorFactory } from "./html-directive.js";
+import type { HTMLTemplateCompilationResult as TemplateCompilationResult } from "./template.js";
+/**
+ * A function capable of compiling a template from the preprocessed form produced
+ * by the html template function into a result that can instantiate views.
+ * @public
+ */
+export type CompilationStrategy = (
+/**
+ * The preprocessed HTML string or template to compile.
+ */
+html: string | HTMLTemplateElement, 
+/**
+ * The behavior factories used within the html that is being compiled.
+ */
+factories: Record<string, ViewBehaviorFactory>, 
+/**
+ * The security policy to compile the html with.
+ */
+policy: DOMPolicy) => TemplateCompilationResult;
+/**
+ * Common APIs related to compilation.
+ * @public
+ */
+export declare const Compiler: {
+    /**
+     * Compiles a template and associated directives into a compilation
+     * result which can be used to create views.
+     * @param html - The html string or template element to compile.
+     * @param factories - The behavior factories referenced by the template.
+     * @param policy - The security policy to compile the html with.
+     * @remarks
+     * The template that is provided for compilation is altered in-place
+     * and cannot be compiled again. If the original template must be preserved,
+     * it is recommended that you clone the original and pass the clone to this API.
+     * @public
+     */
+    compile<TSource = any, TParent = any>(html: string | HTMLTemplateElement, factories: Record<string, ViewBehaviorFactory>, policy?: DOMPolicy): TemplateCompilationResult<TSource, TParent>;
+    /**
+     * Sets the default compilation strategy that will be used by the ViewTemplate whenever
+     * it needs to compile a view preprocessed with the html template function.
+     * @param strategy - The compilation strategy to use when compiling templates.
+     */
+    setDefaultStrategy(strategy: CompilationStrategy): void;
+    /**
+     * Aggregates an array of strings and directives into a single directive.
+     * @param parts - A heterogeneous array of static strings interspersed with
+     * directives.
+     * @param policy - The security policy to use with the aggregated bindings.
+     * @returns A single inline directive that aggregates the behavior of all the parts.
+     */
+    aggregate(parts: (string | ViewBehaviorFactory)[], policy?: DOMPolicy): ViewBehaviorFactory;
+};