@cloud-ru/ds-utils 1.0.0

package/src/hooks/useEventHandler.ts

@@ -0,0 +1,26 @@
+import { useCallback, useRef } from 'react';
+
+import { useLayoutEffect } from './useIsomorphicLayoutEffect';
+
+/**
+ * Хук для создания обработчика событий с неизменной функцией.
+ * @function React hook
+ * @param handler коллбек события, без параметров
+ */
+export function useEventHandler<T extends (...args: never[]) => unknown>(handler: T) {
+  const handlerRef = useRef<T | null>(null);
+
+  useLayoutEffect(() => {
+    handlerRef.current = handler;
+  });
+
+  return useCallback((...args: Parameters<T>) => {
+    const handler = handlerRef.current;
+
+    if (handler === null) {
+      console.warn('The event handler cannot be called during render');
+    }
+
+    return handler?.(...args);
+  }, []) as T;
+}

package/src/hooks/useHierarchicalSelection.ts

@@ -0,0 +1,13 @@
+import { useMemo } from 'react';
+
+import {
+  createHierarchicalSelectionHandlers,
+  HierarchicalSelectionConfig,
+} from '../utils/hierarchicalSelection/createHierarchicalSelectionHandlers';
+
+/**
+ * Возвращает стабильные обработчики иерархического выбора с единым `includeParentsInValue`.
+ */
+export function useHierarchicalSelection({ includeParentsInValue }: HierarchicalSelectionConfig) {
+  return useMemo(() => createHierarchicalSelectionHandlers({ includeParentsInValue }), [includeParentsInValue]);
+}

package/src/hooks/useIsomorphicLayoutEffect.ts

@@ -0,0 +1,11 @@
+// eslint-disable-next-line no-restricted-imports
+import { useEffect, useLayoutEffect as useLayoutEffectInternal } from 'react';
+
+import { isBrowser } from '../utils';
+
+/**
+ * Хук используется вместо стандартного useLayoutEffect-а,
+ * нужен для корректной работы SSR
+ * @function React hook
+ */
+export const useLayoutEffect = isBrowser() ? useLayoutEffectInternal : useEffect;

package/src/hooks/useLocalStorage.ts

@@ -0,0 +1,19 @@
+import { useCallback, useState } from 'react';
+
+import { isBrowser } from '../utils';
+
+export function useLocalStorage<T extends string = string>(key: string, defaultValue: T): [T, (newValue: T) => void] {
+  const [value, setValueState] = useState<T>(((isBrowser() ? localStorage.getItem(key) : null) ?? defaultValue) as T);
+
+  const setValue = useCallback(
+    (newValue: T) => {
+      if (isBrowser()) {
+        localStorage.setItem(key, newValue);
+      }
+      setValueState(newValue);
+    },
+    [key],
+  );
+
+  return [value, setValue];
+}

package/src/hooks/useModalOpenState.ts

@@ -0,0 +1,37 @@
+import { useEffect } from 'react';
+
+import { useEventHandler } from './useEventHandler';
+import { usePopstateSubscription } from './usePopstateSubscription';
+
+type UseModalOpenStateOptions = {
+  /** закрывать модалку при переходе по истории браузера (по умолчанию false) */
+  closeOnPopstate?: boolean;
+  /** закрывать модалку через CloseWatcher (по умолчанию true) */
+  closeByCloseWatcher?: boolean;
+};
+
+/**
+ * Хук для управления состоянием модалки
+ * @returns [open, onClose]
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/CloseWatcher
+ * @function hook
+ */
+export function useModalOpenState(
+  /** состояние модалки */
+  open: boolean,
+  /** колбек закрытия */
+  onClose: () => void,
+  { closeOnPopstate = false, closeByCloseWatcher = true }: UseModalOpenStateOptions,
+) {
+  const closeHandler = useEventHandler(onClose);
+
+  usePopstateSubscription(() => open && closeHandler(), closeOnPopstate);
+
+  useEffect(() => {
+    if (open && 'CloseWatcher' in window && closeByCloseWatcher) {
+      const watcher = new CloseWatcher();
+      watcher.onclose = () => closeHandler();
+      return () => watcher.destroy();
+    }
+  }, [open, closeHandler, closeByCloseWatcher]);
+}

package/src/hooks/usePopstateSubscription.ts

