@sberbusiness/triplex-next-mcp-server 1.45.0-beta → 1.48.0-beta

package/bundle/components/TextareaField.md

@@ -1,9 +1,7 @@
 ---
 component: TextareaField
-category: Form Controls
-figma-node: ""
-figma-file: ""
-related: [TextField, FormField, FormFieldTextarea, TextFieldBase]
+category: TextFields
+related: [TextField, MaskedField, FormField, FormGroup, DateField, MonthYearField]
 tokens: []
 stories: stories/TextareaField/TextareaField.stories.tsx
 version: "1.0"
@@ -13,107 +11,101 @@ version: "1.0"
 
 ## Назначение
 
-Многострочное текстовое поле: тонкая обёртка над `TextFieldBase`,
-вставляющая `FormFieldTextarea` вместо `FormFieldInput`. Получает все
-возможности `TextFieldBase` (label, description, prefix/postfix, counter,
-ошибки, клонирование пропсов через FormField).
+Компонент многострочного текстового ввода — то же поле, что `TextField`, но вместо `<input>` внутри используется `FormFieldTextarea` (`<textarea>`): плавающий лейбл, префикс/постфикс, описание и счётчик символов в одном компоненте. Композиция над семейством `FormField` (`FormGroup` → `FormField` → `FormFieldTextarea` + `FormFieldLabel`/`FormFieldPrefix`/`FormFieldPostfix`/`FormFieldDescription`/`FormFieldCounter`).
 
-Используй когда: нужен большой ввод (комментарий, обращение, описание).
-Для однострочного ввода — `TextField`.
+Используй когда: значение — свободный текст, который может занимать несколько строк: комментарий, назначение платежа, описание, обращение в поддержку. Обычно вместе с лимитом длины (`textareaProps.maxLength`) и счётчиком в `counter`.
 
----
-
-## Файловая структура
-
-```text
-src/components/TextareaField/
-├── TextareaField.tsx     # FC<ITextareaFieldProps>; <TextFieldBase><FormFieldTextarea/></TextFieldBase>
-├── types.ts              # ITextareaFieldProps
-├── __tests__/
-└── index.ts
-```
+Не используй когда: значение однострочное (`TextField`), имеет фиксированный формат (`MaskedField`), это денежная сумма (`AmountField`), дата (`DateField`) или месяц (`MonthYearField`), нужен выбор из подсказок (`SuggestField`).
 
 ---
 
-## Публичный API
+## Варианты и props
 
-### `ITextareaFieldProps`
+`TextareaField` — тонкая обёртка без собственного state: `textareaProps` уходит в `FormFieldTextarea`, остальные props — в `TextFieldBase` (и далее в `FormField`). Логика поля (генерация `id`, отслеживание фокуса и заполненности, реакция на автозаполнение) живёт в `FormFieldTextarea`.
 
-```ts
-extends Omit<ITextFieldBaseProps, "children">
-{
-    textareaProps: IFormFieldTextareaProps & DataAttributes & RefAttributes<HTMLTextAreaElement>;
-}
-```
+### Обязательные props
 
 | Prop | Тип | Описание |
 |---|---|---|
-| `textareaProps` | `IFormFieldTextareaProps & DataAttributes & RefAttributes<HTMLTextAreaElement>` | **Обязателен**. Прокидывается на `FormFieldTextarea`. Включая `ref` на textarea. |
-| `label?` | `ReactNode` | Лейбл (`FormFieldLabel`). От `TextFieldBase`. |
-| `description?` | `ReactNode` | Описание / ошибка (`FormFieldDescription`). |
-| `counter?` | `ReactNode` | Счётчик символов (`FormFieldCounter`), внутри description. |
-| `prefix?` / `postfix?` | `ReactNode` | Префикс/постфикс (`FormFieldPrefix`/`FormFieldPostfix`). |
-| `...IFormFieldProps` | — | Все props `FormField` (size, status, disabled, focused и т.д.). |
+| `textareaProps` | `IFormFieldTextareaProps & DataAttributes & React.RefAttributes<HTMLTextAreaElement>` | Свойства `<textarea>`: стандартные атрибуты, **кроме `disabled`** (`value`, `onChange`, `placeholder`, `maxLength`, `rows`, `name`, `required`…), data-атрибуты и `ref` на сам элемент `<textarea>`. Блокировка задаётся через `status={EFormFieldStatus.DISABLED}`, см. «Особенности поведения». Может быть пустым объектом. |
 
