msr-hooks 1.0.0

package/src/hooks/usePreventZoom/usePreventZoom.js

@@ -0,0 +1,39 @@
+import { useEffect } from 'react';
+
+/**
+ * Prevent page zoom via keyboard shortcuts and scroll wheel.
+ * @param {boolean} scrollCheck - Prevent Ctrl+Scroll zoom, defaults to true
+ * @param {boolean} keyboardCheck - Prevent Ctrl+Plus/Minus zoom, defaults to true
+ * @returns {void}
+ */
+export function usePreventZoom(scrollCheck = true, keyboardCheck = true) {
+    useEffect(() => {
+        const handleKeydown = (e) => {
+            if (!keyboardCheck) return;
+
+            const isCtrlOrCmd = e.ctrlKey || e.metaKey;
+            const zoomKeys = ['61', '107', '173', '109', '187', '189'];
+
+            if (isCtrlOrCmd && zoomKeys.includes(e.code)) {
+                e.preventDefault();
+            }
+        };
+
+        const handleWheel = (e) => {
+            if (!scrollCheck) return;
+
+            const isCtrlOrCmd = e.ctrlKey || e.metaKey;
+            if (isCtrlOrCmd) {
+                e.preventDefault();
+            }
+        };
+
+        document.addEventListener('keydown', handleKeydown);
+        document.addEventListener('wheel', handleWheel, { passive: false });
+
+        return () => {
+            document.removeEventListener('keydown', handleKeydown);
+            document.removeEventListener('wheel', handleWheel);
+        };
+    }, [scrollCheck, keyboardCheck]);
+}

package/src/hooks/usePrevious/index.js

@@ -0,0 +1 @@
+export { usePrevious } from './usePrevious';

package/src/hooks/usePrevious/usePrevious.d.ts

@@ -0,0 +1 @@
+export function usePrevious<T>(value: T): T | undefined;

package/src/hooks/usePrevious/usePrevious.js

@@ -0,0 +1,16 @@
+import { useEffect, useRef } from 'react';
+
+/**
+ * Get the previous render's value.
+ * @param {*} value - Current value
+ * @returns {*} Previous value from last render
+ */
+export function usePrevious(value) {
+    const ref = useRef();
+
+    useEffect(() => {
+        ref.current = value;
+    }, [value]);
+
+    return ref.current;
+}

package/src/hooks/useResize/index.js

@@ -0,0 +1 @@
+export { useResize } from './useResize';

package/src/hooks/useResize/useResize.d.ts

@@ -0,0 +1,16 @@
+export interface UseResizeConfig {
+    defaultSize: number;
+    minSize?: number;
+    maxSize?: number;
+}
+
+export interface UseResizeReturn {
+    size: number;
+    setSize: (size: number) => void;
+    isDragging: boolean;
+    setIsDragging: (dragging: boolean) => void;
+    handleMouseDown: (e: React.MouseEvent) => void;
+    handleMouseUp: () => void;
+}
+
+export function useResize(config: UseResizeConfig): UseResizeReturn;

package/src/hooks/useResize/useResize.js

@@ -0,0 +1,32 @@
+import { useCallback, useState } from 'react';
+
+/**
+ * Manage resizable element state with drag tracking.
+ * @param {object} config - Configuration object
+ * @param {number} config.defaultSize - Initial size value
+ * @param {number} config.minSize - Minimum allowed size
+ * @param {number} config.maxSize - Maximum allowed size
+ * @returns {{size: number, setSize: Function, isDragging: boolean, setIsDragging: Function, handleMouseDown: Function, handleMouseUp: Function}}
+ */
+export function useResize({ defaultSize, minSize, maxSize }) {
+    const [size, setSize] = useState(defaultSize);
+    const [isDragging, setIsDragging] = useState(false);
+
+    const handleMouseDown = useCallback((e) => {
+        setIsDragging(true);
+        e.preventDefault?.();
+    }, []);
+
+    const handleMouseUp = useCallback(() => {
+        setIsDragging(false);
+    }, []);
+
+    return {
+        size,
+        setSize,
+        isDragging,
+        setIsDragging,
+        handleMouseDown,
+        handleMouseUp
+    };
+}

