@cloud-ru/ds-utils 1.0.0

package/src/utils/hierarchicalSelection/toggleHierarchicalSelection.ts

@@ -0,0 +1,109 @@
+import { checkGroupSelection } from './checkGroupSelection';
+import { ToggleHierarchicalSelectionParams } from './types';
+
+function resolveIsSelected<TId extends string | number>({
+  nodeId,
+  descendantIds,
+  selectableDescendantIds,
+  childIds,
+  selectedIds,
+  includeParentsInValue,
+}: ToggleHierarchicalSelectionParams<TId>): boolean {
+  const hasDescendants = descendantIds.length > 0;
+
+  if (!includeParentsInValue && hasDescendants) {
+    const idsForChecked = childIds ?? descendantIds;
+    const selectable = selectableDescendantIds ?? descendantIds;
+    const allChildrenSelected = idsForChecked.length > 0 && idsForChecked.every(id => selectedIds.includes(id));
+    const allEnabledSelected = selectable.length > 0 && selectable.every(id => selectedIds.includes(id));
+
+    return allChildrenSelected || allEnabledSelected;
+  }
+
+  if (hasDescendants) {
+    const { allSelected, someSelected } = checkGroupSelection(descendantIds, selectedIds);
+
+    return allSelected || someSelected;
+  }
+
+  return selectedIds.includes(nodeId);
+}
+
+function toggleWithParentsInValue<TId extends string | number>({
+  nodeId,
+  descendantIds,
+  selectedIds,
+  ancestors,
+  isSelected,
+}: ToggleHierarchicalSelectionParams<TId> & { isSelected: boolean }): TId[] {
+  const idsFromNode = [nodeId, ...descendantIds];
+
+  let updatedSelectedIds = isSelected
+    ? selectedIds.filter(id => !idsFromNode.includes(id))
+    : [...selectedIds, ...idsFromNode.filter(id => !selectedIds.includes(id))];
+
+  if (!ancestors?.length) {
+    return updatedSelectedIds;
+  }
+
+  for (const ancestor of ancestors) {
+    if (!ancestor.childIds.length) {
+      continue;
+    }
+
+    const parentSelection = checkGroupSelection(ancestor.childIds, updatedSelectedIds);
+
+    if (isSelected) {
+      if (!parentSelection.allSelected) {
+        updatedSelectedIds = updatedSelectedIds.filter(id => id !== ancestor.id);
+      }
+    } else if (parentSelection.allSelected && !updatedSelectedIds.includes(ancestor.id)) {
+      updatedSelectedIds = [...updatedSelectedIds, ancestor.id];
+    }
+  }
+
+  return updatedSelectedIds;
+}
+
+function toggleWithoutParentsInValue<TId extends string | number>({
+  nodeId,
+  descendantIds,
+  selectableDescendantIds,
+  selectedIds,
+  isSelected,
+}: ToggleHierarchicalSelectionParams<TId> & { isSelected: boolean }): TId[] {
+  if (!descendantIds.length) {
+    if (isSelected) {
+      return selectedIds.filter(id => id !== nodeId);
+    }
+
+    if (selectedIds.includes(nodeId)) {
+      return selectedIds;
+    }
+
+    return [...selectedIds, nodeId];
+  }
+
+  const selectable = selectableDescendantIds ?? descendantIds;
+
+  if (isSelected) {
+    return selectedIds.filter(id => id !== nodeId && !selectable.includes(id));
+  }
+
+  return [...new Set([...selectedIds, ...selectable])];
+}
+
+/**
+ * Пересчитывает выбранные id после toggle узла с каскадом вниз и опциональным walk вверх.
+ */
+export function toggleHierarchicalSelection<TId extends string | number>(
+  params: ToggleHierarchicalSelectionParams<TId>,
+): TId[] {
+  const isSelected = resolveIsSelected(params);
+
+  if (params.includeParentsInValue) {
+    return toggleWithParentsInValue({ ...params, isSelected });
+  }
+
+  return toggleWithoutParentsInValue({ ...params, isSelected });
+}

