indicator-ui 1.0.46 → 1.0.48

package/dist/types/src/hooks/scroll/hooks/useScrollAnchor.d.ts

@@ -7,52 +7,59 @@ type FunReturnType<T> = {
     revertScroll: RevertScroll<T>;
 };
 /**
- * Хук для сохранения визуальной позиции скролла
- * при добавлении элементов в начало списка (prepend) или
- * при изменение размера `layout` между `зоной видимости`
- * и `началом элемента`.
+ * React-хук для фиксации и восстановления якоря скролла.
  *
- * Используется в сценариях, когда новый контент вставляется
- * выше текущей видимой области, из-за чего увеличивается
- * scrollHeight, а браузер сохраняет `scrollTop`.
+ * Предназначен для сохранения визуальной позиции скролла при изменении размеров
+ * скроллируемой области (например, при добавлении или удалении элементов).
  *
- * Хук компенсирует это смещение, сохраняя пользователя
- * на том же визуальном месте списка.
+ * Типичный кейс — добавление элементов в начало scroll-контейнера:
+ * браузеры могут либо автоматически скорректировать позицию скролла,
+ * либо оставить её без изменений, что приводит к визуальному "прыжку".
  *
  * Принцип работы:
- * 1. `commitScroll` — сохраняет текущее состояние скролла и размеры контейнера.
- * 2. В DOM добавляются элементы в начало списка (prepend).
- * 3. `revertScroll` — компенсирует изменение scrollHeight,
- *    корректируя scrollTop так, чтобы видимая область не сместилась.
+ * 1. Перед изменением layout вызывается {@link commitScroll},
+ *    который сохраняет текущее состояние скролла.
+ * 2. Выполняются изменения DOM / layout (важно, чтобы браузер успел пересчитать размеры).
+ * 3. После этого вызывается {@link revertScroll}, который корректирует позицию скролла
+ *    таким образом, чтобы пользователь визуально остался на том же месте.
  *
- * ⚠️ ВАЖНО:
- * Между вызовами `commitScroll` и `revertScroll`
- * изменение DOM должно происходить до этапа раскраски,
- * на этапе просчета `layout`.
+ * Хук поддерживает настройку направления скролла по вертикали и горизонтали.
  *
- * ⚠️ ОГРАНИЧЕНИЕ:
- * Хук предназначен ТОЛЬКО для сценариев добавления элементов
- * в начало списка.
+ * @template T
+ * Тип HTMLElement, для которого применяется якорь скролла.
  *
- * @template T HTMLElement или его наследник
+ * @param {ScrollDirectionOptions} [props]
+ * Настройки направления движения скролла.
  *
- * @param props Параметры компенсации скролла
+ * @param {'top' | 'bottom'} [props.verticalDirection='bottom']
+ * Определяет, в какую сторонц двигается вертикальный scroll.
  *
- * @param props.scrollVerticalDirection
- * Направление компенсации по вертикали.
- * Для prepend-сценариев обычно используется 'bottom' (по умолчанию).
+ * @param {'left' | 'right'} [props.horizontalDirection='right']
+ * Определяет, в какую сторонц двигается горизонтальный scroll.
  *
- * @param props.scrollHorizontalDirection
- * Направление компенсации по горизонтали (по умолчанию 'right').
+ * @returns {FunReturnType<T>}
+ * Объект с методами управления якорем скролла.
  *
- * @returns Объект с методами управления якорем скролла
+ * @returns {Function} returns.commitScroll
+ * Функция для фиксации текущего состояния скролла.
  *
- * @returns.commitScroll
- * Сохраняет состояние скролла ДО добавления элементов в начало списка.
+ * @returns {Function} returns.revertScroll
+ * Функция для восстановления позиции скролла на основе ранее сохранённого состояния.
  *
- * @returns.revertScroll
- * Восстанавливает позицию скролла ПОСЛЕ добавления элементов,
- * но ДО отрисовки браузером.
+ * @example
+ * ```ts
+ * const { commitScroll, revertScroll } = useScrollAnchor<HTMLDivElement>();
+ *
+ * const handlePrependItems = () => {
+ *   const commit = commitScroll(containerRef.current);
+ *
+ *   prependItems();
+ *
+ *   requestAnimationFrame(() => {
+ *     revertScroll(containerRef.current, commit);
+ *   });
+ * };
+ * ```
  */
 export declare function useScrollAnchor<T extends HTMLElement>(props?: PropsType): FunReturnType<T>;
 export {};

