@fictjs/runtime 0.0.12 → 0.0.13

package/dist/slim.d.cts

@@ -1,504 +0,0 @@
-/**
- * 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;
-/**
- * Effect scope disposer - function to dispose an effect scope
- */
-type EffectScopeDisposer = () => void;
-/**
- * Create a reactive signal
- * @param initialValue - The initial value
- * @returns A signal accessor function
- */
-declare function signal<T>(initialValue: T): SignalAccessor<T>;
-/**
- * Create a reactive effect scope
- * @param fn - The scope function
- * @returns An effect scope disposer function
- */
-declare function effectScope(fn: () => void): EffectScopeDisposer;
-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;
-
-/**
- * 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;
-}
-/**
- * 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: 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;
-/**
- * Bind a reactive style value to an existing element.
- */
-declare function bindStyle(el: Element, getValue: () => string | Record<string, string | number> | null | undefined): Cleanup;
-/**
- * Bind a reactive class value to an existing element.
- */
-declare function bindClass(el: Element, 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: ParentNode & Node, getValue: () => FictNode, markerOrCreateElement?: Node | CreateElementFn, createElementFn?: CreateElementFn): Cleanup;
-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;
-/**
- * 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;
-/**
- * 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.
- * The render callback receives signal accessors for the item and index.
- */
-declare function createList<T>(items: () => T[], renderItem: (item: SignalAccessor<T>, index: SignalAccessor<number>) => FictNode, createElementFn: CreateElementFn, getKey?: KeyFn<T>): BindingHandle;
-
-interface ReactiveScope {
-    run<T>(fn: () => T): T;
-    stop(): void;
-}
-/**
- * Create an explicit reactive scope that can contain effects/memos and be stopped manually.
- * The scope registers with the current root for cleanup.
- */
-declare function createScope(): ReactiveScope;
-/**
- * Run a block of reactive code inside a managed scope that follows a boolean flag.
- * When the flag turns false, the scope is disposed and all contained effects/memos are cleaned up.
- */
-declare function runInScope(flag: MaybeReactive<boolean>, fn: () => void): void;
-
-declare function batch<T>(fn: () => T): T;
-declare function untrack<T>(fn: () => T): T;
-
-/**
- * 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, hostRoot?: RootContext): 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;
-    rendering?: boolean;
-}
-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, type ReactiveScope, __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, createScope, createSelector, signal as createSignal, delegateEvents, destroyMarkerBlock, effectScope, getFirstNodeAfter, insert, insertNodesBefore, mergeProps, moveMarkerBlock, onDestroy, __fictProp as prop, removeNodes, render, runInScope, template, toNodeArray, untrack, useProp };