package/src/utils/hierarchicalSelection/types.ts

@@ -0,0 +1,26 @@
+export type GroupSelectionState = {
+  allSelected: boolean;
+  someSelected: boolean;
+};
+
+export type HierarchicalAncestor<TId extends string | number = string> = {
+  id: TId;
+  childIds: TId[];
+};
+
+export type GetNodeSelectionStateParams<TId extends string | number = string> = {
+  nodeId: TId;
+  childIds: TId[];
+  selectedIds: TId[];
+  includeParentsInValue: boolean;
+};
+
+export type ToggleHierarchicalSelectionParams<TId extends string | number = string> = {
+  nodeId: TId;
+  descendantIds: TId[];
+  selectableDescendantIds?: TId[];
+  childIds?: TId[];
+  selectedIds: TId[];
+  ancestors?: HierarchicalAncestor<TId>[];
+  includeParentsInValue: boolean;
+};

package/src/utils/index.ts

@@ -0,0 +1,10 @@
+export * from './componentPropsProcessors';
+export * from './debounce';
+export * from './hierarchicalSelection';
+export * from './innerRef';
+export * from './isBrowser';
+export * from './copyToClipboard';
+export * from './keyboard';
+export * from './throttle';
+export * from './typeGuards';
+export * from './stopEventPropagation';

package/src/utils/innerRef.ts

@@ -0,0 +1,37 @@
+/**
+ * Маркер «компонент принимает DOM-ноду своего корня через проп `innerRef`».
+ *
+ * Нужен потому, что интроспекция пропсов функционального компонента в рантайме невозможна: обёртки вроде
+ * `Popover` / `Tooltip` / `Dropdown` получают триггер как `ReactElement` и должны решить, каким каналом отдать
+ * ему reference-ноду. У `forwardRef`-компонента это `ref` (определяется через `react-is`), у обычной функции —
+ * проп `innerRef`, и узнать о его поддержке можно только по явной пометке.
+ *
+ * Ключ — `Symbol.for`, поэтому маркер общий для всех копий `@cloud-ru/ds-utils` в дереве зависимостей.
+ */
+export const SUPPORTS_INNER_REF = Symbol.for('@cloud-ru/ds-supports-inner-ref');
+
+/**
+ * Помечает компонент как принимающий `innerRef`. Вызывается один раз рядом с объявлением компонента:
+ *
+ * ```tsx
+ * export function Button<T extends ElementType = 'button'>({ innerRef, ...rest }: ButtonProps<T>) { … }
+ * withInnerRefSupport(Button);
+ * ```
+ *
+ * Помечать нужно только те компоненты, которые прокидывают `innerRef` на **корневой** DOM-узел — именно его
+ * ждёт позиционирование поповера. Компоненты, у которых `innerRef` ведёт на внутренний слот (например, на
+ * нативный `input`), не помечаем.
+ */
+export function withInnerRefSupport<T extends object>(component: T): T {
+  Object.defineProperty(component, SUPPORTS_INNER_REF, { value: true });
+
+  return component;
+}
+
+/** Принимает ли тип элемента DOM-ноду через проп `innerRef`. */
+export function supportsInnerRef(type: unknown): boolean {
+  return (
+    (typeof type === 'function' || (typeof type === 'object' && type !== null)) &&
+    Boolean((type as Record<symbol, unknown>)[SUPPORTS_INNER_REF])
+  );
+}

package/src/utils/isBrowser.ts

@@ -0,0 +1,9 @@
+/**
+ * Функция проверки текущей среды выполнения кода,
+ * нужна для корректной работы SSR
+ * @function helper
+ */
+export function isBrowser() {
+  // eslint-disable-next-line @cloud-ru/ssr-safe-react/domApi
+  return Boolean(typeof window !== 'undefined' && window.document && window.document.createElement);
+}

