@vef-framework/hooks 2.0.10 → 2.1.0

package/dist/types/use-breakpoints/index.d.ts

@@ -29,19 +29,27 @@ export interface UseBreakpointsOptions<T extends string = string> {
     /**
      * Get initial value in effect instead of on mount
      * This helps avoid hydration mismatches in SSR
+     *
      * @default false
      */
     getInitialValueInEffect?: boolean;
 }
 /**
- * Hook to track active breakpoints based on window width
- *
- * @param breakpoints - Breakpoint configuration object
- * @param options - Hook options
- * @returns Current breakpoint information
+ * Tracks active responsive breakpoints based on window width using media queries.
+ * Returns the current breakpoint and all matching breakpoints.
  *
+ * @param breakpoints - Breakpoint configuration object mapping names to min-width values.
+ * @param options - Hook options for SSR and hydration handling.
+ * @returns Current breakpoint information including name, value, and all matches.
  * @remarks
- * **Important**: Since this hook uses `min-width` media queries, you should include
- * a breakpoint starting from 0 to ensure all viewport sizes are covered.
+ * Uses `min-width` media queries, so include a breakpoint starting from 0 to cover all viewport sizes.
+ * @example
+ * ```tsx
+ * const breakpoints = { xs: 0, sm: 640, md: 768, lg: 1024, xl: 1280 };
+ * const { current, matches } = useBreakpoints(breakpoints);
+ *
+ * // current: 'md' (largest matching breakpoint)
+ * // matches: ['xs', 'sm', 'md'] (all matching breakpoints)
+ * ```
  */
 export declare function useBreakpoints<T extends string>(breakpoints: Breakpoints<T>, options?: UseBreakpointsOptions<T>): UseBreakpointsResult<T>;

package/dist/types/use-check-permission/index.d.ts

@@ -1,8 +1,8 @@
 import { PermissionCheckMode } from '@vef-framework/core';
 import { MaybeArray } from '@vef-framework/shared';
 /**
- * The use check permission hook.
+ * Hook that returns a function to check permissions imperatively.
  *
- * @returns The check permission function.
+ * @returns A function that checks if the user has the specified permissions.
  */
 export declare function useCheckPermission(): (permTokens?: MaybeArray<string>, checkMode?: PermissionCheckMode) => boolean;

package/dist/types/use-data-dict-query/index.d.ts

@@ -1,6 +1,6 @@
 import { DataOption, UseQueryOptions, UseQueryResult } from '@vef-framework/core';
 import { Except } from '@vef-framework/shared';
