@ahoo-wang/fetcher-react 2.12.9 → 2.13.1

package/README.md

@@ -31,6 +31,7 @@ robust data fetching capabilities.
   - [usePromiseState Hook](#usepromisestate-hook)
   - [useRequestId Hook](#userequestid-hook)
   - [useLatest Hook](#uselatest-hook)
+  - [useRefs Hook](#userefs-hook)
   - [useKeyStorage Hook](#usekeystorage-hook)
   - [Wow Query Hooks](#wow-query-hooks)
     - [useListQuery Hook](#uselistquery-hook)
@@ -282,6 +283,39 @@ const MyComponent = () => {
 };
 ```
 
+### useRefs Hook
+
+The `useRefs` hook provides a Map-like interface for managing multiple React refs dynamically. It allows registering, retrieving, and managing refs by key, with automatic cleanup on component unmount.
+
+```typescript jsx
+import { useRefs } from '@ahoo-wang/fetcher-react';
+
+const MyComponent = () => {
+  const refs = useRefs<HTMLDivElement>();
+
+  const handleFocus = (key: string) => {
+    const element = refs.get(key);
+    element?.focus();
+  };
+
+  return (
+    <div>
+      <div ref={refs.register('first')} tabIndex={0}>First Element</div>
+      <div ref={refs.register('second')} tabIndex={0}>Second Element</div>
+      <button onClick={() => handleFocus('first')}>Focus First</button>
+      <button onClick={() => handleFocus('second')}>Focus Second</button>
+    </div>
+  );
+};
+```
+
+Key features:
+
+- **Dynamic Registration**: Register refs with string, number, or symbol keys
+- **Map-like API**: Full Map interface with get, set, has, delete, etc.
+- **Automatic Cleanup**: Refs are cleared when component unmounts
+- **Type Safety**: Full TypeScript support for ref types
+
 ### useKeyStorage Hook
 
 The `useKeyStorage` hook provides reactive state management for a KeyStorage instance. It subscribes to storage changes and returns the current value along with a setter function. Optionally accepts a default value to use when the storage is empty.
@@ -1369,6 +1403,39 @@ callbacks.
 
 A ref object with a `current` property containing the latest value
 
+### useRefs
+
+```typescript
+function useRefs<T>(): UseRefsReturn<T>;
+```
+
+A React hook for managing multiple refs with a Map-like interface, allowing dynamic registration and retrieval of refs by key.
+
+**Type Parameters:**
+
+- `T`: The type of the ref instances (e.g., HTMLElement)
+
+**Returns:**
+
+An object implementing `UseRefsReturn<T>` with:
+
+- `register(key: RefKey): (instance: T | null) => void` - Returns a callback to register/unregister a ref
+- `get(key: RefKey): T | undefined` - Get a ref by key
+- `set(key: RefKey, value: T): void` - Set a ref value
+- `has(key: RefKey): boolean` - Check if key exists
+- `delete(key: RefKey): boolean` - Delete a ref by key
+- `clear(): void` - Clear all refs
+- `size: number` - Number of refs
+- `keys(): IterableIterator<RefKey>` - Iterator over keys
+- `values(): IterableIterator<T>` - Iterator over values
+- `entries(): IterableIterator<[RefKey, T]>` - Iterator over entries
+- `Symbol.iterator`: Iterator for for...of loops
+
+**Related Types:**
+
+- `RefKey = string | number | symbol`
+- `UseRefsReturn<T> extends Iterable<[RefKey, T]>`
+
 ### useKeyStorage
 
 ```typescript

package/README.zh-CN.md

@@ -30,6 +30,7 @@
   - [usePromiseState Hook](#usepromisestate-hook)
   - [useRequestId Hook](#userequestid-hook)
   - [useLatest Hook](#uselatest-hook)
+  - [useRefs Hook](#userefs-hook)
   - [useKeyStorage Hook](#usekeystorage-hook)
   - [Wow 查询 Hooks](#wow-查询-hooks)
     - [useListQuery Hook](#uselistquery-hook)
@@ -277,6 +278,39 @@ const MyComponent = () => {
 };
 ```
 
+### useRefs Hook
+
+`useRefs` hook 提供 Map-like 接口用于动态管理多个 React refs。它允许通过键注册、检索和管理 refs，并在组件卸载时自动清理。
+
+```typescript jsx
+import { useRefs } from '@ahoo-wang/fetcher-react';
+
+const MyComponent = () => {
+  const refs = useRefs<HTMLDivElement>();
+
+  const handleFocus = (key: string) => {
+    const element = refs.get(key);
+    element?.focus();
+  };
+
+  return (
+    <div>
+      <div ref={refs.register('first')} tabIndex={0}>第一个元素</div>
+      <div ref={refs.register('second')} tabIndex={0}>第二个元素</div>
+      <button onClick={() => handleFocus('first')}>聚焦第一个</button>
+      <button onClick={() => handleFocus('second')}>聚焦第二个</button>
+    </div>
+  );
+};
+```
+
+关键特性：
+
+- **动态注册**: 使用字符串、数字或符号键注册 refs
+- **Map-like API**: 完整的 Map 接口，包括 get、set、has、delete 等
+- **自动清理**: 组件卸载时自动清空 refs
+- **类型安全**: 完整的 TypeScript 支持
+
 ### useKeyStorage Hook
 
 `useKeyStorage` hook 为 KeyStorage 实例提供反应式状态管理。它订阅存储变化并返回当前值以及设置函数。可选接受默认值以在存储为空时使用。
@@ -738,6 +772,39 @@ function useLatest<T>(value: T): { current: T };
 
 包含 `current` 属性（包含最新值）的 ref 对象
 
+### useRefs
+
+```typescript
+function useRefs<T>(): UseRefsReturn<T>;
+```
+
+React hook，用于使用 Map-like 接口管理多个 refs，允许通过键动态注册和检索 refs。
+
+**类型参数:**
+
+- `T`: ref 实例的类型（例如 HTMLElement）
+
+**返回值:**
+
+实现 `UseRefsReturn<T>` 的对象，具有：
+
+- `register(key: RefKey): (instance: T | null) => void` - 返回用于注册/注销 ref 的回调
+- `get(key: RefKey): T | undefined` - 通过键获取 ref
+- `set(key: RefKey, value: T): void` - 设置 ref 值
+- `has(key: RefKey): boolean` - 检查键是否存在
+- `delete(key: RefKey): boolean` - 通过键删除 ref
+- `clear(): void` - 清空所有 refs
+- `size: number` - refs 数量
+- `keys(): IterableIterator<RefKey>` - 键的迭代器
+- `values(): IterableIterator<T>` - 值的迭代器
+- `entries(): IterableIterator<[RefKey, T]>` - 条目的迭代器
+- `Symbol.iterator`: for...of 循环的迭代器
+
+**相关类型:**
+
+- `RefKey = string | number | symbol`
+- `UseRefsReturn<T> extends Iterable<[RefKey, T]>`
+
 ### useKeyStorage
 
 ```typescript jsx

package/dist/core/index.d.ts

@@ -3,4 +3,5 @@ export * from './usePromiseState';
 export * from './useRequestId';
 export * from './useLatest';
 export * from './useMounted';
+export * from './useRefs';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAaA,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAaA,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}

package/dist/core/useLatest.d.ts

@@ -1,4 +1,4 @@
-import { MutableRefObject } from 'react';
+import { RefObject } from 'react';
 /**
  * A React hook that returns a ref containing the latest value, useful for accessing the current value in async callbacks.
  *
@@ -29,5 +29,5 @@ import { MutableRefObject } from 'react';
  * };
  * ```
  */
-export declare function useLatest<T>(value: T): MutableRefObject<T>;
+export declare function useLatest<T>(value: T): RefObject<T>;
 //# sourceMappingURL=useLatest.d.ts.map

package/dist/core/useLatest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useLatest.d.ts","sourceRoot":"","sources":["../../src/core/useLatest.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,gBAAgB,EAAU,MAAM,OAAO,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAI1D"}
+{"version":3,"file":"useLatest.d.ts","sourceRoot":"","sources":["../../src/core/useLatest.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,SAAS,EAAU,MAAM,OAAO,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAInD"}

package/dist/core/useRefs.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The key type for refs, supporting string, number, or symbol.
+ */
+export type RefKey = string | number | symbol;
+/**
+ * Return type of useRefs hook, providing Map-like interface for managing refs.
+ * @template T - The type of the ref instances.
+ */
+export interface UseRefsReturn<T> extends Iterable<[RefKey, T]> {
+    register: (key: RefKey) => (instance: T | null) => void;
+    get: (key: RefKey) => T | undefined;
+    set: (key: RefKey, value: T) => void;
+    delete: (key: RefKey) => boolean;
+    has: (key: RefKey) => boolean;
+    clear: () => void;
+    readonly size: number;
+    keys: () => IterableIterator<RefKey>;
+    values: () => IterableIterator<T>;
+    entries: () => IterableIterator<[RefKey, T]>;
+}
+/**
+ * A React hook for managing multiple refs with a Map-like interface.
+ * Allows dynamic registration and retrieval of refs by key, with automatic cleanup on unmount.
+ *
+ * @template T - The type of the ref instances (e.g., HTMLElement).
+ * @returns An object with Map methods and a register function for managing refs.
+ *
+ * @example
+ * ```tsx
+ * const refs = useRefs<HTMLDivElement>();
+ *
+ * // Register a ref
+ * const refCallback = refs.register('myDiv');
+ * <div ref={refCallback} />
+ *
+ * // Access the ref
+ * const element = refs.get('myDiv');
+ * ```
+ */
+export declare function useRefs<T>(): UseRefsReturn<T>;
+//# sourceMappingURL=useRefs.d.ts.map

package/dist/core/useRefs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRefs.d.ts","sourceRoot":"","sources":["../../src/core/useRefs.ts"],"names":[],"mappings":"AAeA;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9C;;;GAGG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,CAAE,SAAQ,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAC7D,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,QAAQ,EAAE,CAAC,GAAG,IAAI,KAAK,IAAI,CAAC;IACxD,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,GAAG,SAAS,CAAC;IACpC,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IACrC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACjC,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAC9B,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACrC,MAAM,EAAE,MAAM,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAClC,OAAO,EAAE,MAAM,gBAAgB,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,OAAO,CAAC,CAAC,KAAK,aAAa,CAAC,CAAC,CAAC,CA+C7C"}