@siberiacancode/reactuse 0.3.13 → 0.3.15

package/dist/esm/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/esm/utils/helpers/isTarget.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"isTarget.mjs","sources":["../../../../src/utils/helpers/isTarget.ts"],"sourcesContent":["import type { RefObject } from 'react';\n\nexport const targetSymbol = Symbol('target');\n\nexport type Target = (() => Element) | string | Document | Element | Window;\ninterface BrowserTarget {\n  type: symbol;\n  value: Target;\n}\ninterface StateRef<Value> {\n  (node: Value): void;\n  current: Value;\n  state: Value;\n}\n\nexport type HookTarget =\n  | BrowserTarget\n  | RefObject<Element | null | undefined>\n  | StateRef<Element | null | undefined>;\n\nexport const target = (target: Target) => ({\n  value: target,\n  type: targetSymbol\n});\n\nexport const isRef = (target: HookTarget) => typeof target === 'object' && 'current' in target;\n\nexport const isRefState = (target: HookTarget) =>\n  typeof target === 'function' && 'state' in target && 'current' in target;\n\nexport const isBrowserTarget = (target: HookTarget) =>\n  typeof target === 'object' &&\n  target &&\n  'type' in target &&\n  target.type === targetSymbol &&\n  'value' in target;\n\nexport const isTarget = (target: HookTarget) =>\n  isRef(target) || isRefState(target) || isBrowserTarget(target);\n\nconst getElement = (target: HookTarget) => {\n  if ('current' in target) {\n    return target.current;\n  }\n\n  if (typeof target.value === 'function') {\n    return target.value();\n  }\n\n  if (typeof target.value === 'string') {\n    return document.querySelector(target.value);\n  }\n\n  if (target.value instanceof Document) {\n    return target.value;\n  }\n\n  if (target.value instanceof Window) {\n    return target.value;\n  }\n\n  if (target.value instanceof Element) {\n    return target.value;\n  }\n\n  return target.value;\n};\nexport const getRefState = (target?: HookTarget) => target && 'state' in target && target.state;\nexport const getRawElement = (target: HookTarget) => {\n  if (isRefState(target)) return target.state;\n  if (isBrowserTarget(target)) return (target as BrowserTarget).value;\n\n  return target;\n};\n\nisTarget.wrap = target;\nisTarget.getElement = getElement;\nisTarget.getRefState = getRefState;\nisTarget.getRawElement = getRawElement;\n"],"names":["targetSymbol","target","isRef","isRefState","isBrowserTarget","isTarget","getElement","getRefState","getRawElement"],"mappings":"AAEO,MAAMA,2BAAsB,QAAQ,GAkB9BC,IAAS,CAACA,OAAoB;AAAA,EACzC,OAAOA;AAAAA,EACP,MAAMD;AACR,IAEaE,IAAQ,CAACD,MAAuB,OAAOA,KAAW,YAAY,aAAaA,GAE3EE,IAAa,CAACF,MACzB,OAAOA,KAAW,cAAc,WAAWA,KAAU,aAAaA,GAEvDG,IAAkB,CAACH,MAC9B,OAAOA,KAAW,YAClBA,KACA,UAAUA,KACVA,EAAO,SAASD,KAChB,WAAWC,GAEAI,IAAW,CAACJ,MACvBC,EAAMD,CAAM,KAAKE,EAAWF,CAAM,KAAKG,EAAgBH,CAAM,GAEzDK,IAAa,CAACL,MACd,aAAaA,IACRA,EAAO,UAGZ,OAAOA,EAAO,SAAU,aACnBA,EAAO,MAAA,IAGZ,OAAOA,EAAO,SAAU,WACnB,SAAS,cAAcA,EAAO,KAAK,KAGxCA,EAAO,iBAAiB,YAIxBA,EAAO,iBAAiB,UAIxBA,EAAO,iBAAiB,SACnBA,EAAO,QAKLM,IAAc,CAACN,MAAwBA,KAAU,WAAWA,KAAUA,EAAO,OAC7EO,IAAgB,CAACP,MACxBE,EAAWF,CAAM,IAAUA,EAAO,QAClCG,EAAgBH,CAAM,IAAWA,EAAyB,QAEvDA;AAGTI,EAAS,OAAOJ;AAChBI,EAAS,aAAaC;AACtBD,EAAS,cAAcE;AACvBF,EAAS,gBAAgBG;"}
+{"version":3,"file":"isTarget.mjs","sources":["../../../../src/utils/helpers/isTarget.ts"],"sourcesContent":["import type { RefObject } from 'react';\r\n\r\nexport const targetSymbol = Symbol('target');\r\n\r\nexport type Target = (() => Element) | string | Document | Element | Window;\r\ninterface BrowserTarget {\r\n  type: symbol;\r\n  value: Target;\r\n}\r\ninterface StateRef<Value> {\r\n  (node: Value): void;\r\n  current: Value;\r\n  state: Value;\r\n}\r\n\r\nexport type HookTarget =\r\n  | BrowserTarget\r\n  | RefObject<Element | null | undefined>\r\n  | StateRef<Element | null | undefined>;\r\n\r\nexport const target = (target: Target) => ({\r\n  value: target,\r\n  type: targetSymbol\r\n});\r\n\r\nexport const isRef = (target: HookTarget) => typeof target === 'object' && 'current' in target;\r\n\r\nexport const isRefState = (target: HookTarget) =>\r\n  typeof target === 'function' && 'state' in target && 'current' in target;\r\n\r\nexport const isBrowserTarget = (target: HookTarget) =>\r\n  typeof target === 'object' &&\r\n  target &&\r\n  'type' in target &&\r\n  target.type === targetSymbol &&\r\n  'value' in target;\r\n\r\nexport const isTarget = (target: HookTarget) =>\r\n  isRef(target) || isRefState(target) || isBrowserTarget(target);\r\n\r\nconst getElement = (target: HookTarget) => {\r\n  if ('current' in target) {\r\n    return target.current;\r\n  }\r\n\r\n  if (typeof target.value === 'function') {\r\n    return target.value();\r\n  }\r\n\r\n  if (typeof target.value === 'string') {\r\n    return document.querySelector(target.value);\r\n  }\r\n\r\n  if (target.value instanceof Document) {\r\n    return target.value;\r\n  }\r\n\r\n  if (target.value instanceof Window) {\r\n    return target.value;\r\n  }\r\n\r\n  if (target.value instanceof Element) {\r\n    return target.value;\r\n  }\r\n\r\n  return target.value;\r\n};\r\nexport const getRefState = (target?: HookTarget) => target && 'state' in target && target.state;\r\nexport const getRawElement = (target: HookTarget) => {\r\n  if (isRefState(target)) return target.state;\r\n  if (isBrowserTarget(target)) return (target as BrowserTarget).value;\r\n\r\n  return target;\r\n};\r\n\r\nisTarget.wrap = target;\r\nisTarget.getElement = getElement;\r\nisTarget.getRefState = getRefState;\r\nisTarget.getRawElement = getRawElement;\r\n"],"names":["targetSymbol","target","isRef","isRefState","isBrowserTarget","isTarget","getElement","getRefState","getRawElement"],"mappings":"AAEO,MAAMA,2BAAsB,QAAQ,GAkB9BC,IAAS,CAACA,OAAoB;AAAA,EACzC,OAAOA;AAAAA,EACP,MAAMD;AACR,IAEaE,IAAQ,CAACD,MAAuB,OAAOA,KAAW,YAAY,aAAaA,GAE3EE,IAAa,CAACF,MACzB,OAAOA,KAAW,cAAc,WAAWA,KAAU,aAAaA,GAEvDG,IAAkB,CAACH,MAC9B,OAAOA,KAAW,YAClBA,KACA,UAAUA,KACVA,EAAO,SAASD,KAChB,WAAWC,GAEAI,IAAW,CAACJ,MACvBC,EAAMD,CAAM,KAAKE,EAAWF,CAAM,KAAKG,EAAgBH,CAAM,GAEzDK,IAAa,CAACL,MACd,aAAaA,IACRA,EAAO,UAGZ,OAAOA,EAAO,SAAU,aACnBA,EAAO,MAAA,IAGZ,OAAOA,EAAO,SAAU,WACnB,SAAS,cAAcA,EAAO,KAAK,KAGxCA,EAAO,iBAAiB,YAIxBA,EAAO,iBAAiB,UAIxBA,EAAO,iBAAiB,SACnBA,EAAO,QAKLM,IAAc,CAACN,MAAwBA,KAAU,WAAWA,KAAUA,EAAO,OAC7EO,IAAgB,CAACP,MACxBE,EAAWF,CAAM,IAAUA,EAAO,QAClCG,EAAgBH,CAAM,IAAWA,EAAyB,QAEvDA;AAGTI,EAAS,OAAOJ;AAChBI,EAAS,aAAaC;AACtBD,EAAS,cAAcE;AACvBF,EAAS,gBAAgBG;"}