@@ -0,0 +1,14 @@
+import { useEffect } from 'react';
+
+import { useEventHandler } from './useEventHandler';
+
+export function usePopstateSubscription(callback: (e: PopStateEvent) => void, enabled: boolean = true) {
+  const handler = useEventHandler(callback);
+
+  useEffect(() => {
+    if (!enabled) return;
+
+    window.addEventListener('popstate', handler);
+    return () => window.removeEventListener('popstate', handler);
+  }, [enabled, handler]);
+}

package/src/hooks/useSwipeable.ts

@@ -0,0 +1,85 @@
+import { useRef } from 'react';
+import {
+  SwipeableHandlers,
+  SwipeableProps,
+  SwipeCallback,
+  SwipeDirections,
+  SwipeEventData,
+  useSwipeable as useSwipeableInternal,
+} from 'react-swipeable';
+
+export const DATA_SWIPE_DIRECTIONS_ATTRIBUTE = 'data-swipe-directions';
+
+export type UseSwipeProps = {
+  /**
+   * Включен ли свайп
+   */
+  enabled?: boolean;
+  /**
+   * Направления, в которых будет работать свайп.
+   * Укажите это свойство, чтобы предотвратить конфликты и заблокировать свайп в родительских элементах по этим направлениям.
+   */
+  availableDirections?: SwipeDirections[];
+} & SwipeableProps;
+
+export type UseSwipeReturnType = SwipeableHandlers & {
+  [DATA_SWIPE_DIRECTIONS_ATTRIBUTE]?: string;
+};
+
+/**
+ * Хук для работы с событиями свайпа
+ */
+export function useSwipeable({ availableDirections, enabled = true, ...options }: UseSwipeProps): UseSwipeReturnType {
+  const canSwipe = useRef(true);
+
+  const onSwipeStart: SwipeCallback = eventData => {
+    if (availableDirections) {
+      if (!availableDirections.includes(eventData.dir)) {
+        canSwipe.current = false;
+        return;
+      }
+
+      if (!options.onSwipeStart) {
+        return;
+      }
+
+      eventData.event.stopPropagation();
+    }
+
+    options.onSwipeStart?.(eventData);
+  };
+
+  const onSwiping: SwipeCallback = eventData => {
+    if (availableDirections) {
+      if (!canSwipe.current) {
+        return;
+      }
+
+      eventData.event.stopPropagation();
+    }
+
+    options.onSwiping?.(eventData);
+  };
+
+  const onSwiped: SwipeCallback = eventData => {
+    if (availableDirections) {
+      if (!canSwipe.current) {
+        canSwipe.current = true;
+        return;
+      }
+
+      eventData.event.stopPropagation();
+    }
+
+    options.onSwiped?.(eventData);
+  };
+
+  const handlers = useSwipeableInternal(enabled ? { ...options, onSwipeStart, onSwiping, onSwiped } : {});
+
+  return {
+    ...handlers,
+    [DATA_SWIPE_DIRECTIONS_ATTRIBUTE]: enabled && availableDirections ? availableDirections.join(' ') : undefined,
+  };
+}
+
+export type { SwipeCallback, SwipeDirections, SwipeEventData };

package/src/hooks/useUncontrolledProp.ts

