@cloud-ru/ds-tree 1.0.0

package/src/helperComponents/TreeNode/styles.module.scss

@@ -0,0 +1,300 @@
+@use '@cloud-ru/ds-figma-variables/build/scss/styles/styles.module' as base;
+@use '@cloud-ru/ds-figma-variables/build/scss/components/tree.module' as tree;
+@use '@cloud-ru/ds-materials' as m;
+
+$sizes: ('s', 'm', 'l');
+
+.treeNode {
+  display: flex;
+  align-items: center;
+  box-sizing: border-box;
+  width: 100%;
+}
+
+.treeNodeIcon {
+  display: flex;
+  flex-shrink: 0;
+  align-items: center;
+  justify-content: center;
+
+  box-sizing: border-box;
+
+  color: base.$sn-theme-color-available-version-textTertiary;
+}
+
+.treeNodeTitle {
+  overflow: hidden;
+  display: flex;
+  flex-grow: 1;
+  align-items: center;
+
+  box-sizing: border-box;
+  min-width: 0;
+
+  color: base.$sn-theme-color-available-version-textMain;
+}
+
+.treeNodeActions {
+  // Absolute по правому краю строки: в Figma kebab лежит поверх
+  // contentWrapper'а и не сдвигает текст. Если оставить во flex-потоке
+  // (даже с `visibility: hidden`), он резервирует ширину и title-ellipsis
+  // срабатывает раньше реального правого края контейнера.
+  position: absolute;
+  inset: 0 0 0 auto;
+  display: flex;
+  visibility: hidden;
+
+  // Растягиваем <button> на всю высоту строки.
+  > button {
+    align-self: stretch;
+    height: auto;
+  }
+
+  &:focus-visible,
+  &[data-focused] {
+    visibility: visible;
+  }
+}
+
+.treeNodeContent {
+  cursor: pointer;
+
+  position: relative;
+
+  display: flex;
+  align-items: center;
+
+  box-sizing: border-box;
+  width: 100%;
+  min-width: 0;
+
+  @include m.has-state-layer-as-child(#{stateLayer});
+
+  &:hover .treeNodeActions,
+  &[data-droplist-active] .treeNodeActions {
+    visibility: visible;
+  }
+
+  // Когда у строки открыт дроплист или фокус на kebab — держим hover-фон,
+  // чтобы было видно, какая строка управляется action-меню. Hover-стиль
+  // state-layer-а задаёт миксин `has-state-layer-as-child` только под
+  // `:hover`; здесь повторяем тот же фон под `[data-droplist-active]`.
+  &[data-droplist-active] .stateLayer[data-state='emptyNeutralOnBackground'] {
+    background: base.$sn-theme-color-material-stateLayer-neutral-onBackground-hovered-filled;
+  }
+
+  &[data-droplist-active] .stateLayer[data-state='activatedOnBackground'] {
+    background: base.$sn-theme-color-material-stateLayer-activated-hovered-filled;
+  }
+
+  &:focus-visible {
+    outline: base.$sn-primitive-strokeWeight-strokeSemiBold solid base.$sn-theme-color-available-complementary;
+    outline-offset: calc(-1 * #{base.$sn-primitive-strokeWeight-strokeSemiBold});
+  }
+
+  // У выбранной строки макет даёт `focusedFrame/primary/inside` на фоне самой строки
+  // (у невыбранной — чёрный `regular/inside`). Режим выбора роли не играет.
+  &[aria-selected='true']:focus-visible {
+    outline-color: base.$sn-theme-color-primary-accent;
+  }
+
+  &[data-multiselect] {
+    cursor: default;
+  }
+
+  // Гасит только `opacity` строки: цвет остаётся тем же, что в покое. `textDisabled`
+  // сам несёт альфу, и вместе с этой прозрачностью давал двойное гашение — 0.14
+  // вместо 0.40 у подписи (та же ошибка, что чинили в @cloud-ru/ds-input-private).
+  &[aria-disabled='true'] {
+    cursor: not-allowed;
+    opacity: base.$sn-theme-effect-opacity-disabled;
+  }
+}
+
+.stateLayer {
+  pointer-events: none;
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+}
+
+.treeNodeCheckboxWrap {
+  display: flex;
+  flex-shrink: 0;
+  align-items: center;
+  justify-content: center;
+
+  box-sizing: border-box;
+}
+
+.treeNodeExpandButton {
+  cursor: pointer;
+
+  position: relative;
+
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+  justify-content: center;
+
+  box-sizing: border-box;
+  padding: 0;
+  border: 0;
+  border-radius: base.$sn-brand-anatomy-radius-button-s;
+
+  color: base.$sn-theme-color-neutral-text;
+
+  background: transparent;
+
+  @include m.has-state-layer-as-child(#{treeNodeExpandButtonStateLayer});
+
+  svg {
+    transition: transform 0.2s ease;
+  }
+
+  &[data-expanded] svg {
+    transform: rotate(90deg);
+  }
+
+  &:focus-visible {
+    outline: base.$sn-primitive-strokeWeight-strokeSemiBold solid base.$sn-theme-color-available-complementary;
+    outline-offset: calc(-1 * #{base.$sn-primitive-strokeWeight-strokeSemiBold});
+  }
+}
+
+.treeNodeExpandButtonStateLayer {
+  pointer-events: none;
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+}
+
+// Пустой слот chevron у листьев — те же размеры, что у кнопки раскрытия.
+.treeNodeExpandButtonSpacer {
+  flex-shrink: 0;
+}
+
+// Колонка chevron-а: stretch на высоту строки, chevron по центру, TreeLine ниже.
+.treeNodeExpandButtonWrapper {
+  position: relative;
+
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+  flex-shrink: 0;
+  align-items: center;
+  align-self: stretch;
+  justify-content: center;
+}
+
+.treeNodeExpandButtonWrapper > :last-child:not(.treeNodeExpandButton) {
+  // TreeLine absolute — чтобы не сдвигать chevron из центра. Занимает зазор низ-шеврона → низ-строки.
+  pointer-events: none;
+
+  position: absolute;
+  right: 0;
+  bottom: 0;
+  left: 0;
+
+  width: 100%;
+  height: calc(50% - var(--tree-chevron-size, #{base.$sn-density-size-icon-s}) / 2);
+}
+
+.treeNodeLink {
+  display: block;
+  width: 100%;
+  color: inherit;
+  text-decoration: none;
+}
+
+$icon-size-by-size: (
+  's': base.$sn-density-size-icon-xs,
+  'm': base.$sn-density-size-icon-s,
+  'l': base.$sn-density-size-icon-s,
+);
+
+@each $size in $sizes {
+  .treeNode[data-size='#{$size}'] {
+    $centered-width: base.simple-var(tree.$tree, 'anatomy', 'size', $size, 'treeItem', 'centeredWrapper', 'width');
+    $centered-padding-top: base.simple-var(
+      tree.$tree,
+      'anatomy',
+      'size',
+      $size,
+      'treeItem',
+      'centeredWrapper',
+      'padding-top'
+    );
+    $centered-padding-bottom: base.simple-var(
+      tree.$tree,
+      'anatomy',
+      'size',
+      $size,
+      'treeItem',
+      'centeredWrapper',
+      'padding-bottom'
+    );
+    $icon-size: base.simple-var($icon-size-by-size, $size);
+
+    --tree-chevron-size: #{$centered-width};
+
+    .treeNodeContent {
+      @include base.composite-var(tree.$tree, 'anatomy', 'size', $size, 'treeItem');
+      @include base.composite-var(base.$base-styles, 'sn', 'regular', 'body', $size);
+    }
+
+    .treeNodeCheckboxWrap,
+    .treeNodeExpandButtonWrapper {
+      width: $centered-width;
+    }
+
+    // Слоты иконки и переключателя — один и тот же `centeredWrapper` кита: он несёт
+    // вертикальный паддинг, из которого и складывается высота строки.
+    .treeNodeIcon,
+    .treeNodeCheckboxWrap {
+      padding-top: $centered-padding-top;
+      padding-bottom: $centered-padding-bottom;
+    }
+
+    .treeNodeExpandButton {
+      width: $centered-width;
+      height: $centered-width;
+
+      // Размер иконки шеврона/спиннера задаём через CSS, чтобы не прокидывать
+      // size в JSX каждой иконки (см. паттерн в @cloud-ru/ds-button).
+      // `max-*` обязателен: иконки из @cloud-ru/ds-icons приходят с инлайновым размером,
+      // и он перебивает `width`/`height` из таблицы стилей (приём из @cloud-ru/ds-button).
+      > svg {
+        width: $icon-size;
+        max-width: $icon-size;
+        height: $icon-size;
+        max-height: $icon-size;
+      }
+    }
+
+    .treeNodeExpandButtonSpacer {
+      width: $centered-width;
+      height: $centered-width;
+    }
+
+    .treeNodeIcon svg {
+      width: $icon-size;
+      max-width: $icon-size;
+      height: $icon-size;
+      max-height: $icon-size;
+    }
+
+    // Row-actions: гасим padding контейнера отрицательными margin'ами, чтобы
+    // elevated-кнопка тянулась на всю высоту строки и упиралась в правый край
+    // (иначе остаётся `padding-right` пустой полосы справа от kebab'а).
+    .treeNodeActions {
+      $padding-right: base.simple-var(tree.$tree, 'anatomy', 'size', $size, 'treeItem', 'padding-right');
+      $padding-top: base.simple-var(tree.$tree, 'anatomy', 'size', $size, 'treeItem', 'padding-top');
+      $padding-bottom: base.simple-var(tree.$tree, 'anatomy', 'size', $size, 'treeItem', 'padding-bottom');
+
+      margin-top: calc(-1 * #{$padding-top});
+      margin-right: calc(-1 * #{$padding-right});
+      margin-bottom: calc(-1 * #{$padding-bottom});
+    }
+  }
+}

package/src/helperComponents/TreeNode/types.ts

@@ -0,0 +1,11 @@
+import { KeyboardEventHandler, MouseEventHandler } from 'react';
+
+import { ParentNode, TreeNodeProps } from '../../types';
+
+export type TreeNodeComponentProps = TreeNodeProps & {
+  onChevronClick?: MouseEventHandler<HTMLElement>;
+  onKeyDown?: KeyboardEventHandler<HTMLElement>;
+  loading?: boolean;
+  parentNode?: ParentNode;
+  tabIndexAvailable?: boolean;
+};

package/src/helperComponents/TreeNode/utils.ts

@@ -0,0 +1,9 @@
+import { FocusEvent, MouseEvent } from 'react';
+
+export function stopPropagationClick(e: MouseEvent<HTMLInputElement>) {
+  e.stopPropagation();
+}
+
+export function stopPropagationFocus(e: FocusEvent<HTMLInputElement>) {
+  e.stopPropagation();
+}

package/src/helperComponents/index.ts

@@ -0,0 +1,4 @@
+export * from './ExpandableTreeNode';
+export * from './TreeNode';
+export * from './TreeLine';
+export * from './TreeItem';

package/src/helpers/checkNestedNodesSelection.ts

@@ -0,0 +1,15 @@
+import { checkGroupSelection } from '@cloud-ru/ds-utils';
+
+import { TreeNodeId, TreeNodeProps } from '../types';
+import { findAllChildNodeIds } from './findAllChildNodeIds';
+
+/**
+ * Проверяет состояние выбора дочерних узлов:
+ * выбраны ли все, выбраны ли некоторые.
+ *
+ * @param nodes Дочерние узлы для проверки.
+ * @param selectedKeys Текущий список выбранных id.
+ */
+export function checkNestedNodesSelection(nodes: TreeNodeProps[], selectedKeys: TreeNodeId[]) {
+  return checkGroupSelection(findAllChildNodeIds(nodes), selectedKeys);
+}

package/src/helpers/collectEmptyNestedNodesInExpanded.ts

@@ -0,0 +1,23 @@
+import { TreeNodeProps } from '../types';
+import { traverse } from './traverse';
+
+/**
+ * Возвращает раскрытые узлы, у которых `nested` уже существует, но пока пустой.
+ * Используется для определения узлов, требующих дополнительной подгрузки детей.
+ *
+ * @param nodes Узлы дерева для проверки.
+ * @param expandedIds Множество id раскрытых узлов.
+ */
+export function collectEmptyNestedNodesInExpanded<Node extends TreeNodeProps>(
+  nodes: Node[],
+  expandedIds: Set<string>,
+): Node[] {
+  const result: Node[] = [];
+  traverse(nodes, node => {
+    const hasEmptyNested = Array.isArray(node.nested) && node.nested.length === 0;
+    if (hasEmptyNested && expandedIds.has(node.id)) {
+      result.push(node);
+    }
+  });
+  return result;
+}

package/src/helpers/collectHierarchicalAncestors.ts

@@ -0,0 +1,22 @@
+import { HierarchicalAncestor } from '@cloud-ru/ds-utils';
+
+import { ParentNode } from '../types';
+import { findAllChildNodeIds } from './findAllChildNodeIds';
+
+export function collectHierarchicalAncestors(parentNode?: ParentNode): HierarchicalAncestor[] {
+  const ancestors: HierarchicalAncestor[] = [];
+  let parent: ParentNode | undefined = parentNode;
+
+  while (parent) {
+    if (parent.nested?.length) {
+      ancestors.push({
+        id: parent.id,
+        childIds: findAllChildNodeIds(parent.nested),
+      });
+    }
+
+    parent = parent.parentNode;
+  }
+
+  return ancestors;
+}

package/src/helpers/collectIds.ts

@@ -0,0 +1,17 @@
+import { TreeNodeProps } from '../types';
+import { traverse } from './traverse';
+
+/**
+ * Собирает id всех узлов дерева.
+ *
+ * @param treeNodes Узлы дерева для обхода.
+ * @returns Массив id узлов в порядке обхода BFS.
+ * @function collectIds
+ */
+export function collectIds(treeNodes: TreeNodeProps[]): string[] {
+  const ids: string[] = [];
+
+  traverse(treeNodes, node => ids.push(node.id));
+
+  return ids;
+}

package/src/helpers/extractTreeNodeTitle.ts

@@ -0,0 +1,8 @@
+import { ExtendedTreeNodeProps } from '../types';
+
+/**
+ * Возвращает строковый заголовок узла дерева.
+ * Если title задан функцией, использует getTitle (если он доступен).
+ */
+export const extractTreeNodeTitle = ({ title, getTitle }: ExtendedTreeNodeProps) =>
+  typeof title === 'string' ? title : (getTitle?.() ?? '');

package/src/helpers/findAllChildNodeIds.ts

@@ -0,0 +1,27 @@
+import { TreeNodeId, TreeNodeProps } from '../types';
+
+/**
+ * Собирает id всех недеактивированных узлов в поддереве.
+ *
+ * @param nodes Стартовые узлы обхода.
+ * @returns Массив id всех доступных узлов.
+ * @function findAllChildNodeIds
+ */
+export function findAllChildNodeIds(nodes: TreeNodeProps[]): TreeNodeId[] {
+  const stack = [...nodes];
+  const ids: TreeNodeId[] = [];
+
+  let node: TreeNodeProps | undefined;
+
+  while ((node = stack.pop())) {
+    if (!node.disabled) {
+      ids.push(node.id);
+
+      if (node.nested?.length) {
+        stack.push(...node.nested);
+      }
+    }
+  }
+
+  return ids;
+}

package/src/helpers/findAllExpandedChildNodeIds.ts

@@ -0,0 +1,24 @@
+import { TreeNodeId, TreeNodeProps } from '../types';
+
+/**
+ * Возвращает id узлов в поддереве, проходя только по раскрытым веткам.
+ *
+ * @param nodes Стартовые узлы обхода.
+ * @param expandedNodes Список id раскрытых узлов.
+ */
+export function findAllExpandedChildNodeIds(nodes: TreeNodeProps[], expandedNodes: TreeNodeId[]) {
+  const stack = [...nodes];
+  const ids: TreeNodeId[] = [];
+
+  let node: TreeNodeProps | undefined;
+
+  while ((node = stack.shift())) {
+    ids.push(node.id);
+
+    if (node.nested?.length && expandedNodes.includes(node.id)) {
+      stack.unshift(...node.nested);
+    }
+  }
+
+  return ids;
+}

package/src/helpers/getSearchedTreeItems.ts

@@ -0,0 +1,63 @@
+import { ExtendedTreeNodeProps } from '../types';
+import { extractTreeNodeTitle } from './extractTreeNodeTitle';
+
+const isMatchedTreeItem = (search: string) => {
+  const searchLower = search.toLocaleLowerCase();
+  return (treeItem: ExtendedTreeNodeProps) => {
+    const currentValue = extractTreeNodeTitle(treeItem);
+    return currentValue.toLocaleLowerCase().includes(searchLower);
+  };
+};
+
+type SearchParams = {
+  /** Корневые узлы дерева, по которым выполняется поиск. */
+  tree: ExtendedTreeNodeProps[];
+  searchOptions?: Partial<{
+    /** Поисковая строка (case-insensitive substring match по `title` узла). */
+    query: string;
+    /**
+     * Если `true` и parent матчит query — в результат попадают **все** его дети
+     * без дополнительной фильтрации. По умолчанию `false`: и parent, и дети
+     * фильтруются независимо.
+     */
+    includeChildrenMatchedParent: boolean;
+  }>;
+};
+
+/**
+ * Фильтрует дерево по поисковой строке с сохранением иерархии подходящих узлов.
+ *
+ * @param params {@link SearchParams} — дерево и опции поиска.
+ * @returns Новое дерево, содержащее только совпавшие узлы и их путь в иерархии.
+ */
+export const getSearchedTreeItems = ({ tree, searchOptions }: SearchParams) => {
+  if (!searchOptions?.query) return tree;
+
+  const { query = '', includeChildrenMatchedParent } = searchOptions;
+
+  const matchFunc = isMatchedTreeItem(query);
+
+  const searchItems = (treeItems: ExtendedTreeNodeProps[]): ExtendedTreeNodeProps[] =>
+    treeItems.reduce<ExtendedTreeNodeProps[]>((acc, item) => {
+      const hasMatchingTitle = matchFunc(item);
+      const needDeepSearch = !(hasMatchingTitle && includeChildrenMatchedParent);
+
+      const matchedChildren = item.nested && (needDeepSearch ? searchItems(item.nested) : item.nested);
+
+      if (hasMatchingTitle || matchedChildren?.length) {
+        const newItem = { ...item };
+
+        if (matchedChildren?.length) {
+          newItem.nested = matchedChildren;
+        } else {
+          delete newItem.nested;
+        }
+
+        acc.push(newItem);
+      }
+
+      return acc;
+    }, []);
+
+  return searchItems(tree);
+};

package/src/helpers/getSearchedTreeNodeById.ts

@@ -0,0 +1,54 @@
+import { ExtendedTreeNodeProps } from '../types';
+
+type ReturnSearch<I, T> = I extends string ? T | null : T[];
+
+type SearchByIdParams<I, T> = {
+  tree: T[];
+  searchOptions: {
+    id: I;
+    includeNested?: boolean;
+  };
+};
+
+/**
+ * Ищет узлы дерева по одному id или по массиву id.
+ *
+ * @param params Параметры поиска.
+ * @param params.tree Дерево для поиска.
+ * @param params.searchOptions Опции поиска (id и includeNested).
+ * @returns Для одиночного id возвращает узел или null, для массива id — список узлов.
+ */
+export const getSearchedTreeNodeById = <I extends string | string[], T extends ExtendedTreeNodeProps>({
+  tree,
+  searchOptions: { id, includeNested = true },
+}: SearchByIdParams<I, T>): ReturnSearch<I, T> => {
+  const isArrayIds = Array.isArray(id);
+
+  if (!id || (isArrayIds && id.length === 0)) {
+    return (isArrayIds ? [] : null) as ReturnSearch<I, T>;
+  }
+
+  const foundItems: T[] = [];
+
+  const searchNodes = (nodes: T[]): void => {
+    for (const node of nodes) {
+      const matchCondition = isArrayIds ? id.includes(node.id) : node.id === id;
+
+      if (matchCondition) {
+        foundItems.push(includeNested ? node : { ...node, nested: undefined });
+
+        if (!isArrayIds) {
+          return;
+        }
+      }
+
+      if (node.nested) {
+        searchNodes(node.nested as T[]);
+      }
+    }
+  };
+
+  searchNodes(tree);
+
+  return (isArrayIds ? foundItems : foundItems[0] || null) as ReturnSearch<I, T>;
+};

package/src/helpers/index.ts

@@ -0,0 +1,13 @@
+export * from './checkNestedNodesSelection';
+export * from './collectEmptyNestedNodesInExpanded';
+export * from './collectIds';
+export * from './extractTreeNodeTitle';
+export * from './findAllChildNodeIds';
+export * from './findAllExpandedChildNodeIds';
+export * from './getSearchedTreeItems';
+export * from './getSearchedTreeNodeById';
+export * from './lookupTreeForSelectedNodes';
+export * from './sortTreeItemsByTitle';
+export * from './traverse';
+export * from './traverseWithTarget';
+export * from './updateTreeNode';

package/src/helpers/lookupTreeForSelectedNodes.ts

@@ -0,0 +1,33 @@
+import { HierarchicalSelectionHandlers } from '@cloud-ru/ds-utils';
+
+import { ParentNode, TreeNodeId, TreeNodeProps } from '../types';
+import { collectHierarchicalAncestors } from './collectHierarchicalAncestors';
+import { findAllChildNodeIds } from './findAllChildNodeIds';
+
+/**
+ * Пересчитывает выбранные узлы для режима мультивыбора в дереве.
+ * Учитывает потомков текущего узла и корректирует состояние предков.
+ *
+ * @param params Параметры пересчета выделения.
+ * @returns Обновленный список выбранных id.
+ */
+export function lookupTreeForSelectedNodes({
+  node,
+  selectedNodes,
+  parentNode,
+  toggleSelection,
+}: {
+  node: Pick<TreeNodeProps, 'id' | 'nested' | 'disabled'>;
+  selectedNodes: TreeNodeId[];
+  parentNode?: ParentNode;
+  toggleSelection: HierarchicalSelectionHandlers['toggleSelection'];
+}) {
+  const descendantIds = node.nested?.length ? findAllChildNodeIds(node.nested) : [];
+
+  return toggleSelection({
+    nodeId: node.id,
+    descendantIds,
+    selectedIds: selectedNodes,
+    ancestors: collectHierarchicalAncestors(parentNode),
+  });
+}

package/src/helpers/sortTreeItemsByTitle.ts

@@ -0,0 +1,26 @@
+import { ExtendedTreeNodeProps } from '../types';
+import { extractTreeNodeTitle } from './extractTreeNodeTitle';
+
+/**
+ * Сортирует узлы дерева по заголовку в алфавитном порядке.
+ *
+ * @param items Список узлов для сортировки.
+ * @param options Опции сортировки. По умолчанию сортировка чувствительна к регистру.
+ * @returns Новый отсортированный массив.
+ */
+type SortTreeItemsByTitleOptions = {
+  caseSensitive?: boolean;
+};
+
+export const sortTreeItemsByTitle = (items: ExtendedTreeNodeProps[], options?: SortTreeItemsByTitleOptions) =>
+  items &&
+  [...items].sort((itemA, itemB) => {
+    const valueA = extractTreeNodeTitle(itemA);
+    const valueB = extractTreeNodeTitle(itemB);
+
+    if (options?.caseSensitive ?? true) {
+      return valueA.localeCompare(valueB);
+    }
+
+    return valueA.toLowerCase().localeCompare(valueB.toLowerCase());
+  });