-export type UseDataDictQueryOptions<TData = DataOption> = Except<UseQueryOptions<DataOption[], TData[]>, "queryFn" | "queryKey" | "queryHash" | "queryKeyHashFn"> & {
+export type UseDataDictQueryOptions<TData = DataOption> = Except<UseQueryOptions<DataOption[], TData[], string>, "queryFn" | "queryKey" | "queryHash" | "queryKeyHashFn"> & {
     dataDictKey?: string;
     onFetch?: (data: TData[]) => void;
 };

package/dist/types/use-data-options/index.d.ts

@@ -1,5 +1,5 @@
 import { DataOption, DataOptionWithPinyin, UseQueryOptions, UseQueryResult } from '@vef-framework/core';
-import { Key, MaybeUndefined, Prettify } from '@vef-framework/shared';
+import { Key, MaybeUndefined, Simplify } from '@vef-framework/shared';
 /**
  * Field extractor - can be a string path (e.g., "user.name") or a function
  */
@@ -10,26 +10,31 @@ export type FieldExtractor<TData, TValue> = string | ((item: TData) => TValue);
 export interface DataOptionsFieldMapping<TData = unknown> {
     /**
      * Field mapping for label
+     *
      * @default "label"
      */
     labelKey?: FieldExtractor<TData, string>;
     /**
      * Field mapping for value
+     *
      * @default "value"
      */
     valueKey?: FieldExtractor<TData, Key>;
     /**
      * Field mapping for disabled
+     *
      * @default "disabled"
      */
     disabledKey?: FieldExtractor<TData, MaybeUndefined<boolean>>;
     /**
      * Field mapping for description
+     *
      * @default "description"
      */
     descriptionKey?: FieldExtractor<TData, MaybeUndefined<string>>;
     /**
      * Field mapping for children
+     *
      * @default "children"
      */
     childrenKey?: FieldExtractor<TData, MaybeUndefined<TData[]>>;
@@ -67,13 +72,14 @@ export type UseDataOptionsQueryOptions<TQueryFnData = unknown, TData = TQueryFnD
 /**
  * Return type for useDataOptionsQuery hook
  */
-export type UseDataOptionsQueryResult<TData, TOption> = Prettify<Omit<UseQueryResult<TData[]>, "data"> & {
+export type UseDataOptionsQueryResult<TData, TOption> = Simplify<Omit<UseQueryResult<TData[]>, "data"> & {
     options: TOption[];
 }>;
 export declare function useDataOptionsQuery<TQueryFnData = unknown, TData = TQueryFnData, TParams = never>(config: UseDataOptionsQueryOptions<TQueryFnData, TData, TParams>): UseDataOptionsQueryResult<TData, DataOption<TData>>;
 export declare function useDataOptionsQuery<TQueryFnData = unknown, TData = TQueryFnData, TParams = never>(options: UseDataOptionsQueryOptions<TQueryFnData, TData, TParams> & {
     /**
      * Whether to add pinyin fields for label and description
+     *
      * @default false
      */
     withPinyin: boolean;

package/dist/types/use-deep-callback/index.d.ts

@@ -1,9 +1,11 @@
 import { DependencyList } from 'react';
 /**
- * Use the deep callback of the callback
+ * Memoizes a callback function with deep comparison of dependencies.
+ * Unlike `useCallback`, this performs deep equality checks on dependency values,
+ * preventing unnecessary callback recreation when objects/arrays have the same content.
  *
- * @param callback - The callback to memo.
- * @param dependencies - The dependencies to compare.
- * @returns The memoized callback.
+ * @param callback - The callback function to memoize.
+ * @param dependencies - The dependency array to deeply compare for changes.
+ * @returns The memoized callback that only changes when dependencies are deeply different.
  */
-export declare function useDeepCallback<T extends Function>(callback: T, dependencies: DependencyList): T;
+export declare function useDeepCallback<T extends (...args: any[]) => any>(callback: T, dependencies: DependencyList): T;

package/dist/types/use-deep-compare/index.d.ts

@@ -1,8 +1,9 @@
 import { DependencyList } from 'react';
 /**
- * Use the deep compare of the dependencies
+ * Performs deep comparison of dependency arrays to detect changes.
+ * Unlike React's default shallow comparison, this compares nested objects and arrays by value.
  *
- * @param dependencies - The dependencies to compare.
- * @returns The signal of the dependencies.
+ * @param dependencies - The dependency array to track for deep changes.
+ * @returns A memoized array containing a signal value that changes only when dependencies are deeply different.
  */
 export declare function useDeepCompare(dependencies?: DependencyList): readonly [number];

package/dist/types/use-deep-effect/index.d.ts

@@ -1,9 +1,10 @@
 import { DependencyList, EffectCallback } from 'react';
 /**
- * Use the deep effect of the effect
+ * Runs an effect with deep comparison of dependencies.
+ * Unlike `useEffect`, this performs deep equality checks on dependency values,
+ * preventing unnecessary effect execution when objects/arrays have the same content.
  *
- * @param effect - The effect to run.
- * @param dependencies - The dependencies to compare.
- * @returns The effect.
+ * @param effect - The effect callback to execute.
+ * @param dependencies - The dependency array to deeply compare for changes.
  */
 export declare function useDeepEffect(effect: EffectCallback, dependencies?: DependencyList): void;

package/dist/types/use-deep-isomorphic-effect/index.d.ts

@@ -1,9 +1,11 @@
 import { DependencyList, EffectCallback } from 'react';
 /**
- * Use the deep isomorphic effect of the effect
+ * Runs an isomorphic effect with deep comparison of dependencies.
+ * Uses `useLayoutEffect` on the client and `useEffect` on the server.
+ * Unlike `useIsomorphicEffect`, this performs deep equality checks on dependency values,
+ * preventing unnecessary effect execution when objects/arrays have the same content.
  *
- * @param effect - The effect to run.
- * @param dependencies - The dependencies to compare.
- * @returns The effect.
+ * @param effect - The effect callback to execute.
+ * @param dependencies - The dependency array to deeply compare for changes.
  */
 export declare function useDeepIsomorphicEffect(effect: EffectCallback, dependencies?: DependencyList): void;

package/dist/types/use-deep-layout-effect/index.d.ts

@@ -1,9 +1,10 @@
 import { DependencyList, EffectCallback } from 'react';
 /**
- * Use the deep layout effect of the effect
+ * Runs a layout effect with deep comparison of dependencies.
+ * Unlike `useLayoutEffect`, this performs deep equality checks on dependency values,
+ * preventing unnecessary effect execution when objects/arrays have the same content.
  *
- * @param effect - The effect to run.
- * @param dependencies - The dependencies to compare.
- * @returns The effect.
+ * @param effect - The effect callback to execute synchronously after DOM mutations.
+ * @param dependencies - The dependency array to deeply compare for changes.
  */
 export declare function useDeepLayoutEffect(effect: EffectCallback, dependencies?: DependencyList): void;

package/dist/types/use-deep-memo/index.d.ts

@@ -1,9 +1,11 @@
 import { DependencyList } from 'react';
 /**
- * Use the deep memo of the factory
+ * Memoizes a computed value with deep comparison of dependencies.
+ * Unlike `useMemo`, this performs deep equality checks on dependency values,
+ * preventing unnecessary recomputation when objects/arrays have the same content.
  *
- * @param factory - The factory to memo.
- * @param dependencies - The dependencies to compare.
- * @returns The memoized value.
+ * @param factory - The factory function that computes the memoized value.
+ * @param dependencies - The dependency array to deeply compare for changes.
+ * @returns The memoized value that only recomputes when dependencies are deeply different.
  */
 export declare function useDeepMemo<T>(factory: () => T, dependencies: DependencyList): T;

package/dist/types/use-document-event/index.d.ts

@@ -1,8 +1,19 @@
 /**
- * Hook to listen for document events.
+ * Attaches an event listener to the document with automatic cleanup.
+ * The listener function is always called with the latest version, preventing stale closures.
  *
- * @param type - The type of event to listen for.
- * @param listener - The function to call when the event is triggered.
- * @param options - The options to pass to the event listener.
+ * @param type - Event type to listen for (e.g., 'click', 'keydown').
+ * @param listener - Event handler function.
+ * @param options - Event listener options (capture, passive, once).
+ * @example
+ * ```tsx
+ * function Component() {
+ *   useDocumentEvent('keydown', (event) => {
+ *     if (event.key === 'Escape') {
+ *       closeModal();
+ *     }
+ *   });
+ * }
+ * ```
  */
 export declare function useDocumentEvent<TType extends string>(type: TType, listener: TType extends keyof DocumentEventMap ? (this: Document, event: DocumentEventMap[TType]) => void : (this: Document, event: CustomEvent) => void, options?: boolean | AddEventListenerOptions): void;

package/dist/types/use-emitter-event/index.d.ts

@@ -1,9 +1,17 @@
 import { EventHandler, EventType, EventEmitter } from '@vef-framework/shared';
 /**
- * A hook to listen to an event from an EventEmitter.
+ * Subscribes to an EventEmitter event with automatic cleanup.
  *
- * @param emitter - The EventEmitter instance to listen to.
- * @param eventType - The type of event to listen to.
- * @param eventListener - The function to call when the event is emitted.
+ * @param emitter - EventEmitter instance to subscribe to.
+ * @param eventType - Event type to listen for.
+ * @param eventListener - Event handler function.
+ * @example
+ * ```tsx
+ * function Component({ emitter }) {
+ *   useEmitterEvent(emitter, 'data', (data) => {
+ *     console.log('Received:', data);
+ *   });
+ * }
+ * ```
  */
-export declare function useEmitterEvent<TEvents extends Record<EventType, unknown>>(emitter: EventEmitter<TEvents>, eventType: keyof TEvents, eventListener: EventHandler<TEvents[keyof TEvents]>): void;
+export declare function useEmitterEvent<TEvents extends Record<EventType, any>>(emitter: EventEmitter<TEvents>, eventType: keyof TEvents, eventListener: EventHandler<TEvents[keyof TEvents]>): void;

package/dist/types/use-is-authorized/index.d.ts

@@ -1,10 +1,10 @@
 import { PermissionCheckMode } from '@vef-framework/core';
 import { MaybeArray } from '@vef-framework/shared';
 /**
- * The use is authorized hook.
+ * Hook to check if the user is authorized based on permission tokens.
  *
  * @param permTokens - The permission tokens to check.
- * @param checkMode - The check mode to use.
+ * @param checkMode - The check mode to use (default: "any").
  * @returns Whether the user is authorized to access the resource identified by the permission token.
  */
 export declare function useIsAuthorized(permTokens?: MaybeArray<string>, checkMode?: PermissionCheckMode): boolean;

package/dist/types/use-latest/index.d.ts

@@ -1,8 +1,21 @@
-import { RefObject } from 'react';
+import { MutableRefObject } from 'react';
 /**
- * Use the latest value of the ref
+ * Returns a ref that always contains the latest value.
+ * Useful for accessing current props/state in callbacks without re-creating them.
  *
- * @param value - The value to use.
- * @returns The latest value of the ref.
+ * @param value - The value to track.
+ * @returns A ref object containing the latest value.
+ * @example
+ * ```tsx
+ * function Component({ onChange }) {
+ *   const onChangeRef = useLatest(onChange);
+ *
+ *   useEffect(() => {
+ *     const handler = () => onChangeRef.current();
+ *     window.addEventListener('resize', handler);
+ *     return () => window.removeEventListener('resize', handler);
+ *   }, []); // No need to include onChange in deps
+ * }
+ * ```
  */
-export declare function useLatest<T>(value: T): RefObject<T>;
+export declare function useLatest<T>(value: T): MutableRefObject<T>;

package/dist/types/use-raf-state/index.d.ts

@@ -1,8 +1,23 @@
 import { Dispatch, SetStateAction } from 'react';
 /**
- * A hook to use the request animation frame state.
+ * State hook that batches updates using requestAnimationFrame.
+ * Useful for high-frequency updates (e.g., scroll, resize, mouse move) to prevent excessive re-renders.
  *
- * @param initialState - The initial state.
- * @returns The state and the set state function.
+ * @param initialState - Initial state value or lazy initializer function.
+ * @returns Tuple of [state, setState] similar to useState.
+ * @example
+ * ```tsx
+ * function Component() {
+ *   const [position, setPosition] = useRafState({ x: 0, y: 0 });
+ *
+ *   useEffect(() => {
+ *     const handleMove = (e: MouseEvent) => {
+ *       setPosition({ x: e.clientX, y: e.clientY });
+ *     };
+ *     window.addEventListener('mousemove', handleMove);
+ *     return () => window.removeEventListener('mousemove', handleMove);
+ *   }, []);
+ * }
+ * ```
  */
 export declare function useRafState<T>(initialState: T | (() => T)): [T, Dispatch<SetStateAction<T>>];

package/dist/types/use-shallow-callback/index.d.ts

@@ -1,9 +1,14 @@
 import { DependencyList } from 'react';
 /**
- * Use the shallow callback of the callback
+ * Memoizes a callback function with shallow comparison of dependencies.
  *
- * @param callback - The callback to memo.
- * @param dependencies - The dependencies to compare.
- * @returns The memoized callback.
+ * Similar to React's useCallback, but uses shallow equality comparison for the
+ * dependency array instead of reference equality. This is useful when your
+ * dependencies are objects or arrays that may have the same content but
+ * different references.
+ *
+ * @param callback - The callback function to memoize.
+ * @param dependencies - Dependency array to compare shallowly.
+ * @returns The memoized callback function.
  */
-export declare function useShallowCallback<T extends Function>(callback: T, dependencies: DependencyList): T;
+export declare function useShallowCallback<T extends (...args: any[]) => any>(callback: T, dependencies: DependencyList): T;

package/dist/types/use-shallow-compare/index.d.ts

@@ -1,8 +1,13 @@
 import { DependencyList } from 'react';
 /**
- * Use the shallow compare of the dependencies
+ * Performs shallow comparison of dependency arrays for React hooks.
+ * Returns a stable reference that only changes when dependencies are not shallowly equal.
  *
- * @param dependencies - The dependencies to compare.
- * @returns The signal of the dependencies.
+ * This is useful for optimizing hooks like useEffect, useMemo, and useCallback
+ * when you want to compare object/array dependencies by their shallow content
+ * rather than by reference identity.
+ *
+ * @param dependencies - The dependency array to compare.
+ * @returns A tuple containing a signal number that increments when dependencies change.
  */
 export declare function useShallowCompare(dependencies?: DependencyList): readonly [number];

package/dist/types/use-shallow-effect/index.d.ts

@@ -1,9 +1,13 @@
 import { DependencyList, EffectCallback } from 'react';
 /**
- * Use the shallow effect of the effect
+ * Runs an effect with shallow comparison of dependencies.
  *
- * @param effect - The effect to run.
- * @param dependencies - The dependencies to compare.
- * @returns The effect.
+ * Similar to React's useEffect, but uses shallow equality comparison for the
+ * dependency array instead of reference equality. This is useful when your
+ * dependencies are objects or arrays that may have the same content but
+ * different references.
+ *
+ * @param effect - The effect function to run.
+ * @param dependencies - Dependency array to compare shallowly.
  */
 export declare function useShallowEffect(effect: EffectCallback, dependencies?: DependencyList): void;

package/dist/types/use-shallow-isomorphic-effect/index.d.ts

@@ -1,9 +1,13 @@
 import { DependencyList, EffectCallback } from 'react';
 /**
- * Use the shallow isomorphic effect of the effect
+ * Runs an isomorphic effect with shallow comparison of dependencies.
  *
- * @param effect - The effect to run.
- * @param dependencies - The dependencies to compare.
- * @returns The effect.
+ * Similar to useIsomorphicEffect (useLayoutEffect on client, useEffect on server),
+ * but uses shallow equality comparison for the dependency array instead of reference
+ * equality. This is useful when your dependencies are objects or arrays that may
+ * have the same content but different references.
+ *
+ * @param effect - The effect function to run.
+ * @param dependencies - Dependency array to compare shallowly.
  */
 export declare function useShallowIsomorphicEffect(effect: EffectCallback, dependencies?: DependencyList): void;

package/dist/types/use-shallow-layout-effect/index.d.ts

@@ -1,9 +1,13 @@
 import { DependencyList, EffectCallback } from 'react';
 /**
- * Use the shallow layout effect of the effect
+ * Runs a layout effect with shallow comparison of dependencies.
  *
- * @param effect - The effect to run.
- * @param dependencies - The dependencies to compare.
- * @returns The effect.
+ * Similar to React's useLayoutEffect, but uses shallow equality comparison for the
+ * dependency array instead of reference equality. This is useful when your
+ * dependencies are objects or arrays that may have the same content but
+ * different references.
+ *
+ * @param effect - The effect function to run synchronously after DOM mutations.
+ * @param dependencies - Dependency array to compare shallowly.
  */
 export declare function useShallowLayoutEffect(effect: EffectCallback, dependencies?: DependencyList): void;

package/dist/types/use-shallow-memo/index.d.ts

@@ -1,9 +1,14 @@
 import { DependencyList } from 'react';
 /**
- * Use the shallow memo of the factory
+ * Memoizes a value with shallow comparison of dependencies.
  *
- * @param factory - The factory to memo.
- * @param dependencies - The dependencies to compare.
+ * Similar to React's useMemo, but uses shallow equality comparison for the
+ * dependency array instead of reference equality. This is useful when your
+ * dependencies are objects or arrays that may have the same content but
+ * different references.
+ *
+ * @param factory - Function that returns the value to memoize.
+ * @param dependencies - Dependency array to compare shallowly.
  * @returns The memoized value.
  */
 export declare function useShallowMemo<T>(factory: () => T, dependencies: DependencyList): T;

package/dist/types/use-singleton/index.d.ts

@@ -1,11 +1,18 @@
 import { RefObject } from 'react';
-export interface SingletonRefObject<T> extends RefObject<T> {
-    readonly current: T;
-}
 /**
- * A hook that returns a singleton ref object.
+ * Creates a singleton value that persists across renders and is initialized only once.
+ * The initializer function is called only on the first render.
  *
- * @param initializer - The initializer for the singleton.
- * @returns The singleton ref object.
+ * @param initializer - Function that creates the singleton value.
+ * @returns A ref object containing the singleton value.
+ * @example
+ * ```tsx
+ * function Component() {
+ *   const emitter = useSingleton(() => new EventEmitter());
+ *   const id = useSingleton(() => Math.random());
+ *
+ *   // emitter.current and id.current are stable across renders
+ * }
+ * ```
  */
-export declare function useSingleton<T>(initializer: () => T): SingletonRefObject<T>;
+export declare function useSingleton<T>(initializer: () => T): RefObject<T>;

package/dist/types/use-viewport-size/index.d.ts

@@ -0,0 +1,20 @@
+export interface ViewportSize {
+    width: number;
+    height: number;
+}
+/**
+ * Tracks the current viewport dimensions (window.innerWidth/innerHeight).
+ * Automatically updates on window resize and orientation change events.
+ * Uses requestAnimationFrame to batch updates and prevent excessive re-renders.
+ *
+ * @returns Current viewport size object with width and height.
+ * @example
+ * ```tsx
+ * function Component() {
+ *   const { width, height } = useViewportSize();
+ *
+ *   return <div>Viewport: {width}x{height}</div>;
+ * }
+ * ```
+ */
+export declare function useViewportSize(): ViewportSize;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vef-framework/hooks",
   "type": "module",
-  "version": "2.0.10",
+  "version": "2.1.0",
   "private": false,
   "description": "Hooks for VEF framework",
   "author": {
@@ -20,7 +20,7 @@
   "sideEffects": false,
   "exports": {
     ".": {
-      "source": "./src/index.ts",
+      "vef": "./src/index.ts",
       "import": {
         "types": "./dist/types/index.d.ts",
         "default": "./dist/es/index.js"
@@ -48,13 +48,14 @@
     "react": ">=19"
   },
   "dependencies": {
-    "@mantine/hooks": "^8.3.9",
-    "react-hotkeys-hook": "^5.2.1",
-    "@vef-framework/core": "2.0.10",
-    "@vef-framework/shared": "2.0.10"
+    "@ai-sdk/react": "3.0.140",
+    "@mantine/hooks": "^8.3.18",
+    "react-hotkeys-hook": "^5.2.4",
+    "@vef-framework/shared": "2.1.0",
+    "@vef-framework/core": "2.1.0"
   },
   "devDependencies": {
-    "react": "^19.2.0"
+    "react": "^19.2.4"
   },
   "scripts": {
     "clean": "rimraf dist",