@@ -0,0 +1,65 @@
+import { useCallback, useRef, useState } from 'react';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Сигнатура колбэка смены значения.
+ *
+ * `any` здесь — не небрежность, а воспроизведение публичного типа пакета `uncontrollable`,
+ * на месте которого стоит этот хук. Свободный тип позволяет и колбэки с дополнительными
+ * аргументами (`onSelect(key, node)`), и функциональные апдейтеры (`setValue(prev => …)`,
+ * которые дальше применяет `useState`). Сузить его нельзя, не переписав типы `ToggleGroup`,
+ * `SelectionProvider` и `TreeContext`, — это отдельная задача.
+ */
+export type UncontrolledHandler = (value: any, ...args: any[]) => any;
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+/**
+ * Пара «значение + сеттер» для пропа, который работает и в controlled, и в uncontrolled режиме.
+ * Пока `propValue` задан — источник истины он, а сеттер только зовёт `handler`. Как только
+ * `propValue` становится `undefined`, состояние переходит во внутренний `useState`
+ * и сбрасывается на `defaultValue`.
+ *
+ * Сеттер стабилен между рендерами, пока не меняется `handler`.
+ * @function React hook
+ */
+export function useUncontrolledProp<TValue, THandler extends UncontrolledHandler = UncontrolledHandler>(
+  propValue: TValue | undefined,
+  defaultValue: TValue,
+  handler?: THandler,
+): readonly [TValue, THandler];
+export function useUncontrolledProp<TValue, THandler extends UncontrolledHandler = UncontrolledHandler>(
+  propValue: TValue | undefined,
+  defaultValue?: TValue,
+  handler?: THandler,
+): readonly [TValue | undefined, (...args: Parameters<THandler>) => ReturnType<THandler> | void];
+export function useUncontrolledProp<TValue, THandler extends UncontrolledHandler = UncontrolledHandler>(
+  propValue: TValue | undefined,
+  defaultValue?: TValue,
+  handler?: THandler,
+): readonly [TValue | undefined, (...args: Parameters<THandler>) => ReturnType<THandler> | void] {
+  const isProp = propValue !== undefined;
+  const wasPropRef = useRef(isProp);
+  const [stateValue, setStateValue] = useState(defaultValue);
+
+  const wasProp = wasPropRef.current;
+  wasPropRef.current = isProp;
+
+  // Переход controlled -> uncontrolled: внутреннее состояние отстало от `defaultValue`,
+  // возвращаем его к дефолту, иначе компонент «залипнет» на последнем controlled-значении.
+  if (!isProp && wasProp && stateValue !== defaultValue) {
+    setStateValue(defaultValue);
+  }
+
+  const setValue = useCallback(
+    (...args: Parameters<THandler>) => {
+      const [value, ...rest] = args;
+      const returnValue = handler?.(value, ...rest);
+      setStateValue(value);
+
+      return returnValue;
+    },
+    [handler],
+  );
+
+  return [isProp ? propValue : stateValue, setValue];
+}

package/src/hooks/useValueControl.ts

