tekiyo-physics 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,846 @@
+import { default as default_2 } from 'react';
+import { JSX as JSX_2 } from 'react/jsx-runtime';
+
+export declare interface Bounds {
+    left?: number;
+    right?: number;
+    top?: number;
+    bottom?: number;
+}
+
+/**
+ * Premium card component with physics-based interactions
+ * Features lift on hover, press feedback, and optional glassmorphism
+ */
+export declare const Card: default_2.ForwardRefExoticComponent<CardProps & default_2.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Default card styles (optional, can be applied via className)
+ */
+export declare const cardBaseStyles: default_2.CSSProperties;
+
+export declare interface CardProps {
+    children: default_2.ReactNode;
+    /** Enable hover lift effect (default: true) */
+    lift?: boolean;
+    /** Enable press feedback (default: true) */
+    pressable?: boolean;
+    /** Scale on lift (overrides context) */
+    liftScale?: number;
+    /** Scale reduction on press (default: 0.98) */
+    pressScale?: number;
+    /** Enable glassmorphism background */
+    glass?: boolean;
+    /** Glass blur intensity (default: 20) */
+    glassBlur?: number;
+    /** Spring configuration override */
+    springConfig?: Partial<SpringConfig>;
+    /** Additional class name */
+    className?: string;
+    /** Additional inline styles */
+    style?: default_2.CSSProperties;
+    /** Click handler */
+    onClick?: (e: default_2.MouseEvent) => void;
+    /** Callback when hover state changes */
+    onHover?: (isHovered: boolean) => void;
+    /** Callback when press state changes */
+    onPress?: (isPressed: boolean) => void;
+}
+
+/**
+ * Combine lift style with other transforms
+ */
+export declare function combineLiftStyle(baseStyle: React.CSSProperties, liftStyle: React.CSSProperties): React.CSSProperties;
+
+/**
+ * Combine stretch with position transform
+ */
+export declare function combineStretchStyle(positionStyle: React.CSSProperties, stretchStyle: React.CSSProperties): React.CSSProperties;
+
+export declare const DEFAULT_FRICTION_CONFIG: FrictionConfig;
+
+export declare const DEFAULT_SPRING_CONFIG: SpringConfig;
+
+/**
+ * Draggable component with physics-based motion
+ * Combines drag, lift, and stretch effects
+ */
+export declare const Draggable: default_2.ForwardRefExoticComponent<DraggableProps & default_2.RefAttributes<HTMLDivElement>>;
+
+export declare interface DraggableProps {
+    children: default_2.ReactNode;
+    /** Initial position */
+    initial?: {
+        x: number;
+        y: number;
+    };
+    /** Movement bounds */
+    bounds?: Bounds;
+    /** Enable rubber band at bounds (default: true) */
+    rubberBand?: boolean;
+    /** Enable momentum after release (default: true) */
+    momentum?: boolean;
+    /** Enable lift effect on drag (default: true) */
+    lift?: boolean;
+    /** Enable velocity stretch (default: true) */
+    stretch?: boolean;
+    /** Snap points after release */
+    snapTo?: {
+        x: number;
+        y: number;
+    }[];
+    /** Lock to axis */
+    axis?: 'x' | 'y' | 'both';
+    /** Spring configuration override */
+    springConfig?: Partial<SpringConfig>;
+    /** Additional class name */
+    className?: string;
+    /** Additional inline styles */
+    style?: default_2.CSSProperties;
+    /** Callback on drag start */
+    onDragStart?: (position: {
+        x: number;
+        y: number;
+    }) => void;
+    /** Callback during drag */
+    onDrag?: (position: {
+        x: number;
+        y: number;
+    }) => void;
+    /** Callback on drag end */
+    onDragEnd?: (position: {
+        x: number;
+        y: number;
+    }, velocity: {
+        x: number;
+        y: number;
+    }) => void;
+    /** Callback when animation settles */
+    onRest?: (position: {
+        x: number;
+        y: number;
+    }) => void;
+}
+
+export declare interface FrictionConfig {
+    /** Friction coefficient (0.9-0.99, higher = less friction) */
+    decay: number;
+    /** Minimum velocity before stopping (default: 0.1) */
+    stopThreshold: number;
+    /** Maximum velocity cap (default: 5000 px/s) */
+    maxVelocity: number;
+}
+
+export declare function generatePhysicsId(prefix?: string): string;
+
+/**
+ * Gentle preset
+ * Soft, forgiving, approachable
+ * For friendly, accessible interfaces
+ */
+export declare const gentle: PhysicsPreset;
+
+export declare interface GestureBindings {
+    onPointerDown: (e: React.PointerEvent) => void;
+    onPointerEnter: (e: React.PointerEvent) => void;
+    onPointerLeave: (e: React.PointerEvent) => void;
+    onFocus: (e: React.FocusEvent) => void;
+    onBlur: (e: React.FocusEvent) => void;
+    style: React.CSSProperties;
+}
+
+export declare interface GestureHandlers {
+    onDragStart?: (state: GestureState) => void;
+    onDrag?: (state: GestureState) => void;
+    onDragEnd?: (state: GestureState) => void;
+    onFlick?: (state: GestureState & {
+        flickVelocity: Vector2;
+    }) => void;
+    onHover?: (hovering: boolean) => void;
+    onFocus?: (focused: boolean) => void;
+}
+
+export declare interface GestureState {
+    /** Current position relative to element */
+    position: Vector2;
+    /** Delta from last event */
+    delta: Vector2;
+    /** Delta from start of gesture */
+    offset: Vector2;
+    /** Current velocity in px/s */
+    velocity: Vector2;
+    /** Dominant movement direction */
+    direction: 'up' | 'down' | 'left' | 'right' | 'none';
+    /** Whether gesture is currently active */
+    active: boolean;
+    /** Whether this is first event of gesture */
+    first: boolean;
+    /** Whether this is last event of gesture */
+    last: boolean;
+    /** Original event */
+    event: PointerEvent;
+}
+
+/**
+ * Get friction config from preset name
+ */
+export declare function getFrictionConfig(preset: string | FrictionConfig): FrictionConfig;
+
+/**
+ * Get a preset by name
+ */
+export declare function getPreset(name: string): PhysicsPreset | undefined;
+
+/**
+ * Get spring config from preset name
+ */
+export declare function getSpringConfig(preset: string | SpringConfig): SpringConfig;
+
+/**
+ * iOS-like feel
+ * Smooth, natural, slightly bouncy response
+ * Premium Apple-style interactions
+ */
+export declare const ios: PhysicsPreset;
+
+/**
+ * Momentum system with exponential friction decay
+ * Provides natural deceleration after flick gestures
+ */
+export declare class Momentum {
+    private position;
+    private velocity;
+    private config;
+    private isActive;
+    constructor(initialPosition?: Vector2, config?: Partial<FrictionConfig>);
+    /**
+     * Start momentum with initial velocity
+     */
+    start(position: Vector2, velocity: Vector2): void;
+    /**
+     * Stop momentum immediately
+     */
+    stop(): void;
+    /**
+     * Update momentum simulation
+     * @param deltaTime Time in seconds
+     */
+    step(deltaTime: number): {
+        position: Vector2;
+        velocity: Vector2;
+        isActive: boolean;
+    };
+    /**
+     * Apply rubber band effect at boundaries
+     */
+    applyRubberBand(bounds: {
+        min: Vector2;
+        max: Vector2;
+    }, rubberBandFactor?: number): void;
+    getPosition(): Vector2;
+    getVelocity(): Vector2;
+    getIsActive(): boolean;
+    setPosition(position: Vector2): void;
+    updateConfig(config: Partial<FrictionConfig>): void;
+}
+
+/**
+ * 1D Momentum for single-axis motion
+ */
+export declare class Momentum1D {
+    private position;
+    private velocity;
+    private config;
+    private isActive;
+    constructor(initialPosition?: number, config?: Partial<FrictionConfig>);
+    start(position: number, velocity: number): void;
+    stop(): void;
+    step(deltaTime: number): {
+        position: number;
+        velocity: number;
+        isActive: boolean;
+    };
+    getPosition(): number;
+    setPosition(position: number): void;
+}
+
+export declare interface PhysicsContextValue {
+    spring: SpringConfig;
+    friction: FrictionConfig;
+    stretch: {
+        intensity: number;
+        maxVelocity: number;
+    };
+    lift: {
+        scale: number;
+        shadowIntensity: number;
+    };
+}
+
+export declare const PhysicsEngine: PhysicsEngineCore;
+
+/**
+ * Central physics engine with shared RAF loop
+ * Manages all physics simulations efficiently
+ */
+declare class PhysicsEngineCore {
+    private bodies;
+    private rafId;
+    private lastTime;
+    private isRunning;
+    private readonly maxDelta;
+    /**
+     * Register a physics body to receive updates
+     */
+    register(id: string, update: UpdateCallback, priority?: number): void;
+    /**
+     * Unregister a physics body
+     */
+    unregister(id: string): void;
+    /**
+     * Check if a body is registered
+     */
+    has(id: string): boolean;
+    /**
+     * Start the physics loop
+     */
+    private start;
+    /**
+     * Stop the physics loop
+     */
+    private stop;
+    /**
+     * Main RAF loop
+     */
+    private loop;
+    /**
+     * Get current number of active bodies
+     */
+    getActiveCount(): number;
+    /**
+     * Check if engine is running
+     */
+    getIsRunning(): boolean;
+}
+
+export declare interface PhysicsPreset {
+    name: string;
+    description: string;
+    spring: SpringConfig;
+    friction: FrictionConfig;
+    stretch: {
+        intensity: number;
+        maxVelocity: number;
+    };
+    lift: {
+        scale: number;
+        shadowIntensity: number;
+    };
+}
+
+/**
+ * Provider for global physics configuration
+ * Wrap your app or component tree to set defaults
+ */
+export declare function PhysicsProvider({ children, preset, spring, friction, stretch, lift, }: PhysicsProviderProps): JSX_2.Element;
+
+export declare interface PhysicsProviderProps {
+    children: default_2.ReactNode;
+    /** Preset name or custom configuration */
+    preset?: keyof typeof presets | PhysicsPreset;
+    /** Override spring config */
+    spring?: Partial<SpringConfig>;
+    /** Override friction config */
+    friction?: Partial<FrictionConfig>;
+    /** Override stretch config */
+    stretch?: Partial<{
+        intensity: number;
+        maxVelocity: number;
+    }>;
+    /** Override lift config */
+    lift?: Partial<{
+        scale: number;
+        shadowIntensity: number;
+    }>;
+}
+
+export declare const presets: Record<string, PhysicsPreset>;
+
+/**
+ * Smooth preset
+ * Slow, deliberate, luxurious feel
+ * For premium, elegant interfaces
+ */
+export declare const smooth: PhysicsPreset;
+
+/**
+ * Snappy preset
+ * Ultra-responsive, minimal lag
+ * For UI that needs to feel instant
+ */
+export declare const snappy: PhysicsPreset;
+
+/**
+ * Spring physics simulation using semi-implicit Euler integration
+ * Provides smooth, natural motion without overshoot
+ */
+export declare class Spring {
+    private position;
+    private velocity;
+    private target;
+    private config;
+    constructor(initialPosition?: Vector2, config?: Partial<SpringConfig>);
+    setTarget(target: Vector2): void;
+    setPosition(position: Vector2): void;
+    setVelocity(velocity: Vector2): void;
+    updateConfig(config: Partial<SpringConfig>): void;
+    /**
+     * Advance the spring simulation by deltaTime seconds
+     * Uses semi-implicit Euler for stability
+     */
+    step(deltaTime: number): SpringState;
+    getState(): SpringState;
+    /**
+     * Immediately snap to target
+     */
+    snapToTarget(): void;
+}
+
+/**
+ * 1D Spring for single-value animations (scale, opacity, etc.)
+ */
+export declare class Spring1D {
+    private position;
+    private velocity;
+    private target;
+    private config;
+    constructor(initialValue?: number, config?: Partial<SpringConfig>);
+    setTarget(target: number): void;
+    setPosition(position: number): void;
+    setVelocity(velocity: number): void;
+    step(deltaTime: number): {
+        value: number;
+        velocity: number;
+        isSettled: boolean;
+    };
+    getValue(): number;
+    snapToTarget(): void;
+}
+
+export declare interface SpringConfig {
+    /** Force pulling toward target (100-500, default: 170) */
+    tension: number;
+    /** Resistance to motion (10-50, default: 26) */
+    friction: number;
+    /** Virtual mass affecting inertia (0.5-3, default: 1) */
+    mass: number;
+    /** Threshold to consider animation complete (default: 0.01) */
+    precision: number;
+}
+
+export declare interface SpringState {
+    position: Vector2;
+    velocity: Vector2;
+    target: Vector2;
+    isSettled: boolean;
+}
+
+/**
+ * Stiff preset
+ * Minimal overshoot, direct response
+ * For precision interfaces
+ */
+export declare const stiff: PhysicsPreset;
+
+declare type UpdateCallback = (deltaTime: number) => void;
+
+export declare function useDrag(options?: UseDragOptions): UseDragReturn;
+
+export declare interface UseDragOptions {
+    /** Initial position */
+    initial?: {
+        x: number;
+        y: number;
+    };
+    /** Movement bounds */
+    bounds?: Bounds;
+    /** Enable rubber band effect at bounds (default: true) */
+    rubberBand?: boolean;
+    /** Rubber band resistance (0-1, default: 0.55) */
+    rubberBandFactor?: number;
+    /** Enable momentum after release (default: true) */
+    momentum?: boolean;
+    /** Snap to positions after release */
+    snapTo?: {
+        x: number;
+        y: number;
+    }[];
+    /** Snap threshold distance (default: 50) */
+    snapThreshold?: number;
+    /** Lock to single axis */
+    axis?: 'x' | 'y' | 'both';
+    /** Spring configuration for snap */
+    springConfig?: Partial<SpringConfig>;
+    /** Friction configuration for momentum */
+    frictionConfig?: Partial<FrictionConfig>;
+    /** Callback on drag start */
+    onDragStart?: (position: Vector2) => void;
+    /** Callback during drag */
+    onDrag?: (position: Vector2) => void;
+    /** Callback on drag end */
+    onDragEnd?: (position: Vector2, velocity: Vector2) => void;
+    /** Callback when settled */
+    onRest?: (position: Vector2) => void;
+}
+
+export declare interface UseDragReturn {
+    /** Current x position */
+    x: number;
+    /** Current y position */
+    y: number;
+    /** Whether currently dragging */
+    isDragging: boolean;
+    /** Whether momentum is active */
+    isMomentum: boolean;
+    /** CSS style object */
+    style: React.CSSProperties;
+    /** Bind to element */
+    bind: {
+        onPointerDown: (e: React.PointerEvent) => void;
+        style: React.CSSProperties;
+    };
+    /** Set position programmatically */
+    setPosition: (position: {
+        x: number;
+        y: number;
+    }) => void;
+    /** Snap to position with spring */
+    snapToPosition: (position: {
+        x: number;
+        y: number;
+    }) => void;
+}
+
+export declare function useFlick(options?: UseFlickOptions): UseFlickReturn;
+
+export declare interface UseFlickOptions {
+    /** Initial position */
+    initial?: {
+        x: number;
+        y: number;
+    };
+    /** Minimum velocity to trigger flick (default: 500 px/s) */
+    threshold?: number;
+    /** Friction configuration */
+    friction?: Partial<FrictionConfig>;
+    /** Lock to single axis */
+    axis?: 'x' | 'y' | 'both';
+    /** Callback when flick starts */
+    onFlickStart?: (velocity: Vector2) => void;
+    /** Callback during flick momentum */
+    onFlick?: (position: Vector2, velocity: Vector2) => void;
+    /** Callback when flick ends */
+    onFlickEnd?: (position: Vector2) => void;
+}
+
+export declare interface UseFlickReturn {
+    /** Current x position */
+    x: number;
+    /** Current y position */
+    y: number;
+    /** Whether flick momentum is active */
+    isFlicking: boolean;
+    /** Current velocity */
+    velocity: Vector2;
+    /** CSS style object */
+    style: React.CSSProperties;
+    /** Trigger a flick with given velocity */
+    flick: (velocity: {
+        x: number;
+        y: number;
+    }) => void;
+    /** Stop current flick */
+    stop: () => void;
+    /** Set position (stops any active flick) */
+    setPosition: (position: {
+        x: number;
+        y: number;
+    }) => void;
+    /** Record position sample for velocity tracking */
+    recordSample: (position: {
+        x: number;
+        y: number;
+    }) => void;
+    /** Get current velocity from samples */
+    getCurrentVelocity: () => Vector2;
+    /** Release with current velocity (triggers flick if above threshold) */
+    release: (position: {
+        x: number;
+        y: number;
+    }) => boolean;
+}
+
+/**
+ * Hook to get friction config from context
+ */
+export declare function useFrictionConfig(): Partial<FrictionConfig>;
+
+export declare function useGesture(options: UseGestureOptions): GestureBindings;
+
+export declare interface UseGestureOptions extends GestureHandlers {
+    /** Minimum distance before drag starts (default: 3) */
+    threshold?: number;
+    /** Minimum velocity for flick detection (default: 500 px/s) */
+    flickThreshold?: number;
+    /** Enable touch action prevention */
+    preventTouch?: boolean;
+}
+
+export declare function useLift(options?: UseLiftOptions): UseLiftReturn;
+
+/**
+ * Hook to get lift config from context
+ */
+export declare function useLiftConfig(): {
+    scale: number;
+    shadowIntensity: number;
+};
+
+export declare interface UseLiftOptions {
+    /** When to activate lift effect */
+    trigger?: 'hover' | 'drag' | 'focus' | 'active';
+    /** Scale factor when lifted (default: 1.03) */
+    scale?: number;
+    /** Enable dynamic shadow (default: true) */
+    shadow?: boolean;
+    /** Shadow intensity multiplier (default: 1) */
+    shadowIntensity?: number;
+    /** Spring configuration */
+    springConfig?: Partial<SpringConfig>;
+    /** Callback when lift state changes */
+    onLift?: (isLifted: boolean) => void;
+}
+
+export declare interface UseLiftReturn {
+    /** Whether element is currently lifted */
+    isLifted: boolean;
+    /** Current scale value */
+    scale: number;
+    /** CSS style object */
+    style: React.CSSProperties;
+    /** Event handlers to bind */
+    bind: {
+        onPointerEnter?: () => void;
+        onPointerLeave?: () => void;
+        onPointerDown?: () => void;
+        onPointerUp?: () => void;
+        onFocus?: () => void;
+        onBlur?: () => void;
+    };
+    /** Manually set lift state */
+    setLifted: (lifted: boolean) => void;
+}
+
+/**
+ * Hook to get spring config from context
+ */
+export declare function usePhysicsConfig(): Partial<SpringConfig>;
+
+/**
+ * Hook to access physics configuration
+ */
+export declare function usePhysicsContext(): PhysicsContextValue;
+
+export declare function useSpring(options: UseSpringOptions): UseSpringReturn;
+
+export declare function useSpring1D(options: UseSpring1DOptions): {
+    value: number;
+    isAnimating: boolean;
+    isSettled: boolean;
+    setTarget: (target: number) => void;
+};
+
+/**
+ * 1D Spring hook for single values (scale, opacity, rotation, etc.)
+ */
+export declare interface UseSpring1DOptions {
+    from?: number;
+    to: number;
+    config?: Partial<SpringConfig>;
+    onRest?: () => void;
+    immediate?: boolean;
+}
+
+export declare interface UseSpringOptions {
+    /** Initial position */
+    from?: {
+        x: number;
+        y: number;
+    };
+    /** Target position */
+    to: {
+        x: number;
+        y: number;
+    };
+    /** Spring configuration or preset name */
+    config?: Partial<SpringConfig> | 'ios' | 'snappy' | 'smooth';
+    /** Callback when animation completes */
+    onRest?: () => void;
+    /** Start immediately (default: true) */
+    immediate?: boolean;
+}
+
+export declare interface UseSpringReturn {
+    /** Current x position */
+    x: number;
+    /** Current y position */
+    y: number;
+    /** CSS style object ready to apply */
+    style: React.CSSProperties;
+    /** Whether animation is currently running */
+    isAnimating: boolean;
+    /** Whether animation has reached target */
+    isSettled: boolean;
+    /** Set new target position */
+    setTarget: (target: {
+        x: number;
+        y: number;
+    }) => void;
+    /** Immediately snap to position */
+    snapTo: (position: {
+        x: number;
+        y: number;
+    }) => void;
+    /** Add impulse velocity */
+    impulse: (velocity: {
+        x: number;
+        y: number;
+    }) => void;
+}
+
+/**
+ * Calculate stretch deformation based on velocity
+ * Subtle, directional stretch - never cartoon-like
+ */
+export declare function useStretch(options: UseStretchOptions): UseStretchReturn;
+
+/**
+ * Hook to get stretch config from context
+ */
+export declare function useStretchConfig(): {
+    intensity: number;
+    maxVelocity: number;
+};
+
+export declare interface UseStretchOptions {
+    /** Current velocity vector */
+    velocity: Vector2 | {
+        x: number;
+        y: number;
+    };
+    /** Axis to apply stretch ('x', 'y', or 'both') */
+    axis?: 'x' | 'y' | 'both';
+    /** Maximum stretch intensity (0-0.3, default: 0.12) */
+    intensity?: number;
+    /** Velocity at which max stretch is reached (default: 2000) */
+    maxVelocity?: number;
+}
+
+export declare interface UseStretchReturn {
+    /** Scale X value */
+    scaleX: number;
+    /** Scale Y value */
+    scaleY: number;
+    /** CSS style object with transform */
+    style: React.CSSProperties;
+}
+
+/**
+ * Immutable 2D vector class for physics calculations
+ */
+export declare class Vector2 {
+    readonly x: number;
+    readonly y: number;
+    constructor(x?: number, y?: number);
+    static zero(): Vector2;
+    static from(x: number, y: number): Vector2;
+    static fromObject(obj: {
+        x: number;
+        y: number;
+    }): Vector2;
+    add(other: Vector2): Vector2;
+    subtract(other: Vector2): Vector2;
+    multiply(scalar: number): Vector2;
+    divide(scalar: number): Vector2;
+    get magnitude(): number;
+    get magnitudeSquared(): number;
+    normalize(): Vector2;
+    clamp(maxMagnitude: number): Vector2;
+    clampComponents(min: Vector2, max: Vector2): Vector2;
+    lerp(target: Vector2, t: number): Vector2;
+    dot(other: Vector2): number;
+    distanceTo(other: Vector2): number;
+    equals(other: Vector2, epsilon?: number): boolean;
+    isZero(epsilon?: number): boolean;
+    negate(): Vector2;
+    abs(): Vector2;
+    toObject(): {
+        x: number;
+        y: number;
+    };
+}
+
+/**
+ * Velocity tracker using circular buffer for smooth velocity estimation
+ * Calculates average velocity from recent position history
+ */
+export declare class VelocityTracker {
+    private samples;
+    private maxSamples;
+    private maxAge;
+    constructor(maxSamples?: number, maxAge?: number);
+    /**
+     * Record a position sample
+     */
+    addSample(position: Vector2, timestamp?: number): void;
+    /**
+     * Calculate current velocity from sample history
+     * Returns smoothed velocity vector in pixels per second
+     */
+    getVelocity(): Vector2;
+    /**
+     * Get velocity magnitude in pixels per second
+     */
+    getSpeed(): number;
+    /**
+     * Check if current velocity qualifies as a flick gesture
+     */
+    isFlick(threshold?: number): boolean;
+    /**
+     * Get dominant direction of movement
+     */
+    getDirection(): 'up' | 'down' | 'left' | 'right' | 'none';
+    /**
+     * Clear all samples
+     */
+    reset(): void;
+    /**
+     * Get the last recorded position
+     */
+    getLastPosition(): Vector2 | null;
+}
+
+/**
+ * 1D velocity tracker for single-axis motion
+ */
+export declare class VelocityTracker1D {
+    private samples;
+    private maxSamples;
+    private maxAge;
+    constructor(maxSamples?: number, maxAge?: number);
+    addSample(value: number, timestamp?: number): void;
+    getVelocity(): number;
+    reset(): void;
+}
+
+export { }