@vef-framework/hooks 2.0.11 → 2.1.0

package/dist/es/use-viewport-size/index.js

@@ -0,0 +1,34 @@
+/*! @vef-framework/hooks v2.1.0 made by Venus | 2026-03-27T07:13:03.756Z */
+import { useWindowEvent as e } from "../lib.js";
+import { useRafState as t } from "../use-raf-state/index.js";
+import { isUndefined as n } from "@vef-framework/shared";
+import { useEffect as r } from "react";
+//#region src/use-viewport-size/index.ts
+var i = { passive: !0 };
+function a() {
+	let a = !n(globalThis.window), [o, s] = t(() => ({
+		width: a ? window.innerWidth : 0,
+		height: a ? window.innerHeight : 0
+	}));
+	return r(() => {
+		function e() {
+			n(globalThis.window) || s({
+				width: window.innerWidth,
+				height: window.innerHeight
+			});
+		}
+		e();
+	}, [s]), e("resize", () => {
+		n(globalThis.window) || s({
+			width: window.innerWidth,
+			height: window.innerHeight
+		});
+	}, i), e("orientationchange", () => {
+		n(globalThis.window) || s({
+			width: window.innerWidth,
+			height: window.innerHeight
+		});
+	}, i), o;
+}
+//#endregion
+export { a as useViewportSize };

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
-export { assignRef, getHotkeyHandler, HotkeysProvider, mergeRefs, useColorScheme, useDebouncedCallback, useDebouncedState, useDebouncedValue, useDidUpdate, useDocumentTitle, useElementSize, useEventListener, useFocusTrap, useFullscreen, useHotkeys, useHotkeysContext, useIntersection, useInterval, useIsFirstRender, useIsomorphicEffect, useMediaQuery, useMergedRef, useMounted, useMutationObserver, usePrevious, useRecordHotkeys, useReducedMotion, useResizeObserver, useTimeout, useWindowEvent, type HotkeyCallback, type HotkeysOptions } from './lib';
+export * from './lib';
 export { useAuthorizedItems, type PermissionAware } from './use-authorized-items';
 export { useBreakpoints, type Breakpoints, type UseBreakpointsOptions, type UseBreakpointsResult } from './use-breakpoints';
 export { useCheckPermission } from './use-check-permission';
@@ -23,4 +23,5 @@ export { useShallowEffect } from './use-shallow-effect';
 export { useShallowIsomorphicEffect } from './use-shallow-isomorphic-effect';
 export { useShallowLayoutEffect } from './use-shallow-layout-effect';
 export { useShallowMemo } from './use-shallow-memo';
-export { useSingleton, type SingletonRefObject } from './use-singleton';
+export { useSingleton } from './use-singleton';
+export { useViewportSize } from './use-viewport-size';

package/dist/types/lib.d.ts

@@ -2,5 +2,6 @@ import { UseColorSchemeValue, UseMediaQueryOptions } from '@mantine/hooks';
 export declare function useMediaQuery(query: string, initialValue?: boolean, options?: UseMediaQueryOptions): boolean;
 export declare function useColorScheme(initialValue?: UseColorSchemeValue, options?: UseMediaQueryOptions): UseColorSchemeValue;
 export declare function useReducedMotion(initialValue?: boolean, options?: UseMediaQueryOptions): boolean;
+export { useChat, useCompletion, experimental_useObject as useObject, type Chat, type CreateUIMessage, type UIMessage, type UseChatHelpers, type UseChatOptions, type UseCompletionHelpers, type UseCompletionOptions, type Experimental_UseObjectHelpers as UseObjectHelpers, type Experimental_UseObjectOptions as UseObjectOptions } from '@ai-sdk/react';
 export { assignRef, getHotkeyHandler, mergeRefs, useDebouncedCallback, useDebouncedState, useDebouncedValue, useDidUpdate, useDocumentTitle, useElementSize, useEventListener, useFocusTrap, useFullscreen, useIntersection, useInterval, useIsFirstRender, useIsomorphicEffect, useMergedRef, useMounted, useMutationObserver, usePrevious, useResizeObserver, useTimeout, useWindowEvent } from '@mantine/hooks';
 export { HotkeysProvider, useHotkeys, useHotkeysContext, useRecordHotkeys, type HotkeyCallback, type Options as HotkeysOptions } from 'react-hotkeys-hook';

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

