@qtpy/use-ref-map 0.0.0 → 0.0.2

package/README.md

@@ -1,26 +1,24 @@
-# Документация по хуку useRefMap
-
-`useRefMap` — это пользовательский React-хук для управления множеством ссылок (`RefObject`) с использованием ключей. Он позволяет динамически создавать, получать и удалять ссылки, а также предоставляет список всех ключей. Хук полезен для императивного управления компонентами или DOM-элементами, например, для вызова методов компонентов, фокусировки или обработки событий прокрутки.
-
 ## Содержание
 - [Возвращаемые значения](#возвращаемые-значения)
 - [Использование](#использование)
   - [Базовое использование](#базовое-использование)
   - [Императивное управление (вызов метода компонента)](#императивное-управление-вызов-метода-компонента)
   - [Удаление ссылки](#удаление-ссылки)
+  - [Очистка всех ссылок](#очистка-всех-ссылок)
   - [Получение всех ключей](#получение-всех-ключей)
 - [Типы](#типы)
 - [Примечания](#примечания)
 
 ## Возвращаемые значения
 
-Хук `useRefMap` возвращает объект со следующими методами:
+Хук `useRefMap` возвращает объект со следующими методами и свойствами:
 
-| Метод          | Тип                                      | Описание                                                                 |
+| Метод/Свойство | Тип                                      | Описание                                                                 |
 |----------------|------------------------------------------|--------------------------------------------------------------------------|
-| `getRef`       | `(key: string) => RefObject<Partial<T>>` | Возвращает ссылку (`RefObject`) для указанного ключа. Если ссылка не существует, создаётся новая с `current: null`. |
+| `getRef`       | `(key: string) => RefObject<T>`         | Возвращает ссылку (`RefObject`) для указанного ключа. Если ссылка не существует, создаётся новая с `current: null`. |
 | `deleteRef`    | `(key: string) => void`                 | Удаляет ссылку и соответствующий ключ из внутреннего хранилища.          |
-| `getAllKeys`   | `() => string[]`                        | Возвращает массив всех ключей, связанных с существующими ссылками.       |
+| `clearAllRefs` | `() => void`                            | Очищает все ссылки и ключи из внутреннего хранилища.                     |
+| `allKeys`   | `string[]`                              | Возвращает массив всех ключей, связанных с существующими ссылками.       |
 
 ## Использование
 
@@ -29,12 +27,12 @@
 Пример использования `useRefMap` с `map` для создания ссылок на элементы и обработки события прокрутки:
 
 ```jsx
-import { useRefMap } from './useRefMap';
+import useRefMap from '@qtpy/use-ref-map';
+import useEvent from '@qtpy/use-event'; // хук для обработки событий
 import { useState } from 'react';
-import { useEvent } from './useEvent'; // Предполагаемый хук для обработки событий
 
 function ProjectsPage() {
-  const { getRef } = useRefMap<HTMLDivElement>();
+  const { getRef, allKeys } = useRefMap<HTMLDivElement>();
   const [activeIndex, setActiveIndex] = useState(0);
   const projects = ['Проект 1', 'Проект 2', 'Проект 3'];
 
@@ -66,19 +64,22 @@ function ProjectsPage() {
         ))}
       </div>
       <p>Активный проект: {projects[activeIndex]}</p>
+      <p>Ключи ссылок: {allKeys.join(', ')}</p>
     </div>
   );
 }
 ```
 
-В этом примере хук `useRefMap` используется для создания ссылок на элементы `<div>` с помощью метода `map` и ключей вида `project_${index}`. При прокрутке страницы хук `useEvent` проверяет положение каждого элемента через `getBoundingClientRect` и обновляет `activeIndex`, если элемент выходит за верхнюю границу окна, подсвечивая активный проект.
+Ссылка на хук [**useEvent**](https://www.npmjs.com/package/@qtpy/use-event)
+
+В этом примере хук `useRefMap` используется для создания ссылок на элементы `<div>` с помощью метода `map` и ключей вида `project_${index}`. При прокрутке страницы хук `useEvent` проверяет положение каждого элемента через `getBoundingClientRect` и обновляет `activeIndex`, если элемент выходит за верхнюю границу окна, подсвечивая активный проект. Список ключей выводится через `allKeys`.
 
 ### Императивное управление (вызов метода компонента)
 
 Пример императивного вызова метода компонента через `useRefMap`:
 
 ```jsx
-import { useRefMap } from './useRefMap';
+import useRefMap from '@qtpy/use-ref-map';
 
 interface AnimatedLabelComponent {
   setIsActive: (value: boolean) => void;
@@ -107,7 +108,7 @@ function AccordionCard({ keyName, title }: { keyName: string; title: string }) {
 Удаление ненужной ссылки из хранилища:
 
 ```jsx
-import { useRefMap } from './useRefMap';
+import useRefMap from '@qtpy/use-ref-map';
 
 function Component() {
   const { getRef, deleteRef } = useRefMap<HTMLElement>();
@@ -126,18 +127,44 @@ function Component() {
 }
 ```
 
+### Очистка всех ссылок
+
+Пример использования метода `clearAllRefs` для удаления всех ссылок:
+
+```jsx
+import useRefMap from '@qtpy/use-ref-map';
+
+function Component() {
+  const { getRef, clearAllRefs, allKeys } = useRefMap<HTMLElement>();
+
+  const clearRefs = () => {
+    clearAllRefs();
+    console.log('Все ссылки очищены. Текущие ключи:', allKeys);
+  };
+
+  return (
+    <div>
+      <section ref={getRef('section1')}>Секция 1</section>
+      <section ref={getRef('section2')}>Секция 2</section>
+      <button onClick={clearRefs}>Очистить все ссылки</button>
+      <p>Ключи: {allKeys.join(', ')}</p>
+    </div>
+  );
+}
+```
+
 ### Получение всех ключей
 
 Получение списка всех ключей для проверки существующих ссылок:
 
 ```jsx
-import { useRefMap } from './useRefMap';
+import useRefMap from '@qtpy/use-ref-map';
 
 function Component() {
-  const { getRef, getAllKeys } = useRefMap<HTMLElement>();
+  const { getRef, allKeys } = useRefMap<HTMLElement>();
 
   const logKeys = () => {
-    console.log('Текущие ключи:', getAllKeys());
+    console.log('Текущие ключи:', allKeys);
   };
 
   return (
@@ -145,6 +172,7 @@ function Component() {
       <section ref={getRef('section1')}>Секция 1</section>
       <section ref={getRef('section2')}>Секция 2</section>
       <button onClick={logKeys}>Вывести ключи</button>
+      <p>Ключи: {allKeys.join(', ')}</p>
     </div>
   );
 }
@@ -158,23 +186,24 @@ function Component() {
 export type RefMap<T> = Record<string, RefObject<T>>;
 
 export type RefMapMethods<T> = {
-  getRef: (key: string) => RefObject<Partial<T>>;
+  getRef: (key: string) => RefObject<T>;
   deleteRef: (key: string) => void;
-  getAllKeys: () => string[];
+  clearAllRefs: () => void;
+  allKeys: string[];
 };
 
 export type UseRefMapReturn<T, E extends keyof RefMapMethods<T>> = Pick<RefMapMethods<T>, E>;
 ```
 
 - `RefMap<T>`: Объект, где ключи — это строки, а значения — `RefObject<T>`.
-- `RefMapMethods<T>`: Интерфейс, описывающий методы, возвращаемые хуком.
-- `UseRefMapReturn<T, E>`: Тип возвращаемого значения хука, который позволяет указать подмножество методов через `E`.
+- `RefMapMethods<T>`: Интерфейс, описывающий методы и свойства, возвращаемые хуком.
+- `UseRefMapReturn<T, E>`: Тип возвращаемого значения хука, который позволяет указать подмножество методов/свойств через `E`.
 
 ## Примечания
 
 - **Императивное управление**: Хук удобен для вызова методов компонентов (например, `setIsActive`) или DOM-операций, таких как `scrollIntoView`, `focus` или `getBoundingClientRect`, через свойство `current`.
 - **Инициализация ссылок**: Метод `getRef` создаёт новую ссылку с `current: null`, если ссылка для указанного ключа ещё не существует.
-- **Типизация**: Хук поддерживает обобщённый тип `T` для работы с любыми типами данных (например, пользовательскими интерфейсами компонентов или `HTMLElement`).
-- **Управление памятью**: Метод `deleteRef` предотвращает утечки памяти, удаляя ненужные ссылки.
-- **Сохранение состояния**: Хук использует `useRef` для хранения ссылок и ключей, что обеспечивает их неизменность между рендерами без лишних обновлений.
-- **Ограничение типизации**: `RefObject` возвращает `Partial<T>`, чтобы учесть случаи, когда `current` может быть `null`.
+- **Типизация**: Хук поддерживает обобщённый тип `T` для работы с любыми типами данных (например, пользовательскими интерфейсами компонентов или `HTMLElement`). В отличие от предыдущей версии, `getRef` возвращает `RefObject<T>` вместо `RefObject<Partial<T>>`, предполагая, что `current` может быть `null`, но типизация остаётся строгой.
+- **Управление памятью**: Метод `deleteRef` удаляет отдельные ссылки, а `clearAllRefs` очищает все ссылки, предотвращая утечки памяти. Хук автоматически очищает все ссылки при размонтировании компонента через `useEffect`.
+- **Сохранение состояния**: Хук использует `useRef` для хранения ссылок и ключей, а `useMemo` для кэширования массива ключей, обновляемого через внутренний счётчик версии (`version`).
+- **Ограничение типизации**: Свойство `allKeys` возвращает `string[]` напрямую, а не функцию, что упрощает доступ к ключам, но требует использования `useMemo` для оптимизации рендеринга.

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";const n=require("react");function u(){const r=n.useRef({}),t=n.useRef(new Set);return{getRef:e=>(r.current[e]||(r.current[e]={current:null},t.current.add(e)),r.current[e]),deleteRef:e=>{r.current[e]&&(delete r.current[e],t.current.delete(e))},getAllKeys:()=>Array.from(t.current)}}module.exports=u;
+"use strict";const t=require("react");function l(){const r=t.useRef({}),n=t.useRef(new Set),[u,f]=t.useState(0),o=e=>(r.current[e]||(r.current[e]={current:null},n.current.add(e)),r.current[e]),c=e=>{r.current[e]&&(delete r.current[e],n.current.delete(e))},s=()=>{Object.keys(r.current).forEach(c),f(e=>e+1)};return t.useEffect(()=>()=>s(),[]),{getRef:o,deleteRef:c,clearAllRefs:s,allKeys:t.useMemo(()=>Array.from(n.current),[u])}}module.exports=l;

package/dist/index.d.ts

@@ -1,13 +1,10 @@
-import { RefObject } from "react";
+import { RefObject } from 'react';
 export type RefMap<T> = Record<string, RefObject<T>>;
-export default function useRefMap<T>(): {
+export type RefMapMethods<T> = {
     getRef: (key: string) => RefObject<T>;
     deleteRef: (key: string) => void;
-    getAllKeys: () => string[];
-};
-export type RefMapMethods<T> = {
-    getRef: (key: string) => RefObject<Partial<T>>;
-    deleteRef: (key: string) => RefObject<Partial<T>>;
-    getAllKeys: () => string[];
+    clearAllRefs: () => void;
+    allKeys: string[];
 };
+export default function useRefMap<T>(): RefMapMethods<T>;
 export type UseRefMapReturn<T, E extends keyof RefMapMethods<T>> = Pick<RefMapMethods<T>, E>;

package/dist/index.mjs

@@ -1,14 +1,17 @@
-import { useRef as n } from "react";
-function s() {
-  const r = n({}), t = n(/* @__PURE__ */ new Set());
-  return {
-    getRef: (e) => (r.current[e] || (r.current[e] = { current: null }, t.current.add(e)), r.current[e]),
-    deleteRef: (e) => {
-      r.current[e] && (delete r.current[e], t.current.delete(e));
-    },
-    getAllKeys: () => Array.from(t.current)
+import { useRef as s, useState as l, useEffect as a, useMemo as d } from "react";
+function R() {
+  const r = s({}), t = s(/* @__PURE__ */ new Set()), [u, f] = l(0), o = (e) => (r.current[e] || (r.current[e] = { current: null }, t.current.add(e)), r.current[e]), n = (e) => {
+    r.current[e] && (delete r.current[e], t.current.delete(e));
+  }, c = () => {
+    Object.keys(r.current).forEach(n), f((e) => e + 1);
+  };
+  return a(() => () => c(), []), {
+    getRef: o,
+    deleteRef: n,
+    clearAllRefs: c,
+    allKeys: d(() => Array.from(t.current), [u])
   };
 }
 export {
-  s as default
+  R as default
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qtpy/use-ref-map",
-  "version": "0.0.0",
+  "version": "0.0.2",
   "author": "QtPy",
   "license": "MIT",
   "homepage": "https://github.com/TheOnlyFastCoder2/QtPy-library/tree/main/useRefMap",