@fictjs/runtime 0.0.2

package/dist/slim.d.cts

@@ -0,0 +1,475 @@
+/**
+ * Signal accessor - function to get/set signal value
+ */
+interface SignalAccessor<T> {
+    (): T;
+    (value: T): void;
+}
+/**
+ * Computed accessor - function to get computed value
+ */
+type ComputedAccessor<T> = () => T;
+/**
+ * Create a reactive signal
+ * @param initialValue - The initial value
+ * @returns A signal accessor function
+ */
+declare function signal<T>(initialValue: T): SignalAccessor<T>;
+declare const $state: <T>(value: T) => T;
+/**
+ * Create a selector signal that efficiently updates only when the selected key matches.
+ * Useful for large lists where only one item is selected.
+ *
+ * @param source - The source signal returning the current key
+ * @param equalityFn - Optional equality function
+ * @returns A selector function that takes a key and returns a boolean signal accessor
+ */
+declare function createSelector<T>(source: () => T, equalityFn?: (a: T, b: T) => boolean): (key: T) => boolean;
+
+type Memo<T> = () => T;
+declare function createMemo<T>(fn: () => T): Memo<T>;
+
+/** 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;
+interface ErrorInfo {
+    source: 'render' | 'effect' | 'event' | 'renderChild' | 'cleanup';
+    componentName?: string;
+    eventName?: string;
+}
+interface SuspenseToken {
+    then: Promise<unknown>['then'];
+}
+
+type Effect = () => void | Cleanup;
+declare function createEffect(fn: Effect): () => void;
+declare function createRenderEffect(fn: Effect): () => void;
+
+declare function batch<T>(fn: () => T): T;
+declare function untrack<T>(fn: () => T): T;
+
+/**
+ * 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
+ */
+
+/** 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;
+}
+/**
+ * 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;
+/**
+ * Bind a reactive value to an element's attribute.
+ */
+declare function bindAttribute(el: HTMLElement, key: string, getValue: () => unknown): Cleanup;
+/**
+ * Bind a reactive value to an element's property.
+ */
+declare function bindProperty(el: HTMLElement, key: string, getValue: () => unknown): Cleanup;
+/**
+ * Bind a reactive style value to an existing element.
+ */
+declare function bindStyle(el: HTMLElement, getValue: () => string | Record<string, string | number> | null | undefined): Cleanup;
+/**
+ * Bind a reactive class value to an existing element.
+ */
+declare function bindClass(el: HTMLElement, getValue: () => string | Record<string, boolean> | null | undefined): Cleanup;
+/**
+ * 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: HTMLElement | DocumentFragment, getValue: () => FictNode, markerOrCreateElement?: Node | CreateElementFn, createElementFn?: CreateElementFn): Cleanup;
+declare global {
+    interface HTMLElement {
+        _$host?: HTMLElement;
+        [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;
+/**
+ * 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: HTMLElement, 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: HTMLElement, ref: unknown): Cleanup;
+/**
+ * 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;
+/** Key extractor function type */
+type KeyFn<T> = (item: T, index: number) => string | number;
+/**
+ * Create a reactive list rendering binding with optional keying.
+ */
+declare function createList<T>(items: () => T[], renderItem: (item: T, index: number) => FictNode, createElementFn: CreateElementFn, getKey?: KeyFn<T>): BindingHandle;
+
+/**
+ * Fict DOM Rendering System
+ *
+ * This module provides DOM rendering capabilities with reactive bindings.
+ * It transforms JSX virtual nodes into actual DOM elements, automatically
+ * setting up reactive updates for dynamic values.
+ *
+ * Key Features:
+ * - Reactive text content: `{count}` updates when count changes
+ * - Reactive attributes: `disabled={!isValid}` updates reactively
+ * - Reactive children: `{show && <Modal />}` handles conditionals
+ * - List rendering: `{items.map(...)}` with efficient keyed updates
+ */
+
+/**
+ * Render a Fict view into a container element.
+ *
+ * @param view - A function that returns the view to render
+ * @param container - The DOM container to render into
+ * @returns A teardown function to unmount the view
+ *
+ * @example
+ * ```ts
+ * const unmount = render(() => <App />, document.getElementById('root')!)
+ * // Later: unmount()
+ * ```
+ */
+declare function render(view: () => FictNode, container: HTMLElement): () => void;
+/**
+ * Create a DOM element from a Fict node.
+ * This is the main entry point for converting virtual nodes to real DOM.
+ *
+ * Supports:
+ * - Native DOM nodes (passed through)
+ * - Null/undefined/false (empty text node)
+ * - Arrays (DocumentFragment)
+ * - Strings/numbers (text nodes)
+ * - Booleans (empty text node)
+ * - VNodes (components or HTML elements)
+ * - Reactive values (functions returning any of the above)
+ */
+declare function createElement(node: FictNode): DOMElement;
+/**
+ * Create a template cloning factory from an HTML string.
+ * Used by the compiler for efficient DOM generation.
+ *
+ * @param html - The HTML string to create a template from
+ * @param isImportNode - Use importNode for elements like img/iframe
+ * @param isSVG - Whether the template is SVG content
+ * @param isMathML - Whether the template is MathML content
+ */
+declare function template(html: string, isImportNode?: boolean, isSVG?: boolean, isMathML?: boolean): () => Node;
+
+declare const Fragment: unique symbol;
+
+type LifecycleFn = () => void | Cleanup;
+interface RootContext {
+    parent?: RootContext | undefined;
+    onMountCallbacks?: LifecycleFn[];
+    cleanups: Cleanup[];
+    destroyCallbacks: Cleanup[];
+    errorHandlers?: ErrorHandler[];
+    suspenseHandlers?: SuspenseHandler[];
+}
+type ErrorHandler = (err: unknown, info?: ErrorInfo) => boolean | void;
+type SuspenseHandler = (token: SuspenseToken | PromiseLike<unknown>) => boolean | void;
+declare function onDestroy(fn: LifecycleFn): void;
+
+/**
+ * Low-level DOM node helpers shared across runtime modules.
+ * Keep this file dependency-free to avoid module cycles.
+ */
+/**
+ * Convert a value to a flat array of DOM nodes.
+ * Defensively handles proxies and non-DOM values.
+ */
+declare function toNodeArray(node: Node | Node[] | unknown): Node[];
+/**
+ * Insert nodes before an anchor node, preserving order.
+ * Uses DocumentFragment for batch insertion when inserting multiple nodes.
+ */
+declare function insertNodesBefore(parent: ParentNode & Node, nodes: Node[], anchor: Node | null): void;
+/**
+ * Remove an array of nodes from the DOM.
+ */
+declare function removeNodes(nodes: Node[]): void;
+
+/**
+ * List Helpers for Compiler-Generated Fine-Grained Updates
+ *
+ * These helpers are used by the compiler to generate efficient keyed list rendering.
+ * They provide low-level primitives for DOM node manipulation without rebuilding.
+ */
+
+/**
+ * A keyed block represents a single item in a list with its associated DOM nodes and state
+ */
+interface KeyedBlock<T = unknown> {
+    /** Unique key for this block */
+    key: string | number;
+    /** DOM nodes belonging to this block */
+    nodes: Node[];
+    /** Root context for lifecycle management */
+    root: RootContext;
+    /** Signal containing the current item value */
+    item: SignalAccessor<T>;
+    /** Signal containing the current index */
+    index: SignalAccessor<number>;
+    /** Last raw item value assigned to this block */
+    rawItem: T;
+    /** Last raw index value assigned to this block */
+    rawIndex: number;
+}
+/**
+ * Container for managing keyed list blocks
+ */
+interface KeyedListContainer<T = unknown> {
+    /** Start marker comment node */
+    startMarker: Comment;
+    /** End marker comment node */
+    endMarker: Comment;
+    /** Map of key to block */
+    blocks: Map<string | number, KeyedBlock<T>>;
+    /** Scratch map reused for the next render */
+    nextBlocks: Map<string | number, KeyedBlock<T>>;
+    /** Current nodes in DOM order (including markers) */
+    currentNodes: Node[];
+    /** Next-frame node buffer to avoid reallocations */
+    nextNodes: Node[];
+    /** Ordered blocks in current DOM order */
+    orderedBlocks: KeyedBlock<T>[];
+    /** Next-frame ordered block buffer to avoid reallocations */
+    nextOrderedBlocks: KeyedBlock<T>[];
+    /** Track position of keys in the ordered buffer to handle duplicates */
+    orderedIndexByKey: Map<string | number, number>;
+    /** Cleanup function */
+    dispose: () => void;
+}
+/**
+ * Binding handle returned by createKeyedList for compiler-generated code
+ */
+interface KeyedListBinding {
+    /** Document fragment placeholder inserted by the compiler/runtime */
+    marker: DocumentFragment;
+    /** Start marker comment node */
+    startMarker: Comment;
+    /** End marker comment node */
+    endMarker: Comment;
+    /** Flush pending items - call after markers are inserted into DOM */
+    flush?: () => void;
+    /** Cleanup function */
+    dispose: () => void;
+}
+type FineGrainedRenderItem<T> = (itemSig: SignalAccessor<T>, indexSig: SignalAccessor<number>, key: string | number) => Node[];
+/**
+ * A block identified by start/end comment markers.
+ */
+interface MarkerBlock {
+    start: Comment;
+    end: Comment;
+    root?: RootContext;
+}
+/**
+ * Remove an array of nodes from the DOM
+ *
+ * @param nodes - Array of nodes to remove
+ */
+/**
+ * Move an entire marker-delimited block (including markers) before the anchor.
+ */
+declare function moveMarkerBlock(parent: Node, block: MarkerBlock, anchor: Node | null): void;
+/**
+ * Destroy a marker-delimited block, removing nodes and destroying the associated root.
+ */
+declare function destroyMarkerBlock(block: MarkerBlock): void;
+/**
+ * Create a container for managing a keyed list.
+ * This sets up the marker nodes and provides cleanup.
+ *
+ * @returns Container object with markers, blocks map, and dispose function
+ */
+declare function createKeyedListContainer<T = unknown>(): KeyedListContainer<T>;
+/**
+ * Create a new keyed block with the given render function
+ *
+ * @param key - Unique key for this block
+ * @param item - Initial item value
+ * @param index - Initial index
+ * @param render - Function that creates the DOM nodes and sets up bindings
+ * @returns New KeyedBlock
+ */
+declare function createKeyedBlock<T>(key: string | number, item: T, index: number, render: (item: SignalAccessor<T>, index: SignalAccessor<number>, key: string | number) => Node[], needsIndex?: boolean): KeyedBlock<T>;
+/**
+ * Find the first node after the start marker (for getting current anchor)
+ */
+declare function getFirstNodeAfter(marker: Comment): Node | null;
+/**
+ * Create a keyed list binding with automatic diffing and DOM updates.
+ * This is used by compiler-generated code for efficient list rendering.
+ *
+ * @param getItems - Function that returns the current array of items
+ * @param keyFn - Function to extract unique key from each item
+ * @param renderItem - Function that creates DOM nodes for each item
+ * @returns Binding handle with markers and dispose function
+ */
+declare function createKeyedList<T>(getItems: () => T[], keyFn: (item: T, index: number) => string | number, renderItem: FineGrainedRenderItem<T>, needsIndex?: boolean): KeyedListBinding;
+
+interface HookContext {
+    slots: unknown[];
+    cursor: number;
+}
+declare function __fictUseContext(): HookContext;
+declare function __fictPushContext(): HookContext;
+declare function __fictPopContext(): void;
+declare function __fictResetContext(): void;
+declare function __fictUseSignal<T>(ctx: HookContext, initial: T, slot?: number): SignalAccessor<T>;
+declare function __fictUseMemo<T>(ctx: HookContext, fn: () => T, slot?: number): ComputedAccessor<T>;
+declare function __fictUseEffect(ctx: HookContext, fn: () => void, slot?: number): void;
+declare function __fictRender<T>(ctx: HookContext, fn: () => T): T;
+
+/**
+ * @internal
+ * Marks a zero-arg getter so props proxy can lazily evaluate it.
+ * Users normally never call this directly; the compiler injects it.
+ */
+declare function __fictProp<T>(getter: () => T): () => T;
+declare function createPropsProxy<T extends Record<string, unknown>>(props: T): T;
+/**
+ * Create a rest-like props object while preserving prop getters.
+ * Excludes the specified keys from the returned object.
+ */
+declare function __fictPropsRest<T extends Record<string, unknown>>(props: T, exclude: (string | number | symbol)[]): Record<string, unknown>;
+/**
+ * Merge multiple props-like objects while preserving lazy getters.
+ * Later sources override earlier ones.
+ *
+ * Uses lazy lookup strategy - properties are only accessed when read,
+ * avoiding upfront iteration of all keys.
+ */
+type MergeSource<T extends Record<string, unknown>> = T | (() => T);
+declare function mergeProps<T extends Record<string, unknown>>(...sources: (MergeSource<T> | null | undefined)[]): Record<string, unknown>;
+type PropGetter<T> = (() => T) & {
+    __fictProp: true;
+};
+/**
+ * Memoize a prop getter to cache expensive computations.
+ * Use when prop expressions involve heavy calculations.
+ *
+ * @example
+ * ```tsx
+ * // Without useProp - recomputes on every access
+ * <Child data={expensiveComputation(list, filter)} />
+ *
+ * // With useProp - cached until dependencies change, auto-unwrapped by props proxy
+ * const memoizedData = useProp(() => expensiveComputation(list, filter))
+ * <Child data={memoizedData} />
+ * ```
+ */
+declare function useProp<T>(getter: () => T): PropGetter<T>;
+
+export { $state, Fragment, __fictPopContext, __fictProp, __fictPropsRest, __fictPushContext, __fictRender, __fictResetContext, __fictUseContext, __fictUseEffect, __fictUseMemo, __fictUseSignal, batch, bindAttribute, bindClass, bindEvent, bindProperty, bindRef, bindStyle, bindText, clearDelegatedEvents, createConditional, createEffect, createElement, createKeyedBlock, createKeyedList, createKeyedListContainer, createList, createMemo, createPropsProxy, createRenderEffect, createSelector, signal as createSignal, delegateEvents, destroyMarkerBlock, getFirstNodeAfter, insert, insertNodesBefore, mergeProps, moveMarkerBlock, onDestroy, __fictProp as prop, removeNodes, render, template, toNodeArray, untrack, useProp };