@fictjs/runtime 0.0.13 → 0.0.15

package/dist/effect-Auji1rz9.d.ts

@@ -0,0 +1,350 @@
+/** Any DOM node that can be rendered */
+type DOMElement = Node;
+/** Cleanup function type */
+type Cleanup = () => void;
+/** Fict Virtual Node - represents a component or element in the virtual tree */
+interface FictVNode {
+    /** Element type: tag name, Fragment symbol, or component function */
+    type: string | symbol | ((props: Record<string, unknown>) => FictNode);
+    /** Props passed to the element/component */
+    props: Record<string, unknown> | null;
+    /** Optional key for list rendering optimization */
+    key?: string | undefined;
+}
+/**
+ * Fict Node - represents any renderable value
+ * This type covers all possible values that can appear in JSX
+ */
+type FictNode = FictVNode | FictNode[] | Node | string | number | boolean | null | undefined;
+/** Props that all components receive */
+interface BaseProps {
+    /** Optional key for list rendering */
+    key?: string | number;
+    /** Optional children */
+    children?: FictNode | FictNode[];
+}
+/** A Fict component function */
+type Component<P extends Record<string, unknown> = Record<string, unknown>> = (props: P & BaseProps) => FictNode;
+/** Props with children */
+type PropsWithChildren<P = unknown> = P & {
+    children?: FictNode | FictNode[];
+};
+interface ErrorInfo {
+    source: 'render' | 'effect' | 'event' | 'renderChild' | 'cleanup';
+    componentName?: string;
+    eventName?: string;
+}
+/** Event handler type for type-safe event handling */
+type EventHandler<E extends Event = Event> = (event: E) => void;
+/** Ref callback type */
+type RefCallback<T extends Element = HTMLElement> = (element: T) => void;
+/** Ref object type (for future use with createRef) */
+interface RefObject<T extends Element = HTMLElement> {
+    current: T | null;
+}
+/** Ref type that can be either callback or object */
+type Ref<T extends Element = HTMLElement> = RefCallback<T> | RefObject<T>;
+/** CSS style value - can be string or number (number becomes px) */
+type StyleValue = string | number;
+/** CSS style object */
+type CSSStyleObject = {
+    [K in keyof CSSStyleDeclaration]?: StyleValue;
+} & Record<string, StyleValue>;
+/** Style prop type - can be string or object */
+type StyleProp = string | CSSStyleObject | null | undefined;
+/** Class object for conditional classes */
+type ClassObject = Record<string, boolean | undefined | null>;
+/** Class prop type - can be string or object */
+type ClassProp = string | ClassObject | null | undefined;
+interface SuspenseToken {
+    then: Promise<unknown>['then'];
+}
+
+/**
+ * Fict Reactive DOM Binding System
+ *
+ * This module provides the core mechanisms for reactive DOM updates.
+ * It bridges the gap between Fict's reactive system (signals, effects)
+ * and the DOM, enabling fine-grained updates without a virtual DOM.
+ *
+ * Design Philosophy:
+ * - Values wrapped in functions `() => T` are treated as reactive
+ * - Static values are applied once without tracking
+ * - The compiler transforms JSX expressions to use these primitives
+ */
+
+/** A reactive value that can be either static or a getter function */
+type MaybeReactive<T> = T | (() => T);
+/** Internal type for createElement function reference */
+type CreateElementFn = (node: FictNode) => Node;
+/** Handle returned by conditional/list bindings for cleanup */
+interface BindingHandle {
+    /** Marker node(s) used for positioning */
+    marker: Comment | DocumentFragment;
+    /** Flush pending content - call after markers are inserted into DOM */
+    flush?: () => void;
+    /** Dispose function to clean up the binding */
+    dispose: Cleanup;
+}
+/** Managed child node with its dispose function */
+/**
+ * Check if a value is reactive (a getter function)
+ * Note: Event handlers (functions that take arguments) are NOT reactive values
+ */
+declare function isReactive(value: unknown): value is () => unknown;
+/**
+ * Unwrap a potentially reactive value to get the actual value
+ */
+declare function unwrap<T>(value: MaybeReactive<T>): T;
+/**
+ * Invoke an event handler or handler accessor in a safe way.
+ * Supports handlers that return another handler and handlers that expect an
+ * optional data payload followed by the event.
+ */
+declare function callEventHandler(handler: EventListenerOrEventListenerObject | null | undefined, event: Event, node?: EventTarget | null, data?: unknown): void;
+/**
+ * Create a text node that reactively updates when the value changes.
+ *
+ * @example
+ * ```ts
+ * // Static text
+ * createTextBinding("Hello")
+ *
+ * // Reactive text (compiler output)
+ * createTextBinding(() => $count())
+ * ```
+ */
+declare function createTextBinding(value: MaybeReactive<unknown>): Text;
+/**
+ * Bind a reactive value to an existing text node.
+ * This is a convenience function for binding to existing DOM nodes.
+ */
+declare function bindText(textNode: Text, getValue: () => unknown): Cleanup;
+/** Attribute setter function type */
+type AttributeSetter = (el: Element, key: string, value: unknown) => void;
+/**
+ * Create a reactive attribute binding on an element.
+ *
+ * @example
+ * ```ts
+ * // Static attribute
+ * createAttributeBinding(button, 'disabled', false, setAttribute)
+ *
+ * // Reactive attribute (compiler output)
+ * createAttributeBinding(button, 'disabled', () => !$isValid(), setAttribute)
+ * ```
+ */
+declare function createAttributeBinding(el: Element, key: string, value: MaybeReactive<unknown>, setter: AttributeSetter): void;
+/**
+ * Bind a reactive value to an element's attribute.
+ */
+declare function bindAttribute(el: Element, key: string, getValue: () => unknown): Cleanup;
+/**
+ * Bind a reactive value to an element's property.
+ */
+declare function bindProperty(el: Element, key: string, getValue: () => unknown): Cleanup;
+/**
+ * Apply styles to an element, supporting reactive style objects/strings.
+ */
+declare function createStyleBinding(el: Element, value: MaybeReactive<string | Record<string, string | number> | null | undefined>): void;
+/**
+ * Bind a reactive style value to an existing element.
+ */
+declare function bindStyle(el: Element, getValue: () => string | Record<string, string | number> | null | undefined): Cleanup;
+/**
+ * Apply class to an element, supporting reactive class values.
+ */
+declare function createClassBinding(el: Element, value: MaybeReactive<string | Record<string, boolean> | null | undefined>): void;
+/**
+ * Bind a reactive class value to an existing element.
+ */
+declare function bindClass(el: Element, getValue: () => string | Record<string, boolean> | null | undefined): Cleanup;
+/**
+ * Exported classList function for direct use (compatible with dom-expressions)
+ */
+declare function classList(node: Element, value: Record<string, boolean> | null | undefined, prev?: Record<string, boolean>): Record<string, boolean>;
+/**
+ * Insert reactive content into a parent element.
+ * This is a simpler API than createChildBinding for basic cases.
+ *
+ * @param parent - The parent element to insert into
+ * @param getValue - Function that returns the value to render
+ * @param markerOrCreateElement - Optional marker node to insert before, or createElementFn
+ * @param createElementFn - Optional function to create DOM elements (when marker is provided)
+ */
+declare function insert(parent: ParentNode & Node, getValue: () => FictNode, markerOrCreateElement?: Node | CreateElementFn, createElementFn?: CreateElementFn): Cleanup;
+/**
+ * Create a reactive child binding that updates when the child value changes.
+ * This is used for dynamic expressions like `{show && <Modal />}` or `{items.map(...)}`.
+ *
+ * @example
+ * ```ts
+ * // Reactive child (compiler output for {count})
+ * createChildBinding(parent, () => $count(), createElement)
+ *
+ * // Reactive conditional (compiler output for {show && <Modal />})
+ * createChildBinding(parent, () => $show() && jsx(Modal, {}), createElement)
+ * ```
+ */
+declare function createChildBinding(parent: ParentNode & Node, getValue: () => FictNode, createElementFn: CreateElementFn): BindingHandle;
+declare global {
+    interface Element {
+        _$host?: Element;
+        [key: `$$${string}`]: EventListener | [EventListener, unknown] | undefined;
+        [key: `$$${string}Data`]: unknown;
+    }
+    interface Document extends Record<string, unknown> {
+    }
+}
+/**
+ * Initialize event delegation for a set of event names.
+ * Events will be handled at the document level and dispatched to the appropriate handlers.
+ *
+ * @param eventNames - Array of event names to delegate
+ * @param doc - The document to attach handlers to (default: window.document)
+ *
+ * @example
+ * ```ts
+ * // Called automatically by the compiler for delegated events
+ * delegateEvents(['click', 'input', 'keydown'])
+ * ```
+ */
+declare function delegateEvents(eventNames: string[], doc?: Document): void;
+/**
+ * Clear all delegated event handlers from a document.
+ *
+ * @param doc - The document to clear handlers from (default: window.document)
+ */
+declare function clearDelegatedEvents(doc?: Document): void;
+/**
+ * Add an event listener to an element.
+ * If the event is in DelegatedEvents, it uses event delegation for better performance.
+ *
+ * @param node - The element to add the listener to
+ * @param name - The event name (lowercase)
+ * @param handler - The event handler or [handler, data] tuple
+ * @param delegate - Whether to use delegation (auto-detected based on event name)
+ */
+declare function addEventListener(node: Element, name: string, handler: EventListener | [EventListener, unknown] | null | undefined, delegate?: boolean): void;
+/**
+ * Bind an event listener to an element.
+ * Uses event delegation for better performance when applicable.
+ *
+ * @example
+ * ```ts
+ * // Static event
+ * bindEvent(button, 'click', handleClick)
+ *
+ * // Reactive event (compiler output)
+ * bindEvent(button, 'click', () => $handler())
+ *
+ * // With modifiers
+ * bindEvent(button, 'click', handler, { capture: true, passive: true, once: true })
+ * ```
+ */
+declare function bindEvent(el: Element, eventName: string, handler: EventListenerOrEventListenerObject | null | undefined, options?: boolean | AddEventListenerOptions): Cleanup;
+/**
+ * Bind a ref to an element.
+ * Supports both callback refs and ref objects.
+ *
+ * @param el - The element to bind the ref to
+ * @param ref - Either a callback function, a ref object, or a reactive getter
+ * @returns Cleanup function
+ *
+ * @example
+ * ```ts
+ * // Callback ref
+ * bindRef(el, (element) => { store.input = element })
+ *
+ * // Ref object
+ * const inputRef = createRef()
+ * bindRef(el, inputRef)
+ *
+ * // Reactive ref (compiler output)
+ * bindRef(el, () => props.ref)
+ * ```
+ */
+declare function bindRef(el: Element, ref: unknown): Cleanup;
+/**
+ * Apply spread props to an element with reactive updates.
+ * This handles dynamic spread like `<div {...props}>`.
+ *
+ * @param node - The element to apply props to
+ * @param props - The props object (may have reactive getters)
+ * @param isSVG - Whether this is an SVG element
+ * @param skipChildren - Whether to skip children handling
+ * @returns The previous props for tracking changes
+ *
+ * @example
+ * ```ts
+ * // Compiler output for <div {...props} />
+ * spread(el, props, false, false)
+ * ```
+ */
+declare function spread(node: Element, props?: Record<string, unknown>, isSVG?: boolean, skipChildren?: boolean): Record<string, unknown>;
+/**
+ * Assign props to a node, tracking previous values for efficient updates.
+ * This is the core prop assignment logic used by spread.
+ *
+ * @param node - The element to assign props to
+ * @param props - New props object
+ * @param isSVG - Whether this is an SVG element
+ * @param skipChildren - Whether to skip children handling
+ * @param prevProps - Previous props for comparison
+ * @param skipRef - Whether to skip ref handling
+ */
+declare function assign(node: Element, props: Record<string, unknown>, isSVG?: boolean, skipChildren?: boolean, prevProps?: Record<string, unknown>, skipRef?: boolean): void;
+/**
+ * Create a conditional rendering binding.
+ * Efficiently renders one of two branches based on a condition.
+ *
+ * This is an optimized version for `{condition ? <A /> : <B />}` patterns
+ * where both branches are known statically.
+ *
+ * @example
+ * ```ts
+ * // Compiler output for {show ? <A /> : <B />}
+ * createConditional(
+ *   () => $show(),
+ *   () => jsx(A, {}),
+ *   () => jsx(B, {}),
+ *   createElement
+ * )
+ * ```
+ */
+declare function createConditional(condition: () => boolean, renderTrue: () => FictNode, createElementFn: CreateElementFn, renderFalse?: () => FictNode): BindingHandle;
+/**
+ * Create a show/hide binding that uses CSS display instead of DOM manipulation.
+ * More efficient than conditional when the content is expensive to create.
+ *
+ * @example
+ * ```ts
+ * createShow(container, () => $visible())
+ * ```
+ */
+declare function createShow(el: Element & {
+    style: CSSStyleDeclaration;
+}, condition: () => boolean, displayValue?: string): void;
+/**
+ * Create a portal that renders content into a different DOM container.
+ *
+ * @example
+ * ```ts
+ * createPortal(
+ *   document.body,
+ *   () => jsx(Modal, { children: 'Hello' }),
+ *   createElement
+ * )
+ * ```
+ */
+declare function createPortal(container: ParentNode & Node, render: () => FictNode, createElementFn: CreateElementFn): BindingHandle;
+
+/**
+ * Effect callback run synchronously; async callbacks are not tracked after the first await.
+ * TypeScript will reject `async () => {}` here—split async work or read signals before awaiting.
+ */
+type Effect = () => void | Cleanup;
+declare function createEffect(fn: Effect): () => void;
+declare function createRenderEffect(fn: Effect): () => void;
+
+export { bindRef as A, type BaseProps as B, type Cleanup as C, type DOMElement as D, type Effect as E, type FictNode as F, insert as G, createConditional as H, spread as I, assign as J, classList as K, delegateEvents as L, clearDelegatedEvents as M, addEventListener as N, type MaybeReactive as O, type PropsWithChildren as P, type BindingHandle as Q, type RefObject as R, type SuspenseToken as S, type CreateElementFn as T, type AttributeSetter as U, createChildBinding as a, createAttributeBinding as b, createTextBinding as c, createStyleBinding as d, createClassBinding as e, createShow as f, createRenderEffect as g, createEffect as h, isReactive as i, createPortal as j, type FictVNode as k, type Component as l, type Ref as m, type RefCallback as n, type StyleProp as o, type ClassProp as p, type EventHandler as q, type ErrorInfo as r, bindText as s, bindAttribute as t, unwrap as u, bindStyle as v, bindClass as w, bindEvent as x, callEventHandler as y, bindProperty as z };