@@ -0,0 +1,27 @@
+export * from './lib';
+export { useAuthorizedItems, type PermissionAware } from './use-authorized-items';
+export { useBreakpoints, type Breakpoints, type UseBreakpointsOptions, type UseBreakpointsResult } from './use-breakpoints';
+export { useCheckPermission } from './use-check-permission';
+export { useDataDictQuery, type UseDataDictQueryOptions } from './use-data-dict-query';
+export { useDataOptionsQuery, type FieldExtractor, type UseDataOptionsQueryOptions, type UseDataOptionsQueryResult } from './use-data-options';
+export { useDeepCallback } from './use-deep-callback';
+export { useDeepCompare } from './use-deep-compare';
+export { useDeepEffect } from './use-deep-effect';
+export { useDeepIsomorphicEffect } from './use-deep-isomorphic-effect';
+export { useDeepLayoutEffect } from './use-deep-layout-effect';
+export { useDeepMemo } from './use-deep-memo';
+export { useDocumentEvent } from './use-document-event';
+export { useEmitterEvent } from './use-emitter-event';
+export { useHasFetching } from './use-has-fetching';
+export { useHasMutating } from './use-has-mutating';
+export { useIsAuthorized } from './use-is-authorized';
+export { useLatest } from './use-latest';
+export { useRafState } from './use-raf-state';
+export { useShallowCallback } from './use-shallow-callback';
+export { useShallowCompare } from './use-shallow-compare';
+export { useShallowEffect } from './use-shallow-effect';
+export { useShallowIsomorphicEffect } from './use-shallow-isomorphic-effect';
+export { useShallowLayoutEffect } from './use-shallow-layout-effect';
+export { useShallowMemo } from './use-shallow-memo';
+export { useSingleton } from './use-singleton';
+export { useViewportSize } from './use-viewport-size';

package/dist/types/src/lib.d.ts

@@ -0,0 +1,7 @@
+import { UseColorSchemeValue, UseMediaQueryOptions } from '@mantine/hooks';
+export declare function useMediaQuery(query: string, initialValue?: boolean, options?: UseMediaQueryOptions): boolean;
+export declare function useColorScheme(initialValue?: UseColorSchemeValue, options?: UseMediaQueryOptions): UseColorSchemeValue;
+export declare function useReducedMotion(initialValue?: boolean, options?: UseMediaQueryOptions): boolean;
+export { useChat, useCompletion, experimental_useObject as useObject, type Chat, type CreateUIMessage, type UIMessage, type UseChatHelpers, type UseChatOptions, type UseCompletionHelpers, type UseCompletionOptions, type Experimental_UseObjectHelpers as UseObjectHelpers, type Experimental_UseObjectOptions as UseObjectOptions } from '@ai-sdk/react';
+export { assignRef, getHotkeyHandler, mergeRefs, useDebouncedCallback, useDebouncedState, useDebouncedValue, useDidUpdate, useDocumentTitle, useElementSize, useEventListener, useFocusTrap, useFullscreen, useIntersection, useInterval, useIsFirstRender, useIsomorphicEffect, useMergedRef, useMounted, useMutationObserver, usePrevious, useResizeObserver, useTimeout, useWindowEvent } from '@mantine/hooks';
+export { HotkeysProvider, useHotkeys, useHotkeysContext, useRecordHotkeys, type HotkeyCallback, type Options as HotkeysOptions } from 'react-hotkeys-hook';

package/dist/types/src/use-authorized-items/index.d.ts

@@ -0,0 +1,22 @@
+import { PermissionCheckMode } from '@vef-framework/core';
+import { MaybeArray } from '@vef-framework/shared';
+/**
+ * Interface for items that have permission requirements.
+ */
+export interface PermissionAware {
+    /**
+     * The permission tokens to check.
+     */
+    permTokens?: MaybeArray<string>;
+    /**
+     * The permission check mode (default: "any").
+     */
+    checkMode?: PermissionCheckMode;
+}
+/**
+ * Hook to filter items based on user permissions.
+ *
+ * @param items - The items to filter based on permissions.
+ * @returns The filtered items that the user is authorized to access.
+ */
+export declare function useAuthorizedItems<T extends PermissionAware>(items: T[]): T[];

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

