@sberbusiness/triplex-next-mcp-server 0.24.0-beta2 → 0.36.0-beta0

package/bundle/components/CollapsibleTree.md

@@ -0,0 +1,581 @@
+---
+component: CollapsibleTree
+category: CollapsibleTree
+related: [CollapsibleTreeExtended, CollapsibleTreeNodeHeader, CollapsibleTreeNodeLabel, TreeView, AccordionBase]
+tokens:
+  - --triplex-next-CollapsibleTree-Header_Background_Hover
+  - --triplex-next-CollapsibleTree-Header_Shadow_Focus
+stories: stories/CollapsibleTree/CollapsibleTree.stories.tsx
+version: "1.0"
+---
+
+# CollapsibleTree
+
+## Назначение
+
+Готовое дерево с раскрывающимися ветками и типовым UI узла: кнопка-заголовок с
+шевроном-индикатором раскрытия, hover и focus-visible на интерактивной строке.
+Обёртка над [`CollapsibleTreeExtended`](../CollapsibleTreeExtended/CollapsibleTreeExtended-ai.md).
+
+Структура задаётся декларативно через массив `nodes`: ветка
+(`ICollapsibleTreeNodeBranch`) с `label` и опциональными `children`, либо лист
+(`ICollapsibleTreeNodeLeaf`) с произвольным `content`. На верхнем уровне
+допустимы только ветки.
+
+Используй `CollapsibleTree` когда: достаточно типового UI «папка/файл», нужен
+шеврон, hover и focus-visible, и хочется задавать структуру через данные.
+
+Используй `CollapsibleTreeExtended` когда: нужен нестандартный UI узла —
+своя иконка раскрытия, кастомный header, особое поведение клика, layout с
+несколькими колонками, полный контроль состояния раскрытия из родителя.
+
+---
+
+## Варианты и props
+
+### `CollapsibleTree`
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `nodes` | `ICollapsibleTreeNodeBranch[]` | — | Данные дерева. На верхнем уровне — только ветки; листья — внутри `children` ветки |
+| `children` | `never` | — | Запрещён — структура задаётся через `nodes` |
+| `...HTMLUListElementAttributes` | — | — | Атрибуты `<ul>`, наследуются от `CollapsibleTreeExtended` → `TreeView` |
+
+### Модель данных
+
+`ICollapsibleTreeNodeBranch` — ветка:
+
+| Поле | Тип | Описание |
+|---|---|---|
+| `id` | `string` | Уникальный идентификатор узла в дереве |
+| `label` | `React.ReactNode` | Содержимое заголовка. Для типовой типографики — оборачивай в `CollapsibleTreeNodeLabel` |
+| `children` | `TCollapsibleTreeNode[]` | Дочерние узлы. Пустой массив / `undefined` — ветка отображается без шеврона и не раскрывается |
+| `defaultOpened` | `boolean` | Начальное состояние раскрытия |
+| `disabled` | `boolean` | Отключает узел: кнопка заголовка неактивна, шеврон отображается приглушённым цветом. Шеврон и `aria-expanded` сохраняются. Для приглушённого текста передавай `type={EFontType.DISABLED}` в `CollapsibleTreeNodeLabel` внутри `label` |
+
+`ICollapsibleTreeNodeLeaf` — лист:
+
+| Поле | Тип | Описание |
+|---|---|---|
+| `id` | `string` | Уникальный идентификатор узла в дереве |
+| `content` | `React.ReactNode` | Произвольный контент листа |
+
+Type guard: `isCollapsibleTreeNodeLeaf(node)` — `"content" in node`.
+
+### `CollapsibleTreeNodeHeader`
+
+Кнопка-заголовок для интеграции с кастомным `renderHeader` у
+`CollapsibleTreeExtended`. Принимает provide-props из `CollapsibleTreeExtended.Node`
+(`opened`, `toggle`, `hasChildNodes`, `animating`, `activeNode`, `isLastNode`)
+и все стандартные `React.ButtonHTMLAttributes<HTMLButtonElement>`. Внутри
+`CollapsibleTree` подставляется автоматически.
+
+| Поведение | Условие |
+|---|---|
+| `disabled={true}` на `<button>` | `hasChildNodes === false` либо проп `disabled === true` |
+| `aria-expanded={opened}` | `hasChildNodes === true` (для листьев не ставится, при `disabled` сохраняется) |
+| Шеврон отрендерен | `hasChildNodes === true` (в том числе при `disabled`) |
+| Класс `interactive` | `hasChildNodes === true && !disabled` |
+| Глобальные классы `hoverable disabled` | проп `disabled === true` — управляют приглушённым цветом шеврона через стили `@sberbusiness/icons-next` (как в `IconWrapper`) |
+| Класс `chevron.opened` | `opened === true` |
+| `toggle(!opened)` вызывается | по клику, только при `hasChildNodes === true && !disabled` |
+| Кастомный `onClick` | вызывается всегда после `toggle` |
+
+Проп `disabled` (из `ButtonHTMLAttributes`) — единственный HTML-атрибут,
+который header интерпретирует сам: он добавляет визуальное disabled-состояние
+и блокирует `toggle`. Передать `disabled={false}` для узла без детей нельзя —
+внутренняя логика важнее (`disabled || !hasChildNodes`).
+
+### `CollapsibleTreeNodeLabel`
+
+Обёртка над `Text` для лейбла ветки. Дефолты — `size=B1`, `weight=SEMIBOLD`.
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `size` | `ETextSize` | `B1` | Размер текста |
+| `weight` | `EFontWeightText` | `SEMIBOLD` | Толщина шрифта |
+| `...TTextProps` | — | — | Все props `Text<"span">` кроме `tag` и `size` (тэг зафиксирован как `span`) |
+
+---
+
+## Дизайн-токены
+
+```text
+--triplex-next-CollapsibleTree-Header_Background_Hover
+--triplex-next-CollapsibleTree-Header_Shadow_Focus
+```
+
+Цвета disabled-состояния задаются без собственных токенов: шеврон — глобальными
+классами `hoverable disabled` на кнопке заголовка (стили `@sberbusiness/icons-next`),
+текст — `type={EFontType.DISABLED}` у `CollapsibleTreeNodeLabel` на стороне потребителя.
+
+Анимация раскрытия и базовая семантика дерева наследуются от
+`CollapsibleTreeExtended` / `TreeView` / `AccordionBase` — своих токенов на
+анимацию у `CollapsibleTree` нет.
+
+---
+
+## Инварианты
+
+- **`CollapsibleTree` — FC без `forwardRef`.** Под капотом class-компонент
+  `TreeView`, ref не пробрасывается осмысленно. Тот же инвариант, что у
+  `CollapsibleTreeExtended` и `CollapsibleTreeLeafNode` (тоже проксируют в
+  class-компонент).
+- **`CollapsibleTreeNodeHeader` — `forwardRef<HTMLButtonElement>`** — ref
+  идёт на корневой `<button>`, чтобы потребитель мог управлять фокусом
+  заголовка (например, программно фокусировать конкретный узел).
+- **`CollapsibleTreeLeafContent` — `forwardRef<HTMLDivElement>`** — ref на
+  корневой `<div>` контента листа (стандартный контракт для контейнерных
+  компонентов).
+- **`CollapsibleTreeNodeLabel` — `forwardRef<HTMLSpanElement>`** — нужен для
+  измерения ширины лейбла потребителем.
+- **Публичные экспорты barrel** (`src/components/CollapsibleTree/index.ts`):
+  `CollapsibleTree`, `CollapsibleTreeNodeHeader`, `CollapsibleTreeNodeLabel`,
+  все типы из `types.ts` (`ICollapsibleTreeNodeBranch`, `ICollapsibleTreeNodeLeaf`,
+  `TCollapsibleTreeNode`, `isCollapsibleTreeNodeLeaf`). Менять имена нельзя.
+- **Внутренние компоненты** — `CollapsibleTreeBranchNode`, `CollapsibleTreeLeafNode`,
+  `CollapsibleTreeLeafContent` — намеренно НЕ в barrel. Если внешнему
+  потребителю нужен кастомный лист или ветка — это сигнал использовать
+  `CollapsibleTreeExtended` напрямую, а не расширять `CollapsibleTree`.
+- **Диспетчер ветка/лист инлайнится в `CollapsibleTreeBranchNode`** — выбор
+  через `isCollapsibleTreeNodeLeaf(child)` прямо в `renderBody`. Раньше был
+  отдельный `CollapsibleTreeNode.tsx`, но это создавало циклическую
+  зависимость `BranchNode ↔ Node` (madge `deps:cycles`). Не возвращать.
+- **`children: never` на `CollapsibleTree`** — структура задаётся только через
+  `nodes`. Передача `children` запрещена типом.
+- **`CollapsibleTreeBranchNode` хранит локальный `opened`** — инициализируется
+  из `node.defaultOpened ?? false`. Чтобы программно менять раскрытие извне —
+  используй `CollapsibleTreeExtended` (controlled-режим через `opened` /
+  `toggle`).
+- **`CollapsibleTreeLeafNode` использует «семантический хак»** — передаёт в
+  `CollapsibleTreeExtended.Node` `opened={true}` и `toggle=noop`. Это
+  намеренное решение по контракту API `Extended.Node` (renderBody возвращает
+  `null`, шеврон не рендерится потому, что `hasChildNodes === false`).
+  Не переписывать без обсуждения с командой.
+- **Корневой DOM** — `<ul>` от `TreeView`, узлы — `<li>`.
+
+---
+
+## Accessibility
+
+- Семантика дерева наследуется от `TreeView` — корневой `<ul>`, узлы `<li>`,
+  ветки оборачиваются в `<ul role="group">` через `TreeView.Group` при наличии
+  детей.
+- Клавиатурная навигация по дереву (стрелки, Home/End, раскрытие/сворачивание)
+  обрабатывается на уровне `TreeView` — `CollapsibleTree` ничего не добавляет
+  сверху.
+- `CollapsibleTreeNodeHeader` рендерит нативный `<button>` с
+  `aria-expanded={opened}` для веток с детьми; для веток без детей и листьев
+  кнопка `disabled` и `aria-expanded` не выставляется.
+- Лейбл (`label` в `ICollapsibleTreeNodeBranch`) — это видимая текстовая
+  подпись, которая служит accessible name кнопки-заголовка. Если в `label`
+  передаётся не-текстовый контент (иконка, badge) — потребитель **обязан**
+  обеспечить accessible name через `aria-label` на самой кнопке заголовка
+  через `CollapsibleTreeExtended` (для типового UI таких кейсов не бывает).
+- Свёрнутая ветка получает `visibility: hidden` на body через
+  `CollapsibleTreeExtended` — Tab не уходит в скрытое содержимое.
+- Фокус-стиль — `:focus-visible` через токен
+  `--triplex-next-CollapsibleTree-Header_Shadow_Focus`.
+
+---
+
+## Связанные компоненты
+
+- [`CollapsibleTreeExtended`](../CollapsibleTreeExtended/CollapsibleTreeExtended-ai.md)
+  — низкоуровневая база с произвольным `renderHeader`/`renderBody`.
+  `CollapsibleTree` — типовая обёртка над ней.
+- `CollapsibleTreeNodeHeader` (этот же barrel) — кнопка-заголовок с шевроном,
+  доступна для использования в кастомном `renderHeader` у `CollapsibleTreeExtended`.
+- `CollapsibleTreeNodeLabel` (этот же barrel) — типографика заголовка
+  (`Text` со span-тегом, дефолты B1 / SEMIBOLD). Используй внутри `label`
+  ветки или в кастомном header'е, когда нужен другой `size`/`weight`.
+- `TreeView` (`src/components/TreeView`) — нижний слой: семантика дерева,
+  абстрактное дерево нод, фокус, активная нода, клавиатурная навигация.
+- `AccordionBase` (`src/components/AccordionBase`) — анимация раскрытия,
+  используется внутри каждой ветки через `CollapsibleTreeExtended`.
+
+---
+
+## Stories
+
+Основные истории: `stories/CollapsibleTree/CollapsibleTree.stories.tsx`
+Файлы примеров: `stories/CollapsibleTree/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | — | Интерактивный контрол `nodes` |
+| `Default` | `Default.tsx` | Базовое плоское дерево «папка/файл» |
+| `Opened` | `Opened.tsx` | Стартово раскрытая ветка через `defaultOpened` |
+| `Nested` | `Nested.tsx` | Многоуровневое дерево с вложенными ветками |
+| `Custom label` | `CustomLabel.tsx` | Переопределение `size`/`weight` через `CollapsibleTreeNodeLabel` |
+| `Disabled` | `Disabled.tsx` | Отключённый узел через `disabled: true` |
+| `VisualTests` | `VisualTestsExample.tsx` | Четыре состояния в одном кадре — для baseline-скриншотов |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-05-15 | Создан документ. Зафиксирован «семантический хак» `LeafNode` (`opened=true + toggle=noop`), список внутренних компонентов вне barrel, инварианты по `forwardRef` |
+| 2026-05-15 | `CollapsibleTreeNodeHeader` и `CollapsibleTreeLeafContent` переведены на `forwardRef` (DOM-ref на `<button>` и `<div>` соответственно). Защищены инварианты `<button>` (`type`, `disabled`, `aria-expanded`) от перетирания через `{...props}` |
+| 2026-07-06 | Шеврон открытого узла теперь указывает вверх (`rotate(-90deg)`), а не вниз |
+| 2026-07-06 | Добавлено свойство `disabled` у `ICollapsibleTreeNodeBranch` и поддержка пропа `disabled` в `CollapsibleTreeNodeHeader`. Без новых токенов: шеврон приглушается глобальными классами `hoverable disabled` (icons-next), текст — через `type={EFontType.DISABLED}` у лейбла |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/CollapsibleTree/examples/Default.tsx`
+
+```tsx
+import React from "react";
+import {
+    CollapsibleTree,
+    CollapsibleTreeNodeLabel,
+    ETextSize,
+    ICollapsibleTreeNodeBranch,
+    Text,
+} from "@sberbusiness/triplex-next";
+
+const nodes: ICollapsibleTreeNodeBranch[] = [
+    {
+        id: "folder-1",
+        label: <CollapsibleTreeNodeLabel>Folder text</CollapsibleTreeNodeLabel>,
+        children: [
+            {
+                id: "file-1",
+                content: (
+                    <>
+                        <Text size={ETextSize.B1} tag="span">
+                            File text
+                        </Text>
+                        <Text size={ETextSize.B1} tag="span">
+                            File text
+                        </Text>
+                    </>
+                ),
+            },
+        ],
+    },
+    {
+        id: "folder-2",
+        label: <CollapsibleTreeNodeLabel>Folder text</CollapsibleTreeNodeLabel>,
+        children: [
+            {
+                id: "file-2",
+                content: (
+                    <Text size={ETextSize.B1} tag="span">
+                        File text
+                    </Text>
+                ),
+            },
+        ],
+    },
+    {
+        id: "folder-3",
+        label: <CollapsibleTreeNodeLabel>Folder text</CollapsibleTreeNodeLabel>,
+        children: [
+            {
+                id: "file-3",
+                content: (
+                    <Text size={ETextSize.B1} tag="span">
+                        File text
+                    </Text>
+                ),
+            },
+        ],
+    },
+];
+
+export const Default = () => (
+    <div style={{ maxWidth: 320 }}>
+        <CollapsibleTree nodes={nodes} />
+    </div>
+);
+```
+
+### Opened
+
+`stories/CollapsibleTree/examples/Opened.tsx`
+
+```tsx
+import React from "react";
+import {
+    CollapsibleTree,
+    CollapsibleTreeNodeLabel,
+    ETextSize,
+    ICollapsibleTreeNodeBranch,
+    Text,
+} from "@sberbusiness/triplex-next";
+
+const nodes: ICollapsibleTreeNodeBranch[] = [
+    {
+        id: "folder-1",
+        label: <CollapsibleTreeNodeLabel>Folder text</CollapsibleTreeNodeLabel>,
+        children: [
+            {
+                id: "file-1",
+                content: (
+                    <Text size={ETextSize.B1} tag="span">
+                        File text
+                    </Text>
+                ),
+            },
+        ],
+    },
+    {
+        id: "folder-2",
+        label: <CollapsibleTreeNodeLabel>Folder text</CollapsibleTreeNodeLabel>,
+        defaultOpened: true,
+        children: [
+            {
+                id: "file-2",
+                content: (
+                    <Text size={ETextSize.B1} tag="span">
+                        File text
+                    </Text>
+                ),
+            },
+        ],
+    },
+    {
+        id: "folder-3",
+        label: <CollapsibleTreeNodeLabel>Folder text</CollapsibleTreeNodeLabel>,
+        children: [
+            {
+                id: "file-3",
+                content: (
+                    <Text size={ETextSize.B1} tag="span">
+                        File text
+                    </Text>
+                ),
+            },
+        ],
+    },
+];
+
+export const Opened = () => (
+    <div style={{ maxWidth: 320 }}>
+        <CollapsibleTree nodes={nodes} />
+    </div>
+);
+```
+
+### Nested
+
+`stories/CollapsibleTree/examples/Nested.tsx`
+
+```tsx
+import React from "react";
+import {
+    CollapsibleTree,
+    CollapsibleTreeNodeLabel,
+    ETextSize,
+    ICollapsibleTreeNodeBranch,
+    Text,
+} from "@sberbusiness/triplex-next";
+
+const nodes: ICollapsibleTreeNodeBranch[] = [
+    {
+        id: "folder-1",
+        label: <CollapsibleTreeNodeLabel>Folder text</CollapsibleTreeNodeLabel>,
+        children: [
+            {
+                id: "file-1",
+                content: (
+                    <Text size={ETextSize.B1} tag="span">
+                        File text
+                    </Text>
+                ),
+            },
+        ],
+    },
+    {
+        id: "folder-2",
+        label: <CollapsibleTreeNodeLabel>Folder text</CollapsibleTreeNodeLabel>,
+        defaultOpened: true,
+        children: [
+            {
+                id: "folder-2-1",
+                label: <CollapsibleTreeNodeLabel>Folder text</CollapsibleTreeNodeLabel>,
+                defaultOpened: true,
+                children: [
+                    {
+                        id: "file-2-1-1",
+                        content: (
+                            <Text size={ETextSize.B1} tag="span">
+                                File text
+                            </Text>
+                        ),
+                    },
+                ],
+            },
+        ],
+    },
+    {
+        id: "folder-3",
+        label: <CollapsibleTreeNodeLabel>Folder text</CollapsibleTreeNodeLabel>,
+        defaultOpened: true,
+        children: [
+            {
+                id: "file-3",
+                content: (
+                    <Text size={ETextSize.B1} tag="span">
+                        File text
+                    </Text>
+                ),
+            },
+        ],
+    },
+];
+
+export const Nested = () => (
+    <div style={{ maxWidth: 420 }}>
+        <CollapsibleTree nodes={nodes} />
+    </div>
+);
+```
+
+### Custom label
+
+`stories/CollapsibleTree/examples/CustomLabel.tsx`
+
+```tsx
+import React from "react";
+import {
+    CollapsibleTree,
+    CollapsibleTreeNodeLabel,
+    EFontWeightText,
+    ETextSize,
+    ICollapsibleTreeNodeBranch,
+    Text,
+} from "@sberbusiness/triplex-next";
+
+const nodes: ICollapsibleTreeNodeBranch[] = [
+    {
+        id: "folder-1",
+        label: <CollapsibleTreeNodeLabel size={ETextSize.B3}>Folder text (B3)</CollapsibleTreeNodeLabel>,
+        children: [
+            {
+                id: "file-1",
+                content: (
+                    <Text size={ETextSize.B3} tag="span">
+                        File text
+                    </Text>
+                ),
+            },
+        ],
+    },
+    {
+        id: "folder-2",
+        label: (
+            <CollapsibleTreeNodeLabel size={ETextSize.B2} weight={EFontWeightText.REGULAR}>
+                Folder text (B2, regular)
+            </CollapsibleTreeNodeLabel>
+        ),
+        defaultOpened: true,
+        children: [
+            {
+                id: "file-2",
+                content: (
+                    <Text size={ETextSize.B2} tag="span">
+                        File text
+                    </Text>
+                ),
+            },
+        ],
+    },
+    {
+        id: "folder-3",
+        label: <CollapsibleTreeNodeLabel size={ETextSize.B1}>Folder text (B1, default)</CollapsibleTreeNodeLabel>,
+        children: [
+            {
+                id: "file-3",
+                content: (
+                    <Text size={ETextSize.B1} tag="span">
+                        File text
+                    </Text>
+                ),
+            },
+        ],
+    },
+];
+
+export const CustomLabel = () => (
+    <div style={{ maxWidth: 360 }}>
+        <CollapsibleTree nodes={nodes} />
+    </div>
+);
+```
+
+### Disabled
+
+`stories/CollapsibleTree/examples/Disabled.tsx`
+
+```tsx
+import React from "react";
+import {
+    CollapsibleTree,
+    CollapsibleTreeNodeLabel,
+    EFontType,
+    ETextSize,
+    ICollapsibleTreeNodeBranch,
+    Text,
+} from "@sberbusiness/triplex-next";
+
+const nodes: ICollapsibleTreeNodeBranch[] = [
+    {
+        id: "folder-1",
+        label: <CollapsibleTreeNodeLabel>Folder text</CollapsibleTreeNodeLabel>,
+        children: [
+            {
+                id: "file-1",
+                content: (
+                    <Text size={ETextSize.B1} tag="span">
+                        File text
+                    </Text>
+                ),
+            },
+        ],
+    },
+    {
+        id: "folder-2",
+        label: <CollapsibleTreeNodeLabel type={EFontType.DISABLED}>Disabled folder</CollapsibleTreeNodeLabel>,
+        disabled: true,
+        children: [
+            {
+                id: "file-2",
+                content: (
+                    <Text size={ETextSize.B1} tag="span">
+                        File text
+                    </Text>
+                ),
+            },
+        ],
+    },
+    {
+        id: "folder-3",
+        label: <CollapsibleTreeNodeLabel>Folder text</CollapsibleTreeNodeLabel>,
+        children: [
+            {
+                id: "file-3",
+                content: (
+                    <Text size={ETextSize.B1} tag="span">
+                        File text
+                    </Text>
+                ),
+            },
+        ],
+    },
+];
+
+export const Disabled = () => (
+    <div style={{ maxWidth: 320 }}>
+        <CollapsibleTree nodes={nodes} />
+    </div>
+);
+```
+