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

package/bundle/components/LightBox.md

@@ -0,0 +1,322 @@
+---
+component: LightBox
+category: Overlays
+figma-node: ""
+figma-file: ""
+related: [ModalWindow, Overlay, TopOverlay, Portal, MobileView, FocusTrap]
+tokens:
+  - --lightBox-screen-left
+  - --lightBox-screen-width
+  - --lightBox-screen-top
+stories: stories/LightBox/LightBox.stories.tsx
+version: "1.0"
+---
+
+# LightBox
+
+## Назначение
+
+Полноэкранный модальный контейнер (лайтбокс) — занимает всю область окна
+с backdrop'ом и focus-trap'ом. Composite: Header-controls + Content +
+левая/правая sidebar-панели + выезжающий справа SideOverlay + TopOverlay.
+Рассчитан на "иммерсивные" сценарии (просмотр документа, мастер настройки,
+workflow-редактор).
+
+Используй когда: нужен полноэкранный режим с собственным scroll-container'ом,
+focus management и возможностью иметь вложенные overlay'и (sidebar,
+top-bar, боковая панель). Для стандартного диалога — `ModalWindow`.
+
+---
+
+## Файловая структура
+
+```text
+src/components/LightBox/
+├── LightBox.tsx                      # Основной компонент + Object.assign
+├── LightBoxContent.tsx               # Скроллируемый контент, paddingTop = высота controls
+├── enums.ts                          # ELightBoxSize (SM/MD/LG/XL)
+├── index.ts                          # Barrel (+ re-export SideOverlay, enums)
+├── LightBoxControls/
+│   ├── LightBoxControls.tsx          # Container с data-lightbox-component="controls"
+│   ├── LightBoxClose.tsx
+│   ├── LightBoxNext.tsx
+│   └── LightBoxPrev.tsx
+├── LightBoxSidebars/
+│   ├── LightBoxLeftSidebar.tsx       # forwardRef, ResizeObserver, show/hide по minVisibleWidth
+│   └── LightBoxRightSidebar.tsx
+├── LightBoxSideOverlay/
+│   ├── LightBoxSideOverlay.tsx       # Выезжающая справа панель (Overlay direction=RIGHT)
+│   ├── LightBoxSideOverlayCloseDesktop.tsx
+│   ├── LightBoxSideOverlayCloseMobile.tsx
+│   ├── LightBoxSideOverlayLoader.tsx
+│   └── index.ts                      # Re-export SideOverlay
+├── LightBoxViewManager/
+│   ├── LightBoxViewManager.tsx       # Вычисляет CSS-переменные --lightBox-screen-*
+│   └── LightBoxViewManagerConsts.ts
+└── styles/
+    ├── LightBox.module.less
+    ├── LightBoxControls.module.less
+    └── LightBoxScroll.module.less
+```
+
+---
+
+## Compound-структура
+
+```tsx
+<LightBox size={ELightBoxSize.LG} isLoading={loading}>
+    <LightBox.Controls>
+        <LightBox.Controls.Prev onClick={...} />
+        <LightBox.Controls.Next onClick={...} />
+        <LightBox.Controls.Close onClick={onClose} />
+    </LightBox.Controls>
+
+    <LightBox.LeftSidebar fixed onShow={...}>
+        {/* Левая панель — список разделов */}
+    </LightBox.LeftSidebar>
+
+    <LightBox.Content isLoading={contentLoading} loadingTitle="Загрузка…">
+        {/* Основной контент */}
+    </LightBox.Content>
+
+    <LightBox.RightSidebar>{/* Правая панель */}</LightBox.RightSidebar>
+
+    <LightBox.SideOverlay opened={sideOpen} onClose={...}>
+        {/* Выезжает справа */}
+    </LightBox.SideOverlay>
+
+    <LightBox.TopOverlay>{/* TopOverlay из components/TopOverlay */}</LightBox.TopOverlay>
+</LightBox>
+```
+
+`LightBox.TopOverlay` — **реэкспорт внешнего** компонента `TopOverlay`,
+а не локальный. Это нужно учитывать при типизации.
+
+---
+
+## Варианты и props
+
+### LightBox — `ILightBoxProps extends HTMLAttributes<HTMLDivElement>`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `children` | `ReactElement[]` | — | Обязателен как массив (не `ReactNode`). Компонент рендерит всех без перебора — дети статичные слоты. |
+| `size` | `ELightBoxSize` | `MD` | `SM`/`MD`/`LG`/`XL` — влияет на ширину контентной зоны. |
+| `focusTrapProps` | `FocusTrapProps` | — | Переопределение параметров `focus-trap-react`. |
+| `forwardRef` | `MutableRefObject<HTMLElement \| null>` | — | **Не `ref`**, а отдельный prop. Корневой компонент — не `forwardRef`. |
+| `mountNode` | `HTMLDivElement` | auto | Куда рендерить через Portal. По умолчанию — DOM-элемент `#LightBox-next-mount-node` (создаётся при первом монтировании). |
+| `lightBoxViewManagerNodeId` | `string` | `"LightBox-next-view-manager-node"` | DOM-элемент, по границам которого позиционируется LightBox (для кейса "LightBox не на весь экран"). |
+| `isLoading` | `boolean` | — | Показывает loader, блокирует FocusTrap. |
+| `isSideOverlayOpened` | `boolean` | — | Родитель контролирует — включает классы `.lightBoxSideOverlayActive` на корне. |
+| `isTopOverlayOpened` | `boolean` | — | Аналогично для TopOverlay. |
+
+### ELightBoxSize
+
+```ts
+enum ELightBoxSize { SM = "sm", MD = "md", LG = "lg", XL = "xl" }
+```
+
+**Не `EComponentSize`** — собственный enum с дополнительным `XL`.
+
+### LightBox.Content — `ILightBoxContentProps`
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `isLoading` | `boolean` | Накладывает `LoaderScreen` поверх контента. |
+| `loadingTitle` | `ReactNode` | Подпись под спиннером. |
+
+- Внутри — свой scroll-контейнер. `paddingTop` **вычисляется рантайм** по высоте `data-lightbox-component="controls"` (querySelector — **не по ref**).
+- Слушает resize через `react-resize-detector` (debounce 100ms) и `WindowResizeListener`.
+
+### LightBox.LeftSidebar / RightSidebar — `forwardRef<HTMLDivElement>`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `fixed` | `boolean` | — | Закрепляет панель (не скроллится вместе с контентом). |
+| `minVisibleWidth` | `number` | `100` | Ширина (px), ниже которой контент панели скрывается классом `.hidden`. |
+| `onShow` / `onHide` | `() => void` | — | Callback'и при пересечении порога ширины. Хранятся в ref — замыкание на актуальное значение. |
+
+Использует `ResizeObserver` на outer-элементе.
+
+### LightBox.SideOverlay — `ILightBoxSideOverlayProps`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `opened` | `boolean` | — | Управляемое состояние. |
+| `onClose` / `onOpen` | `() => void` | — | Срабатывают после завершения `transitionend` (не сразу при смене `opened`). |
+| `focusTrapProps` | `FocusTrapProps` | — | Собственный FocusTrap внутри LightBox'овского (вложенные trap'ы). |
+| `isLoading` | `boolean` | — | Показывает внутренний loader. |
+| `isTopLevelSideOverlayOpened` | `boolean` | — | Если сверху открыт ещё один overlay — отключить scroll в текущем. |
+| `isTopOverlayOpened` | `boolean` | — | Аналогично. |
+| `size` | `EComponentSize` | `MD` | Ширина панели. |
+
+- Имеет подкомпоненты `.CloseDesktop` и `.CloseMobile` (две разных кнопки закрытия по вьюпорту).
+- Внутри — `OverlayBase direction={RIGHT}` + `OverlayMask` + `FocusTrap`.
+- Отслеживает `opening`/`closing` state'ы по `prevOpened` (useRef) — для анимированных переходов.
+
+### LightBox.Controls — `ILightBoxControlsFC` (Object.assign)
+
+Container с `data-lightbox-component="controls"` — **используется для вычисления paddingTop контента** (querySelector в LightBoxContent). Не менять атрибут.
+
+Подкомпоненты: `.Close`, `.Next`, `.Prev`.
+
+### LightBox.TopOverlay
+
+Реэкспорт `TopOverlay` из `../TopOverlay/TopOverlay`. Используй как `<LightBox.TopOverlay>` или `<TopOverlay>` — идентично.
+
+---
+
+## Ключевые особенности реализации
+
+### Два portal'а + ViewManager
+
+```tsx
+<>
+    <Portal container={lightBoxMountNode.current}>{renderLightBox()}</Portal>
+    <LightBoxViewManager lightBoxViewManagerNode={...} lightBoxMountNode={...} />
+</>
+```
+
+- **LightBox** рендерится в `#LightBox-next-mount-node` (обычно в body).
+- **ViewManager** рендерится в `#LightBox-next-view-manager-node` (по умолчанию в body, но потребитель может создать его в нужном контейнере) и **вычисляет CSS-переменные** `--lightBox-screen-left/width/top` через `<style>`-тег на mountNode.
+- Это позволяет LightBox'у "уменьшаться" до размеров конкретной области (например, если есть глобальный sidebar — LightBox не должен его перекрывать).
+
+### `FocusTrap` + `MobileView` fallback
+
+```tsx
+<MobileView fallback={<FocusTrap ...>{renderLightBox()}</FocusTrap>}>
+    {renderLightBox()}
+</MobileView>
+```
+
+- На mobile (определяется `MobileView`) — **без focus trap'а** (нативный scroll/focus лучше работает без trap'а на мобильных).
+- На desktop — `FocusTrap` с `initialFocus = getFirstInteractionElementByDataAttr` из `FocusTrapUtils`.
+- `active={!isLoading}` — trap неактивен во время загрузки.
+
+### Safari z-index hack
+
+```tsx
+<span ref={tempButtonRef} className={styles.tempElSafariBug} />
+
+useEffect(() => {
+    if (!isSideOverlayOpened && tempButtonRef.current) {
+        const nextZIndex = Math.round(Math.random() * 100);
+        tempButtonRef.current.style.zIndex = nextZIndex.toString();
+    }
+}, [isSideOverlayOpened]);
+```
+
+- Невидимый `<span>`, у которого меняется `z-index` при закрытии SideOverlay — **принудительно вызывает repaint** в Safari. Баг-тикет `DCBSWT-2866`. Не трогать.
+
+### Scrollbar-width и body lock
+
+```ts
+useEffect(() => {
+    addClassNameWithScrollbarWidth(scrollStyles); // вычисляет ширину скроллбара, прописывает в CSS
+    addClassNamesToDocumentElement();             // .bodyOverflowHidden → documentElement
+    setTimeout(addClassNamesToDocumentElement, 100); // fix: при переключении двух LightBox
+    return () => bodyClassNamesIsLightBoxOpen.forEach(c => document.documentElement.classList.remove(c));
+}, []);
+```
+
+- Блокировка скролла — на `documentElement`, не `body`.
+- `setTimeout(100)` — фикс роутерного бага: новый LightBox монтируется **до** размонтирования старого, классы удаляются старым — повторно добавляем через 100ms.
+
+### `LightBoxContent.paddingTop` — вычисление по querySelector
+
+```ts
+const controlsNode = document.querySelector(`[data-lightbox-component="controls"]`);
+if (controlsNode) nextPaddingTop += controlsNode.offsetHeight;
+```
+
+- Контент добавляет сверху padding равный высоте Controls-бара, чтобы они не перекрывали начало контента.
+- Debounce 100ms, изменение применяется при `deltaTop > 1` — антидрожание.
+
+### `LightBoxSideOverlay` — разделение `opening`/`closing`/`opened`
+
+```ts
+useEffect(() => {
+    if (prevOpened.current && !opened) { setOpening(false); setClosing(true); }
+    else if (!prevOpened.current && opened) { setClosing(false); setOpening(true); }
+    prevOpened.current = opened;
+}, [opened]);
+```
+
+- Tri-state: `opened` + `opening` (анимация раскрытия) + `closing` (анимация закрытия). `onOpen`/`onClose` срабатывают **после `transitionEnd`**, не сразу.
+- FocusTrap активен только когда `opened && !opening && !closing`.
+
+### `LeftSidebar.onShow/onHide` через ref
+
+Чтобы `ResizeObserver`-коллбэк не пересоздавался при смене обработчиков, они пишутся в `onShowRef`/`onHideRef` через `useEffect`. Паттерн "stable callback".
+
+---
+
+## Инварианты
+
+- **`children: ReactElement[]`** — типом заявлен массив. Потребители фактически пишут слоты подряд — TypeScript нестрого проверяет. Не менять без переосмысления.
+- **`data-lightbox-component="controls"`** атрибут на Controls-контейнере — **необходим** для работы `LightBoxContent` (querySelector). При замене на ref нужно править `LightBoxContent.tsx`.
+- **IDs `LightBox-next-mount-node` и `LightBox-next-view-manager-node`** — константы в модуле, переименование — breaking.
+- **`forwardRef` prop (а не `ref`)** — публичный API. LightBoxBase — не `forwardRef`; `Object.assign` поверх. Не переименовывать в `ref`.
+- **`ELightBoxSize`** — собственный enum, не `EComponentSize`; есть значение `XL`.
+- **Safari span `tempElSafariBug`** — не удалять без регрессии (см. DCBSWT-2866).
+- **`setTimeout(100)` на body-lock** — костыль против роутерных гонок, не убирать.
+- **`LightBox.SideOverlay.CloseDesktop`/`.CloseMobile`** — две отдельные кнопки, не одна. Mobile/desktop визуально разные.
+- **`Portal` + `lightBoxMountNode`** — LightBox никогда не рендерится inline. При SSR потребителю нужен ClientOnly-wrapper.
+- **`MobileView` fallback wraps FocusTrap, children — нет**: на mobile focus trap не активен.
+- **`onOpen`/`onClose` SideOverlay** вызываются по `transitionend`, не по смене `opened`. Важно для консьюмеров, ждущих завершения анимации.
+
+---
+
+## Accessibility
+
+- `role="dialog"` + `aria-modal="true"` — на корне LightBox и на SideOverlay.
+- FocusTrap удерживает фокус внутри (desktop). Потребитель должен проставить tabbable-элементы и осмысленные labels.
+- Initial focus — первый элемент с `data-focus-initial` (см. `FocusTrapUtils.getFirstInteractionElementByDataAttr`) или первый tabbable.
+- `allowOutsideClick: true` — клик вне модалки не ломает trap (но и не закрывает — консьюмер сам вешает onClose).
+- **Mobile — без focus trap'а**. Семантика диалога остаётся через `role="dialog"`, но скринридеры могут не удерживать фокус — закладывайте это для мобильных UX-тестов.
+- Контент не анонсируется при открытии (нет `aria-labelledby`/`aria-describedby` по умолчанию) — потребитель должен добавить через `...rest`.
+
+---
+
+## Дизайн-токены
+
+LightBoxViewManager прописывает **runtime CSS-переменные**:
+
+```
+--lightBox-screen-left
+--lightBox-screen-width
+--lightBox-screen-top
+```
+
+Их значения вычисляются по `getBoundingClientRect` у `lightBoxViewManagerNode`. Эти переменные используются LESS-стилями LightBox для позиционирования.
+
+Прочие визуальные токены — от ThemeProvider (`scopeClassName` подставляется на корень).
+
+---
+
+## Связанные компоненты
+
+- `ModalWindow` — простой диалог, не полноэкранный.
+- `Overlay` / `OverlayBase` / `OverlayMask` — основа для SideOverlay.
+- `TopOverlay` — верхняя выезжающая панель (реэкспортируется как `LightBox.TopOverlay`).
+- `Portal` — используется для render'а.
+- `MobileView` — разграничение desktop/mobile.
+- `LoaderScreen` — loader внутри Content.
+- `focus-trap-react` — FocusTrap.
+- `react-resize-detector` — resize-listener в Content и ViewManager.
+
+---
+
+## Stories
+
+`stories/LightBox/LightBox.stories.tsx`
+`stories/LightBox/LightBoxInitialOpened.stories.tsx`
+Примеры: `stories/LightBox/examples/`
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/Link.md

