@sberbusiness/triplex-next-mcp-server 0.24.0-beta1

package/bundle/components/Dropdown.md

@@ -0,0 +1,433 @@
+---
+component: Dropdown
+category: Overlays
+figma-node: ""
+figma-file: ""
+related: [DropdownList, DropdownListItem, Portal, OverlayBase, MobileView, SelectField, Suggest, DatePickerExtended]
+tokens: [Dropdown_Background, DropdownList_*, DropdownMobile_*, DropdownMobileList_*]
+stories: stories/Dropdown/Dropdown.stories.tsx
+version: "1.0"
+---
+
+# Dropdown
+
+## Назначение
+
+Основной overlay-компонент библиотеки для выпадающих меню. Renders в
+`Portal` на `document.body`, **автоматически разветвляется**:
+- **Desktop (`DropdownDesktop`)** — абсолютно позиционированный блок
+  рядом с `targetRef` (top/bottom auto-flip, left/right alignment,
+  ширина content/target/min-target), слушает window resize, document
+  scroll и ResizeObserver для reposition; блокирует внешний скролл
+  и клавиатурные события при открытии.
+- **Mobile (`DropdownMobile`)** — полноэкранный bottom-overlay
+  (`OverlayBase direction=BOTTOM`), с композицией
+  `Header`/`Body`/`Footer`/`Close`.
+
+Имеет внутренние compound-структуры:
+- **`DropdownList`** + `DropdownList.Item` — список с клавиатурной
+  навигацией (↑/↓, scroll-into-view, active-descendant через
+  `DropdownListContext`).
+- **`DropdownMobileList`** + `DropdownMobileListItem` — аналог для
+  мобильной ветки.
+- **`DropdownMobileInput` / `DropdownMobileMaskedInput`** —
+  специальные input'ы в header'е мобильного Dropdown'а.
+
+Используй когда: строишь любой выпадающий UI (Select, Suggest, Menu,
+DatePicker, custom dropdown). **В большинстве случаев** бери готовую
+обёртку (`SelectField`, `Suggest`, `DatePickerExtended`) — Dropdown
+прямо в UI встречается реже.
+Не используй как: абсолютный "tooltip" — бери `Tooltip`; bottom sheet
+без target'а — `OverlayBase`/`SideOverlay`; модалку — `LightBox`/
+`ModalWindow`.
+
+---
+
+## Файловая структура
+
+```text
+src/components/Dropdown/
+├── Dropdown.tsx                            # forwardRef, разветвление MobileView
+├── DropdownListContext.ts                  # Context { activeDescendant, setActiveDescendant }
+├── index.ts                                # Barrel
+├── desktop/
+│   ├── DropdownDesktop.tsx                 # forwardRef, positioning + scroll-block
+│   ├── DropdownList.tsx                    # FC, клавиатурная навигация, role="listbox"
+│   ├── DropdownListItem.tsx                # ListItem (role="option", active, selected)
+│   ├── enums.ts                            # EDropdownDirection/Alignment/Width
+│   └── index.ts
+├── mobile/
+│   ├── DropdownMobile.tsx                  # forwardRef, OverlayBase wrapper
+│   ├── DropdownMobileInner.tsx             # Внутренняя разметка (animation, overflow)
+│   ├── DropdownMobileHeader.tsx            # Header с title/controlButtons
+│   ├── DropdownMobileBody.tsx              # Scrollable body
+│   ├── DropdownMobileFooter.tsx            # Footer (sticky)
+│   ├── DropdownMobileClose.tsx             # Кнопка закрытия
+│   ├── DropdownMobileList.tsx              # List для мобильного
+│   ├── DropdownMobileListItem.tsx          # Item для мобильного
+│   ├── DropdownMobileInput.tsx             # Input в header
+│   ├── DropdownMobileMaskedInput.tsx       # MaskedInput в header
+│   ├── DropdownMobileLoader.tsx            # Loader
+│   └── index.ts
+└── styles/
+    ├── DropdownDesktop.module.less
+    ├── DropdownDesktopList.module.less
+    ├── DropdownMobile.module.less
+    ├── DropdownMobileInput.module.less
+    └── DropdownMobileMaskedInput.module.less
+```
+
+Особенности:
+- **Portal → `document.body`** — всегда, независимо от desktop/mobile.
+- **Два параллельных дерева подкомпонентов** (desktop + mobile) с
+  похожими именами, но разными props и поведением.
+- **`data-tx`** на desktop и mobile root.
+- **`useToken().scopeClassName`** на DropdownDesktop — получает
+  namespace для CSS-переменных из ThemeProvider.
+
+---
+
+## Варианты и props
+
+### Root: `IDropdownProps extends IDropdownDesktopProps`
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `opened` | `boolean` | Открыт/закрыт. Controlled. |
+| `setOpened` | `(opened: boolean) => void` | Сеттер, вызываемый из outside-click / mobile close. |
+| `targetRef` | `RefObject<HTMLElement>` | Target для позиционирования (desktop) / точка привязки жеста. |
+| `size` | `EComponentSize` | `MD` default. |
+| `direction` | `EDropdownDirection` | `AUTO` \| `BOTTOM` \| `TOP` — desktop. |
+| `alignment` | `EDropdownAlignment` | `LEFT` \| `RIGHT` — desktop. |
+| `width` | `EDropdownWidth` | `CONTENT` \| `TARGET` \| `MIN_TARGET` — desktop. |
+| `onOpen` | `() => void` | Callback при открытии (после mount). |
+| `onClose` | `() => void` | Callback при закрытии. |
+| `mobileViewProps` | `Omit<IDropdownMobileProps, "opened" \| "setOpened">` | **Если задан** — на мобильном открывается полноэкранный DropdownMobile. Если не задан — на мобильном тот же desktop-дропдаун. |
+| `...HTMLDivAttributes` | — | — |
+
+### `DropdownDesktop` props (также все → root Dropdown)
+
+Все выше + `style`, `className`, `...HTMLDivAttributes`.
+
+### `DropdownMobile` props (через `mobileViewProps`)
+
+- `children` (может быть разный от desktop).
+- `className`.
+- `...HTMLDivAttributes`.
+- (opened, setOpened форвардятся из Dropdown.)
+
+### `DropdownList` compound
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `dropdownOpened` | `boolean` | — | Необходим для подписки на keydown только когда открыто. |
+| `listRef` | `RefObject<HTMLDivElement>` | — | Ссылка на скролл-контейнер. |
+| `loading` | `boolean` | — | Добавляет loader-item в конец списка. |
+| `size` | `EComponentSize` | `MD` | Влияет на классы. |
+| `children` | `DropdownList.Item` | — | Только Item'ы. |
+
+Статик: `DropdownList.Item = DropdownListItem`.
+
+### Enums
+
+**`EDropdownDirection`:**
+- `AUTO = "auto"` — сначала пытается снизу, если не влезает — сверху, иначе снизу.
+- `BOTTOM = "bottom"` — принудительно снизу.
+- `TOP = "top"` — принудительно сверху.
+
+**`EDropdownAlignment`:**
+- `LEFT = "left"` — левая граница dropdown'а = левая target'а.
+- `RIGHT = "right"` — правая граница dropdown'а = правая target'а.
+
+**`EDropdownWidth`:**
+- `CONTENT = "content"` — по ширине контента.
+- `TARGET = "target"` — `width = targetRect.width`.
+- `MIN_TARGET = "min-target"` — `minWidth = targetRect.width`.
+
+---
+
+## Ключевые особенности реализации
+
+### Portal → document.body
+
+```tsx
+<Portal container={document.body}>...</Portal>
+```
+
+Dropdown всегда рендерится в `body`, чтобы не зависеть от `overflow:hidden`
+родителей и z-index-стеков. Минус: вычисление позиции в window-координатах,
+а не относительно родителя.
+
+### MobileView разветвление — только при `mobileViewProps`
+
+```tsx
+{mobileViewProps ? (
+    <MobileView fallback={<DropdownDesktop .../>}>
+        <DropdownMobile>{mobileViewProps?.children || children}</DropdownMobile>
+    </MobileView>
+) : (
+    <DropdownDesktop>{children}</DropdownDesktop>
+)}
+```
+
+**Если `mobileViewProps` не передан — даже на мобильном будет
+DropdownDesktop.** Это разумно для меню (просто маленький dropdown),
+но для полноэкранных селектов требуется явный `mobileViewProps`.
+
+### Desktop: позиционирование через `getBoundingClientRect`
+
+```ts
+const setPosition = useCallback(() => {
+    const dropdownRect = dropdownRef.current.getBoundingClientRect();
+    const targetRect = targetRef.current.getBoundingClientRect();
+    // ...
+    setStyleState(css); // { top/bottom, left, width?, minWidth? }
+}, [...]);
+```
+
+**`direction=AUTO`:** сначала пробует low (bottom), если не влезает
+→ top, если тоже не влезает → bottom (скролл). 4px offset между
+target и dropdown (`offset = 4`).
+
+**`alignment=LEFT`:** dropdown.left = target.left, если влезает вправо;
+иначе target.right - dropdown.width (с `Math.max(0, ...)`).
+**`alignment=RIGHT`:** зеркально.
+
+### Desktop: блокировка скролла и клавиш при открытии
+
+```ts
+document.addEventListener("wheel", wheelHandler, { passive: false });
+document.addEventListener("keydown", keyDownHandler);
+document.body.classList.add(overflowHiddenClassName);
+```
+
+- **`wheelHandler`:** preventDefault колеса, если target не внутри
+  dropdown'а. Эффект: страница не скроллится, но dropdown (если в нём
+  есть scroll) — скроллится.
+- **`keyDownHandler`:** preventDefault на Space/PageUp/PageDown/End/Home/
+  Arrows, **но только если `event.target === document.body`**. Это
+  защита от "прыжка страницы", когда ни одно поле не сфокусировано.
+  Если фокус в input'е — клавиши работают нормально.
+- **`body.classList.add(overflowHiddenClassName)`:** визуально
+  "замораживает" страницу.
+
+**Эффект отписки:** `removeEventListener` + `classList.remove` —
+обязательны. Memory leak и залипший overflow без них.
+
+### Desktop: ResizeObserver + scroll/resize listeners
+
+```ts
+const observer = new ResizeObserver(setPosition);
+observer.observe(dropdownRef.current);
+observer.observe(targetRef.current);
+// + document.addEventListener("scroll", updatePosition, true);
+// + window.addEventListener("resize", updatePosition);
+```
+
+**Три источника изменений:**
+1. **ResizeObserver** — dropdown или target изменили размер (загрузка
+   данных).
+2. **`scroll` с `capture=true`** — любой предок target'а скроллится
+   → dropdown должен следовать.
+3. **`resize`** — окно поменяло размер.
+
+`updatePosition = () => setTimeout(setPosition)` — пересчёт в следующем
+кадре, чтобы дать браузеру layout'нуть.
+
+### Desktop: `{opacity: 0}` при закрытии
+
+Первый рендер — `{opacity: 0}`, пока `setPosition` не отработал.
+После первого layout — setStyleState с рассчитанными top/left/width.
+Это **анти-flicker трюк**: если dropdown-ом монтируется и **рендерится
+первым кадром в (0, 0)**, юзер увидит скачок. `opacity: 0` скрывает
+эту микросекунду.
+
+### Desktop: `if (!opened) return null`
+
+При закрытии компонент **размонтируется**. Это важно:
+- Не платим за event listeners при закрытом dropdown'е.
+- Каждое открытие — новый цикл позиционирования.
+- **Потеря внутреннего state** (scroll position, focus) при закрытии.
+
+### Desktop: `useToken().scopeClassName`
+
+```ts
+const { scopeClassName } = useToken();
+const classNames = clsx(styles.dropdownDesktop, sizeToClassNameMap[size], scopeClassName, className);
+```
+
+**`scopeClassName` нужен**, потому что `Portal` выносит dropdown в
+`body`, и ThemeProvider-scope родителя пропадает. `scopeClassName`
+возвращает класс, под которым активна текущая тема, — dropdown его
+тянет явно.
+
+**Без этого** dropdown получит дефолтную (светлую) тему,
+независимо от того, что родитель в `<ThemeProvider theme="dark">`.
+
+### Dropdown.onOpen/onClose — effect с `mountedRef`
+
+```ts
+const mountedRef = useRef(false);
+useEffect(() => {
+    if (!mountedRef.current) {
+        mountedRef.current = true;
+    } else if (opened) {
+        onOpen?.();
+    } else {
+        onClose?.();
+    }
+}, [opened]);
+```
+
+**Пропуск первого вызова** (initial mount) — чтобы `onOpen`/`onClose`
+срабатывали только на **реальное** переключение, а не на initial
+`opened=false`. Если удалить `mountedRef` — `onClose` вызовется сразу
+после mount.
+
+### DropdownList: keyboard navigation + activeDescendant
+
+```ts
+// Esc/Arrows на document, preventDefault:
+if (keyCode === ARROW_DOWN) nextIndex = (currentIndex + 1) % childrenLength;
+if (keyCode === ARROW_UP) nextIndex = (currentIndex - 1 + childrenLength) % childrenLength;
+```
+
+**Wrap-around** — стрелки зацикливают навигацию (вниз с последнего →
+на первый, вверх с первого → на последний).
+
+**`scrollContainerToItem(nextIndex)`** — виртуально-скроллит контейнер,
+чтобы активный элемент был в видимой области, с 4px offset.
+
+**`DropdownListContext.setActiveDescendant(id)`** — контекст для
+target'а (input/button), который использует `aria-activedescendant=id`
+для screen reader'ов. Target вне `DropdownList`, но в родительском
+контексте.
+
+**Initial active:** при открытии — ищет первый `selected` child
+(`child.props.selected === true`), если не найдено — ставит active=0.
+Скроллит в начало при отсутствии selected.
+
+### DropdownList: cloneElement + MouseOver/MouseOut
+
+Каждый child клонируется с `active={activeListItemIndex === index}` +
+`onMouseOver/Out` переопределены — move mouse на item тоже меняет
+активный.
+
+**Dual navigation:** клавиатура и мышь вместе работают. Движение
+мыши "отбрасывает" клавиатурный активный индекс и синхронизирует с
+местом курсора.
+
+### Mobile: OverlayBase + body-overflow block
+
+```tsx
+<OverlayBase setOpened={setOpened} opened={opened} direction={EOverlayDirection.BOTTOM}>
+    {(props) => <DropdownMobileInner {...props} ... />}
+</OverlayBase>
+```
+
+**OverlayBase** — базовый "шторка" оверлей с анимацией bottom-up,
+swipe-to-close и overlay-backdrop. DropdownMobile — лишь стайлинг
+поверх.
+
+**`document.body.classList.add(dropdownMobileBodyOverflowClassName)`**
+— блокирует скролл body, пока открыт мобильный dropdown.
+
+### `data-tx={process.env.npm_package_version}` — на desktop и mobile root
+
+Стандарт. Оба разветвления ставят `data-tx`. Не удалять.
+
+---
+
+## Инварианты
+
+- **`opened` + `setOpened`** — обязательная пара (controlled).
+- **`targetRef` обязателен** — без него desktop не может позиционироваться.
+  Если target недоступен — dropdown не откроется корректно.
+- **Portal → document.body всегда** — не менять на inline.
+- **`scopeClassName` из `useToken()`** — обязателен на DropdownDesktop.
+  Без него Portal-теряет контекст темы.
+- **Desktop `if (!opened) return null`** — компонент размонтируется,
+  не скрывается через CSS. Не менять.
+- **`data-tx`** на desktop и mobile root.
+- **`mobileViewProps` — необязательный**. Если не задан — мобильная
+  версия использует DropdownDesktop.
+- **`DropdownList.Item`** — единственный допустимый child (технически
+  клонирование игнорирует не-ReactElement'ы, но API об этом).
+- **Wrap-around navigation в DropdownList** — поведение, не менять.
+- **`mountedRef` в Dropdown.tsx** — skip first effect fire, не удалять.
+- **`wheelHandler` с `passive: false`** — обязательно для preventDefault.
+- **`keyDownHandler` фильтрует по `event.target === document.body`** —
+  не preventDefault'ить клавиши в input'ах.
+- **`overflowHiddenClassName` add/remove на body** — аккуратно
+  отписываться.
+- **Selected→active логика при открытии DropdownList** — работает
+  как "scroll to selected". Не сломать.
+
+---
+
+## Accessibility
+
+- **`role="listbox"`** на DropdownList; `role="option"` на DropdownListItem
+  (последнее в соответствующем компоненте).
+- **`aria-activedescendant`** — target (input/button) должен
+  выставлять его из `DropdownListContext.activeDescendant`. Screen
+  reader объявляет активный option.
+- **Клавиатура:**
+  - Esc — закрыть (обрабатывается потребителем, Dropdown сам не ловит).
+  - ↑/↓ — навигация по DropdownList.
+  - Enter — выбор (DropdownListItem сам обрабатывает).
+  - Tab — не работает внутри (DropdownList не в tab-order).
+- **Mobile:** OverlayBase + swipe-to-close. Focus-trap через OverlayBase.
+- **`role="dialog" aria-modal="true"`** — не проставляется автоматически,
+  потребитель может передать через `...rest` (как делает
+  `DatePickerExtendedDropdown`).
+- **Body-scroll lock** — предотвращает "прыжки" при скролле на
+  мобильных.
+
+---
+
+## Дизайн-токены
+
+Группы в `src/components/DesignTokens/components/`:
+- **`Dropdown.ts`** — `--triplex-next-Dropdown-Background` + border/shadow
+- **`DropdownList.ts`** — hover/active/selected для item'ов
+- **`DropdownMobile.ts`** — фон, border-radius, header/footer
+- **`DropdownMobileList.ts`** — item'ы в мобильной ветке
+
+---
+
+## Связанные компоненты
+
+- `Portal` (`src/components/Portal`) — рендер в body.
+- `MobileView` (`src/components/MobileView`) — разветвление.
+- `OverlayBase` (`src/components/Overlay`) — база для мобильного.
+- `useToken` / `ThemeProvider` — scopeClassName.
+- `DropdownList` / `DropdownListItem` — compound-список (desktop).
+- `DropdownMobile*` — mobile compound-семейство.
+- Основные обёртки: `SelectField`, `SelectExtendedField`, `Suggest`,
+  `SuggestField`, `DatePickerExtended`, `MultiselectField`.
+- `createSizeToClassNameMap` — утилита для size-класса.
+
+---
+
+## Stories
+
+`stories/Dropdown/Dropdown.stories.tsx`
+Примеры: `stories/Dropdown/examples/`
+
+Типовые stories:
+- `Default` — базовый открывающийся dropdown
+- `Directions` — auto/bottom/top
+- `Alignments` — left/right
+- `Widths` — content/target/min-target
+- `MobileView` — с `mobileViewProps`
+- `DropdownList` — список с item'ами
+- `Playground` — интерактив
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/Ellipsis.md

@@ -0,0 +1,208 @@
+---
+component: Ellipsis
+category: Typography
+figma-node: ""
+figma-file: ""
+related: [Typography, Tooltip, Spoiler]
+tokens: []
+stories: stories/Ellipsis/Ellipsis.stories.tsx
+version: "1.0"
+---
+
+# Ellipsis
+
+## Назначение
+
+Обрезает многострочный текст с **многоточием** после заданного числа
+строк (`maxLines`). Использует `-webkit-line-clamp` CSS — работает во
+всех современных браузерах (Chromium, Firefox, Safari).
+
+Управление числом строк — через CSS-переменную `--ellipsis-line-clamp`,
+устанавливаемую inline-style'ом. `maxLines=1` включает дополнительный
+класс `.oneLine` с `word-break: break-all` (чтобы длинное слово не
+оставляло пустую строку).
+
+Используй когда: у тебя блочный контейнер с текстом, который должен
+помещаться в фиксированное количество строк.
+Не используй когда: нужна интерактивность (развернуть/свернуть) — бери
+`Spoiler`; нужен tooltip с полным текстом — оборачивай в `Tooltip`.
+
+---
+
+## Файловая структура
+
+```text
+src/components/Ellipsis/
+├── Ellipsis.tsx                      # forwardRef<HTMLDivElement>
+├── index.ts                          # Barrel
+├── styles/Ellipsis.module.less       # -webkit-line-clamp через CSS-var
+└── __tests__/Ellipsis.test.tsx
+```
+
+Особенности:
+- **`forwardRef`** есть (в отличие от Col/Divider).
+- **`data-tx`** есть.
+- **Единственный проп помимо HTML attributes** — `maxLines`.
+- **Тесты** покрывают базовое поведение.
+
+---
+
+## Варианты и props
+
+### `IEllipsisProps extends React.HTMLAttributes<HTMLDivElement>`
+
+| Prop | Тип | Обязателен | Описание |
+|---|---|---|---|
+| `maxLines` | `number` | Да | Максимум строк. После `maxLines`-й строки — многоточие. |
+| `children` | `ReactNode` | — | Текст или inline-элементы. |
+| `className` | `string` | — | Через `clsx`. |
+| `...HTMLDivAttributes` | — | — | Стандартные. |
+
+**Нет дефолтного `maxLines`** — обязательный проп. Если передать 0
+или отрицательное — получишь пустой контейнер (браузер сочтёт 0-строк).
+
+---
+
+## Ключевые особенности реализации
+
+### `--ellipsis-line-clamp` CSS-переменная
+
+```tsx
+style={{ "--ellipsis-line-clamp": maxLines } as React.CSSProperties}
+```
+
+```less
+.ellipsisLineClamp {
+    --ellipsis-line-clamp: 1;
+    -webkit-line-clamp: var(--ellipsis-line-clamp);
+    line-clamp: var(--ellipsis-line-clamp);
+}
+```
+
+**Почему через var, не напрямую inline `WebkitLineClamp`:** чтобы дать
+потребителю возможность переопределить через CSS-scope
+(`.my-class { --ellipsis-line-clamp: 5; }`). Inline-style всегда
+побеждает media-query; переменная может быть перезаписана по
+breakpoint'у.
+
+**TypeScript-каст `as React.CSSProperties`** — CSSProperties не
+допускает custom properties без кастинга. Стандартный приём.
+
+**Fallback `--ellipsis-line-clamp: 1;`** в базовом классе — защита
+если по каким-то причинам inline var не подхватился.
+
+### `-webkit-line-clamp` требует специальной связки
+
+```less
+display: -webkit-box;
+-webkit-line-clamp: var(--ellipsis-line-clamp);
+-webkit-box-orient: vertical;
+overflow: hidden;
+```
+
+**Все четыре свойства обязательны.** Без `display: -webkit-box` +
+`-webkit-box-orient: vertical` — `-webkit-line-clamp` игнорируется.
+Без `overflow: hidden` — многоточия не будет.
+
+**`line-clamp` (без `-webkit-`)** — стандартное свойство, добавлено
+для будущей совместимости. На данный момент все браузеры всё ещё
+используют vendor-префикс, но standard работает в свежих версиях.
+
+### `white-space: normal` (не nowrap)
+
+```less
+white-space: normal;
+```
+
+**Важно:** стандартное `white-space: normal` гарантирует, что текст
+может переноситься на новые строки. Без этого `-webkit-line-clamp`
+не сработает — текст просто обрежется справа.
+
+### `word-break: break-word` vs `break-all` для `maxLines=1`
+
+```less
+word-break: break-word;  // default — разрывает только по слову/пробелу
+&.oneLine {
+    word-break: break-all;  // разрывает посреди слова
+}
+```
+
+**Для `maxLines=1`** — `break-all`. Причина: при одной строке,
+если слишком длинное слово, `break-word` оставит **пустую строку**
+перед словом (оно перенесётся целиком на следующую, но её нет).
+`break-all` гарантирует, что хоть часть слова влезет в одну строку,
+а остальное обрежется многоточием.
+
+Для `maxLines > 1` — `break-word` — красивее (слова не разрываются).
+
+### Компонент — `<div>`, не `<p>`
+
+Не рендерит semantic `<p>` или `<span>`. Потребитель может обернуть
+любой текст. Если нужна семантика — использовать `as` через прокидывание
+(не реализовано) или выбрать `Typography.Text` + обернуть в Ellipsis.
+
+---
+
+## Инварианты
+
+- **`maxLines` — обязательный проп**, без дефолта.
+- **Все 4 CSS-свойства** (`display`, `-webkit-line-clamp`, `-webkit-box-orient`,
+  `overflow: hidden`) — обязательны. Не удалять по отдельности.
+- **`--ellipsis-line-clamp` CSS-переменная** — источник значения. Inline
+  style задаёт, LESS читает. Не хардкодить `WebkitLineClamp`.
+- **`white-space: normal`** — обязателен. Не менять на `nowrap`.
+- **`word-break: break-all` только для `maxLines=1`** — класс `.oneLine`
+  добавляется именно при `=== 1`. Не применять для многострочных.
+- **`forwardRef`** — есть.
+- **`data-tx`** — есть, не удалять.
+- **Рендерит `<div>`** — не `<p>`/`<span>`, семантика на потребителе.
+
+---
+
+## Accessibility
+
+- **Screen reader получает полный текст** — только `overflow: hidden`
+  визуально, но DOM-текст доступен полностью. Screen reader читает всё.
+- **Если нужен alt/full-text на hover** — оборачивать в `Tooltip` с
+  полным текстом.
+- **Tab-навигация** — div не focusable по умолчанию. Если дети
+  interactive — они доступны обычно.
+- **Нет `title`-атрибута** — Ellipsis не проставляет. Потребитель
+  может передать через `...rest`.
+
+---
+
+## Дизайн-токены
+
+**Нет собственных.** Чисто CSS-техника обрезания.
+
+---
+
+## Связанные компоненты
+
+- `Typography.Text`/`Title` — типичные child'ы (задают шрифт/цвет).
+- `Tooltip` — частая обёртка для показа полного текста при hover'е.
+- `Spoiler` — альтернатива, когда нужна возможность "раскрыть"
+  обрезанный текст.
+
+---
+
+## Stories
+
+`stories/Ellipsis/Ellipsis.stories.tsx`
+Примеры: `stories/Ellipsis/examples/`
+
+Типовые stories:
+- `Default` — 1 строка
+- `MultipleLines` — 2, 3, 5 строк
+- `LongWord` — демонстрация `break-all` на одной строке
+- `WithTooltip` — комбинация с Tooltip для показа полного текста
+- `Playground` — интерактив
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |