@sberbusiness/triplex-next-mcp-server 0.24.0-beta2 → 1.40.0-beta

package/bundle/components/CollapsibleTreeExtended.md

@@ -0,0 +1,422 @@
+---
+component: CollapsibleTreeExtended
+category: CollapsibleTree
+related: [CollapsibleTree, TreeView, AccordionBase]
+tokens: []
+stories: stories/CollapsibleTreeExtended/CollapsibleTreeExtended.stories.tsx
+version: "1.0"
+---
+
+# CollapsibleTreeExtended
+
+## Назначение
+
+Низкоуровневое декларативное дерево с раскрывающимися узлами. Тонкая обёртка
+над `TreeView`, дополняющая каждую ноду accordion-логикой (анимация раскрытия,
+controlled/uncontrolled-состояние) через `CollapsibleTreeExtended.Node`.
+
+Узел рендерится через две render-функции:
+
+- `renderHeader` — видимая часть узла, всегда отрисовывается в `<li>`. Кнопка с
+  шевроном, текст, иконка-toggle, бэйдж — любая разметка.
+- `renderBody` — раскрываемое содержимое (обычно дочерние ноды, но может быть
+  любым контентом).
+
+Используй `CollapsibleTreeExtended` когда: нужен нестандартный UI узла (своя
+иконка раскрытия, кликабельный header целиком, layout с несколькими колонками,
+полный контроль состояния раскрытия из родителя).
+
+Используй `CollapsibleTree` когда: достаточно типового UI «папка/файл» с
+шевроном, hover и focus-visible. `CollapsibleTree` построен поверх
+`CollapsibleTreeExtended` и закрывает большинство случаев.
+
+---
+
+## Варианты и props
+
+### `CollapsibleTreeExtended`
+
+FC-обёртка над `TreeView` без собственных props.
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `children` | `React.ReactNode` | — | Дочерние `CollapsibleTreeExtended.Node` |
+| `...HTMLUListElementAttributes` | — | — | Все стандартные атрибуты `<ul>` (наследуются от `TreeView`) |
+
+Доступ к ноде: `CollapsibleTreeExtended.Node` (статическое свойство, ссылка на
+`CollapsibleTreeExtendedNode`).
+
+### `CollapsibleTreeExtended.Node` (`CollapsibleTreeExtendedNode`)
+
+Обязательные props:
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `id` | `string` | Уникальный идентификатор ноды (наследуется из `TreeView.Node`) |
+| `renderHeader` | `(props: ICollapsibleTreeExtendedNodeHeaderProvideProps) => React.ReactNode` | Видимая часть ноды |
+| `renderBody` | `(props: ICollapsibleTreeExtendedNodeBodyProvideProps) => React.ReactNode` | Раскрываемое содержимое |
+
+Опциональные props:
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `opened` | `boolean` | `undefined` | Контролируемое состояние раскрытия. Если задан — нода controlled |
+| `toggle` | `(opened: boolean) => void` | — | Запрос на смену `opened` в controlled-режиме. Вызывается с новым значением |
+| `onToggle` | `(opened: boolean) => void` | — | Колбэк по факту завершения анимации раскрытия/сворачивания |
+| `children` | `never` | — | Запрещён — содержимое задаётся через `renderBody` |
+
+### Provide-props в render-функциях
+
+`renderHeader` получает `ICollapsibleTreeExtendedNodeHeaderProvideProps`:
+
+| Поле | Описание |
+|---|---|
+| `opened` | Текущее состояние раскрытия |
+| `toggle(opened)` | Функция смены `opened` (no-op при совпадении значений) |
+| `animating` | Идёт ли анимация раскрытия (из `AccordionBase`) |
+| `activeNode` | Текущая активная нода дерева (из `TreeView`) |
+| `hasChildNodes` | Есть ли у текущей ноды дочерние |
+| `isLastNode` | Последняя ли нода на своём уровне |
+
+`renderBody` получает `ICollapsibleTreeExtendedNodeBodyProvideProps` — тот же
+набор без `isLastNode`.
+
+### Controlled vs uncontrolled
+
+Режим вычисляется на **каждом** рендере по `props.opened !== undefined` —
+переход controlled ↔ uncontrolled во время жизни ноды поддерживается.
+
+- **Controlled** (`opened` задан): состояние читается из props, `toggle(next)`
+  делегируется в `props.toggle`. `setOpenedNode` (внутреннее состояние
+  `TreeView`) не вызывается.
+- **Uncontrolled** (`opened === undefined`): состояние хранит `TreeView`,
+  `toggle(next)` вызывает `setOpenedNode`. `props.toggle` не дергается.
+- В обоих режимах `onToggle` срабатывает после завершения анимации
+  раскрытия/сворачивания.
+
+---
+
+## Дизайн-токены
+
+Собственных CSS-переменных компонент не определяет. Используется
+`visibility: hidden` для скрытого содержимого (чтобы Tab не уходил в свёрнутую
+ветку) — без токенов.
+
+Анимация раскрытия и визуальные токены наследуются от `AccordionBase` и
+`TreeView`.
+
+---
+
+## Инварианты
+
+- **`CollapsibleTreeExtended.Node` — class-компонент.** Намеренное решение —
+  не переписывать на FC + hooks без согласования. `forwardRef` к нему не
+  применяется (классы используют обычный `ref`).
+- **`CollapsibleTreeExtended` — FC без `forwardRef`.** Это тонкая обёртка
+  `props → <TreeView>`, своего рендера нет; `ref` не имеет смысла, потому
+  что под капотом — class-компонент `TreeView` с собственной обработкой
+  фокуса.
+- **Доступ к ноде только через `CollapsibleTreeExtended.Node`** (compound
+  pattern). Прямой импорт `CollapsibleTreeExtendedNode` из barrel разрешён,
+  но в потребительском коде предпочтительнее `.Node`.
+- **Публичный API** — имена `ICollapsibleTreeExtendedNodeProps`,
+  `ICollapsibleTreeExtendedNodeBodyProvideProps`,
+  `ICollapsibleTreeExtendedNodeHeaderProvideProps`, `ICollapsibleTreeExtendedProps`,
+  `ICollapsibleTreeExtendedSFC` и сигнатуры `toggle`, `onToggle`,
+  `renderHeader`, `renderBody` — нельзя менять без breaking. Зависимости:
+  `CollapsibleTree`, `CollapsibleTreeBranchNode`, `CollapsibleTreeLeafNode`.
+- **`children: never` на `Node`** — содержимое задаётся только через
+  `renderBody`. Передача `children` запрещена типом.
+- **`opened` — controlled-флаг.** Считать `controlled = props.opened !== undefined`
+  на каждом рендере. Не возвращать хранение режима в state (был баг, починен
+  в 2026-05).
+- **Корневой DOM** — `<ul>` от `TreeView`, узлы — `<li>` (см. accessibility).
+
+---
+
+## Accessibility
+
+- Семантика дерева задаётся `TreeView` — корневой `<ul>`, узлы `<li>`, ветки
+  оборачиваются в `<TreeView.Group>` (доп. `<ul role="group">`) при наличии
+  детей.
+- Клавиатурная навигация по дереву (стрелки, Home/End, раскрытие/сворачивание)
+  обрабатывается на уровне `TreeView` — `CollapsibleTreeExtended` ничего не
+  добавляет сверху.
+- `aria-expanded`, `aria-label` на toggle-кнопке и любые другие aria-атрибуты
+  узла **передаёт потребитель** в разметке `renderHeader`. Компонент не
+  хардкодит текст и aria-атрибуты — библиотека мультиязычная и `renderHeader`
+  по контракту произвольный.
+- Свёрнутое `renderBody` получает `visibility: hidden` — фокус Tab не уходит
+  в скрытое содержимое, но reflow сохраняется (важно для анимации).
+- Активная нода (`activeNode` в provide-props) — это нода в фокусе клавиатуры
+  `TreeView`, не selected-состояние. Визуальную подсветку реализует
+  потребитель через `renderHeader`.
+
+---
+
+## Связанные компоненты
+
+- `CollapsibleTree` (`src/components/CollapsibleTree`) — готовая обёртка
+  верхнего уровня с типовым UI узла (шеврон, hover, focus-visible). Если
+  нестандартный UI узла не нужен — используй её.
+- `TreeView` (`src/components/TreeView`) — нижний слой: семантика дерева,
+  абстрактное дерево нод, фокус, активная нода, клавиатурная навигация.
+- `AccordionBase` (`src/components/AccordionBase`) — анимация раскрытия и
+  `onToggle` после завершения анимации. Используется внутри каждой ноды.
+
+---
+
+## Stories
+
+Основные истории: `stories/CollapsibleTreeExtended/CollapsibleTreeExtended.stories.tsx`
+Файлы примеров: `stories/CollapsibleTreeExtended/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `defaultOpened` и `withCustomToggle` |
+| `Default` | `DefaultExample.tsx` | Типовой UI: кнопка с шевроном для веток, плоский `div` для листьев (по сути воспроизводит `CollapsibleTree`) |
+| `Custom toggle (Plus/Minus)` | `CustomToggleExample.tsx` | Альтернативная иконка раскрытия — Plus/Minus вместо шеврона |
+| `VisualTests` | `VisualTestsExample.tsx` | Три состояния в одном кадре: collapsed, expanded, custom toggle — для baseline-скриншотов |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-05-15 | Создан документ. Зафиксирован фикс controlled-инварианта (режим вычисляется на каждом рендере) и пополнение stories (`Playground`, `VisualTests`) |
+| 2026-07-06 | В story-примерах шеврон открытого узла теперь указывает вверх (`rotate(-90deg)`), а не вниз — синхронно с `CollapsibleTree` |
+| 2026-07-14 | В story-примерах на кнопку заголовка добавлены глобальные классы icons-next: `hoverable` всегда и `active` при `opened` — цвет иконки раскрытия, синхронно с `CollapsibleTreeNodeHeader` |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/CollapsibleTreeExtended/examples/DefaultExample.tsx`
+
+```tsx
+import React from "react";
+import clsx from "clsx";
+import { CaretrightStrokeSrvIcon24 } from "@sberbusiness/icons-next";
+import { CollapsibleTreeExtended, EFontWeightText, ETextSize, Text } from "@sberbusiness/triplex-next";
+import "./DefaultExample.less";
+
+interface ITreeNodeData {
+    id: string;
+    label: React.ReactNode;
+    defaultOpened?: boolean;
+    children?: ITreeNodeData[];
+}
+
+const nodes: ITreeNodeData[] = [
+    {
+        id: "folder-1",
+        label: "Folder text",
+        children: [{ id: "file-1", label: "File text" }],
+    },
+    {
+        id: "folder-2",
+        label: "Folder text",
+        defaultOpened: true,
+        children: [
+            {
+                id: "folder-2-1",
+                label: "Folder text",
+                defaultOpened: true,
+                children: [
+                    { id: "file-2-1-1", label: "File text" },
+                    { id: "file-2-1-2", label: "File text" },
+                ],
+            },
+        ],
+    },
+    {
+        id: "folder-3",
+        label: "Folder text",
+        defaultOpened: true,
+        children: [{ id: "file-3", label: "File text" }],
+    },
+];
+
+interface ITreeNodeProps {
+    node: ITreeNodeData;
+    prevNode?: ITreeNodeData;
+    nextNode?: ITreeNodeData;
+}
+
+const TreeNode: React.FC<ITreeNodeProps> = ({ node, prevNode, nextNode }) => {
+    const hasChildren = Boolean(node.children?.length);
+    const [opened, setOpened] = React.useState(node.defaultOpened ?? false);
+
+    return (
+        <CollapsibleTreeExtended.Node
+            id={node.id}
+            opened={opened}
+            toggle={setOpened}
+            prevNodeId={prevNode?.id}
+            nextNodeId={nextNode?.id}
+            renderHeader={({ hasChildNodes }) =>
+                hasChildNodes ? (
+                    <button
+                        type="button"
+                        // Глобальные классы @sberbusiness/icons-next "hoverable" и "active" — задают цвет шеврона.
+                        className={clsx("collapsible-tree-extended-example-header", "hoverable", { active: opened })}
+                        onClick={() => setOpened(!opened)}
+                        aria-expanded={opened}
+                    >
+                        <CaretrightStrokeSrvIcon24
+                            paletteIndex={5}
+                            className={clsx("collapsible-tree-extended-example-chevron", { opened })}
+                            aria-hidden
+                        />
+                        <Text size={ETextSize.B1} tag="span" weight={EFontWeightText.SEMIBOLD}>
+                            {node.label}
+                        </Text>
+                    </button>
+                ) : (
+                    <div className="collapsible-tree-extended-example-leaf">
+                        <Text size={ETextSize.B1} tag="span">
+                            {node.label}
+                        </Text>
+                    </div>
+                )
+            }
+            renderBody={() =>
+                hasChildren
+                    ? node.children!.map((child, index) => (
+                          <TreeNode
+                              key={child.id}
+                              node={child}
+                              prevNode={node.children![index - 1]}
+                              nextNode={node.children![index + 1]}
+                          />
+                      ))
+                    : null
+            }
+        />
+    );
+};
+
+export const DefaultExample = () => (
+    <div className="collapsible-tree-extended-example" style={{ maxWidth: 420 }}>
+        <CollapsibleTreeExtended>
+            {nodes.map((node, index) => (
+                <TreeNode key={node.id} node={node} prevNode={nodes[index - 1]} nextNode={nodes[index + 1]} />
+            ))}
+        </CollapsibleTreeExtended>
+    </div>
+);
+```
+
+### Custom toggle (Plus/Minus)
+
+`stories/CollapsibleTreeExtended/examples/CustomToggleExample.tsx`
+
+```tsx
+import React from "react";
+import clsx from "clsx";
+import { MinusStrokeSrvIcon24, PlusStrokeSrvIcon24 } from "@sberbusiness/icons-next";
+import { CollapsibleTreeExtended, EFontWeightText, ETextSize, Text } from "@sberbusiness/triplex-next";
+import "./CustomToggleExample.less";
+
+interface ITreeNodeData {
+    id: string;
+    label: React.ReactNode;
+    defaultOpened?: boolean;
+    children?: ITreeNodeData[];
+}
+
+const nodes: ITreeNodeData[] = [
+    {
+        id: "section-1",
+        label: "Section 1",
+        defaultOpened: true,
+        children: [
+            { id: "item-1-1", label: "Item 1.1" },
+            { id: "item-1-2", label: "Item 1.2" },
+        ],
+    },
+    {
+        id: "section-2",
+        label: "Section 2",
+        children: [
+            { id: "item-2-1", label: "Item 2.1" },
+            { id: "item-2-2", label: "Item 2.2" },
+        ],
+    },
+];
+
+interface ITreeNodeProps {
+    node: ITreeNodeData;
+    prevNode?: ITreeNodeData;
+    nextNode?: ITreeNodeData;
+}
+
+const TreeNode: React.FC<ITreeNodeProps> = ({ node, prevNode, nextNode }) => {
+    const hasChildren = Boolean(node.children?.length);
+    const [opened, setOpened] = React.useState(node.defaultOpened ?? false);
+
+    return (
+        <CollapsibleTreeExtended.Node
+            id={node.id}
+            opened={opened}
+            toggle={setOpened}
+            prevNodeId={prevNode?.id}
+            nextNodeId={nextNode?.id}
+            renderHeader={({ hasChildNodes }) =>
+                hasChildNodes ? (
+                    <button
+                        type="button"
+                        // Глобальные классы @sberbusiness/icons-next "hoverable" и "active" — задают цвет иконки.
+                        className={clsx("custom-toggle-example-header", "hoverable", { active: opened })}
+                        onClick={() => setOpened(!opened)}
+                        aria-expanded={opened}
+                    >
+                        <span className="custom-toggle-example-icon" aria-hidden>
+                            {opened ? (
+                                <MinusStrokeSrvIcon24 paletteIndex={5} />
+                            ) : (
+                                <PlusStrokeSrvIcon24 paletteIndex={5} />
+                            )}
+                        </span>
+                        <Text size={ETextSize.B1} tag="span" weight={EFontWeightText.SEMIBOLD}>
+                            {node.label}
+                        </Text>
+                    </button>
+                ) : (
+                    <div className="custom-toggle-example-leaf">
+                        <Text size={ETextSize.B1} tag="span">
+                            {node.label}
+                        </Text>
+                    </div>
+                )
+            }
+            renderBody={() =>
+                hasChildren
+                    ? node.children!.map((child, index) => (
+                          <TreeNode
+                              key={child.id}
+                              node={child}
+                              prevNode={node.children![index - 1]}
+                              nextNode={node.children![index + 1]}
+                          />
+                      ))
+                    : null
+            }
+        />
+    );
+};
+
+export const CustomToggleExample = () => (
+    <div className="custom-toggle-example" style={{ maxWidth: 420 }}>
+        <CollapsibleTreeExtended>
+            {nodes.map((node, index) => (
+                <TreeNode key={node.id} node={node} prevNode={nodes[index - 1]} nextNode={nodes[index + 1]} />
+            ))}
+        </CollapsibleTreeExtended>
+    </div>
+);
+```
+