@siberiacancode/reactuse 0.2.18 → 0.2.20

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/types/hooks/index.d.ts

@@ -1,5 +1,6 @@
 export * from './useActiveElement/useActiveElement';
 export * from './useAsync/useAsync';
+export * from './useAudio/useAudio';
 export * from './useBattery/useBattery';
 export * from './useBluetooth/useBluetooth';
 export * from './useBoolean/useBoolean';
@@ -65,6 +66,7 @@ export * from './useLogger/useLogger';
 export * from './useLongPress/useLongPress';
 export * from './useMap/useMap';
 export * from './useMeasure/useMeasure';
+export * from './useMediaControls/useMediaControls';
 export * from './useMediaQuery/useMediaQuery';
 export * from './useMemory/useMemory';
 export * from './useMount/useMount';
@@ -84,6 +86,7 @@ export * from './usePaint/usePaint';
 export * from './useParallax/useParallax';
 export * from './usePerformanceObserver/usePerformanceObserver';
 export * from './usePermission/usePermission';
+export * from './usePictureInPicture/usePictureInPicture';
 export * from './usePointerLock/usePointerLock';
 export * from './usePostMessage/usePostMessage';
 export * from './usePreferredColorScheme/usePreferredColorScheme';
@@ -108,6 +111,7 @@ export * from './useScrollIntoView/useScrollIntoView';
 export * from './useScrollTo/useScrollTo';
 export * from './useSessionStorage/useSessionStorage';
 export * from './useSet/useSet';
+export * from './useShallowEffect/useShallowEffect';
 export * from './useShare/useShare';
 export * from './useSpeechRecognition/useSpeechRecognition';
 export * from './useSpeechSynthesis/useSpeechSynthesis';

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

@@ -0,0 +1,58 @@
+/** Type sprite map */
+export interface SpriteMap {
+    /** [start time in seconds, end time in seconds] */
+    [key: string]: [number, number];
+}
+/** Type use audio options */
+export interface UseAudioOptions {
+    /** Whether audio playback is initially enabled */
+    immediately?: boolean;
+    /** Whether to stop current playback when starting a new one */
+    interrupt?: boolean;
+    /** Initial playback speed (0.5 to 2) */
+    playbackRate?: number;
+    /** Map of named audio segments for sprite-based playback */
+    sprite?: SpriteMap;
+    /** Initial volume level (0 to 1) */
+    volume?: number;
+}
+/** Type use audio return type */
+export interface UseAudioReturn {
+    /** Current playback speed (0.5 to 2) */
+    playbackRate: number;
+    /** Whether audio is currently playing */
+    playing: boolean;
+    /** Current volume level (0 to 1) */
+    volume: number;
+    /** Set playback speed (0.5 to 2) */
+    changePlaybackRate: (value: number) => void;
+    /** Pause audio playback at current position */
+    pause: () => void;
+    /** Start audio playback from the beginning or specified sprite segment */
+    play: (sprite?: string) => Promise<void>;
+    /** Set audio volume level (0 to 1) */
+    setVolume: (value: number) => void;
+    /** Stop audio playback and reset position to start */
+    stop: () => void;
+}
+/**
+ * @name useAudio
+ * @description - Hook that manages audio playback with sprite support
+ * @category Browser
+ *
+ * @browserapi Audio https://developer.mozilla.org/en-US/docs/Web/API/Audio
+ *
+ * @template Value The type of the value
+ * @param {string} url The URL of the audio file to play
+ * @param {UseAudioOptions} [options] Audio configuration options
+ * @param {number} [options.volume=1] Initial volume level (0 to 1)
+ * @param {number} [options.playbackRate=1] Initial playback speed (0.5 to 2)
+ * @param {boolean} [options.interrupt=false] Whether to stop current playback when starting a new one
+ * @param {boolean} [options.soundEnabled=true] Whether audio playback is initially enabled
+ * @param {SpriteMap} [options.sprite] Map of named audio segments for sprite-based playback
+ * @returns {UseAudioReturn} An object containing audio controls and state
+ *
+ * @example
+ * const audio = useAudio("/path/to/sound.mp3");
+ */
+export declare const useAudio: (src: string, options?: UseAudioOptions) => UseAudioReturn;

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

@@ -3,7 +3,7 @@ export interface UseCopyReturn {
     /** Whether copy is in progress */
     copied: boolean;
     /** The copied value */
-    value: string | null;
+    value?: string;
     /** Function to copy text */
     copy: (value: string) => Promise<void>;
 }

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

@@ -4,12 +4,14 @@ import { StateRef } from '../useRefState/useRefState';
 export interface UseCssVarReturn {
     /** The value of the CSS variable */
     value: string;
+    /** Remove the value of the CSS variable */
+    remove: () => void;
     /** Set the value of the CSS variable */
     set: (value: string) => void;
 }
 export interface UseCssVar {
-    (key: string, initialValue?: string): UseCssVarReturn & {
-        ref: StateRef<Element>;
+    <Target extends HTMLElement>(key: string, initialValue?: string): UseCssVarReturn & {
+        ref: StateRef<Target>;
     };
     (target: HookTarget, key: string, initialValue?: string): UseCssVarReturn;
 }
@@ -24,7 +26,7 @@ export interface UseCssVar {
  * @returns {UseCssVarReturn & { ref: StateRef<Element> }} The object containing the value of the CSS variable and ref
  *
  * @example
- * const { ref, value, set } = useCssVar('--color', 'red');
+ * const { ref, value, set, remove } = useCssVar('--color', 'red');
  *
  * @overload
  * @param {HookTarget} target The target element
@@ -33,6 +35,6 @@ export interface UseCssVar {
  * @returns {UseCssVarReturn} The object containing the value of the CSS variable
  *
  * @example
- * const { value, set } = useCssVar(ref, '--color', 'red');
+ * const { value, set, remove } = useCssVar(ref, '--color', 'red');
  */
 export declare const useCssVar: UseCssVar;

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

@@ -1,14 +1,18 @@
 import { HookTarget } from '../../utils/helpers';
 import { StateRef } from '../useRefState/useRefState';
 export type DoubleClickEvents = MouseEvent | TouchEvent;
+/** The use double click options type */
 export interface UseDoubleClickOptions {
+    /** The threshold time in milliseconds between clicks */
     threshold?: number;
+    /** The callback function to be invoked on single click */
     onSingleClick?: (event: DoubleClickEvents) => void;
 }
 export interface UseDoubleClick {
     (target: HookTarget, callback: (event: DoubleClickEvents) => void, options?: UseDoubleClickOptions): boolean;
     <Target extends Element>(callback: (event: DoubleClickEvents) => void, options?: UseDoubleClickOptions, target?: never): StateRef<Target>;
 }
+export declare const DEFAULT_THRESHOLD_TIME = 300;
 /**
  * @name useDoubleClick
  * @description - Hook that defines the logic when double clicking an element

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

@@ -5,10 +5,11 @@ type UseHashReturn = [string, (value: string) => void];
  * @description - Hook that manages the hash value
  * @category Browser
  *
+ * @param {string} [initialValue] The initial hash value if no hash exists
  * @returns {UseHashReturn} An array containing the hash value and a function to set the hash value
  *
  * @example
- * const [hash, setHash] = useHash();
+ * const [hash, setHash] = useHash("initial");
  */
-export declare const useHash: () => UseHashReturn;
+export declare const useHash: (initialValue?: string, mode?: "initial" | "replace") => UseHashReturn;
 export {};

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

@@ -0,0 +1,101 @@
+import { HookTarget } from '../../utils/helpers';
+import { StateRef } from '../useRefState/useRefState';
+export declare const timeRangeToArray: (timeRanges: TimeRanges) => [number, number][];
+/** The media source configuration type */
+export interface UseMediaSource {
+    /** The media attribute of the media */
+    media?: string;
+    /** The source URL of the media */
+    src: string;
+    /** The MIME type of the media */
+    type?: string;
+}
+/** The media controls return type */
+export interface UseMediaControlsReturn {
+    /** Whether the media is currently buffering */
+    buffered: [number, number][];
+    /** The current playback position in seconds */
+    currentTime: number;
+    /** The total duration of the media in seconds */
+    duration: number;
+    /** Whether the media has ended */
+    ended: boolean;
+    /** Whether the media is currently muted */
+    muted: boolean;
+    /** The current playback rate (1.0 is normal speed) */
+    playbackRate: number;
+    /** Whether the media is currently playing */
+    playing: boolean;
+    /** Whether the media is currently seeking */
+    seeking: boolean;
+    /** Whether the media is currently stalled */
+    stalled: boolean;
+    /** The current volume level (0.0 to 1.0) */
+    volume: number;
+    /** Whether the media is currently waiting */
+    waiting: boolean;
+    /** Set the playback rate */
+    changePlaybackRate: (rate: number) => void;
+    /** Set the volume level (0.0 to 1.0) */
+    changeVolume: (volume: number) => void;
+    /** Set the muted state */
+    mute: () => void;
+    /** Pause the media */
+    pause: () => void;
+    /** Start playing the media */
+    play: () => Promise<void>;
+    /** Seek to a specific time in seconds */
+    seek: (time: number) => void;
+    /** Toggle between play and pause */
+    toggle: () => Promise<void>;
+    /** Set the unmuted state */
+    unmute: () => void;
+}
+export interface UseMediaControls {
+    (target: HookTarget, src: string): UseMediaControlsReturn;
+    (target: HookTarget, options: UseMediaSource): UseMediaControlsReturn;
+    <Target extends HTMLMediaElement>(src: string): UseMediaControlsReturn & {
+        ref: StateRef<Target>;
+    };
+    <Target extends HTMLMediaElement>(options: UseMediaSource): UseMediaControlsReturn & {
+        ref: StateRef<Target>;
+    };
+}
+/**
+ * @name useMediaControls
+ * @description Hook that provides controls for HTML media elements (audio/video)
+ * @category Browser
+ *
+ * @overload
+ * @param {HookTarget} target The target media element
+ * @param {string} src The source URL of the media
+ * @returns {UseMediaControlsReturn} An object containing media controls and state
+ *
+ * @example
+ * const { playing, play, pause } = useMediaControls(videoRef, 'video.mp4');
+ *
+ * @overload
+ * @param {HookTarget} target The target media element
+ * @param {UseMediaSource} options The media source configuration
+ * @returns {UseMediaControlsReturn} An object containing media controls and state
+ *
+ * @example
+ * const { playing, play, pause } = useMediaControls(audioRef, { src: 'audio.mp3', type: 'audio/mp3' });
+ *
+ * @overload
+ * @template Target The target media element type
+ * @param {string} src The source URL of the media
+ * @returns {UseMediaControlsReturn & { ref: StateRef<Target> }} An object containing media controls, state and ref
+ *
+ * @example
+ * const { ref, playing, play, pause } = useMediaControls<HTMLVideoElement>('video.mp4');
+ *
+ * @overload
+ * @template Target The target media element type
+ * @param {UseMediaSource} options The media source configuration
+ * @returns {UseMediaControlsReturn & { ref: StateRef<Target> }} An object containing media controls, state and ref
+ *
+ * @example
+ * const { ref, playing, play, pause } = useMediaControls<HTMLVideoElement>({ src: 'video.mp4', type: 'video/mp4' });
+ */
+export declare const useMediaControls: UseMediaControls;

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

@@ -0,0 +1,53 @@
+import { HookTarget } from '../../utils/helpers';
+import { StateRef } from '../useRefState/useRefState';
+/** The use picture in picture options type */
+export interface UsePictureInPictureOptions {
+    /** The callback when Picture-in-Picture mode is entered */
+    onEnter?: () => void;
+    /** The callback when Picture-in-Picture mode is exited */
+    onExit?: () => void;
+}
+/** The use picture in picture return type */
+export interface UsePictureInPictureReturn {
+    /** Whether Picture-in-Picture mode is currently active */
+    open: boolean;
+    /** Whether Picture-in-Picture mode is supported by the browser */
+    supported: boolean;
+    /** Request to enter Picture-in-Picture mode */
+    enter: () => Promise<void>;
+    /** Request to exit Picture-in-Picture mode */
+    exit: () => Promise<void>;
+    /** Toggle Picture-in-Picture mode */
+    toggle: () => Promise<void>;
+}
+export interface UsePictureInPicture {
+    (target: HookTarget, options?: UsePictureInPictureOptions): UsePictureInPictureReturn;
+    (options?: UsePictureInPictureOptions): UsePictureInPictureReturn & {
+        ref: StateRef<HTMLVideoElement>;
+    };
+}
+/**
+ * @name usePictureInPicture
+ * @description - Hook that provides Picture-in-Picture functionality for video elements
+ * @category Browser
+ *
+ * @browserapi window.PictureInPicture https://developer.mozilla.org/en-US/docs/Web/API/Picture-in-Picture_API
+ *
+ * @overload
+ * @param {HookTarget} target The target video element
+ * @param {() => void} [options.onEnter] Callback when Picture-in-Picture mode is entered
+ * @param {() => void} [options.onExit] Callback when Picture-in-Picture mode is exited
+ * @returns {UsePictureInPictureReturn} An object containing Picture-in-Picture state and controls
+ *
+ * @example
+ * const { open, supported, enter, exit, toggle } = usePictureInPicture(videoRef);
+ *
+ * @overload
+ * @param {() => void} [options.onEnter] Callback when Picture-in-Picture mode is entered
+ * @param {() => void} [options.onExit] Callback when Picture-in-Picture mode is exited
+ * @returns {UsePictureInPictureReturn & { ref: StateRef<HTMLVideoElement> }} An object containing Picture-in-Picture state, controls and ref
+ *
+ * @example
+ * const { ref, open, supported, enter, exit, toggle } = usePictureInPicture();
+ */
+export declare const usePictureInPicture: UsePictureInPicture;

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

@@ -0,0 +1,14 @@
+import { DependencyList, EffectCallback } from 'react';
+export declare const deepEqual: (a: any, b: any) => boolean;
+/**
+ * @name useShallowEffect
+ * @description - Hook that executes an effect only when dependencies change shallowly or deeply.
+ * @category Lifecycle
+ *
+ * @param {EffectCallback} effect The effect callback
+ * @param {DependencyList} [deps] The dependencies list for the effect
+ *
+ * @example
+ * useShallowEffect(() => console.log("effect"), [user]);
+ */
+export declare const useShallowEffect: (effect: EffectCallback, deps?: DependencyList) => void;

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

@@ -11,12 +11,8 @@ export interface UseStorageReturn<Value> {
     set: (value: Value) => void;
 }
 export interface UseStorage {
-    <Value>(key: string, options: UseStorageOptions<Value> & {
-        initialValue: UseStorageInitialValue<Value>;
-    }): UseStorageReturn<Value>;
     <Value>(key: string, options?: UseStorageOptions<Value>): UseStorageReturn<Value | undefined>;
-    <Value>(key: string, initialValue: UseStorageInitialValue<Value>): UseStorageReturn<Value>;
-    <Value>(key: string): UseStorageReturn<Value | undefined>;
+    <Value>(key: string, initialValue?: UseStorageInitialValue<Value>): UseStorageReturn<Value | undefined>;
 }
 export declare const STORAGE_EVENT = "reactuse-storage";
 export declare const dispatchStorageEvent: (params: Partial<StorageEvent>) => boolean;

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

@@ -1,3 +1,6 @@
+export type ThrottledCallback<Params extends unknown[]> = ((...args: Params) => void) & {
+    cancel: () => void;
+};
 /**
  * @name useThrottleCallback
  * @description - Hook that creates a throttled callback
@@ -12,4 +15,4 @@
  * @example
  * const throttled = useThrottleCallback(() => console.log('callback'), 500);
  */
-export declare const useThrottleCallback: <Params extends unknown[], Return>(callback: (...args: Params) => Return, delay: number) => (...args: Params) => void;
+export declare const useThrottleCallback: <Params extends unknown[], Return>(callback: (...args: Params) => Return, delay: number) => ThrottledCallback<Params>;

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

@@ -12,7 +12,7 @@ export interface WizardItem<WizardStepId> {
  * @returns {UseWizardReturn<WizardStepId>} An object containing the current step id and functions to interact with the wizard
  *
  * @example
- * const { currentStepId, set, reset, back, history } = useWizard([
+ * const { currentStepId, set, reset, back, next, history } = useWizard([
  *  { id: 'step1', nodes: ['step2', 'step3'] },
  *  { id: 'step2', nodes: ['step3'] },
  *  { id: 'step3', nodes: [] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siberiacancode/reactuse",
-  "version": "0.2.18",
+  "version": "0.2.20",
   "description": "The ultimate collection of react hooks",
   "author": {
     "name": "SIBERIA CAN CODE 🧊",
@@ -72,11 +72,11 @@
     "@types/react-dom": "^19.1.6",
     "@types/web-bluetooth": "^0.0.21",
     "@vitejs/plugin-react": "^4.6.0",
-    "core-js": "^3.43.0",
+    "core-js": "^3.44.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "shx": "^0.4.0",
-    "vite": "^7.0.2",
+    "vite": "^7.0.4",
     "vite-plugin-dts": "^4.5.4",
     "vitest": "^3.2.4"
   },