package/dist/types/helpers/createContextHook/createContextHook.d.ts

@@ -0,0 +1,26 @@
+import { ReactNode } from 'react';
+/**
+ * @name createContextHook
+ * @description - Hook that runs inside a Provider; Provider accepts params (the hook's arguments). Use when you need a scoped instance per subtree.
+ * @category Helpers
+ * @usage low
+ *
+ * @warning - For complex interfaces, we strongly recommend using state management solutions outside of React like createStore, reatom, effector, or zustand instead of context
+ *
+ * @param useHook - The hook to run in the Provider (e.g. useMediaQuery)
+ * @returns { Provider, use } — Provider takes params; use() returns the value and must be used inside Provider
+ *
+ * @example
+ * const { Provider, use } = createContextHook(useMediaQuery);
+ * <Provider params={["(max-width: 768px)"]}>
+ *   <Component />
+ * </Provider>
+ * const matches = use();
+ */
+export declare const createContextHook: <Hook extends (...args: any[]) => any>(useHook: Hook) => {
+    Provider: ({ children, params }: {
+        children: ReactNode;
+        params: Parameters<Hook>;
+    }) => import("react/jsx-runtime").JSX.Element;
+    use: () => ReturnType<Hook> | null;
+};

package/dist/types/helpers/createSharedHook/createSharedHook.d.ts

@@ -0,0 +1,21 @@
+export declare const mount: (component: React.ReactNode) => () => void;
+/**
+ * @name createSharedHook
+ * @description - One shared instance of the hook globally. First subscriber's args are used; when subscribers hit zero, the runner unmounts.
+ * @category Helpers
+ * @usage low
+ *
+ * @warning - For complex interfaces, we strongly recommend using state management solutions outside of React like createStore, reatom, effector, or zustand instead of context
+ *
+ * @template Hook - The hook to create a shared instance of
+ * @param {Hook} useHook - The hook to create a shared instance of
+ * @returns {Hook & { useShared: typeof useShared }} - The shared hook
+ *
+ * @example
+ * const useSharedMediaQuery = createSharedHook(useMediaQuery);
+ * const matches = useSharedMediaQuery("(max-width: 768px)");
+ */
+export declare const createSharedHook: <Hook extends (...args: any[]) => any>(useHook: Hook) => {
+    (...args: Parameters<Hook>): any;
+    useShared: /*elided*/ any;
+} | ((...args: Parameters<Hook>) => ReturnType<Hook>);

package/dist/types/helpers/index.d.ts

@@ -1,4 +1,6 @@
 export * from './createContext/createContext';
+export * from './createContextHook/createContextHook';
 export * from './createEventEmitter/createEventEmitter';
 export * from './createReactiveContext/createReactiveContext';
+export * from './createSharedHook/createSharedHook';
 export * from './createStore/createStore';

package/dist/types/hooks/useField/useField.d.ts

@@ -1,12 +1,10 @@
 import { RefObject } from 'react';
 /** The use field params type */
-export interface UseFieldParams<Value> {
+export interface UseFieldOptions {
     /** The auto focus */
     autoFocus?: boolean;
     /** The initial touched */
     initialTouched?: boolean;
-    /** The initial value */
-    initialValue?: Value;
     /** The validate on blur */
     validateOnBlur?: boolean;
     /** The validate on mount */
@@ -16,10 +14,6 @@ export interface UseFieldParams<Value> {
 }
 /** The use field register params type */
 export interface UseFieldRegisterParams {
-    /** The required validation */
-    required?: string;
-    /** The custom validation */
-    validate?: (value: string) => Promise<string | true>;
     /** The min value validation */
     max?: {
         value: number;
@@ -45,6 +39,10 @@ export interface UseFieldRegisterParams {
         value: RegExp;
         message: string;
     };
+    /** The required validation */
+    required?: string;
+    /** The custom validation */
+    validate?: (value: string) => Promise<string | true>;
 }
 /** The use field return type */
 export interface UseFieldReturn<Value> {
@@ -85,7 +83,7 @@ export interface UseFieldReturn<Value> {
  *
  * @template Value The input value
  * @template Type The input value type
- * @param {Value} [params.initialValue] Initial value
+ * @param {Value} [params.initialValue = ""] Initial value
  * @param {boolean} [params.initialTouched=false] Initial touched state
  * @param {boolean} [params.autoFocus=false] Auto focus
  * @param {boolean} [params.validateOnChange=false] Validate on change
@@ -96,4 +94,4 @@ export interface UseFieldReturn<Value> {
  * @example
  * const { register, getValue, setValue, reset, dirty, error, setError, clearError, touched, focus, watch } = useField();
  */
-export declare const useField: <Value extends boolean | number | string = string, Type = Value extends string ? string : Value extends boolean ? boolean : number>(params?: UseFieldParams<Value>) => UseFieldReturn<Type>;
+export declare const useField: <Value extends boolean | number | string = string, Type = Value extends string ? string : Value extends boolean ? boolean : number>(initialValue?: Value, options?: UseFieldOptions) => UseFieldReturn<Type>;

package/dist/types/hooks/useMouse/useMouse.d.ts

@@ -2,6 +2,13 @@ import { HookTarget } from '../../utils/helpers';
 import { StateRef } from '../useRefState/useRefState';
 /** The use mouse return type */
 export interface UseMouseReturn {
+    /** The latest mouse value snapshot */
+    snapshot: UseMouseValue;
+    /** Function to enable subscriptions and rerender on next updates */
+    watch: () => UseMouseValue;
+}
+/** The use mouse value type */
+export interface UseMouseValue {
     /** The current mouse client x position */
     clientX: number;
     /** The current mouse client y position */
@@ -19,12 +26,13 @@ export interface UseMouseReturn {
     /** The current mouse y position */
     y: number;
 }
+export type UseMouseCallback = (value: UseMouseValue, event: Event) => void;
 export interface UseMouse {
-    (target: HookTarget): UseMouseReturn;
-    <Target extends Element>(target?: never): UseMouseReturn & {
+    (target: HookTarget, callback?: UseMouseCallback): UseMouseReturn;
+    <Target extends Element>(callback?: UseMouseCallback, target?: never): UseMouseReturn & {
         ref: StateRef<Target>;
     };
-    (target?: Window): UseMouseReturn;
+    (target?: Window, callback?: UseMouseCallback): UseMouseReturn;
 }
 /**
  * @name useMouse
@@ -34,16 +42,18 @@ export interface UseMouse {
  *
  * @overload
  * @param {HookTarget} [target=window] The target element to manage the mouse position for
- * @returns {UseMouseReturn} An object with the current mouse position
+ * @param {(value: UseMouseValue, event: Event) => void} [callback] The callback to invoke on mouse updates
+ * @returns {UseMouseReturn} An object with mouse value controls
  *
  * @example
- * const { x, y, clientX, clientY, elementX, elementY, elementPositionX, elementPositionY } = useMouse(ref);
+ * const mouse = useMouse(ref);
  *
  * @overload
  * @template Target The target element
- * @returns {UseMouseReturn & { ref: StateRef<Target> }} An object with the current mouse position and a ref
+ * @param {(value: UseMouseValue, event: Event) => void} [callback] The callback to invoke on mouse updates
+ * @returns {UseMouseReturn & { ref: StateRef<Target> }} An object with mouse value controls and a ref
  *
  * @example
- * const { ref, x, y, clientX, clientY, elementX, elementY, elementPositionX, elementPositionY } = useMouse();
+ * const mouse = useMouse<HTMLDivElement>();
  */
 export declare const useMouse: UseMouse;

package/dist/types/hooks/useProgress/useProgress.d.ts

@@ -1,5 +1,7 @@
 /** The use progress options type */
 export interface UseProgressOptions {
+    /** Delay before reset to null after done */
+    delay?: number;
     /** Start progress immediately */
     immediately?: boolean;
     /** Maximum progress value */
@@ -26,7 +28,7 @@ export interface UseProgressReturn {
 }
 /**
  * @name useProgress
- * @description - Hook that creates a lightweight progress bar state with NProgress-like behavior
+ * @description - Hook that creates a lightweight progress bar
  * @category Time
  * @usage medium
  *
@@ -35,7 +37,7 @@ export interface UseProgressReturn {
  * @param {number} [options.maximum=0.95] Maximum value when progress starts
  * @param {number} [options.speed=250] Auto increment interval in milliseconds
  * @param {number} [options.rate=0.02] Additional random increment amount on each tick
- * @param {number} [options.doneResetDelay=250] Delay before reset to null after done
+ * @param {number} [options.delay=250] Delay before reset to null after done
  * @returns {UseProgressReturn} Current progress state and control methods
  *
  * @example

package/dist/types/hooks/useScroll/useScroll.d.ts

@@ -1,10 +1,6 @@
 import { HookTarget } from '../../utils/helpers';
 import { StateRef } from '../useRefState/useRefState';
 export interface UseScrollOptions {
-    /** The on scroll callback */
-    onScroll?: (params: UseScrollCallbackParams, event: Event) => void;
-    /** The on end scroll callback */
-    onStop?: (event: Event) => void;
     /** Offset arrived states by x pixels. */
     offset?: {
         left?: number;
@@ -12,12 +8,12 @@ export interface UseScrollOptions {
         top?: number;
         bottom?: number;
     };
+    /** The on scroll callback */
+    onScroll?: (params: UseScrollCallbackParams, event: Event) => void;
+    /** The on end scroll callback */
+    onStop?: (event: Event) => void;
 }
 export interface UseScrollCallbackParams {
-    /** The element x position */
-    x: number;
-    /** The element y position */
-    y: number;
     /** State of scroll arrived */
     arrived: {
         left: boolean;
@@ -32,6 +28,10 @@ export interface UseScrollCallbackParams {
         top: boolean;
         bottom: boolean;
     };
+    /** The element x position */
+    x: number;
+    /** The element y position */
+    y: number;
 }
 /** The scroll into view params type */
 export interface ScrollIntoViewParams {
@@ -47,16 +47,18 @@ export interface ScrollToParams {
 }
 /** The use scroll return type */
 export interface UseScrollReturn {
-    /** The state of scrolling */
-    scrolling: boolean;
+    /** The latest scroll value snapshot */
+    snapshot: UseScrollCallbackParams;
     /** Function to scroll element into view */
     scrollIntoView: (params?: ScrollIntoViewParams) => void;
     /** Function to scroll element to a specific position */
     scrollTo: (params?: ScrollToParams) => void;
+    /** Function to enable subscriptions and rerender on next updates */
+    watch: () => UseScrollCallbackParams;
 }
 export interface UseScroll {
     (target?: HookTarget, callback?: (params: UseScrollCallbackParams, event: Event) => void): UseScrollReturn;
-    (target?: HookTarget, options?: UseScrollOptions): UseScrollReturn;
+    (target: HookTarget, options?: UseScrollOptions): UseScrollReturn;
     <Target extends Element>(callback?: (params: UseScrollCallbackParams, event: Event) => void, target?: never): UseScrollReturn & {
         ref: StateRef<Target>;
     };

package/dist/types/hooks/useUrlSearchParams/useUrlSearchParams.d.ts

@@ -11,7 +11,6 @@ export interface UseUrlSearchParamsSetOptions {
 export type UseUrlSearchParamsInitialValue<Value> = (() => Value) | Value;
 /** The use url search params options type */
 export interface UseUrlSearchParamsOptions<Value> {
-    initialValue?: UseUrlSearchParamsInitialValue<string | URLSearchParams | Value>;
     /** The mode to use for writing to the URL */
     mode?: UrlSearchParamsMode;
     /** The mode to use for writing to the URL  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siberiacancode/reactuse",
-  "version": "0.3.13",
+  "version": "0.3.15",
   "description": "The ultimate collection of react hooks",
   "author": {
     "name": "SIBERIA CAN CODE 🧊",
@@ -64,18 +64,19 @@
     "screenfull": "^6.0.2"
   },
   "devDependencies": {
-    "@siberiacancode/vitest": "^2.3.0",
+    "@siberiacancode/vitest": "^2.4.1",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/dom-speech-recognition": "^0.0.7",
-    "@types/react": "^19.2.13",
+    "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@types/web-bluetooth": "^0.0.21",
-    "@vitejs/plugin-react": "^5.1.3",
+    "@vitejs/plugin-react": "^5.1.4",
     "core-js": "^3.48.0",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "shx": "^0.4.0",
+    "tailwindcss": "4.2.1",
     "vite": "^7.3.1",
     "vite-plugin-dts": "^4.5.4",
     "vitest": "^4.0.18"