@@ -0,0 +1,161 @@
+---
+component: Link
+category: Navigation
+figma-node: ""
+figma-file: ""
+related: [Button, IconWrapper, Typography]
+tokens:
+  - --triplex-next-Link-Color
+  - --triplex-next-Link-Color-Hover
+  - --triplex-next-Link-Color-Active
+stories: stories/Link/Link.stories.tsx
+version: "1.0"
+---
+
+# Link
+
+## Назначение
+
+Инлайновая ссылка — `<a>` с дизайн-цветами бренда и поддержкой
+**leading/trailing-контента** (иконки). Вставляет zero-width space
+для корректного выравнивания иконки с текстом и умеет **привязывать
+иконку к первому/последнему слову** многословной ссылки, чтобы иконка
+не "отлетала" на новую строку при переносе.
+
+Используй когда: нужна стандартная текстовая ссылка (в тексте, в списке).
+Для стилизованной кнопки-CTA — `Button` с `type="link"`.
+
+---
+
+## Файловая структура
+
+```text
+src/components/Link/
+├── Link.tsx                   # forwardRef<HTMLAnchorElement>
+├── index.ts                   # Barrel
+├── styles/Link.module.less
+└── __tests__/Link.test.tsx
+```
+
+---
+
+## Варианты и props
+
+### `ILinkCommonProps extends AnchorHTMLAttributes<HTMLAnchorElement>`
+
+| Prop | Тип | Обязателен | Описание |
+|---|---|---|---|
+| `children` | `ReactNode` | Да | Текст или node. Для строк включается логика "иконка + первое/последнее слово". |
+| `contentBefore` | `() => ReactElement` | Нет | Рендер-функция leading-контента (обычно иконка). |
+| `contentAfter` | `() => ReactElement` | Нет | Рендер-функция trailing-контента. |
+| `href`, `target`, `rel`, `onClick`, … | стандартные `<a>`-атрибуты | — | Передаются на `<a>`. |
+
+**`contentBefore` / `contentAfter` — render-props**, не `ReactNode`. Функции вызываются каждый раз при рендере.
+
+---
+
+## Ключевые особенности реализации
+
+### Zero-width space перед leading-контентом
+
+```tsx
+const renderContentBefore = () =>
+    contentBefore ? <>{"\u200B"}{contentBefore()}</> : null;
+```
+
+- `"\u200B"` (ZWSP) — невидимый символ, используется для корректного **выравнивания по baseline**. Без него иконка "прыгает" относительно текста.
+- Аналогичного для `contentAfter` нет — баланс достигается CSS-стилями.
+
+### Привязка иконки к первому/последнему слову
+
+```tsx
+if (words.length < 2 || (words.length < 3 && contentBefore && contentAfter)) {
+    return <span>{before}{text}{after}</span>; // всё в одном span
+}
+// Иначе: первый + оставшиеся + последний слово как отдельные узлы
+return <>{firstNode} {restWords} {lastNode}</>;
+```
+
+- Для строковых `children` Link парсит текст по пробелам и **оборачивает первое/последнее слово** в `<span>` вместе с `contentBefore`/`contentAfter`.
+- Это гарантирует, что иконка не разорвётся с соседним словом при word-wrap.
+- Для нестроковых `children` — простая конкатенация: `{before}{node}{after}`.
+- Edge case: `words.length < 2` (одно слово) или `< 3` при обоих before+after → всё в одном `<span>` (иначе нечего "разделять").
+
+### `IconWrapper displayContents`
+
+```tsx
+<a>
+    <IconWrapper displayContents>{content}</IconWrapper>
+</a>
+```
+
+- Оборачивает **весь контент** в `IconWrapper` с `display: contents`, чтобы включить `hoverable`-класс для иконок в `contentBefore`/`contentAfter` (меняет `fill` при hover).
+- `displayContents` нужен, чтобы обёртка не создавала свой box и не ломала inline-поток.
+
+### `data-tx={process.env.npm_package_version}` atribute
+
+Версия библиотеки пишется в DOM — для дебага на production (можно узнать версию, просмотрев разметку). Этот атрибут стоит сохранить при изменениях.
+
+### `role="link"` на `<a>`
+
+**Избыточно** — `<a href>` по умолчанию имеет role="link". Но без `href` роль теряется → `role="link"` делает компонент семантически корректным и для "кнопкоподобных" ссылок без href'а. Не удалять без рефакторинга.
+
+### `onBlur` / `onMouseDown` прокидываются отдельно
+
+Остальные handler'ы идут через `...rest`, но эти два — отдельно. **Легаси** — можно убрать, упростив до `...rest`. При рефакторинге проверять storybook-примеры.
+
+---
+
+## Инварианты
+
+- **`<a>` с `role="link"`** — не менять тег на `<span>`/`<button>` (нарушит screen reader'ов).
+- **`contentBefore` / `contentAfter` — функции**, не nodes. Публичный API.
+- **ZWSP перед leading-контентом** — не убирать без визуальной регрессии.
+- **Строковые children обрабатываются специально** (первое/последнее слово). Не все потребители это знают; при рефакторинге поддерживать логику разрыва слов.
+- **`IconWrapper displayContents`** — обязателен, обеспечивает `hoverable` для иконок внутри.
+- **`data-tx` атрибут** — продакшн-маркер версии, не трогать.
+- **`forwardRef<HTMLAnchorElement>`** — не `HTMLElement`.
+
+---
+
+## Accessibility
+
+- `<a>` с `href` — полная клавиатурная навигация (Tab, Enter).
+- `role="link"` — дублирующая роль, но нужна для `<a>` без href (interactive span-like ссылки).
+- Иконки в `contentBefore`/`contentAfter` не имеют `aria-label` — потребитель должен передать нужные атрибуты через `contentBefore={() => <Icon aria-hidden="true" />}` (если декоративная) или осмысленный `aria-label` у иконки (если несёт смысл).
+- `disabled`-состояние у `<a>` невозможно; для блокировки — `tabIndex={-1}` + CSS (нет в компоненте).
+
+---
+
+## Дизайн-токены
+
+```
+--triplex-next-Link-Color             # основной цвет
+--triplex-next-Link-Color-Hover       # hover
+--triplex-next-Link-Color-Active      # active
+```
+
+(Названия могут отличаться — проверь `styles/Link.module.less`.)
+
+---
+
+## Связанные компоненты
+
+- `IconWrapper` — обёртка для `hoverable`-стилей иконок (используется внутри).
+- `Button` с `type="link"` — кнопка, стилизованная как ссылка.
+- `Typography` — для текста без ссылочной функции.
+
+---
+
+## Stories
+
+`stories/Link/Link.stories.tsx`
+Примеры: `stories/Link/examples/`
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |