@siberiacancode/reactuse 0.2.31 → 0.2.33

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/elements.d.ts

@@ -5,6 +5,7 @@ export * from './useDoubleClick/useDoubleClick';
 export * from './useDropZone/useDropZone';
 export * from './useFileDialog/useFileDialog';
 export * from './useFocus/useFocus';
+export * from './useFocusTrap/useFocusTrap';
 export * from './useHover/useHover';
 export * from './useImage/useImage';
 export * from './useLongPress/useLongPress';

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

@@ -1,3 +1,4 @@
+export * from './useAsyncEffect/useAsyncEffect';
 export * from './useDidUpdate/useDidUpdate';
 export * from './useIsFirstRender/useIsFirstRender';
 export * from './useIsomorphicLayoutEffect/useIsomorphicLayoutEffect';

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

@@ -1,4 +1,5 @@
 export * from './useBoolean/useBoolean';
+export * from './useControllableState/useControllableState';
 export * from './useCookie/useCookie';
 export * from './useCookies/useCookies';
 export * from './useCounter/useCounter';

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

@@ -1,12 +1,14 @@
 import { HookTarget } from '../../utils/helpers';
 import { StateRef } from '../useRefState/useRefState';
+/** The use active element return type */
+export type UseActiveElementReturn<ActiveElement extends HTMLElement = HTMLElement> = ActiveElement | null;
 export interface UseActiveElement {
-    (): HTMLElement | null;
+    (): UseActiveElementReturn;
     <Target extends Element, ActiveElement extends HTMLElement = HTMLElement>(target?: never): {
         ref: StateRef<Target>;
-        value: ActiveElement | null;
+        value: UseActiveElementReturn<ActiveElement>;
     };
-    <ActiveElement extends HTMLElement = HTMLElement>(target: HookTarget): ActiveElement | null;
+    <ActiveElement extends HTMLElement = HTMLElement>(target: HookTarget): UseActiveElementReturn<ActiveElement>;
 }
 /**
  * @name useActiveElement

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

@@ -0,0 +1,14 @@
+import { DependencyList } from 'react';
+/**
+ * @name useAsyncEffect
+ * @description – Hook that triggers the effect callback on updates
+ * @category Lifecycle
+ * @usage medium
+
+ * @param {EffectCallback} effect The effect callback
+ * @param {DependencyList} [deps] The dependencies list for the effect
+ *
+ * @example
+ * useAsyncEffect(async () => console.log("effect runs on updates"), deps);
+ */
+export declare const useAsyncEffect: (сallback: () => Promise<any>, deps?: DependencyList) => void;

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

@@ -0,0 +1,34 @@
+/** The use controllable state options type */
+export interface UseControllableStateOptions<Value> {
+    /** The initial value for uncontrolled state */
+    initialValue?: Value;
+    /** The controlled value */
+    value?: Value;
+    /** The onChange callback */
+    onChange?: (value: Value) => void;
+}
+/** The use controllable state return type */
+export type UseControllableStateReturn<Value> = [
+    /** Current value */
+    value: Value,
+    /** Setter function that works with both controlled and uncontrolled state */
+    setValue: (nextValue: ((prevValue: Value) => Value) | Value) => void,
+    /** Whether the state is controlled */
+    isControlled: boolean
+];
+/**
+ * @name useControllableState
+ * @description - Hook that manages both controlled and uncontrolled state patterns
+ * @category State
+ * @usage medium
+ *
+ * @template Value The type of the state value
+ * @param {Value} [options.value] The controlled value. When provided, the component becomes controlled
+ * @param {Value} [options.initialValue] The initial value for uncontrolled state
+ * @param {(value: Value) => void} [options.onChange] The callback function called when the state changes
+ * @returns {UseControllableStateReturn<Value>} A tuple containing the current value, setter function, and controlled flag
+ *
+ * @example
+ * const [value, setValue, isControlled] = useControllableState({ initialValue: 'initial' });
+ */
+export declare function useControllableState<Value>(options: UseControllableStateOptions<Value>): UseControllableStateReturn<Value>;

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

@@ -0,0 +1,42 @@
+import { HookTarget } from '../../utils/helpers';
+import { StateRef } from '../useRefState/useRefState';
+/** The use focus trap return type */
+export interface UseFocusTrapReturn {
+    /** Whether focus trap is active */
+    active: boolean;
+    /** Disable focus trap */
+    disable: () => void;
+    /** Enable focus trap */
+    enable: () => void;
+    /** Toggle focus trap */
+    toggle: () => void;
+}
+export interface UseFocusTrap {
+    (target: HookTarget, active?: boolean): UseFocusTrapReturn;
+    <Target extends HTMLElement>(active?: boolean, target?: never): UseFocusTrapReturn & {
+        ref: StateRef<Target>;
+    };
+}
+/**
+ * @name useFocusTrap
+ * @description - Hook that traps focus within a given element
+ * @category Elements
+ * @usage medium
+ *
+ * @overload
+ * @param {HookTarget} target The target element for focus trap
+ * @param {boolean} [active=true] Whether focus trap is active
+ * @returns {UseFocusTrapReturn} Object with control methods and state
+ *
+ * @example
+ * const { active, disable, toggle, enable } = useFocusTrap(ref, true);
+ *
+ * @overload
+ * @template Target The target element type
+ * @param {boolean} [active=true] Whether focus trap is active
+ * @returns {UseFocusTrapReturn & { ref: StateRef<Target> }} Object with ref and controls
+ *
+ * @example
+ * const { ref, active, disable, toggle, enable } = useFocusTrap(true);
+ */
+export declare const useFocusTrap: UseFocusTrap;

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

@@ -33,16 +33,35 @@ export interface UseScrollCallbackParams {
         bottom: boolean;
     };
 }
+/** The scroll into view params type */
+export interface ScrollIntoViewParams {
+    behavior?: ScrollBehavior;
+    block?: ScrollLogicalPosition;
+    inline?: ScrollLogicalPosition;
+}
+/** The scroll to params type */
+export interface ScrollToParams {
+    behavior?: ScrollBehavior;
+    x: number;
+    y: number;
+}
+/** The use scroll return type */
+export interface UseScrollReturn {
+    /** The state of scrolling */
+    scrolling: boolean;
+    /** Function to scroll element into view */
+    scrollIntoView: (params?: ScrollIntoViewParams) => void;
+    /** Function to scroll element to a specific position */
+    scrollTo: (params?: ScrollToParams) => void;
+}
 export interface UseScroll {
-    (target?: HookTarget, callback?: (params: UseScrollCallbackParams, event: Event) => void): boolean;
-    (target?: HookTarget, options?: UseScrollOptions): boolean;
-    <Target extends Element>(callback?: (params: UseScrollCallbackParams, event: Event) => void, target?: never): {
+    (target?: HookTarget, callback?: (params: UseScrollCallbackParams, event: Event) => void): UseScrollReturn;
+    (target?: HookTarget, options?: UseScrollOptions): UseScrollReturn;
+    <Target extends Element>(callback?: (params: UseScrollCallbackParams, event: Event) => void, target?: never): UseScrollReturn & {
         ref: StateRef<Target>;
-        scrolling: boolean;
     };
-    <Target extends Element>(options?: UseScrollOptions, target?: never): {
+    <Target extends Element>(options?: UseScrollOptions, target?: never): UseScrollReturn & {
         ref: StateRef<Target>;
-        scrolling: boolean;
     };
 }
 /**
@@ -60,18 +79,18 @@ export interface UseScroll {
  * @param {number} [options.offset.bottom=0] The bottom offset for arrived states
  * @param {(params: UseScrollCallbackParams, event: Event) => void} [options.onScroll] The callback function to be invoked on scroll
  * @param {(event: Event) => void} [options.onStop] The callback function to be invoked on scroll end
- * @returns {boolean} The state of scrolling
+ * @returns {UseScrollReturn} The state of scrolling
  *
  * @example
- * const scrolling = useScroll(ref, options);
+ * const { scrolling, scrollIntoView, scrollTo} = useScroll(ref, options);
  *
  * @overload
  * @template Target The target element
  * @param {(params: UseScrollCallbackParams, event: Event) => void} [callback] The callback function to be invoked on scroll
- * @returns {boolean} The state of scrolling
+ * @returns {UseScrollReturn} The state of scrolling
  *
  * @example
- * const scrolling = useScroll(ref, () => console.log('callback'));
+ * const { scrolling, scrollIntoView, scrollTo} = useScroll(ref, () => console.log('callback'));
  *
  * @overload
  * @template Target The target element
@@ -83,18 +102,18 @@ export interface UseScroll {
  * @param {number} [options.offset.bottom=0] The bottom offset for arrived states
  * @param {(params: UseScrollCallbackParams, event: Event) => void} [options.onScroll] The callback function to be invoked on scroll
  * @param {(event: Event) => void} [options.onStop] The callback function to be invoked on scroll end
- * @returns {[StateRef<Target>, boolean]} The state of scrolling
+ * @returns {UseScrollReturn & { ref: StateRef<Target> }} The state of scrolling
  *
  * @example
- * const { ref, scrolling } = useScroll(options);
+ * const { ref, scrolling, scrollIntoView, scrollTo} = useScroll(options);
  *
  * @overload
  * @template Target The target element
  * @param {Target} target The target element to scroll
  * @param {(params: UseScrollCallbackParams, event: Event) => void} [callback] The callback function to be invoked on scroll
- * @returns {[StateRef<Target>, boolean]} The state of scrolling
+ * @returns {UseScrollReturn & { ref: StateRef<Target> }} The state of scrolling
  *
  * @example
- * const { ref, scrolling } = useScroll(() => console.log('callback'));
+ * const { ref, scrolling, scrollIntoView, scrollTo} = useScroll(() => console.log('callback'));
  */
 export declare const useScroll: UseScroll;

package/package.json

@@ -1,89 +1,89 @@
-{
-  "name": "@siberiacancode/reactuse",
-  "version": "0.2.31",
-  "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.1",
-    "@testing-library/react": "^16.3.0",
-    "@types/dom-speech-recognition": "^0.0.6",
-    "@types/react": "^19.1.10",
-    "@types/react-dom": "^19.1.7",
-    "@types/web-bluetooth": "^0.0.21",
-    "@vitejs/plugin-react": "^5.0.1",
-    "core-js": "^3.45.0",
-    "react": "^19.1.1",
-    "react-dom": "^19.1.1",
-    "shx": "^0.4.0",
-    "vite": "^7.1.3",
-    "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.33",
+  "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.1",
+    "@testing-library/react": "^16.3.0",
+    "@types/dom-speech-recognition": "^0.0.6",
+    "@types/react": "^19.1.10",
+    "@types/react-dom": "^19.1.7",
+    "@types/web-bluetooth": "^0.0.21",
+    "@vitejs/plugin-react": "^5.0.1",
+    "core-js": "^3.45.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "shx": "^0.4.0",
+    "vite": "^7.1.3",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^3.2.4"
+  },
+  "lint-staged": {
+    "*.{js,ts,tsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  }
+}