@siberiacancode/reactuse 0.2.23 → 0.2.25

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,6 +1,7 @@
 export * from './useActiveElement/useActiveElement';
 export * from './useAsync/useAsync';
 export * from './useAudio/useAudio';
+export * from './useAutoScroll/useAutoScroll';
 export * from './useBattery/useBattery';
 export * from './useBluetooth/useBluetooth';
 export * from './useBoolean/useBoolean';

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

@@ -1,13 +1,32 @@
+import { HookTarget } from '../../utils/helpers';
+import { StateRef } from '../useRefState/useRefState';
+export interface UseActiveElement {
+    (): HTMLElement | null;
+    <Target extends Element, ActiveElement extends HTMLElement = HTMLElement>(target?: never): {
+        ref: StateRef<Target>;
+        value: ActiveElement | null;
+    };
+    <ActiveElement extends HTMLElement = HTMLElement>(target: HookTarget): ActiveElement | null;
+}
 /**
  * @name useActiveElement
  * @description - Hook that returns the active element
  * @category Elements
  *
+ * @overload
+ * @param {HookTarget} [target=window] The target element to observe active element changes
  * @returns {ActiveElement | null} The active element
  *
  * @example
- * const activeElement = useActiveElement();
+ * const activeElement = useActiveElement(ref);
+ *
+ * @overload
+ * @template ActiveElement The active element type
+ * @returns {{ ref: StateRef<Element>; activeElement: ActiveElement | null }} An object containing the ref and active element
+ *
+ * @example
+ * const { ref, value } = useActiveElement();
  *
  * @see {@link https://siberiacancode.github.io/reactuse/functions/hooks/useActiveElement.html}
  */
-export declare const useActiveElement: <ActiveElement extends HTMLElement>() => ActiveElement | null;
+export declare const useActiveElement: UseActiveElement;

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

@@ -0,0 +1,35 @@
+import { HookTarget } from '../../utils/helpers';
+import { StateRef } from '../useRefState/useRefState';
+/** The use auto scroll options type */
+export interface UseAutoScrollOptions {
+    /** Whether auto-scrolling is enabled */
+    enabled?: boolean;
+    /** Whether to force auto-scrolling regardless of user interactions */
+    force?: boolean;
+}
+export interface UseAutoScroll {
+    (target: HookTarget, options?: UseAutoScrollOptions): void;
+    <Target extends HTMLElement>(options?: UseAutoScrollOptions): StateRef<Target>;
+}
+/**
+ * @name useAutoScroll
+ * @description - Hook that automatically scrolls a list element to the bottom
+ * @category Sensors
+ *
+ * @overload
+ * @param {HookTarget} target The target element to auto-scroll
+ * @param {boolean} [options.enabled] Whether auto-scrolling is enabled
+ * @returns {void}
+ *
+ * @example
+ * useAutoScroll(ref);
+ *
+ * @overload
+ * @template Target
+ * @param {boolean} [options.enabled] Whether auto-scrolling is enabled
+ * @returns {StateRef<Target>} A React ref to attach to the list element
+ *
+ * @example
+ * const ref = useAutoScroll();
+ */
+export declare const useAutoScroll: UseAutoScroll;

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

@@ -23,7 +23,7 @@ export interface UseKeyPress {
  * @returns {boolean} The pressed state of the key
  *
  * @example
- * const isKeyPressed = useKeyPress('a', window);
+ * const isKeyPressed = useKeyPress(ref, 'a');
  *
  * @overload
  * @template Target The target element type

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

@@ -1,17 +1,21 @@
 import { HookTarget } from '../../utils/helpers';
 import { StateRef } from '../useRefState/useRefState';
-/** The keyboard event handler type */
+/** The use keyboard event handler type */
 export type KeyboardEventHandler = (event: KeyboardEvent) => void;
-/** The use keyboard options type */
-export interface UseKeyboardOptions {
+/** The use keyboard event options type */
+export interface UseKeyboardEventOptions {
     /** The callback function to be invoked on key down */
     onKeyDown?: KeyboardEventHandler;
     /** The callback function to be invoked on key up */
     onKeyUp?: KeyboardEventHandler;
 }
 export interface UseKeyboard {
-    (target: HookTarget | Window, options: UseKeyboardOptions): void;
-    <Target extends Element>(options: UseKeyboardOptions, target?: never): {
+    (target: HookTarget, callback: KeyboardEventHandler): void;
+    (target: HookTarget, options: UseKeyboardEventOptions): void;
+    <Target extends HTMLElement>(callback: KeyboardEventHandler, target?: never): {
+        ref: StateRef<Target>;
+    };
+    <Target extends HTMLElement>(options: UseKeyboardEventOptions, target?: never): {
         ref: StateRef<Target>;
     };
 }
@@ -21,8 +25,16 @@ export interface UseKeyboard {
  * @category Sensors
  *
  * @overload
- * @param {HookTarget | Window} target The target to attach the event listeners to
- * @param {UseKeyboardOptions} [options] The keyboard event options
+ * @param {HookTarget} target The target to attach the event listeners to
+ * @param {KeyboardEventHandler} callback The callback function to be invoked on key down
+ * @returns {void}
+ *
+ * @example
+ * useKeyboard(ref, (event) => console.log('key down'));
+ *
+ * @overload
+ * @param {HookTarget} target The target to attach the event listeners to
+ * @param {UseKeyboardEventOptions} [options] The keyboard event options
  * @returns {void}
  *
  * @example
@@ -30,7 +42,15 @@ export interface UseKeyboard {
  *
  * @overload
  * @template Target The target element type
- * @param {UseKeyboardOptions} [options] The keyboard event options
+ * @param {KeyboardEventHandler} callback The callback function to be invoked on key down
+ * @returns {{ ref: StateRef<Target> }} An object containing the ref
+ *
+ * @example
+ * const ref = useKeyboard((event) => console.log('key down'));
+ *
+ * @overload
+ * @template Target The target element type
+ * @param {UseKeyboardEventOptions} [options] The keyboard event options
  * @returns {{ ref: StateRef<Target> }} An object containing the ref
  *
  * @example

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

@@ -25,8 +25,8 @@ export interface UseStopwatchReturn {
 }
 /** The use stopwatch options */
 export interface UseStopwatchOptions {
-    /** The enabled state of the timer */
-    enabled?: boolean;
+    /** The immediately state of the timer */
+    immediately?: boolean;
 }
 interface UseStopwatch {
     (initialTime?: number, options?: UseStopwatchOptions): UseStopwatchReturn;

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

@@ -2,7 +2,7 @@ import { UseEventListenerOptions } from '../useEventListener/useEventListener';
 /**
  * @name useWindowEvent
  * @description - Hook attaches an event listener to the window object for the specified event
- * @category Browser
+ * @category Sensors
  *
  * @template Event Key of window event map.
  * @param {Event} event The event to listen for.

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

@@ -6,7 +6,7 @@ export declare const scrollTo: ({ x, y, behavior }: Partial<ScrollPosition & Scr
 /**
  * @name useWindowScroll
  * @description - Hook that manages the window scroll position
- * @category Browser
+ * @category Sensors
  *
  * @returns {UseWindowScrollReturn} An object containing the current window scroll position
  *

package/dist/types/utils/helpers/getElement.d.ts

@@ -9,4 +9,4 @@ export declare const target: (target: Target) => {
     value: Target;
     type: symbol;
 };
-export declare const getElement: (target: HookTarget) => Element | Window | Document | null | undefined;
+export declare const getElement: (target: HookTarget) => Document | Element | Window | null | undefined;

package/package.json

@@ -1,89 +1,89 @@
-{
-  "name": "@siberiacancode/reactuse",
-  "version": "0.2.23",
-  "description": "The ultimate collection of react hooks",
-  "author": {
-    "name": "SIBERIA CAN CODE 🧊",
-    "url": "https://github.com/siberiacancode"
-  },
-  "license": "MIT",
-  "homepage": "https://siberiacancode.github.io/reactuse/",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/siberiacancode/reactuse.git",
-    "directory": "packages/core"
-  },
-  "bugs": "https://github.com/siberiacancode/reactuse/issues",
-  "keywords": [
-    "react",
-    "react hooks",
-    "react use",
-    "use",
-    "hooks"
-  ],
-  "sideEffects": false,
-  "exports": {
-    "types": "./dist/types/index.d.ts",
-    "import": "./dist/esm/index.mjs",
-    "require": "./dist/cjs/index.cjs"
-  },
-  "main": "dist/cjs/index.cjs",
-  "module": "dist/esm/index.mjs",
-  "types": "dist/types/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "engines": {
-    "node": ">=14"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "prepublishOnly": "pnpm unit-test run && pnpm build",
-    "build": "shx rm -rf dist && vite build",
-    "build:js": "tsc --project tsconfig.build.json && prettier --write src/bundle",
-    "lint": "eslint . --fix",
-    "lint-inspector": "npx @eslint/config-inspector@latest",
-    "format": "prettier --write .",
-    "pretty": "pnpm lint && pnpm format",
-    "unit-test": "vitest",
-    "lint-staged": "lint-staged"
-  },
-  "peerDependencies": {
-    "@types/react": "^18 || ^19",
-    "react": "^18 || ^19",
-    "react-dom": "^18 || ^19"
-  },
-  "peerDependenciesMeta": {
-    "@types/react": {
-      "optional": true
-    }
-  },
-  "dependencies": {
-    "screenfull": "^6.0.2"
-  },
-  "devDependencies": {
-    "@siberiacancode/vitest": "^2.1.0",
-    "@testing-library/dom": "^10.4.0",
-    "@testing-library/react": "^16.3.0",
-    "@types/dom-speech-recognition": "^0.0.6",
-    "@types/react": "^19.1.8",
-    "@types/react-dom": "^19.1.6",
-    "@types/web-bluetooth": "^0.0.21",
-    "@vitejs/plugin-react": "^4.6.0",
-    "core-js": "^3.44.0",
-    "react": "^19.1.0",
-    "react-dom": "^19.1.0",
-    "shx": "^0.4.0",
-    "vite": "^7.0.4",
-    "vite-plugin-dts": "^4.5.4",
-    "vitest": "^3.2.4"
-  },
-  "lint-staged": {
-    "*.{js,ts,tsx}": [
-      "eslint --fix",
-      "prettier --write"
-    ]
-  }
-}
+{
+  "name": "@siberiacancode/reactuse",
+  "version": "0.2.25",
+  "description": "The ultimate collection of react hooks",
+  "author": {
+    "name": "SIBERIA CAN CODE 🧊",
+    "url": "https://github.com/siberiacancode"
+  },
+  "license": "MIT",
+  "homepage": "https://siberiacancode.github.io/reactuse/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/siberiacancode/reactuse.git",
+    "directory": "packages/core"
+  },
+  "bugs": "https://github.com/siberiacancode/reactuse/issues",
+  "keywords": [
+    "react",
+    "react hooks",
+    "react use",
+    "use",
+    "hooks"
+  ],
+  "sideEffects": false,
+  "exports": {
+    "types": "./dist/types/index.d.ts",
+    "import": "./dist/esm/index.mjs",
+    "require": "./dist/cjs/index.cjs"
+  },
+  "main": "dist/cjs/index.cjs",
+  "module": "dist/esm/index.mjs",
+  "types": "dist/types/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=14"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepublishOnly": "pnpm unit-test run && pnpm build",
+    "build": "shx rm -rf dist && vite build",
+    "build:js": "tsc --project tsconfig.build.json && prettier --write src/bundle",
+    "lint": "eslint . --fix",
+    "lint-inspector": "npx @eslint/config-inspector@latest",
+    "format": "prettier --write .",
+    "pretty": "pnpm lint && pnpm format",
+    "unit-test": "vitest",
+    "lint-staged": "lint-staged"
+  },
+  "peerDependencies": {
+    "@types/react": "^18 || ^19",
+    "react": "^18 || ^19",
+    "react-dom": "^18 || ^19"
+  },
+  "peerDependenciesMeta": {
+    "@types/react": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "screenfull": "^6.0.2"
+  },
+  "devDependencies": {
+    "@siberiacancode/vitest": "^2.1.0",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/dom-speech-recognition": "^0.0.6",
+    "@types/react": "^19.1.8",
+    "@types/react-dom": "^19.1.6",
+    "@types/web-bluetooth": "^0.0.21",
+    "@vitejs/plugin-react": "^4.6.0",
+    "core-js": "^3.44.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "shx": "^0.4.0",
+    "vite": "^7.0.4",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^3.2.4"
+  },
+  "lint-staged": {
+    "*.{js,ts,tsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  }
+}