package/src/hooks/useSpringValue/index.js

@@ -0,0 +1 @@
+export { useSpringValue } from './useSpringValue';

package/src/hooks/useSpringValue/useSpringValue.d.ts

@@ -0,0 +1,4 @@
+export function useSpringValue(
+    target: number,
+    config?: { stiffness?: number; damping?: number; mass?: number; precision?: number }
+): number;

package/src/hooks/useSpringValue/useSpringValue.js

@@ -0,0 +1,66 @@
+import { useEffect, useRef, useState } from 'react';
+
+/**
+ * Spring-animate a numeric value toward a target.
+ * @param {number} target
+ * @param {{ stiffness?: number; damping?: number; mass?: number; precision?: number }} config
+ */
+export function useSpringValue(target, config = {}) {
+    const { stiffness = 170, damping = 26, mass = 1, precision = 0.001 } = config;
+    const [value, setValue] = useState(target);
+    const velocityRef = useRef(0);
+    const frameRef = useRef();
+    const lastTimeRef = useRef();
+
+    useEffect(() => {
+        if (typeof window === 'undefined') {
+            setValue(target);
+            return undefined;
+        }
+
+        let cancelled = false;
+
+        const step = (timestamp) => {
+            if (cancelled) return;
+            if (lastTimeRef.current == null) {
+                lastTimeRef.current = timestamp;
+            }
+            const delta = (timestamp - lastTimeRef.current) / 1000;
+            lastTimeRef.current = timestamp;
+
+            setValue((current) => {
+                const displacement = current - target;
+                const springForce = -stiffness * displacement;
+                const dampingForce = -damping * velocityRef.current;
+                const acceleration = (springForce + dampingForce) / mass;
+
+                velocityRef.current += acceleration * delta;
+                const next = current + velocityRef.current * delta;
+
+                const settled = Math.abs(velocityRef.current) < precision && Math.abs(next - target) < precision;
+                if (settled) {
+                    velocityRef.current = 0;
+                    frameRef.current = undefined;
+                    lastTimeRef.current = undefined;
+                    return target;
+                }
+
+                frameRef.current = window.requestAnimationFrame(step);
+                return next;
+            });
+        };
+
+        frameRef.current = window.requestAnimationFrame(step);
+
+        return () => {
+            cancelled = true;
+            if (frameRef.current) {
+                window.cancelAnimationFrame(frameRef.current);
+            }
+            frameRef.current = undefined;
+            lastTimeRef.current = undefined;
+        };
+    }, [target, stiffness, damping, mass, precision]);
+
+    return value;
+}

package/src/hooks/useStateHistory/index.js

@@ -0,0 +1 @@
+export { useStateHistory } from './useStateHistory';

package/src/hooks/useStateHistory/useStateHistory.d.ts

@@ -0,0 +1,17 @@
+export interface UseStateHistoryReturn<T> {
+    state: T;
+    set: (newState: T) => void;
+    history: T[];
+    pointer: number;
+    jump: (index: number) => void;
+    canUndo: boolean;
+    canRedo: boolean;
+    undo: () => void;
+    redo: () => void;
+    clearHistory: () => void;
+}
+
+export function useStateHistory<T>(
+    initialState: T,
+    options?: { limit?: number }
+): UseStateHistoryReturn<T>;

package/src/hooks/useStateHistory/useStateHistory.js