package/src/utils/keyboard.ts

@@ -0,0 +1,68 @@
+/**
+ * Клавиши-стрелки. Внутри компонентов с собственной клавиатурной навигацией (списки, сетка
+ * календаря, roving-кнопки) их нативное поведение — прокрутка страницы — нужно гасить, иначе
+ * событие «улетает» за компонент и скроллит документ.
+ */
+export const ARROW_KEYS = ['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'] as const;
+
+/**
+ * Вертикальные стрелки. Для текстовых полей гасить нужно только их (горизонтальные `ArrowLeft` /
+ * `ArrowRight` двигают каретку — их перехватывать нельзя), тогда как в сетках/списках/roving-кнопках
+ * без текста гасятся все четыре (см. {@link ARROW_KEYS}).
+ */
+export const VERTICAL_ARROW_KEYS = ['ArrowUp', 'ArrowDown'] as const;
+
+export type ArrowKey = (typeof ARROW_KEYS)[number];
+
+/** `true`, если клавиша — одна из стрелок навигации. */
+export function isArrowKey(key: string): key is ArrowKey {
+  return (ARROW_KEYS as readonly string[]).includes(key);
+}
+
+/** `true`, если клавиша — вертикальная стрелка (`ArrowUp` / `ArrowDown`). */
+export function isVerticalArrowKey(key: string): boolean {
+  return (VERTICAL_ARROW_KEYS as readonly string[]).includes(key);
+}
+
+/**
+ * Гасит нативную прокрутку страницы для клавиш-стрелок: если нажата стрелка — вызывает
+ * `preventDefault()` и возвращает `true`. Использовать в начале keydown-обработчика компонента,
+ * который сам обрабатывает стрелочную навигацию.
+ *
+ * @example
+ * const handleKeyDown = (e) => {
+ *   preventScrollOnArrowKeys(e);
+ *   // …собственная навигация
+ * };
+ */
+export function preventScrollOnArrowKeys(event: Pick<KeyboardEvent, 'key' | 'preventDefault'>): boolean {
+  if (isArrowKey(event.key)) {
+    event.preventDefault();
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Как {@link preventScrollOnArrowKeys}, но только для вертикальных стрелок (`ArrowUp` / `ArrowDown`).
+ * Для текстовых полей: гасит прокрутку страницы по Up/Down, не трогая горизонтальные стрелки —
+ * каретка по тексту продолжает двигаться.
+ */
+export function preventScrollOnVerticalArrows(event: Pick<KeyboardEvent, 'key' | 'preventDefault'>): boolean {
+  if (isVerticalArrowKey(event.key)) {
+    event.preventDefault();
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Программный фокус без авто-прокрутки страницы к элементу (`focus({ preventScroll: true })`).
+ * Применять при перемещении фокуса по клавиатуре внутри уже видимого компонента (ячейка
+ * календаря, элемент списка), иначе браузер скроллит документ к новому фокусу.
+ */
+export function focusWithoutScroll(element: HTMLElement | null | undefined): void {
+  element?.focus({ preventScroll: true });
+}

package/src/utils/stopEventPropagation.ts

@@ -0,0 +1,5 @@
+import { KeyboardEvent, MouseEvent } from 'react';
+
+export function stopEventPropagation(event: MouseEvent<HTMLElement> | KeyboardEvent<HTMLElement>) {
+  event.stopPropagation();
+}

package/src/utils/throttle.ts

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

package/src/utils/typeGuards.ts

@@ -0,0 +1,9 @@
+export const isNil = (value: unknown): value is undefined | null => value === undefined || value === null;
+
+export const isBoolean = (value: unknown): value is boolean => typeof value === 'boolean';
+
+export const isString = (value: unknown): value is string => typeof value === 'string';
+
+export const isArray = <T>(value: unknown): value is Array<T> => Array.isArray(value);
+
+export const isObject = (value: unknown): value is object => typeof value === 'object' && !isArray(value);