@sberbusiness/triplex-next-mcp-server 1.42.0-beta → 1.44.0-beta

package/bundle/components/TreeViewNode.md

@@ -0,0 +1,436 @@
+---
+component: TreeViewNode
+category: TreeView
+related: [TreeView]
+tokens: []
+stories: stories/TreeView/TreeView.stories.tsx
+version: "1.0"
+---
+
+# TreeViewNode
+
+## Назначение
+
+Узел визуального дерева `TreeView` (доступен также как `TreeView.Node`). Рендерит
+`<li role="treeitem">` с `aria-expanded` и `tabIndex`, регистрирует себя в
+абстрактном дереве `TreeView`, обрабатывает `focus`/`blur` для перемещения
+активной ноды с клавиатуры и отдаёт потребителю пять provide-props через
+render-функцию `children`.
+
+Собственного оформления у ноды нет: она добавляет только семантику и сброс
+маркеров списка — всю разметку узла (шеврон, подпись, линии-коннекторы,
+подсветку активного состояния) рисует потребитель.
+
+Используй когда: строишь дерево на `TreeView` и нужен полный контроль над
+разметкой узла.
+
+Не используй когда:
+- нужно типовое дерево «папка/файл» с шевроном, hover и focus-visible — бери
+  `CollapsibleTree`;
+- нужен свой UI узла, но с анимацией раскрытия и controlled/uncontrolled
+  состоянием — бери `CollapsibleTreeExtended`, он оборачивает `TreeView.Node`
+  и добавляет accordion-логику;
+- узел нужен вне `TreeView` — вне провайдера контекста нода получает
+  `initialTreeContext`, где `registerNode` и остальные методы пустые: `<li>`
+  отрисуется, но в дерево нода не попадёт, `tabIndex` останется `-1`,
+  `hasChildNodes` всегда будет `false` (дети не регистрируются), а
+  `isLastNode` — всегда `true` (у ноды нет родителя).
+
+---
+
+## Варианты и props
+
+Экспортируемый `TreeViewNode` — это `withTreeViewContext(TreeViewNodeWithContext)`,
+то есть class-компонент, обёрнутый HOC-ом контекста. Prop `treeViewContext`
+подставляет HOC, снаружи его передавать не нужно.
+
+### Обязательные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `id` | `string` | Идентификатор ноды, уникальный в пределах дерева. По нему абстрактное дерево ищет и связывает ноды, на него ссылаются `prevNodeId` / `nextNodeId` соседей |
+| `children` | `(props: ITreeViewNodeProvideProps) => JSX.Element` | Render-функция разметки узла. Не ReactNode: нода отдаёт своё состояние только через аргумент |
+
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `opened` | `boolean` | `false` | Состояние раскрытия. Синхронизируется в абстрактное дерево в конструкторе и далее в `componentDidUpdate` при смене значения |
+| `prevNodeId` | `string` | — | Id ноды, после которой вставить текущую в абстрактное дерево |
+| `nextNodeId` | `string` | — | Id ноды, перед которой вставить текущую в абстрактное дерево |
+| `...HTMLAttributes` | — | — | Уходят на `<li>`. `className` мерджится с собственным классом, `onFocus` / `onBlur` вызываются после внутренних обработчиков |
+
+`ITreeViewNodeProps` расширяет `Omit<React.HTMLAttributes<HTMLElement>, "children">` —
+`children` переопределён под render-функцию намеренно.
+
+### Provide-props render-функции (`ITreeViewNodeProvideProps`)
+
+| Поле | Описание |
+|---|---|
+| `activeNode` | Нода активна при перемещении с клавиатуры. Подсветку рисует потребитель |
+| `openedNode` | Нода раскрыта — значение из абстрактного дерева, а не из prop `opened` |
+| `hasChildNodes` | У ноды есть **зарегистрированные** дочерние ноды |
+| `isLastNode` | Нода последняя в дереве целиком (последняя на своём уровне и все её предки — последние). Используется для линий-коннекторов |
+| `setOpenedNode(opened)` | Пишет флаг раскрытия в абстрактную ноду и инкрементит `updateCount` в `TreeView` для перерендера. Uncontrolled-путь: prop `opened` при этом не меняется |
+
+### Порядок нод и `prevNodeId` / `nextNodeId`
+
+Абстрактное дерево заполняется в **конструкторах** нод, то есть в порядке
+рендера. `prevNodeId` / `nextNodeId` позволяют вставить ноду в произвольное
+место уровня: порядок в абстрактном дереве (а значит `isLastNode` и порядок
+обхода стрелками) может отличаться от порядка в разметке. Ссылаться можно
+только на **уже зарегистрированную** ноду: к моменту конструктора текущей ноды
+конструктор соседа должен был отработать — монтирование при этом не требуется,
+оно происходит позже. Id соседей выводят из массива данных
+`CollapsibleTree` и `CheckboxTree`; `CollapsibleTreeExtended` своего массива не
+имеет и пробрасывает `prevNodeId` / `nextNodeId` как есть от потребителя.
+
+Промаха по id компонент не сигнализирует, но два случая промаха ведут себя
+по-разному. Ноду с указанным id ищут **в поддереве текущего родителя**, а не по
+всему дереву.
+
+- **Id не найден** — нода добавляется в конец своего уровня, то есть в порядке
+  рендера. Детерминированно и безопасно; это штатный режим, а не ошибка.
+  Именно так работает `nextNodeId` в `CollapsibleTree` и `CheckboxTree`: они
+  передают id следующей ноды из массива данных, а та на момент конструктора
+  текущей ещё не зарегистрирована — промах и откат в порядок рендера здесь
+  происходят всегда.
+- **Id найден, но это не прямой ребёнок того же родителя** — позиция
+  определяется индексной арифметикой `splice` в `AbstractTreeNode.addChild`.
+  Это **деталь текущей реализации, а не контракт**: тестами не закреплена,
+  класс общий для всех абстрактных деревьев, полагаться нельзя.
+
+Правильное употребление одно: ссылаться на уже зарегистрированную соседнюю ноду
+того же уровня.
+
+### Раскрытие и регистрация детей
+
+`hasChildNodes` вычисляется по абстрактному дереву, поэтому дочерние ноды
+должны быть **смонтированы**. Если размонтировать `TreeView.Group` в свёрнутом
+состоянии, родитель получит `hasChildNodes === false` и, например, не отрисует
+шеврон. Рабочий приём (используется в stories и в `CollapsibleTreeExtended`) —
+держать группу в разметке всегда, скрывая её стилями.
+
+---
+
+## Дизайн-токены
+
+Собственных CSS-переменных нода не определяет. Класс `treeViewNode` в
+`styles/TreeView.module.less` задаёт только сброс отступов и маркера списка
+плюс `outline: none` — focus-стиль рисует потребитель.
+
+---
+
+## Инварианты
+
+- **`TreeViewNodeWithContext` — class-компонент, и `forwardRef` на нём нет.**
+  Регистрация в абстрактном дереве происходит в **конструкторе** (до маунта
+  детей), а снятие — в `componentWillUnmount`; порядок этих вызовов и есть
+  порядок нод в дереве. Перевод на функциональный компонент меняет момент
+  регистрации и ломает `prevNodeId` / `nextNodeId`. Не мигрировать без
+  отдельного решения мейнтейнера.
+- **Корневой DOM-элемент — `<li>`.** Менять тег нельзя: `role="treeitem"`
+  валиден только внутри `<ul role="tree">` / `<ul role="group">`.
+- **`role="treeitem"` и `aria-expanded` выставляются после `{...props}`** —
+  семантика узла часть контракта компонента, потребитель её не переопределяет.
+  `tabIndex` остаётся **до** спреда: roving tabindex — поведение, а не
+  семантика, и потребитель при желании может задать его сам. Но переданный
+  `tabIndex` побеждает навсегда: `TreeView.updateTabIndexNodes` продолжит
+  пересчитывать значение в абстрактной ноде, на DOM это уже не повлияет. Поставив
+  `tabIndex={0}` всем нодам, потребитель получит не свой roving tabindex, а
+  дерево, где каждая нода — отдельная остановка Tab. Переопределять — только если
+  берёшь управление фокусом целиком на себя.
+- **`event.stopPropagation()` в `handleFocus` / `handleBlur` обязателен.**
+  `focusin` всплывает, и без остановки активной становилась бы не текущая нода,
+  а её родитель. Пользовательские `onFocus` / `onBlur` вызываются после
+  внутренней логики — порядок менять нельзя.
+- **`children` — функция, а не `ReactNode`.** Смена сигнатуры — breaking change
+  для всей цепочки потребителей. Напрямую `TreeView.Node` рендерит только
+  `CollapsibleTreeExtended`; `CollapsibleTree` строится поверх него, а
+  `CheckboxTree` доходит до ноды через `CheckboxTreeExtended` →
+  `CollapsibleTreeExtended`.
+- **Barrel `src/components/TreeView/index.ts`** реэкспортирует модуль ноды
+  целиком (`export * from "./components/TreeViewNode"`), поэтому публичны и
+  `TreeViewNode`, и класс `TreeViewNodeWithContext`, и типы
+  `ITreeViewNodeProps`, `ITreeViewNodeProvideProps`,
+  `ITreeViewNodePropsWithContext` — всё это через `src/components/index.ts`
+  доходит до корня пакета. Состав и имена менять нельзя.
+- **`displayName` класса — `"TreeViewNodeWithContext"`**, у экспортируемой
+  обёртки — `"WithTreeViewContext(TreeViewNodeWithContext)"` (добавляет HOC).
+  Значения видны в React DevTools и в snapshot-тестах.
+- **Абстрактная нода мутируемая.** `this.abstractNode` меняется на месте, и сам
+  по себе перерендер не вызывает: любая мутация должна идти через методы
+  контекста (`setOpenedNode`, `setActiveNode`, `registerNode`, `removeNode`),
+  которые инкрементят `updateCount` в состоянии `TreeView`. Прямая запись в
+  `abstractNode` в обход контекста оставит ноду с устаревшими
+  `hasChildNodes` / `isLastNode`.
+
+---
+
+## Accessibility
+
+Ориентир — WAI-ARIA Authoring Practices,
+[treeview-2a](https://www.w3.org/TR/wai-aria-practices-1.1/examples/treeview/treeview-2/treeview-2a.html).
+
+- Узел — `<li role="treeitem">` с `aria-expanded`, отражающим состояние
+  раскрытия из абстрактного дерева. Вложенные ноды оборачиваются в
+  `TreeView.Group` (`<ul role="group">`).
+- **Roving tabindex.** `tabIndex` нода читает из абстрактной ноды
+  (`getTabIndex()`): первая нода первого уровня получает `0`, остальные `-1`.
+  Пересчитывает значения `TreeView` при регистрации и удалении нод — в дерево
+  можно попасть одним Tab.
+- **Активная нода ≠ DOM-фокус.** Активной нода становится по `focus`, а стрелки
+  (`ArrowDown` / `ArrowUp`, обрабатываются в `TreeView` на `window`) двигают
+  только флаг активности в абстрактном дереве — DOM-фокус остаётся на исходном
+  узле. Потребитель обязан визуально отрисовать активное состояние по
+  provide-prop `activeNode`, иначе клавиатурная навигация не видна.
+- `blur` снимает активность; когда активной ноды в дереве не остаётся,
+  `TreeView` отписывает слушатель стрелок.
+- Раскрытие/сворачивание по клавиатуре (`ArrowRight` / `ArrowLeft`,
+  `Home` / `End`) нода **не** реализует — это на потребителе, в его разметке
+  узла.
+- Текстовые подписи и `aria-label` нода не хардкодит: библиотека мультиязычная,
+  всю разметку узла даёт потребитель. `aria-label` на дерево вешается на
+  `TreeView`.
+
+---
+
+## Связанные компоненты
+
+- `TreeView` (`src/components/TreeView`) — родительский компонент и владелец
+  абстрактного дерева: регистрирует ноды, считает `tabIndex`, обрабатывает
+  стрелки. Нода без него не работает.
+- `TreeViewGroup` (`TreeView.Group`) — `<ul role="group">`, обёртка вложенных
+  нод. Тривиальная обёртка (`forwardRef` + `clsx` + спред), отдельного AI.md
+  нет.
+- `CollapsibleTreeExtended` (`src/components/CollapsibleTreeExtended`) — обёртка
+  над `TreeView.Node`, добавляющая анимацию раскрытия и
+  controlled/uncontrolled состояние. Берут вместо голой ноды, когда свой UI
+  узла нужен, а возиться с состоянием — нет.
+- `CollapsibleTree` (`src/components/CollapsibleTree`) и `CheckboxTree`
+  (`src/components/CheckboxTree`) — готовые деревья поверх ноды; оба
+  протаскивают `prevNodeId` / `nextNodeId` из массива данных.
+
+---
+
+## Stories
+
+Отдельных stories у ноды нет: без `TreeView` она не рендерится, а собственного
+оформления у неё нет — все её состояния показаны в stories родителя. Ниже —
+только те, что демонстрируют API самой ноды; полный список историй семейства
+(`Playground`, `Default`) — в [TreeView-ai.md](./TreeView-ai.md).
+
+Основные истории: `stories/TreeView/TreeView.stories.tsx`
+Файлы примеров: `stories/TreeView/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Nested` | `Nested.tsx` | Вложенность через `TreeView.Group`, prop `opened`, provide-props `openedNode` и `hasChildNodes` |
+| `Keyboard navigation` | `KeyboardNavigation.tsx` | Перемещение `activeNode` стрелками, подсветка активной ноды, `isLastNode` |
+| `VisualTests` | `VisualTests.tsx` | Свёрнутая и раскрытая нода, узел с детьми и лист, `isLastNode`; активная нода снимается через `play` |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-08-26 | Создан документ. Описание ноды вынесено из `TreeView-ai.md`. Добавлен unit-тест на `prevNodeId` — единственный публичный prop ноды, не покрытый тестами |
+
+---
+
+## Примеры использования
+
+### Nested
+
+`stories/TreeView/examples/Nested.tsx`
+
+```tsx
+import React from "react";
+import clsx from "clsx";
+import { CaretrightStrokeSrvIcon24 } from "@sberbusiness/icons-next";
+import { ETextSize, Text, TreeView } from "@sberbusiness/triplex-next";
+import "./Nested.less";
+
+interface INodeData {
+    id: string;
+    label: string;
+    children?: INodeData[];
+}
+
+const nodes: INodeData[] = [
+    {
+        id: "folder-1",
+        label: "Folder text",
+        children: [
+            { id: "file-1-1", label: "File text" },
+            { id: "file-1-2", label: "File text" },
+        ],
+    },
+    {
+        id: "folder-2",
+        label: "Folder text",
+        children: [
+            {
+                id: "folder-2-1",
+                label: "Folder text",
+                children: [{ id: "file-2-1-1", label: "File text" }],
+            },
+        ],
+    },
+    { id: "file-3", label: "File text" },
+];
+
+interface ITreeNodeProps {
+    node: INodeData;
+}
+
+const TreeNode = ({ node }: ITreeNodeProps) => {
+    const [opened, setOpened] = React.useState(false);
+    const branch = Boolean(node.children?.length);
+
+    const toggle = () => setOpened((prevOpened) => !prevOpened);
+
+    const handleClick = (event: React.MouseEvent<HTMLElement>) => {
+        // Клик по вложенной ноде не должен раскрывать родительскую.
+        event.stopPropagation();
+
+        if (branch) {
+            toggle();
+        }
+    };
+
+    const handleKeyDown = (event: React.KeyboardEvent<HTMLElement>) => {
+        if (event.key !== "Enter" && event.key !== " ") {
+            return;
+        }
+
+        event.preventDefault();
+        event.stopPropagation();
+
+        if (branch) {
+            toggle();
+        }
+    };
+
+    return (
+        <TreeView.Node id={node.id} opened={opened} onClick={handleClick} onKeyDown={handleKeyDown}>
+            {({ hasChildNodes, openedNode }) => (
+                <>
+                    <div className={clsx("tree-view-nested-example-row", { branch })}>
+                        {hasChildNodes ? (
+                            <CaretrightStrokeSrvIcon24
+                                paletteIndex={5}
+                                className={clsx("tree-view-nested-example-chevron", { opened: openedNode })}
+                                aria-hidden
+                            />
+                        ) : (
+                            <span className="tree-view-nested-example-chevron-placeholder" />
+                        )}
+                        <Text size={ETextSize.B1} tag="span">
+                            {node.label}
+                        </Text>
+                    </div>
+                    {node.children ? (
+                        // Группа остаётся смонтированной: так вложенные ноды зарегистрированы в дереве
+                        // и родитель знает про hasChildNodes даже в свёрнутом состоянии.
+                        <TreeView.Group className={clsx("tree-view-nested-example-group", { collapsed: !openedNode })}>
+                            {node.children.map((child) => (
+                                <TreeNode key={child.id} node={child} />
+                            ))}
+                        </TreeView.Group>
+                    ) : null}
+                </>
+            )}
+        </TreeView.Node>
+    );
+};
+
+export const Nested = () => (
+    <div className="tree-view-nested-example" style={{ maxWidth: 420 }}>
+        <TreeView aria-label="Tree">
+            {nodes.map((node) => (
+                <TreeNode key={node.id} node={node} />
+            ))}
+        </TreeView>
+    </div>
+);
+```
+
+### Keyboard navigation
+
+`stories/TreeView/examples/KeyboardNavigation.tsx`
+
+```tsx
+import React from "react";
+import clsx from "clsx";
+import { ECaptionSize, ETextSize, Caption, Text, TreeView } from "@sberbusiness/triplex-next";
+import "./KeyboardNavigation.less";
+
+interface INodeData {
+    id: string;
+    label: string;
+    children?: INodeData[];
+}
+
+const nodes: INodeData[] = [
+    {
+        id: "folder-1",
+        label: "Folder text",
+        children: [
+            { id: "file-1-1", label: "File text" },
+            { id: "file-1-2", label: "File text" },
+        ],
+    },
+    {
+        id: "folder-2",
+        label: "Folder text",
+        children: [{ id: "file-2-1", label: "File text" }],
+    },
+];
+
+interface ITreeNodeProps {
+    node: INodeData;
+}
+
+const TreeNode = ({ node }: ITreeNodeProps) => (
+    // Ветки раскрыты сразу: стрелки спускаются только в раскрытые ноды.
+    <TreeView.Node id={node.id} opened>
+        {({ activeNode, isLastNode }) => (
+            <>
+                <div className={clsx("tree-view-keyboard-example-row", { active: activeNode })}>
+                    <Text size={ETextSize.B1} tag="span">
+                        {node.label}
+                    </Text>
+                    {isLastNode ? (
+                        <Caption size={ECaptionSize.C2} tag="span">
+                            isLastNode
+                        </Caption>
+                    ) : null}
+                </div>
+                {node.children ? (
+                    <TreeView.Group>
+                        {node.children.map((child) => (
+                            <TreeNode key={child.id} node={child} />
+                        ))}
+                    </TreeView.Group>
+                ) : null}
+            </>
+        )}
+    </TreeView.Node>
+);
+
+export const KeyboardNavigation = () => (
+    <div className="tree-view-keyboard-example" style={{ maxWidth: 420 }}>
+        <Caption size={ECaptionSize.C1} tag="p">
+            Поставьте фокус на любой узел и используйте стрелки вверх/вниз.
+        </Caption>
+        <TreeView aria-label="Tree">
+            {nodes.map((node) => (
+                <TreeNode key={node.id} node={node} />
+            ))}
+        </TreeView>
+    </div>
+);
+```
+