@@ -0,0 +1,55 @@
+export type BreakpointValue = number | string;
+export type Breakpoints<T extends string = string> = Record<T, BreakpointValue>;
+/**
+ * Result returned by useBreakpoints hook
+ */
+export interface UseBreakpointsResult<T extends string = string> {
+    /**
+     * The name of the current active breakpoint (largest matching)
+     */
+    current?: T;
+    /**
+     * The numeric value of the current breakpoint
+     */
+    value?: BreakpointValue;
+    /**
+     * Array of all matching breakpoint names
+     */
+    matches: T[];
+}
+/**
+ * Options for useBreakpoints hook
+ */
+export interface UseBreakpointsOptions<T extends string = string> {
+    /**
+     * Initial breakpoint name for SSR (server-side rendering)
+     * If not provided, will default to null during SSR
+     */
+    initialBreakpoint?: T;
+    /**
+     * Get initial value in effect instead of on mount
+     * This helps avoid hydration mismatches in SSR
+     *
+     * @default false
+     */
+    getInitialValueInEffect?: boolean;
+}
+/**
+ * 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
+ * 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/src/use-check-permission/index.d.ts

@@ -0,0 +1,8 @@
+import { PermissionCheckMode } from '@vef-framework/core';
+import { MaybeArray } from '@vef-framework/shared';
+/**
+ * Hook that returns a function to check permissions imperatively.
+ *
+ * @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/src/use-data-dict-query/index.d.ts

@@ -0,0 +1,15 @@
+import { DataOption, UseQueryOptions, UseQueryResult } from '@vef-framework/core';
+import { Except } from '@vef-framework/shared';
+export type UseDataDictQueryOptions<TData = DataOption> = Except<UseQueryOptions<DataOption[], TData[], string>, "queryFn" | "queryKey" | "queryHash" | "queryKeyHashFn"> & {
+    dataDictKey?: string;
+    onFetch?: (data: TData[]) => void;
+};
+/**
+ * A hook for querying data dictionary.
+ * Uses the dataDictQueryFn from app context to fetch data dictionary options.
+ *
+ * @param dataDictKey - The key of the data dictionary to query.
+ * @param options - Additional query options (excluding queryFn and queryKey).
+ * @returns The query result containing data dictionary options.
+ */
+export declare function useDataDictQuery<TData = DataOption>({ dataDictKey, onFetch, ...options }: UseDataDictQueryOptions<TData>): UseQueryResult<TData[]>;

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

@@ -0,0 +1,86 @@
+import { DataOption, DataOptionWithPinyin, UseQueryOptions, UseQueryResult } from '@vef-framework/core';
+import { Key, MaybeUndefined, Simplify } from '@vef-framework/shared';
+/**
+ * Field extractor - can be a string path (e.g., "user.name") or a function
+ */
+export type FieldExtractor<TData, TValue> = string | ((item: TData) => TValue);
+/**
+ * Base field mapping options
+ */
+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[]>>;
+}
+/**
+ * Options for useDataOptionsQuery with regular query
+ */
+export type UseDataOptionsQueryOptionsWithQuery<TQueryFnData = unknown, TData = TQueryFnData, TParams = never> = DataOptionsFieldMapping<TData> & {
+    /**
+     * Options for fetching data using regular query
+     */
+    queryOptions: UseQueryOptions<TQueryFnData[], TData[], TParams>;
+    /**
+     * Data dictionary key - should not be provided when using queryOptions
+     */
+    dataDictKey?: never;
+};
+/**
+ * Options for useDataOptionsQuery with data dictionary query
+ */
+export type UseDataOptionsQueryOptionsWithDataDict<TData = DataOption> = DataOptionsFieldMapping<TData> & {
+    /**
+     * Data dictionary key
+     */
+    dataDictKey: string;
+    /**
+     * Regular query options - should not be provided when using dataDictKey
+     */
+    queryOptions?: never;
+};
+/**
+ * Options for useDataOptionsQuery hook - supports both regular query and data dictionary query
+ */
+export type UseDataOptionsQueryOptions<TQueryFnData = unknown, TData = TQueryFnData, TParams = never> = UseDataOptionsQueryOptionsWithQuery<TQueryFnData, TData, TParams> | UseDataOptionsQueryOptionsWithDataDict<TData>;
+/**
+ * Return type for useDataOptionsQuery hook
+ */
+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;
+}): UseDataOptionsQueryResult<TData, DataOptionWithPinyin<TData>>;

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