@@ -0,0 +1,70 @@
+import { useCallback, useState } from 'react';
+
+/**
+ * Full state timeline with time-travel navigation.
+ * @template T
+ * @param {T} initialState
+ * @param {{ limit?: number }} options
+ */
+export function useStateHistory(initialState, options = {}) {
+    const { limit = 50 } = options;
+
+    const [history, setHistory] = useState([initialState]);
+    const [pointer, setPointer] = useState(0);
+
+    const state = history[pointer];
+
+    const set = useCallback((newState) => {
+        setHistory((prev) => {
+            // Remove any "future" states after current pointer
+            const truncated = prev.slice(0, pointer + 1);
+            // Add new state
+            const updated = [...truncated, newState];
+            // Enforce limit by removing oldest entries
+            const trimmed = updated.length > limit ? updated.slice(updated.length - limit) : updated;
+            return trimmed;
+        });
+        setPointer((prev) => {
+            const newLength = Math.min(pointer + 2, limit);
+            return newLength - 1;
+        });
+    }, [pointer, limit]);
+
+    const jump = useCallback((index) => {
+        const clampedIndex = Math.max(0, Math.min(index, history.length - 1));
+        setPointer(clampedIndex);
+    }, [history.length]);
+
+    const undo = useCallback(() => {
+        if (pointer > 0) {
+            setPointer(pointer - 1);
+        }
+    }, [pointer]);
+
+    const redo = useCallback(() => {
+        if (pointer < history.length - 1) {
+            setPointer(pointer + 1);
+        }
+    }, [pointer, history.length]);
+
+    const clearHistory = useCallback(() => {
+        setHistory([state]);
+        setPointer(0);
+    }, [state]);
+
+    const canUndo = pointer > 0;
+    const canRedo = pointer < history.length - 1;
+
+    return {
+        state,
+        set,
+        history,
+        pointer,
+        jump,
+        canUndo,
+        canRedo,
+        undo,
+        redo,
+        clearHistory,
+    };
+}

package/src/hooks/useThrottle/index.js

@@ -0,0 +1 @@
+export { useThrottle } from './useThrottle';

package/src/hooks/useThrottle/useThrottle.d.ts

@@ -0,0 +1 @@
+export function useThrottle<T>(value: T, limit?: number): T;

package/src/hooks/useThrottle/useThrottle.js

@@ -0,0 +1,25 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+/**
+ * Throttle a changing value or function.
+ * @param {*} value - Value to throttle
+ * @param {number} limit - Throttle limit in ms, defaults to 500
+ * @returns {*} Throttled value
+ */
+export function useThrottle(value, limit = 500) {
+    const [throttled, setThrottled] = useState(value);
+    const lastRan = useRef(Date.now());
+
+    useEffect(() => {
+        const handler = setTimeout(() => {
+            if (Date.now() - lastRan.current >= limit) {
+                setThrottled(value);
+                lastRan.current = Date.now();
+            }
+        }, limit - (Date.now() - lastRan.current));
+
+        return () => clearTimeout(handler);
+    }, [value, limit]);
+
+    return throttled;
+}

package/src/hooks/useTimeout/index.js

@@ -0,0 +1 @@
+export { useTimeout } from './useTimeout';

package/src/hooks/useTimeout/useTimeout.d.ts

@@ -0,0 +1,4 @@
+export function useTimeout(
+    callback: () => void,
+    delay: number | null
+): void;

package/src/hooks/useTimeout/useTimeout.js

@@ -0,0 +1,22 @@
+import { useEffect, useRef } from 'react';
+
+/**
+ * Declarative setTimeout with cleanup.
+ * @param {Function} callback - Function to call after timeout
+ * @param {number|null} delay - Delay in ms, null to cancel
+ * @returns {void}
+ */
+export function useTimeout(callback, delay) {
+    const savedCallback = useRef();
+
+    useEffect(() => {
+        savedCallback.current = callback;
+    }, [callback]);
+
+    useEffect(() => {
+        if (delay === null) return undefined;
+
+        const id = setTimeout(() => savedCallback.current(), delay);
+        return () => clearTimeout(id);
+    }, [delay]);
+}

package/src/hooks/useToggle/index.js

@@ -0,0 +1 @@
+export { useToggle } from './useToggle';

package/src/hooks/useToggle/useToggle.d.ts

@@ -0,0 +1,3 @@
+export function useToggle(
+    initial?: boolean
+): [boolean, () => void, () => void, () => void];

package/src/hooks/useToggle/useToggle.js

@@ -0,0 +1,16 @@
+import { useCallback, useState } from 'react';
+
+/**
+ * Boolean state with toggle and setter helpers.
+ * @param {boolean} initial - Initial value, defaults to false
+ * @returns {[boolean, Function, Function, Function]} [value, toggle, setTrue, setFalse]
+ */
+export function useToggle(initial = false) {
+    const [value, setValue] = useState(Boolean(initial));
+
+    const toggle = useCallback(() => setValue((v) => !v), []);
+    const setTrue = useCallback(() => setValue(true), []);
+    const setFalse = useCallback(() => setValue(false), []);
+
+    return [value, toggle, setTrue, setFalse];
+}