-`IFormFieldProps` приходит из `FormField` (см. FormField-AI.md, если существует).
+### Опциональные props
 
----
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `size` | `EComponentSize` | `LG` | Размер поля: SM / MD / LG. Задаёт шрифт, отступы и `min-height` области ввода. |
+| `status` | `EFormFieldStatus` | `DEFAULT` | Статус: default / error / warning / disabled. `DISABLED` автоматически ставит `disabled` на `<textarea>`. |
+| `active` | `boolean` | `false` | Принудительно активное (focused) визуальное состояние рамки. |
+| `label` | `ReactNode` | — | Плавающий лейбл; связывается с `<textarea>` через `htmlFor`. |
+| `prefix` | `ReactNode` | — | Контент слева от поля, рендерится в `FormFieldPrefix`. |
+| `postfix` | `ReactNode` | — | Контент справа от поля (`FormFieldClear`, `HelpBox`, иконка), рендерится в `FormFieldPostfix`. |
+| `description` | `ReactNode` | — | Описание под полем (`FormFieldDescription`). |
+| `counter` | `ReactNode` | — | Счётчик символов справа под полем (`FormFieldCounter`). Блок описания рендерится, если задан `description` ИЛИ `counter`. |
 
-## Структура DOM
+Остальные неперечисленные props (`className`, data-атрибуты, div-атрибуты) пробрасываются на корневой `FormField` (div).
 
-```tsx
-<FormGroup>
-    <FormField {...formFieldProps}>
-        {prefix && <FormFieldPrefix>{prefix}</FormFieldPrefix>}
-        <FormFieldTextarea {...textareaProps} />
-        {label && <FormFieldLabel>{label}</FormFieldLabel>}
-        {postfix && <FormFieldPostfix>{postfix}</FormFieldPostfix>}
-    </FormField>
-    {(description || counter) && (
-        <FormFieldDescription>
-            {description}
-            {counter && <FormFieldCounter>{counter}</FormFieldCounter>}
-        </FormFieldDescription>
-    )}
-</FormGroup>
-```
+### Особенности поведения
 
-Реализация полностью наследуется от `TextFieldBase` — изменения в нём
-автоматически распространяются на `TextareaField`.
+- **Поле не растёт по содержимому.** У `<textarea>` выставлен `resize: none`, автоувеличения высоты нет — размер области ввода задаёт только `size` (`min-height` 64px для SM, 60px для MD и LG). Увеличить высоту можно через `textareaProps.rows`; уменьшить — только своим классом на `textareaProps.className`, переопределив `min-height` с достаточной специфичностью (правило задано селектором `.formFieldTextarea.lg`).
+- **`disabled` задаётся только через `status`.** `FormFieldTextarea` выставляет `disabled={status === EFormFieldStatus.DISABLED}` после спреда остальных props, поэтому передать `disabled` в `textareaProps` нельзя — атрибут исключён из `IFormFieldTextareaProps` через `Omit`, и попытка его передать будет ошибкой компиляции. Для блокировки поля используй `status={EFormFieldStatus.DISABLED}`.
+- **`placeholder` виден только в активном состоянии.** Пока поле не активно (нет фокуса и не передан `active`), плейсхолдер скрыт (`opacity: 0`) — его место занимает опущенный `label`. Когда поле становится активным, лейбл уезжает наверх и плейсхолдер проявляется. Поэтому плейсхолдер не заменяет лейбл: если `label` не задан, у пустого неактивного поля не будет видимой подписи.
+- **Поле работает и контролируемым, и неконтролируемым.** Состояние «заполнено» (от него зависит положение лейбла) синхронизируется на маунте из `value ?? defaultValue`, далее — из `value` для контролируемого поля и из событий `change`/`focus`/`blur` для неконтролируемого.
+- **Автозаполнение браузером отслеживается** через CSS-хуки `animationstart` (`autofill-applied-hook` / `autofill-cancelled-hook`), поэтому лейбл поднимается и при подстановке значения браузером. Свой `textareaProps.onAnimationStart` при этом вызывается.
+- **Счётчик не встроен**: `maxLength` передаётся в `textareaProps`, а текст счётчика (`{value.length}/{maxLength}`) считает и рендерит потребитель в `counter`.
+- Кнопка очистки не встроена — передаётся потребителем как `postfix={<FormFieldClear onClick={...} />}`. Блок постфикса позиционируется по центру поля по вертикали (`top: 50%` + `translateY(-50%)` в `FormFieldPostfix`), что для многострочного поля обычно не то, что нужно: чтобы прижать содержимое к верху, оберни его в div с `alignSelf: "flex-start"` и отрицательным `marginTop`, зависящим от `size` (см. `ProductionExample.tsx` и `PlaygroundExample.tsx`).
+
+---
+
+## Дизайн-токены
+
+Собственных CSS-токенов и стилей у `TextareaField` нет — поэтому `tokens` во frontmatter пустой. Внешний вид наследуется от семейства `FormField`; сам `<textarea>` красится токенами `FormField.Input_Color_Default`, `FormField.Input_Color_Disabled` и `FormField.Placeholder_Color`.
 
 ---
 
 ## Инварианты
 