@@ -0,0 +1,41 @@
+import { useCallback, useRef } from 'react';
+
+import { useUncontrolledProp } from './useUncontrolledProp';
+
+type UseValueControl<TValue> = {
+  /**
+   * Значение состояния
+   */
+  value?: TValue;
+  /**
+   * Значение по умолчанию
+   */
+  defaultValue?: TValue;
+  /**
+   * Колбек, вызываемый на смену состояния
+   */
+  onChange?(value: TValue): void;
+};
+
+/**
+ * Хук для работы с состоянием.
+ * Нужен для поддержки controlled/uncontrolled поведения, в зависимости от того были ли переданы входные аргументы
+ */
+export function useValueControl<TValue>({ value, onChange, defaultValue }: UseValueControl<TValue>) {
+  // Значение читаем из ref: иначе handler пересоздавался бы на каждую смену `value`,
+  // а вместе с ним — и сеттер из `useUncontrolledProp`.
+  const valueRef = useRef(value);
+  valueRef.current = value;
+
+  const handleChange = useCallback(
+    (newValue: TValue) => {
+      const newState =
+        typeof newValue === 'function' ? (newValue as (prev?: TValue) => TValue)(valueRef.current) : newValue;
+
+      onChange?.(newState);
+    },
+    [onChange],
+  );
+
+  return useUncontrolledProp<TValue>(value, defaultValue, handleChange);
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './hooks';
+export * from './utils';
+export * from './types';

package/src/types/index.ts

@@ -0,0 +1,2 @@
+export * from './polymorphic';
+export * from './valueOf';

package/src/types/polymorphic.ts

@@ -0,0 +1,4 @@
+import { ComponentPropsWithRef, ElementType } from 'react';
+
+/** Тип ref'а для полиморфного компонента: то, что примет элемент/компонент, переданный в `as`. */
+export type PolymorphicRef<T extends ElementType> = ComponentPropsWithRef<T>['ref'];

package/src/types/valueOf.ts

@@ -0,0 +1,5 @@
+/**
+ * Utility-тип, преобразующий константные значения объекта в union
+ * @function type
+ */
+export type ValueOf<T> = T[keyof T];

package/src/utils/componentPropsProcessors.ts

@@ -0,0 +1,55 @@
+import { AriaAttributes } from 'react';
+const DATA_TEST_REGEXP = /^data-test-/;
+const DATA_AND_ARIA_REGEXP = /^(data|aria)-/;
+
+function excludeProps<T extends Record<string, unknown>>(props: T, regexp: RegExp) {
+  return Object.keys(props)
+    .filter(prop => !prop.match(regexp))
+    .reduce(
+      (nextProps, prop) => ({
+        ...nextProps,
+        [prop]: props[prop],
+      }),
+      {},
+    );
+}
+
+function extractProps<T extends Record<string, unknown>>(props: T, regex: RegExp) {
+  return Object.keys(props).reduce(
+    (nextProps, prop) => {
+      if (prop.match(regex)) nextProps[prop] = props[prop];
+
+      return nextProps;
+    },
+    {} as Record<string, unknown>,
+  );
+}
+
+export type WithSupportProps<T> = {
+  'data-test-id'?: string;
+} & AriaAttributes &
+  T;
+
+/**
+ * Функция для исключения вспомогательных свойств (data-test-id & aria-*)
+ * @function helper
+ */
+export function excludeSupportProps<T extends Record<string, unknown>>(props: T) {
+  return excludeProps(props, DATA_AND_ARIA_REGEXP);
+}
+
+/**
+ * Функция для отбора свойства data-test-id
+ * @function helper
+ */
+export function extractDataTestProps<T extends Record<string, unknown>>(props: T) {
+  return extractProps(props, DATA_TEST_REGEXP);
+}
+
+/**
+ * Функция для отбора вспомогательных свойств (data-test-id & aria-*)
+ * @function helper
+ */
+export function extractSupportProps<T extends Record<string, unknown>>(props: T) {
+  return extractProps(props, DATA_AND_ARIA_REGEXP);
+}

package/src/utils/copyToClipboard.ts

@@ -0,0 +1,46 @@
+import { isBrowser } from './isBrowser';
+
+/**
+ * Копирует текст в буфер обмена. Сначала пробует Async Clipboard API, при отказе
+ * (нет разрешения, insecure-context) падает на `execCommand('copy')` со скрытым textarea.
+ *
+ * Возвращает `true`, если запись удалась — по этому признаку поля и кнопки показывают
+ * индикатор «скопировано».
+ *
+ * Проверки `isBrowser()` продублированы внутри веток намеренно: правило
+ * `@cloud-ru/ssr-safe-react/domApi` требует, чтобы доступ к `navigator`/`document` стоял
+ * непосредственно внутри такого условия, а ранний выход оно не учитывает.
+ */
+export async function copyToClipboard(value: string): Promise<boolean> {
+  if (!isBrowser()) return false;
+
+  if (isBrowser() && navigator.clipboard?.writeText) {
+    try {
+      await navigator.clipboard.writeText(value);
+
+      return true;
+    } catch {
+      // fall through to execCommand fallback
+    }
+  }
+
+  if (isBrowser()) {
+    const textarea = document.createElement('textarea');
+    textarea.value = value;
+    textarea.setAttribute('readonly', '');
+    textarea.style.position = 'fixed';
+    textarea.style.opacity = '0';
+    document.body.appendChild(textarea);
+    textarea.select();
+
+    try {
+      return document.execCommand('copy');
+    } catch {
+      return false;
+    } finally {
+      document.body.removeChild(textarea);
+    }
+  }
+
+  return false;
+}

package/src/utils/debounce.ts

@@ -0,0 +1,31 @@
+/** Функция-обёртка `debounce`: вызывается как исходная, плюс умеет отменить отложенный вызов. */
+export type Debounced<TArgs extends unknown[]> = {
+  (...args: TArgs): void;
+  /** Отменяет запланированный вызов. Нужен в cleanup эффекта, чтобы не стрелять после размонтирования. */
+  cancel(): void;
+};
+
+/**
+ * Откладывает вызов `callback` на `wait` мс, перезапуская таймер на каждом новом вызове.
+ * Срабатывает по заднему фронту — с аргументами последнего вызова.
+ */
+export function debounce<TArgs extends unknown[]>(callback: (...args: TArgs) => void, wait = 0): Debounced<TArgs> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const cancel = () => {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+  };
+
+  const debounced = (...args: TArgs): void => {
+    cancel();
+    timer = setTimeout(() => {
+      timer = undefined;
+      callback(...args);
+    }, wait);
+  };
+
+  return Object.assign(debounced, { cancel });
+}