package/dist/types/src/hooks/utils/useLockedCallback.d.ts

@@ -1,26 +1,59 @@
 type Args = any[];
+type Return = Promise<any> | void;
+type Callback<TArgs extends Args, TReturn extends Return> = (...args: TArgs) => TReturn;
 /**
- * React-хук, возвращающий эксклюзивную версию callback-функции.
+ * React-хук, возвращающий "заблокированную" (эксклюзивную) версию callback-функции.
  *
- * Функция может быть вызвана многократно, но пока выполняется,
- * повторные вызовы будут **игнорироваться**.
+ * Полученная функция может вызываться многократно, однако:
+ * пока выполняется текущий вызов, все последующие вызовы будут проигнорированы.
  *
- * Полезно для:
- * - кнопок Submit (защита от double click)
- * - async side-effects, которые нельзя выполнять параллельно
- * - любых операций, где нужен mutex на выполнение
+ * Хук поддерживает как синхронные, так и асинхронные callback-функции.
+ * В случае Promise-базированного callback блокировка снимается после его завершения
+ * (`finally`). Для синхронных функций разблокировка происходит сразу после выполнения.
  *
- * @template TArgs Тип аргументов callback-функции
- * @param callback Асинхронная или синхронная функция, которую нужно защитить от параллельных вызовов
- * @returns Функцию с той же сигнатурой, но блокирующую повторные вызовы пока выполняется
+ * Дополнительно можно указать задержку (`delay`), которая определяет время (в миллисекундах)
+ * между завершением callback-функции и снятием блокировки.
+ *
+ * Типичные сценарии использования:
+ * - защита кнопок отправки форм от повторных кликов
+ * - предотвращение параллельного выполнения async side-effect'ов
+ * - реализация простого mutex-механизма на уровне UI
+ *
+ * @template TArgs
+ * Кортеж аргументов callback-функции.
+ *
+ * @template TReturn
+ * Тип возвращаемого значения callback-функции.
+ * Может быть `void` для синхронных операций или `Promise<any>` для асинхронных.
+ *
+ * @param {Callback<TArgs, TReturn>} callback
+ * Синхронная или асинхронная функция, вызовы которой должны выполняться эксклюзивно.
+ *
+ * @param {number} [delay=0]
+ * Задержка в миллисекундах перед снятием блокировки после завершения callback-функции.
+ *
+ * @returns {(…args: TArgs) => TReturn | void}
+ * Функция с той же сигнатурой, что и `callback`, но с защитой от параллельных вызовов.
+ * Если вызов был проигнорирован из-за активной блокировки, возвращается `void`.
  *
  * @example
+ * ```ts
  * const save = useLockedCallback(async (data: string) => {
- *   await api.save(data)
- * })
+ *   await api.save(data);
+ * });
+ *
+ * save('hello'); // выполнится
+ * save('world'); // будет проигнорирован, если предыдущий вызов ещё не завершён
+ * ```
+ *
+ * @example
+ * ```ts
+ * const onClick = useLockedCallback(() => {
+ *   console.log('clicked');
+ * }, 500);
  *
- * save('hello') // выполнится
- * save('world') // проигнорируется, если предыдущий вызов ещё не завершился
+ * // повторный вызов будет доступен только через 500ms
+ * ```
  */
-export declare function useLockedCallback<TArgs extends Args>(callback: (...args: TArgs) => Promise<any> | void): (...args: TArgs) => void | Promise<any>;
+export declare function useLockedCallback<TArgs extends Args, TReturn extends Return>(callback: Callback<TArgs, TReturn>, delay?: number): (...args: TArgs) => TReturn | undefined;
 export {};

package/dist/types/src/ui/Buttons/types/ButtonTypes.d.ts

@@ -43,4 +43,5 @@ export type ButtonPropsType<T extends React.ElementType> = AsProps<T, {
     theme?: "light" | "dark" | undefined;
     isLoading?: boolean;
     counter?: React.ReactNode;
+    className?: string;
 }, React.ComponentProps<'button'>>;

package/package.json

@@ -11,7 +11,7 @@
     "react-components",
     "ui-kit"
   ],
-  "version": "1.0.46",
+  "version": "1.0.48",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",