-- **`FC, не forwardRef`** — для ref'а на DIV-обёртку используется `TextFieldBase` (forwardRef'нутый), но `TextareaField` сам ref не пробрасывает на корневой элемент. Ref на `<textarea>` — через `textareaProps.ref`.
-- **`textareaProps` обязателен** (нет default'а).
-- **Label рендерится ПОСЛЕ children** в DOM — это требование `FormField` (для CSS-эффекта плавающего лейбла); порядок не менять.
-- **`description` и `counter` объединены в одну `FormFieldDescription`** — counter внутри `<FormFieldCounter>`. Не дублировать.
-- **Структура зашита** — нет children API. Для кастомного содержимого `FormField` использовать `TextFieldBase` напрямую.
+- `forwardRef` на `TextareaField` — не убирать. Внешний `ref` указывает на корневой `<div>` `FormField`, ref на сам `<textarea>` передаётся через `textareaProps.ref`.
+- Публичный API (`ITextareaFieldProps`: `textareaProps` + `label`/`prefix`/`postfix`/`description`/`counter` + унаследованные от `IFormFieldProps` `size`/`status`/`active`) — изменение имён/типов/значений enum — breaking change.
+- `textareaProps` обязателен: у поля нет дефолтных атрибутов ввода. Минимально допустимое значение — пустой объект `{}`.
+- Уникальный `id` для связки label↔textarea генерируется в `FormFieldTextarea` через `uniqueId("textarea_")` из `lodash-es` — не заменять на `useId` (React 17 совместимость через `release-0`).
+- Высота и отступы области ввода завязаны на `size` через классы `sm`/`md`/`lg` в `FormFieldTextarea.module.less` — эти имена читаются unit-тестом и не переименовываются в одиночку.
 
 ---
 
 ## Accessibility
 
-- `<textarea>` приходит из `FormFieldTextarea` — он отвечает за `id`, `aria-describedby`, `aria-invalid` и т.п.
-- `label` — `<label>` с правильным `htmlFor` от `FormField`/`FormFieldLabel`.
-- Ошибки — через `description` + `status` `FormField`'а.
+- Лейбл — настоящий `<label htmlFor>`, связанный с `id` поля (`id` генерируется автоматически или берётся из `textareaProps.id`).
+- `status={EFormFieldStatus.DISABLED}` выставляет нативный атрибут `disabled` — поле штатно выпадает из таб-обхода.
+- Семантика ошибки (`aria-invalid`, `aria-describedby` на `description`) не хардкодится — при необходимости потребитель передаёт атрибуты через `textareaProps`.
+- Плейсхолдер визуально скрыт до фокуса, но остаётся в DOM и читается скринридером. Смысловую подпись поля задавай через `label`, а не через `placeholder`.
+- Собственной клавиатурной логики нет: `Enter` вставляет перенос строки нативно, форма по `Enter` из `<textarea>` не отправляется.
+- Кнопке очистки в `postfix` доступное имя задаёт потребитель (`aria-label`) — библиотека мультиязычная и строк не хардкодит.
 
 ---
 
 ## Связанные компоненты
 
-- `TextField` — однострочный аналог.
-- `TextFieldBase` — общая база.
-- `FormFieldTextarea` — реальный `<textarea>` с обёрткой стилей.
-- `FormField` / `FormGroup` / `FormFieldLabel` / `FormFieldDescription` / `FormFieldCounter` / `FormFieldPrefix` / `FormFieldPostfix` — внутренние составляющие.
+- `TextFieldBase` (внутренний, не в barrel) — базовая раскладка `FormGroup`/`FormField` + слоты `prefix`/`children`/`label`/`postfix` и блок `description`/`counter`. Описан в `TextField-ai.md`.
+- `FormFieldTextarea` — сам элемент `<textarea>` со всей логикой поля. Используется напрямую, когда нужна нестандартная композиция.
+- `FormGroup` / `FormField` — контейнеры раскладки поля и описания.
+- `FormFieldClear` — кнопка очистки, передаётся в `postfix`.
+- `HelpBox` — подсказка в `postfix`.
+- `TextField`, `MaskedField`, `AmountField`, `SuggestField`, `DateField`, `MonthYearField` — специализированные поля той же группы `TextFields`.
 
 ---
 
 ## Stories
 
 Основные истории: `stories/TextareaField/TextareaField.stories.tsx`
-Примеры: `stories/TextareaField/examples/`
+Файлы примеров: `stories/TextareaField/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль size / status / label / active / textareaProps и переключатели постфикса, описания и счётчика |
+| `Default` | `DefaultExample.tsx` | Минимальное контролируемое поле с label и placeholder |
+| `Sizes` | `SizesExample.tsx` | Размеры SM / MD / LG |
+| `Statuses` | `StatusesExample.tsx` | Статусы default / error / warning / disabled |
+| `Production` | `ProductionExample.tsx` | Production-композиция (`Example: production`): лимит длины со счётчиком, кнопка очистки и `HelpBox` в постфиксе, description со ссылкой |
 
 ---
 
@@ -121,4 +113,220 @@ extends Omit<ITextFieldBaseProps, "children">
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-09-17 | Создан документ (TRI-96). AI-рефакторинг `TextareaField`: проброс `ref` на корневой `<div>` через `forwardRef`, `displayName`, unit-тесты вместо mock-заглушек |
+| 2026-09-17 | Ломающее изменение: `disabled` убран из `IFormFieldTextareaProps` (`Omit`), поэтому его больше нельзя передать в `textareaProps` — блокировка только через `status`. Правка по ревью PR #629, зафиксирована в release notes 1.47.0 |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/TextareaField/examples/DefaultExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { TextareaField, EComponentSize, EFormFieldStatus } from "@sberbusiness/triplex-next";
+
+export const DefaultExample = () => {
+    const [value, setValue] = useState("");
+
+    const handleTextareaChange: React.ChangeEventHandler<HTMLTextAreaElement> = (event) => {
+        setValue(event.target.value);
+    };
+
+    return (
+        <div style={{ maxWidth: 300 }}>
+            <TextareaField
+                size={EComponentSize.LG}
+                status={EFormFieldStatus.DEFAULT}
+                textareaProps={{
+                    value,
+                    placeholder: "Type to proceed",
+                    onChange: handleTextareaChange,
+                }}
+                label="Label"
+            />
+        </div>
+    );
+};
+```
+
+### Sizes
+
+`stories/TextareaField/examples/SizesExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { TextareaField, EComponentSize, EFormFieldStatus } from "@sberbusiness/triplex-next";
+
+interface ISizeItemProps {
+    size: EComponentSize;
+}
+
+const SizeItem = ({ size }: ISizeItemProps) => {
+    const [value, setValue] = useState("");
+
+    const handleTextareaChange: React.ChangeEventHandler<HTMLTextAreaElement> = (event) => {
+        setValue(event.target.value);
+    };
+
+    return (
+        <div style={{ maxWidth: 300 }}>
+            <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{size.toUpperCase()}</div>
+            <TextareaField
+                size={size}
+                status={EFormFieldStatus.DEFAULT}
+                textareaProps={{
+                    value,
+                    placeholder: "Type to proceed",
+                    onChange: handleTextareaChange,
+                }}
+                label="Label"
+            />
+        </div>
+    );
+};
+
+const SIZES = Object.values(EComponentSize);
+
+export const SizesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+        {SIZES.map((size) => (
+            <SizeItem key={size} size={size} />
+        ))}
+    </div>
+);
+```
+
+### Statuses
+
+`stories/TextareaField/examples/StatusesExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { TextareaField, EComponentSize, EFormFieldStatus } from "@sberbusiness/triplex-next";
+
+interface IStatusItemProps {
+    status: EFormFieldStatus;
+}
+
+const StatusItem = ({ status }: IStatusItemProps) => {
+    const [value, setValue] = useState("");
+
+    const handleTextareaChange: React.ChangeEventHandler<HTMLTextAreaElement> = (event) => {
+        setValue(event.target.value);
+    };
+
+    return (
+        <div style={{ maxWidth: 300 }}>
+            <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{status.toUpperCase()}</div>
+            <TextareaField
+                size={EComponentSize.LG}
+                status={status}
+                textareaProps={{
+                    value,
+                    placeholder: "Type to proceed",
+                    onChange: handleTextareaChange,
+                }}
+                label="Label"
+            />
+        </div>
+    );
+};
+
+const STATUSES = Object.values(EFormFieldStatus);
+
+export const StatusesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+        {STATUSES.map((status) => (
+            <StatusItem key={status} status={status} />
+        ))}
+    </div>
+);
+```
+
+### Production
+
+`stories/TextareaField/examples/ProductionExample.tsx`
+
+```tsx
+import React, { useState, useRef } from "react";
+import {
+    TextareaField,
+    FormFieldClear,
+    Text,
+    HelpBox,
+    Link,
+    EComponentSize,
+    EFormFieldStatus,
+    ETextSize,
+    EFontType,
+    ETooltipSize,
+} from "@sberbusiness/triplex-next";
+
+const postfixStyles: React.CSSProperties = {
+    alignSelf: "flex-start",
+    marginTop: -4, // 20px from top
+    display: "flex",
+    alignItems: "center",
+    gap: 8,
+};
+
+const MAX_LENGTH = 201;
+
+export const ProductionExample = () => {
+    const [value, setValue] = useState("");
+    const textareaRef = useRef<HTMLTextAreaElement>(null);
+
+    const handleTextareaChange: React.ChangeEventHandler<HTMLTextAreaElement> = (event) => {
+        setValue(event.target.value);
+    };
+
+    const handleClearButtonClick: React.MouseEventHandler<HTMLButtonElement> = () => {
+        setValue("");
+        textareaRef.current?.focus();
+    };
+
+    const handleLinkClick: React.MouseEventHandler<HTMLAnchorElement> = (event) => {
+        event.preventDefault();
+    };
+
+    return (
+        <div style={{ maxWidth: 300 }}>
+            <TextareaField
+                size={EComponentSize.LG}
+                status={EFormFieldStatus.DEFAULT}
+                textareaProps={{
+                    value,
+                    placeholder: "Type to proceed",
+                    maxLength: MAX_LENGTH,
+                    onChange: handleTextareaChange,
+                    ref: textareaRef,
+                }}
+                label="Label"
+                postfix={
+                    <div style={postfixStyles}>
+                        <FormFieldClear aria-label="clear value" onClick={handleClearButtonClick} />
+                        <HelpBox tooltipSize={ETooltipSize.SM}>Helpful details appear here</HelpBox>
+                    </div>
+                }
+                description={
+                    <Text size={ETextSize.B4} type={EFontType.SECONDARY}>
+                        (21) Description{" "}
+                        <Link href="#" onClick={handleLinkClick}>
+                            Link text
+                        </Link>
+                    </Text>
+                }
+                counter={
+                    <Text size={ETextSize.B4} type={EFontType.SECONDARY}>
+                        {value.length}/{MAX_LENGTH}
+                    </Text>
+                }
+            />
+        </div>
+    );
+};
+```
+

package/bundle/components/TopOverlay.md

@@ -110,7 +110,10 @@ Runtime CSS-переменная (задаётся компонентом чер
 
 Кроме токена компонент читает служебные CSS-переменные `LightBox`:
 `--lightBox-screen-top` (в TS, для позиционирования), `--lightBox-screen-left` и
-`--lightBox-screen-width` (в LESS, для растяжки маски по экрану лайтбокса).
+`--lightBox-screen-width` (в LESS, для растяжки маски по экрану лайтбокса),
+`--lightBox-content-padding-x` (боковые отступы контента лайтбокса — их повторяет
+обёртка панели) и `--lightBox-content-max-width` (потолок ширины колонки страницы —
+его повторяет сама панель).
 
 ---
 
@@ -135,6 +138,18 @@ Runtime CSS-переменная (задаётся компонентом чер
 - Props потребителя во вложенный `Overlay` не уходят: `className` и `direction`
   задаются ему явно, а `ref`, `className`, `style` и DOM-атрибуты остаются на
   обёртке. Спреда `restProps` в `Overlay` больше нет — не возвращать.
+- Ширина панели рассчитана на то, что ближайший позиционированный предок обёртки —
+  `.lightBoxContent` (`LightBox.Content`): от него берутся боковые отступы
+  (`--lightBox-content-padding-x`). Потолок ширины (`--lightBox-content-max-width`)
+  приходит наследованием с корневого `.lightBox`, где он и объявлен. Внутри другого
+  позиционированного контейнера отступы отсчитаются от него и панель уедет.
+  Вне `LightBox` обе переменные не определены: отступы дают фолбэк 0, а `max-width`
+  схлопывается в `none`, то есть ширину панель занимает всю. Боковые паддинги 32px
+  и авто-маргины при этом остаются — содержимое отступает от краёв панели.
+- Внутри `LightBox.SideOverlay` панель по колонке `Page` **не** выравнивается: сайд-оверлей
+  задаёт странице свою ширину (`@sideOverlay{SM,MD,LG}Width`), а панель ограничена шириной
+  колонки лайтбокса. Расхождение маскирует `Confirm` с `parentComponent`; для произвольного
+  содержимого его нужно ограничивать самому.
 - Родительскому `LightBox` потребитель обязан передать `isTopOverlayOpened` —
   иначе контролы лайтбокса не приглушатся под открытой панелью.
 - Классы `.topOverlayMask`, `.topOverlayPanel`, `.topOverlayWrapper` и `.topOverlay`
@@ -202,6 +217,7 @@ Runtime CSS-переменная (задаётся компонентом чер
 
 | Дата | Изменение |
 |---|---|
+| 2026-09-21 | Панель выровнена по колонке контента `LightBox`: обёртка сводится к колонке через `--lightBox-content-padding-x`, панель повторяет `--lightBox-content-max-width` и боковые паддинги `Page`. |
 | 2026-08-27 | `TopOverlay` переведён на `forwardRef`, `ITopOverlayProps` расширен атрибутами `<div>`: `ref`, `className`, `style` и DOM-атрибуты адресуют обёртку. Монтирование сразу с `opened={true}` запускает цикл открытия (ловушка фокуса, `onOpen`) — исправлено в `OverlayBase`, см. `Overlay-ai.md`; пересчёт позиции на маунте намеренно не делается. Рассчитанная позиция переехала из inline-`top` в runtime-переменную `--triplex-next-runtime-TopOverlay-Top`. |
 | 2026-08-25 | Создан документ. AI-рефакторинг: позиционирование вынесено в `utils.ts`, добавлен `displayName`, unit-тесты на расчёт позиции и ловушку фокуса; добавлены stories `stories/TopOverlay/` |
 

package/bundle/components/TreeView.md

@@ -32,12 +32,14 @@ JSX-разметке, управление `tabIndex` и перемещение
 
 ### `TreeView`
 
-Class-компонент. Собственных props, кроме `children`, нет — остальное это
-стандартные атрибуты `<ul>`.
+`forwardRef`-обёртка над внутренним class-компонентом `TreeViewBase`.
+Собственных props, кроме `children`, нет — остальное это стандартные атрибуты
+`<ul>`.
 
 | Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
 | `children` | `React.ReactNode` | — | Ноды дерева: `TreeView.Node` напрямую или компоненты-обёртки над ним |
+| `ref` | `React.Ref<HTMLUListElement>` | — | Указывает на корневой `<ul role="tree">` |
 | `...HTMLUListElementAttributes` | — | — | Все стандартные атрибуты `<ul>`; `className` мерджится с собственным классом |
 
 Статические свойства: `TreeView.Node` (= `TreeViewNode`),
@@ -68,13 +70,19 @@ render-prop `children` с пятью provide-props, контракт по `focus
 
 ## Инварианты
 
-- **`TreeView` и `TreeViewNodeWithContext` — class-компоненты.** Это legacy,
-  зафиксированный публичным API: `ref` на `TreeView` отдаёт инстанс класса.
-  Перевод на функциональные компоненты и добавление `forwardRef` — breaking
-  change поведения `ref`. Не мигрировать без отдельного решения мейнтейнера.
+- **`ref` на `TreeView` отдаёт корневой `<ul role="tree">`.** Наружу компонент
+  экспортируется как `React.ForwardRefExoticComponent`: реализация осталась
+  классом `TreeViewBase`, а публичный `TreeView` — обёртка `forwardRef`, которая
+  передаёт внешний `ref` в класс свойством `forwardedRef`. Класс нельзя обернуть
+  `forwardRef` напрямую, отсюда и эта прослойка. До 1.47.0 `ref` отдавал инстанс
+  класса — см. release notes 1.47.0.
+- **`TreeViewBase` и `TreeViewNodeWithContext` — class-компоненты.** Это legacy;
+  перевод на функциональные компоненты не делается без отдельного решения
+  мейнтейнера. `TreeViewBase` наружу не экспортируется.
 - **Barrel `src/components/TreeView/index.ts`** реэкспортирует модули семейства
   целиком (`export * from ...`), поэтому публично всё, что они экспортируют:
-  `TreeView` и `ITreeViewProps`, `TreeViewGroup` и `ITreeViewGroupProps`, а от
+  `TreeView`, `ITreeViewProps` и `ITreeViewFC`, `TreeViewGroup` и
+  `ITreeViewGroupProps`, а от
   ноды — состав, перечисленный в
   [TreeViewNode-ai.md](./TreeViewNode-ai.md) (там же и класс
   `TreeViewNodeWithContext`). Состав и имена менять нельзя — от них зависят
@@ -163,6 +171,7 @@ render-prop `children` с пятью provide-props, контракт по `focus
 
 | Дата | Изменение |
 |---|---|
+| 2026-09-17 | TRI-22: `ref` на `TreeView` переведён с инстанса класса на корневой `<ul>`; реализация вынесена во внутренний `TreeViewBase`, наружу экспортируется обёртка `forwardRef` со статикой `Node` / `Group` |
 | 2026-08-26 | Описание `TreeView.Node` вынесено в отдельный `TreeViewNode-ai.md`, здесь оставлена ссылка |
 | 2026-08-25 | Слушатель `keydown` подписан только пока в дереве есть активная нода: после ухода фокуса из дерева стрелки снова достаются странице. `role` и `aria-expanded` перенесены после `{...props}` — потребитель больше не может их переопределить |
 | 2026-08-24 | `ArrowUp` с первой ноды дерева больше не заходит внутрь свёрнутой последней ветки — активной становится последняя видимая нода (`TreeViewAbstractNodeUtils.getPrevNode`) |