@@ -0,0 +1,11 @@
+import { DependencyList } from 'react';
+/**
+ * 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 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 (...args: any[]) => any>(callback: T, dependencies: DependencyList): T;

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

@@ -0,0 +1,9 @@
+import { DependencyList } from 'react';
+/**
+ * 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 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/src/use-deep-effect/index.d.ts

@@ -0,0 +1,10 @@
+import { DependencyList, EffectCallback } from 'react';
+/**
+ * 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 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/src/use-deep-isomorphic-effect/index.d.ts

@@ -0,0 +1,11 @@
+import { DependencyList, EffectCallback } from 'react';
+/**
+ * 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 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/src/use-deep-layout-effect/index.d.ts

@@ -0,0 +1,10 @@
+import { DependencyList, EffectCallback } from 'react';
+/**
+ * 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 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/src/use-deep-memo/index.d.ts

@@ -0,0 +1,11 @@
+import { DependencyList } from 'react';
+/**
+ * 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 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/src/use-document-event/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 - 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/src/use-emitter-event/index.d.ts

@@ -0,0 +1,17 @@
+import { EventHandler, EventType, EventEmitter } from '@vef-framework/shared';
+/**
+ * Subscribes to an EventEmitter event with automatic cleanup.
+ *
+ * @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, any>>(emitter: EventEmitter<TEvents>, eventType: keyof TEvents, eventListener: EventHandler<TEvents[keyof TEvents]>): void;

package/dist/types/src/use-has-fetching/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A hook to check if there are any active queries fetching for a specific query key.
+ *
+ * @param key - The base query key to check for fetching status.
+ * @param params - Optional parameters to include in the query key for more specific filtering.
+ * @returns True if there are any active queries fetching with the specified key, false otherwise.
+ */
+export declare function useHasFetching(key: string, params?: unknown): boolean;

package/dist/types/src/use-has-mutating/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A hook to check if there are any active mutations for a specific mutation key.
+ *
+ * @param key - The base mutation key to check for mutating status.
+ * @returns True if there are any active mutations with the specified key, false otherwise.
+ */
+export declare function useHasMutating(key: string): boolean;

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

@@ -0,0 +1,10 @@
+import { PermissionCheckMode } from '@vef-framework/core';
+import { MaybeArray } from '@vef-framework/shared';
+/**
+ * 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 (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/src/use-latest/index.d.ts

@@ -0,0 +1,21 @@
+import { MutableRefObject } from 'react';
+/**
+ * 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 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): MutableRefObject<T>;

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

@@ -0,0 +1,23 @@
+import { Dispatch, SetStateAction } from 'react';
+/**
+ * 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 - 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/src/use-shallow-callback/index.d.ts

@@ -0,0 +1,14 @@
+import { DependencyList } from 'react';
+/**
+ * Memoizes a callback function with shallow comparison of dependencies.
+ *
+ * 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 (...args: any[]) => any>(callback: T, dependencies: DependencyList): T;

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

@@ -0,0 +1,13 @@
+import { DependencyList } from 'react';
+/**
+ * Performs shallow comparison of dependency arrays for React hooks.
+ * Returns a stable reference that only changes when dependencies are not shallowly equal.
+ *
+ * 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/src/use-shallow-effect/index.d.ts

@@ -0,0 +1,13 @@
+import { DependencyList, EffectCallback } from 'react';
+/**
+ * Runs an effect with shallow comparison of dependencies.
+ *
+ * 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/src/use-shallow-isomorphic-effect/index.d.ts

@@ -0,0 +1,13 @@
+import { DependencyList, EffectCallback } from 'react';
+/**
+ * Runs an isomorphic effect with shallow comparison of dependencies.
+ *
+ * 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/src/use-shallow-layout-effect/index.d.ts

@@ -0,0 +1,13 @@
+import { DependencyList, EffectCallback } from 'react';
+/**
+ * Runs a layout effect with shallow comparison of dependencies.
+ *
+ * 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/src/use-shallow-memo/index.d.ts

@@ -0,0 +1,14 @@
+import { DependencyList } from 'react';
+/**
+ * Memoizes a value with shallow comparison of dependencies.
+ *
+ * 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/src/use-singleton/index.d.ts

@@ -0,0 +1,18 @@
+import { RefObject } from 'react';
+/**
+ * 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 - 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): RefObject<T>;

package/dist/types/src/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/dist/types/use-authorized-items/index.d.ts

@@ -1,7 +1,7 @@
 import { PermissionCheckMode } from '@vef-framework/core';
 import { MaybeArray } from '@vef-framework/shared';
 /**
- * The permission aware interface.
+ * Interface for items that have permission requirements.
  */
 export interface PermissionAware {
     /**
@@ -9,14 +9,14 @@ export interface PermissionAware {
      */
     permTokens?: MaybeArray<string>;
     /**
-     * The permission check mode.
+     * The permission check mode (default: "any").
      */
     checkMode?: PermissionCheckMode;
 }
 /**
- * The use authorized items hook.
+ * Hook to filter items based on user permissions.
  *
- * @param items - The items to filter.
- * @returns The filtered items.
+ * @param items - The items to filter based on permissions.
+ * @returns The filtered items that the user is authorized to access.
  */
 export declare function useAuthorizedItems<T extends PermissionAware>(items: T[]): T[];