package/src/hooks/useUndoRedo/index.js

@@ -0,0 +1 @@
+export { useUndoRedo } from './useUndoRedo';

package/src/hooks/useUndoRedo/useUndoRedo.d.ts

@@ -0,0 +1,18 @@
+export interface UseUndoRedoOptions {
+    limit?: number;
+}
+
+export interface UseUndoRedoReturn<T> {
+    state: T;
+    set: (value: T | ((prev: T) => T)) => void;
+    undo: () => void;
+    redo: () => void;
+    canUndo: boolean;
+    canRedo: boolean;
+    reset: (value?: T) => void;
+}
+
+export function useUndoRedo<T>(
+    initialValue: T,
+    options?: UseUndoRedoOptions
+): UseUndoRedoReturn<T>;

package/src/hooks/useUndoRedo/useUndoRedo.js

@@ -0,0 +1,49 @@
+import { useCallback, useRef, useState } from 'react';
+
+/**
+ * State management helper with undo/redo history.
+ * @param {*} initialValue - Initial state value
+ * @param {object} options
+ * @param {number} [options.limit=50] - Max history length
+ * @returns {{state: *, set: Function, undo: Function, redo: Function, canUndo: boolean, canRedo: boolean, reset: Function}}
+ */
+export function useUndoRedo(initialValue, { limit = 50 } = {}) {
+    const historyRef = useRef([initialValue]);
+    const pointerRef = useRef(0);
+    const [state, setState] = useState(initialValue);
+
+    const set = useCallback((value) => {
+        const resolved = typeof value === 'function' ? value(historyRef.current[pointerRef.current]) : value;
+        const history = historyRef.current.slice(0, pointerRef.current + 1);
+        history.push(resolved);
+        if (history.length > limit) history.shift();
+        historyRef.current = history;
+        pointerRef.current = history.length - 1;
+        setState(resolved);
+    }, [limit]);
+
+    const undo = useCallback(() => {
+        if (pointerRef.current === 0) return;
+        pointerRef.current -= 1;
+        const next = historyRef.current[pointerRef.current];
+        setState(next);
+    }, []);
+
+    const redo = useCallback(() => {
+        if (pointerRef.current >= historyRef.current.length - 1) return;
+        pointerRef.current += 1;
+        const next = historyRef.current[pointerRef.current];
+        setState(next);
+    }, []);
+
+    const reset = useCallback((value = initialValue) => {
+        historyRef.current = [value];
+        pointerRef.current = 0;
+        setState(value);
+    }, [initialValue]);
+
+    const canUndo = pointerRef.current > 0;
+    const canRedo = pointerRef.current < historyRef.current.length - 1;
+
+    return { state, set, undo, redo, canUndo, canRedo, reset };
+}

package/src/hooks/useWindowSize/index.js

@@ -0,0 +1 @@
+export { useWindowSize } from './useWindowSize';

package/src/hooks/useWindowSize/useWindowSize.d.ts

@@ -0,0 +1 @@
+export function useWindowSize(): { width: number; height: number };

package/src/hooks/useWindowSize/useWindowSize.js

@@ -0,0 +1,29 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * Track window dimensions with SSR guard.
+ * @returns {{width: number, height: number}} Current window size
+ */
+export function useWindowSize() {
+    const isBrowser = typeof window !== 'undefined';
+    const [windowSize, setWindowSize] = useState({
+        width: isBrowser ? window.innerWidth : 0,
+        height: isBrowser ? window.innerHeight : 0
+    });
+
+    useEffect(() => {
+        if (!isBrowser) return undefined;
+
+        const handleResize = () => {
+            setWindowSize({
+                width: window.innerWidth,
+                height: window.innerHeight
+            });
+        };
+
+        window.addEventListener('resize', handleResize);
+        return () => window.removeEventListener('resize', handleResize);
+    }, [isBrowser]);
+
+    return windowSize;
+}

package/src/index.d.ts

@@ -0,0 +1 @@
+export * from './hooks';

package/src/index.js

@@ -0,0 +1 @@
+export * from './hooks';