package/src/utils/hierarchicalSelection/applySelectionDiff.ts

@@ -0,0 +1,20 @@
+/**
+ * Применяет diff к набору выбранных id.
+ */
+export function applySelectionDiff<TId extends string | number>(
+  selectedIds: TId[],
+  added: TId[],
+  removed: TId[],
+): TId[] {
+  const result = new Set(selectedIds);
+
+  for (const id of added) {
+    result.add(id);
+  }
+
+  for (const id of removed) {
+    result.delete(id);
+  }
+
+  return [...result];
+}

package/src/utils/hierarchicalSelection/checkGroupSelection.ts

@@ -0,0 +1,22 @@
+import { GroupSelectionState } from './types';
+
+/**
+ * Проверяет состояние выбора группы по flat-списку дочерних id.
+ */
+export function checkGroupSelection<TId extends string | number>(
+  childIds: TId[],
+  selectedIds: TId[],
+): GroupSelectionState {
+  if (!childIds.length) {
+    return { allSelected: false, someSelected: false };
+  }
+
+  const selectedCount = childIds.filter(id => selectedIds.includes(id)).length;
+  const someSelected = selectedCount > 0;
+  const allSelected = someSelected && selectedCount === childIds.length;
+
+  return {
+    allSelected,
+    someSelected: !allSelected && someSelected,
+  };
+}

package/src/utils/hierarchicalSelection/createHierarchicalSelectionHandlers.ts

@@ -0,0 +1,35 @@
+import { checkGroupSelection } from './checkGroupSelection';
+import { getNodeSelectionState } from './getNodeSelectionState';
+import { toggleHierarchicalSelection } from './toggleHierarchicalSelection';
+import { GetNodeSelectionStateParams, ToggleHierarchicalSelectionParams } from './types';
+
+export type HierarchicalSelectionConfig = {
+  includeParentsInValue: boolean;
+};
+
+export type HierarchicalSelectionNodeParams<TId extends string | number = string> = Omit<
+  GetNodeSelectionStateParams<TId>,
+  'includeParentsInValue'
+>;
+
+export type HierarchicalSelectionToggleParams<TId extends string | number = string> = Omit<
+  ToggleHierarchicalSelectionParams<TId>,
+  'includeParentsInValue'
+>;
+
+/**
+ * Создаёт набор обработчиков иерархического выбора с единым `includeParentsInValue`.
+ */
+export function createHierarchicalSelectionHandlers({ includeParentsInValue }: HierarchicalSelectionConfig) {
+  return {
+    getSelectionState<TId extends string | number>(params: HierarchicalSelectionNodeParams<TId>) {
+      return getNodeSelectionState({ ...params, includeParentsInValue });
+    },
+    toggleSelection<TId extends string | number>(params: HierarchicalSelectionToggleParams<TId>) {
+      return toggleHierarchicalSelection({ ...params, includeParentsInValue });
+    },
+    checkGroupSelection,
+  };
+}
+
+export type HierarchicalSelectionHandlers = ReturnType<typeof createHierarchicalSelectionHandlers>;

package/src/utils/hierarchicalSelection/getNodeSelectionState.ts

@@ -0,0 +1,29 @@
+import { checkGroupSelection } from './checkGroupSelection';
+import { GetNodeSelectionStateParams } from './types';
+
+/**
+ * Единая формула checked/indeterminate для иерархического мультивыбора.
+ */
+export function getNodeSelectionState<TId extends string | number>({
+  nodeId,
+  childIds,
+  selectedIds,
+  includeParentsInValue,
+}: GetNodeSelectionStateParams<TId>) {
+  const { allSelected, someSelected } = checkGroupSelection(childIds, selectedIds);
+
+  if (!includeParentsInValue) {
+    return {
+      checked: allSelected,
+      indeterminate: someSelected,
+    };
+  }
+
+  const inValue = selectedIds.includes(nodeId);
+  const checked = inValue || allSelected;
+
+  return {
+    checked,
+    indeterminate: !checked && someSelected,
+  };
+}

package/src/utils/hierarchicalSelection/index.ts

@@ -0,0 +1,6 @@
+export * from './applySelectionDiff';
+export * from './checkGroupSelection';
+export * from './createHierarchicalSelectionHandlers';
+export * from './getNodeSelectionState';
+export * from './toggleHierarchicalSelection';
+export * from './types';