@mateosuarezdev/flash 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,600 @@
+/**
+ * @license
+ * Flash
+ * Copyright (c) 2025 Mateo Suarez. All rights reserved.
+ *
+ * Free to use in your own personal or commercial applications and projects.
+ * Unauthorized copying, modification, or distribution is strictly prohibited.
+ * See LICENSE file for full terms.
+ */
+
+import { batch } from '@preact/signals-core';
+import { Computed } from '@preact/signals-core';
+import { computed } from '@preact/signals-core';
+import { Effect } from '@preact/signals-core';
+import { effect } from '@preact/signals-core';
+import { Signal } from '@preact/signals-core';
+import { signal } from '@preact/signals-core';
+
+export { batch }
+
+declare class CancelToken {
+    private _cancelled;
+    private _cancelCallbacks;
+    get cancelled(): boolean;
+    cancel(): void;
+    onCancel(callback: () => void): void;
+    throwIfCancelled(): void;
+}
+
+/**
+ * Chain configuration - without read phase
+ */
+declare interface ChainConfigWithoutRead<U> {
+    update: (readData?: any, data?: FrameData) => U;
+    render: (data: U, frameData?: FrameData) => void;
+}
+
+/**
+ * Chain configuration - without update phase
+ */
+declare interface ChainConfigWithoutUpdate<R> {
+    read: (data?: FrameData) => R;
+    render: (data: R, frameData?: FrameData) => void;
+}
+
+/**
+ * Chain configuration object
+ * Must have at least read+render OR read+update+render
+ */
+/**
+ * Chain configuration - with update phase
+ */
+declare interface ChainConfigWithUpdate<R, U> {
+    read: (data?: FrameData) => R;
+    update: (readData: R, data?: FrameData) => U;
+    render: (data: U, frameData?: FrameData) => void;
+}
+
+export declare type Child = IntrinsicVNode | VNode | ReactiveVNode | Text | string | number | boolean | null | undefined | (() => Child);
+
+export declare type Children = Child | Children[];
+
+declare type ComponentFunction<P = Props> = (props: P) => Child;
+
+export { Computed }
+
+export { computed }
+
+declare interface Context<T> {
+    _id: Symbol;
+    _defaultValue: T;
+    provide: (value: T) => void;
+}
+
+export declare function createContext<T>(defaultValue: T): Context<T>;
+
+/**
+ * Factory function for creating gestures - the only exported function
+ * Returns an object with just init() and destroy() methods
+ */
+export declare function createGesture(el: HTMLElement, options: GestureOptions): Gesture;
+
+export { Effect }
+
+export { effect }
+
+export declare const Fragment: unique symbol;
+
+/**
+ * Frame scheduler implementation inspired by Framer Motion
+ * Provides a high-performance animation loop with read-update-render phases
+ * to prevent layout thrashing and optimize DOM operations.
+ */
+declare type FrameCallback = (data?: FrameData) => void;
+
+declare interface FrameData {
+    timestamp: number;
+    delta: number;
+}
+
+export declare class FrameScheduler {
+    private readCallbacks;
+    private updateCallbacks;
+    private renderCallbacks;
+    private readKeepAlive;
+    private updateKeepAlive;
+    private renderKeepAlive;
+    private isProcessing;
+    private frameScheduled;
+    private frameId;
+    private lastTimestamp;
+    private currentDelta;
+    private readonly trackFPS;
+    private readonly fpsHistorySize;
+    private fpsHistory;
+    constructor(options?: FrameSchedulerOptions);
+    /**
+     * Schedule a callback to run in the READ phase (for DOM measurements)
+     * Use this for: offsetHeight, getBoundingClientRect, getComputedStyle, etc.
+     *
+     * @param callback - Function to execute during the read phase
+     * @param keepAlive - If true, callback runs every frame until cancelled
+     * @returns The callback function (can be passed to cancelFrame)
+     *
+     * @example
+     * frame.read(() => {
+     *   const height = element.offsetHeight;
+     * });
+     *
+     * // With frame data if needed
+     * frame.read((data) => {
+     *   console.log('Delta:', data.delta);
+     * });
+     */
+    read(callback: FrameCallback, keepAlive?: boolean): FrameCallback;
+    /**
+     * Schedule a callback to run in the UPDATE phase (for calculations)
+     * Use this for: computing animation values, business logic, etc.
+     *
+     * @param callback - Function to execute during the update phase
+     * @param keepAlive - If true, callback runs every frame until cancelled
+     * @returns The callback function (can be passed to cancelFrame)
+     *
+     * @example
+     * frame.update(() => {
+     *   position += velocity;
+     * });
+     *
+     * // Delta-time independent animation
+     * frame.update((data) => {
+     *   position += velocity * (data.delta / 1000);
+     * }, true);
+     */
+    update(callback: FrameCallback, keepAlive?: boolean): FrameCallback;
+    /**
+     * Schedule a callback to run in the RENDER phase (for DOM writes)
+     * Use this for: style updates, classList changes, DOM mutations, etc.
+     *
+     * @param callback - Function to execute during the render phase
+     * @param keepAlive - If true, callback runs every frame until cancelled
+     * @returns The callback function (can be passed to cancelFrame)
+     *
+     * @example
+     * frame.render(() => {
+     *   element.style.transform = `translateX(${x}px)`;
+     * });
+     */
+    render(callback: FrameCallback, keepAlive?: boolean): FrameCallback;
+    /**
+     * Schedule a read-update-render chain with typed data flow
+     * Must provide at least read+render or read+update+render
+     *
+     * @example
+     * // With update
+     * frame.chain({
+     *   read: () => element.offsetHeight,
+     *   update: (height) => height * 2,
+     *   render: (doubled) => element.style.height = `${doubled}px`
+     * });
+     *
+     * // Without update (render receives read data directly)
+     * frame.chain({
+     *   read: () => element.offsetHeight,
+     *   render: (height) => element.style.height = `${height}px`
+     * });
+     */
+    chain<R, U>(config: ChainConfigWithUpdate<R, U>): void;
+    chain<R>(config: ChainConfigWithoutUpdate<R>): void;
+    chain<U>(config: ChainConfigWithoutRead<U>): void;
+    /**
+     * Cancel a scheduled callback from all phases
+     *
+     * @param callback - The callback function to cancel
+     */
+    cancel(callback: FrameCallback): void;
+    /**
+     * Cancel all scheduled callbacks and stop the frame loop
+     */
+    cancelAll(): void;
+    /**
+     * Get current frame data (timestamp and delta)
+     */
+    get data(): FrameData;
+    /**
+     * Check if frame loop is currently running
+     */
+    get isRunning(): boolean;
+    /**
+     * Get current instantaneous FPS
+     * Only available if trackFPS is enabled
+     */
+    get fps(): number;
+    /**
+     * Get average FPS over the history window
+     * Only available if trackFPS is enabled
+     */
+    get averageFps(): number;
+    /**
+     * Get estimated refresh rate (rounded FPS)
+     * Only available if trackFPS is enabled
+     */
+    get refreshRate(): number;
+    private scheduleFrame;
+    private processFrame;
+    private executeCallbacks;
+    private hasKeepAliveCallbacks;
+    private isKeepAliveSet;
+}
+
+declare interface FrameSchedulerOptions {
+    /** Enable FPS tracking (adds minimal overhead) */
+    trackFPS?: boolean;
+    /** Number of frames to track for average FPS calculation */
+    fpsHistorySize?: number;
+}
+
+/**
+ * Main Gesture Class with public and private members
+ */
+declare class Gesture {
+    private el;
+    private options;
+    private details;
+    private minTouches;
+    private maxTouches;
+    private threshold;
+    private direction;
+    private lastMoveTime;
+    private prevX;
+    private prevY;
+    private initialDistance;
+    private initialAngle;
+    private boundOnStart;
+    private boundOnMove;
+    private boundOnEnd;
+    private passive;
+    private hasPassedThreshold;
+    private controller;
+    private id;
+    private name;
+    private priority;
+    private useThreshold;
+    constructor(controller: GestureController, id: number, el: HTMLElement, name: string, priority: number, options: GestureOptions);
+    /**
+     * Calculate distance between two touch points
+     */
+    private getDistance;
+    /**
+     * Calculate angle between two touch points in degrees
+     */
+    private getAngle;
+    /**
+     * Get center point of all touches
+     */
+    private getCenter;
+    /**
+     * Check if the gesture can start based on touch count
+     */
+    private canStart;
+    /**
+     * Check if we've moved enough to pass the threshold
+     */
+    private checkThreshold;
+    private onStart;
+    private onMove;
+    private tryCapture;
+    private onEnd;
+    /**
+     * Public method to initialize the gesture
+     */
+    init(): void;
+    /**
+     * Public method to clean up the gesture
+     */
+    destroy(): void;
+}
+
+/**
+ * Gesture Controller - manages and coordinates between multiple gestures
+ * This is kept as a private class not exported from the module
+ */
+declare class GestureController {
+    private gestureId;
+    private activeGestures;
+    private disabledGestures;
+    private capturedId?;
+    private gestureWithPriority;
+    private maxPriority;
+    /**
+     * Creates a new gesture ID
+     */
+    private newId;
+    /**
+     * Check if a gesture can start
+     */
+    canStart(gestureName: string): boolean;
+    /**
+     * Register a gesture as wanting to start
+     */
+    start(id: number, gestureName: string, priority: number): boolean;
+    /**
+     * Attempt to capture control with this gesture
+     */
+    capture(id: number, gestureName: string, priority: number): boolean;
+    /**
+     * Release a gesture's attempt to capture
+     */
+    release(id: number): void;
+    /**
+     * Disable a specific gesture type
+     */
+    disableGesture(gestureName: string, id: number): void;
+    /**
+     * Enable a previously disabled gesture type
+     */
+    enableGesture(gestureName: string, id: number): void;
+    /**
+     * Create a gesture through this controller
+     */
+    createGesture(el: HTMLElement, options: GestureOptions): Gesture;
+}
+
+declare type GestureDetails = {
+    isTracking: boolean;
+    startX: number;
+    startY: number;
+    currentX: number;
+    currentY: number;
+    deltaX: number;
+    deltaY: number;
+    velocityX: number;
+    velocityY: number;
+    touchCount: number;
+    scale: number;
+    rotation: number;
+    type: string;
+    event?: TouchEvent | MouseEvent;
+};
+
+declare type GestureDirection = "x" | "y" | "all";
+
+declare type GestureOptions = {
+    name?: string;
+    priority?: number;
+    threshold?: number;
+    direction?: GestureDirection;
+    minTouches?: number;
+    maxTouches?: number;
+    passive?: boolean;
+    canStart?: (details: GestureDetails) => boolean;
+    onStart?: (details: GestureDetails) => void;
+    onMove?: (details: GestureDetails) => void;
+    onEnd?: (details: GestureDetails) => void;
+};
+
+/**
+ * Performs a tracking read of a value.
+ * If the input is a Signal, it accesses the value and registers a dependency
+ * if called within a reactive context (like effect or computed).
+ *
+ * @template T
+ * @param {HybridSignal<T>} toRead - The signal or static value to subscribe to.
+ * @returns {T} The current value.
+ */
+export declare function get<T>(toRead: HybridSignal<T>): T;
+
+/**
+ * Represents a value that is either static or a lazy reactive computation.
+ * Use this for props that will be passed directly into JSX boundaries.
+ * @template T
+ */
+export declare type HybridReactive<T> = T | (() => T);
+
+/**
+ * Represents a value that is either static or a direct Signal instance.
+ * Use this for data sources that need to be read or tracked within component logic.
+ * @template T
+ */
+export declare type HybridSignal<T> = T | Signal<T>;
+
+export declare function hydrate(node: JSX.Element, container: HTMLElement, mode?: HydrationMode): void;
+
+declare type HydrationMode = "self" | "children";
+
+declare interface IntrinsicVNode {
+    type: string;
+    kind: "IntrinsicVNode";
+    props: Props;
+    key?: Key;
+    _id: number;
+    _dom?: HTMLElement | SVGElement;
+    _parent: VNode | ReactiveVNode | IntrinsicVNode | null;
+    _renderedChildren: (VNode | ReactiveVNode | IntrinsicVNode)[];
+    _onMountCallbacks: (() => void)[];
+    _onUnmountCallbacks: (() => void)[];
+    _onBeforeExitCallbacks: ((token: CancelToken) => void | Promise<void>)[];
+    _lifecycleState?: "mounting" | "mounted" | "exiting" | "exited";
+}
+
+declare type Key = string | number;
+
+/**
+ * Normalizes a value into a format suitable for JSX rendering.
+ * Converts Signals into reactive getters and passes through primitives or
+ * existing reactive boundaries. This ensures the UI remains fine-grained.
+ *
+ * @template T
+ * @param {HybridSignal<T> | HybridReactive<T>} toBind - The input to normalize.
+ * @returns {T | (() => T)} A static value or a reactive function wrapper.
+ */
+export declare function link<T>(toBind: HybridSignal<T> | HybridReactive<T>): HybridReactive<T>;
+
+/**
+ * Register a callback to run before the component exits (for exit animations).
+ * Can be sync or async.
+ * Receives a CancelToken to handle animation interruption.
+ *
+ * @example
+ * onBeforeExit(async (token) => {
+ *   const animation = animate(ref, { opacity: 0 });
+ *
+ *   // Handle cancellation - reverse the animation
+ *   token.onCancel(() => {
+ *     animation.reverse();
+ *   });
+ *
+ *   await animation.finished;
+ * });
+ */
+export declare function onBeforeExit(callback: (token: CancelToken) => void | Promise<void>): void;
+
+/**
+ * This code will run after page loads
+ * on client side only, way before any flash
+ * runtime related code, use it for a pure
+ * vanilla workflow or to enhance instant
+ * hydration experiences, letting flash
+ * hydrate later, inside here, flash refs
+ * will not exist, but html parsed dom will
+ *
+ * You can also use it to opt out of flash for client side
+ * and add pure standard vanilla interactivity
+ * so you get JSX server rendered HTML Templating with
+ * all it's advantages, and fine grained per page bundle
+ * with vanilla js integrations
+ *
+ * @example
+ * onLoad(() => {
+ *  const someEl = document.getElementById("element-id")
+ *
+ *  fancyCriticalEnterAnimation(someEL)
+ * })
+ */
+export declare function onLoad(cb: VoidFunction): void;
+
+/**
+ * Register a callback to run when the component is mounted.
+ */
+export declare function onMount(callback: () => void): void;
+
+/**
+ * Register a callback to run when the component is unmounted.
+ */
+export declare function onUnmount(callback: () => void): void;
+
+/**
+ * Performs a non-tracking read of a value.
+ * If the input is a Signal, it returns the current value without subscribing
+ * the caller to future changes.
+ *
+ * @template T
+ * @param {HybridSignal<T>} toRead - The signal or static value to peek.
+ * @returns {T} The current raw value.
+ */
+export declare function peek<T>(toRead: HybridSignal<T>): T;
+
+declare interface Props {
+    children?: Children;
+    ref?: (element: HTMLElement | SVGElement) => void;
+    key?: string | number;
+    [key: string]: any;
+}
+
+declare interface ReactiveVNode {
+    type: "reactive";
+    kind: "ReactiveVNode";
+    fn: () => Child;
+    _id: number;
+    _dispose: VoidFunction | null;
+    _currentChild: VNode | IntrinsicVNode | ReactiveVNode | null;
+    _currentDom: Node | null;
+    _placeholder: Comment | null;
+    _parent: VNode | ReactiveVNode | IntrinsicVNode | null;
+    _renderedChildren: (VNode | ReactiveVNode | IntrinsicVNode)[];
+    _listState?: {
+        items: any[];
+    };
+}
+
+export declare function render(node: JSX.Element, container: HTMLElement): void;
+
+/**
+ * Sets the new value of a signal
+ */
+export declare function set<T>(signal: Signal<T>, value: T | (() => T)): void;
+
+export { Signal }
+
+export { signal }
+
+export declare function startViewTransition(cb: VoidFunction): void;
+
+/**
+ * Creates a suspended component that handles async data fetching
+ * with loading and error states.
+ *
+ * @param asyncFn - Async function that returns a Child (component)
+ * @param fallback - Component to show while loading (default: "Loading...")
+ * @param errorFallback - Component or function to show on error (default: "Error")
+ *
+ * @example
+ * ```tsx
+ * const UserProfile = suspend(
+ *   async ({ userId }) => {
+ *     const user = await fetchUser(userId);
+ *     return <div>{user.name}</div>;
+ *   },
+ *   <div>Loading user...</div>,
+ *   (error) => <div>Error: {error.message}</div>
+ * );
+ * ```
+ */
+export declare function suspend<P = any>(asyncFn: (props: P) => Promise<Child>, fallback?: Child, errorFallback?: Child | ((error: Error) => Child)): SuspendedComponent<P>;
+
+/**
+ * Component function that always returns a SuspendedVNode
+ */
+declare type SuspendedComponent<P = any> = (props: P) => SuspendedVNode;
+
+declare interface SuspendedVNode {
+    type: "suspended";
+    kind: "SuspendedVNode";
+    promise: Promise<Child>;
+    fallback: Child;
+    errorFallback: Child | ((error: Error) => Child);
+    _id: number;
+    _componentName: string;
+    _parent: VNode | ReactiveVNode | IntrinsicVNode | SuspendedVNode | null;
+    _renderedChildren: (VNode | ReactiveVNode | IntrinsicVNode | SuspendedVNode)[];
+    _currentChild: VNode | IntrinsicVNode | ReactiveVNode | SuspendedVNode | null;
+    _state: "pending" | "resolved" | "error";
+}
+
+export declare function useContext<T>(context: Context<T>): T;
+
+declare interface ViewTransitionOptions {
+    duration?: number;
+    namePrefix?: string;
+}
+
+declare interface VNode {
+    type: ComponentFunction;
+    kind: "VNode";
+    props: Props;
+    children: Children;
+    key?: Key;
+    _id: number;
+    _onMountCallbacks: (() => void)[];
+    _onUnmountCallbacks: (() => void)[];
+    _onBeforeExitCallbacks: ((token: CancelToken) => void | Promise<void>)[];
+    _element: Node | null;
+    _parent: VNode | ReactiveVNode | IntrinsicVNode | null;
+    _renderedChildren: (VNode | ReactiveVNode | IntrinsicVNode)[];
+    _lifecycleState?: "mounting" | "mounted" | "exiting" | "exited";
+    _contextMap?: Map<Symbol, any>;
+}
+
+export declare function withViewTransition(mutate: () => void, elements?: HTMLElement[], options?: ViewTransitionOptions): void;
+
+export { }