@sberbusiness/triplex-next-mcp-server 1.40.0-beta → 1.41.0-beta

package/bundle/components/ThemeProvider.md

@@ -1,11 +1,9 @@
 ---
 component: ThemeProvider
-category: Infrastructure
-figma-node: ""
-figma-file: ""
-related: [DesignTokens]
+category: ThemeProvider
+related: [useToken]
 tokens: []
-stories: ""
+stories: stories/ThemeProvider/ThemeProvider.stories.tsx
 version: "1.0"
 ---
 
@@ -13,169 +11,359 @@ version: "1.0"
 
 ## Назначение
 
-Провайдер темы и дизайн-токенов: задаёт область видимости CSS-переменных
-через scoped className на HTML-элементе и подставляет токены темы (LIGHT/
-DARK) + опциональные пользовательские override'ы. Токены доступны через
-контекст (`useToken`).
+Провайдер темы: рендерит css-переменные всех дизайн-токенов выбранной темы в тег `<style>`,
+ограничивает их областью видимости элемента из `scopeRef` и передаёт тему и итоговые токены
+дочерним компонентам через контекст (читается хуком `useToken`).
 
-Используй когда: нужно применить тему ко всему приложению или к
-изолированному поддереву (например, тёмная панель внутри светлого
-интерфейса). Вне `ThemeProvider` работает дефолтное `LIGHT` оформление.
+Используй когда: приложению нужна тема Triplex Next (светлая или тёмная) либо точечное
+переопределение дизайн-токенов — глобально на корне приложения или локально для части дерева.
+
+Не используй когда: нужно поменять внешний вид одного компонента — для этого есть props
+компонента (`theme`, `size`, `status`) и его собственные токены, а не подмена всей темы.
 
 ---
 
-## Файловая структура
-
-```text
-src/components/ThemeProvider/
-├── ThemeProvider.tsx                       # FC<IThemeProviderProps>; updateCSS/removeCSS + ThemeProviderView
-├── ThemeProviderContext.ts                 # IThemeProviderContext + контекст с дефолтом LIGHT
-├── ETriplexNextTheme.ts                    # enum LIGHT/DARK
-├── useToken.ts                             # хук-обёртка над контекстом
-├── components/
-│   └── ThemeProviderView.tsx               # классname на scopeRef + Context.Provider с merged-токенами
-├── __tests__/
-└── index.ts
-```
+## Варианты и props
 
----
+### Обязательные props
 
-## Публичный API
+| Prop | Тип | Описание |
+|---|---|---|
+| `children` | `React.ReactNode` | Контент, внутри которого действуют тема и токены |
+| `scopeRef` | `React.RefObject<HTMLElement>` | Ref на элемент, на который навешивается `scopeClassName`. Именно этот элемент и его потомки видят css-переменные темы |
 
-### `IThemeProviderProps`
+### Опциональные props
 
-| Prop | Тип | Default | Описание |
+| Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `children` | `ReactNode` | — | Дерево, использующее тему. |
-| `scopeRef` | `RefObject<HTMLElement>` | — | **Обязателен**. Ref на DOM-элемент, к которому добавится `scopeClassName` (обычно `html`/`body`/корневой div). |
-| `scopeClassName?` | `string` | `triplex-next-theme-{n}` (uniqueId) | Класс для области видимости. Если не передан — генерируется автоматически. |
-| `theme?` | `ETriplexNextTheme` | `LIGHT` | Тема. |
-| `tokens?` | `TDesignTokensPartial` | `{}` | Override отдельных токенов. |
-
-### `ETriplexNextTheme`
-
-```ts
-enum ETriplexNextTheme {
-    LIGHT = "light",
-    DARK  = "dark",
-}
-```
+| `theme` | `ETriplexNextTheme` | `ETriplexNextTheme.LIGHT` | Дизайн-тема: `LIGHT` / `DARK` |
+| `scopeClassName` | `string` | `uniqueId("triplex-next-theme-")` | Класс области видимости css-переменных. Задавай явно, если класс нужен снаружи (например, для портала, который рендерится вне `scopeRef`) |
+| `tokens` | `TDesignTokensPartial` | `{}` | Частичное переопределение токенов поверх токенов темы |
+
+### Особенности
+
+- `scopeRef` должен указывать на элемент **внутри** `children` (или на предка, существующего
+  на момент эффекта). Класс навешивается в `useEffect`, поэтому до первого эффекта переменных
+  на элементе ещё нет.
+- `tokens` мерджится через `defaultsDeep` в порядке «переопределения потребителя → core-токены
+  темы → токены компонентов темы»: значения потребителя всегда выигрывают.
+- `tokens` сравнивается по ссылке. Инлайн-литерал в JSX пересобирает `<style>` на каждый рендер —
+  выноси объект в константу или мемоизируй.
+- Провайдеры вкладываются: `useToken` возвращает значения ближайшего `ThemeProvider`.
+- Вне `ThemeProvider` контекст отдаёт светлую тему, токены по умолчанию и пустой `scopeClassName`.
 
-### `IThemeProviderContext`
+---
 
-```ts
-{
-    scopeClassName: string;
-    theme: ETriplexNextTheme;
-    tokens: TDesignTokens;     // полные токены (Core + Components, по теме + override)
-}
-```
+## Дизайн-токены
 
-### `useToken()`
+Собственных токенов у компонента нет — он **источник** css-переменных для всех остальных
+компонентов. В `<style>` с ключом `triplex-next-dynamic-tokens-{scopeClassName}` выводятся все
+токены выбранной темы (core + компонентные) в виде:
 
-```ts
-() => { scopeClassName: string; theme: ETriplexNextTheme; tokens: TDesignTokens }
+```
+--triplex-next-{Группа}-{Токен}-{версия}: {значение};
 ```
 
-Чтение текущей темы и токенов из контекста.
+Версия в имени переменной — версия пакета с точками, заменёнными на дефисы
+(см. `DesignTokenUtils.getCSSVariableByTokenGroup`).
 
 ---
 
-## Поведение
+## Инварианты
 
-### Внедрение CSS
+- `ThemeProvider` не рендерит собственный DOM-элемент — `forwardRef` неприменим,
+  ref на DOM передаётся потребителем через `scopeRef`.
+- Публичные экспорты `src/components/ThemeProvider/index.ts` — `ThemeProvider`,
+  `IThemeProviderProps`, `ThemeProviderContext`, `IThemeProviderContext`, `ETriplexNextTheme`,
+  `useToken`. Ни один не удалять и не переименовывать.
+- Значения `ETriplexNextTheme` (`"light"` / `"dark"`) — часть публичного API.
+- Ключ тега стилей `triplex-next-dynamic-tokens-{scopeClassName}` и префикс автогенерируемого
+  класса `triplex-next-theme-` менять нельзя: по ключу стили обновляются и удаляются,
+  а класс попадает в разметку потребителя.
+- Порядок аргументов `defaultsDeep` в `ThemeProviderView` менять нельзя — иначе токены темы
+  начнут переопределять пользовательские.
+- `ThemeProviderContext` должен оставаться единственным экземпляром модуля: `useToken`
+  импортирует его по пути пакета (`@sberbusiness/triplex-next/components/ThemeProvider/...`).
+  Дублирование модуля через разные спецификаторы разорвёт связь провайдера и потребителей.
+- Компоненты, рендерящиеся в портал вне `scopeRef`, сами переносят `scopeClassName`
+  из `useToken` на свой корневой узел — иначе css-переменные до них не доходят.
+  Новые портальные компоненты должны делать так же, и способ зависит от контейнера:
+  - **собственный контейнер** (`Dropdown`, `ModalWindow`, `LightBox`) — класс просто
+    добавляется в `clsx` корневого элемента;
+  - **общий контейнер, разделяемый несколькими экземплярами** (`Tooltip`,
+    см. `utils/useTooltipTheme.ts`) — класс навешивается через `classList` в эффекте
+    со счётчиком использований в data-атрибуте и снимается с задержкой после закрытия.
+    Без счётчика соседние экземпляры на том же контейнере затирали бы тему друг другу,
+    без задержки класс снимался бы до конца анимации закрытия.
+- При размонтировании и при смене `scopeClassName` тег стилей удаляется, а класс снимается
+  с элемента — утечка стилей на страницу недопустима.
 
-`useLayoutEffect` (`ThemeProvider.tsx`):
-1. `DesignTokenUtils.getStyle(theme, tokens)` → строка `--var-name: value;`.
-2. `updateCSS(`.${scopeCssClassName} {…}`, ключ `triplex-next-dynamic-tokens-${scopeCssClassName}`)` — вставляет/обновляет `<style>` тег (через `rc-util/Dom/dynamicCSS`).
-3. SSR: `canUseDom() === false` → `console.log` warning, без вставки.
+---
 
-При размонтировании — `removeCSS` по тому же ключу.
+## Accessibility
 
-### Применение области видимости (`ThemeProviderView`)
+Компонент не рендерит DOM и не влияет на семантику, фокус и клавиатуру. Отдельных требований
+нет. Контрастность цветов — ответственность значений токенов темы.
 
-`useEffect` на `[scopeClassName, scopeRef]`:
-- Добавляет `scopeClassName` в `scopeRef.current.classList`.
-- При cleanup — удаляет `prevScopeClassName.current` (хранит предыдущий класс для корректного removal).
+---
 
-### Сборка токенов в Context
+## Связанные компоненты
 
-`useMemo`:
-```ts
-defaultsDeep(
-    {},
-    tokensProps,                                              // 1. user override
-    theme === LIGHT ? DesignTokensCore : DesignTokensCoreThemeDark,
-    theme === LIGHT ? DesignTokensComponents : DesignTokensComponentsThemeDark,
-);
-```
+- `useToken` — хук доступа к текущей теме, токенам и `scopeClassName`. Основной способ
+  прочитать тему внутри компонента.
+- `ThemeProviderContext` — контекст темы; экспортируется для нестандартных сценариев,
+  в обычном коде используй `useToken`.
+- `ETriplexNextTheme` — enum доступных тем.
+- `ThemeProviderView` — внутренний компонент (навешивает класс, собирает значение контекста),
+  не экспортируется из barrel.
+- `DesignTokens` (`DesignTokensCore`, `DesignTokensComponents` и их тёмные варианты) —
+  источник значений токенов; `DesignTokenUtils.getStyle` формирует css-переменные.
+- `Dropdown`, `ModalWindow`, `LightBox`, `Tooltip` — потребители `useToken`: переносят
+  `scopeClassName` на свои портальные контейнеры.
+
+---
+
+## Stories
 
-**Порядок важен** — `defaultsDeep` НЕ перезаписывает уже определённые ключи,
-поэтому первые источники имеют приоритет (user > Core > Components).
+Основные истории: `stories/ThemeProvider/ThemeProvider.stories.tsx`
+Файлы примеров: `stories/ThemeProvider/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный подбор темы, `scopeClassName` и переопределяемых токенов |
+| `Default` | `Default.tsx` | Минимальный пример: светлая тема по умолчанию |
+| `DarkTheme` | `DarkTheme.tsx` | Тёмная тема |
+| `CustomTokens` | `CustomTokens.tsx` | Переопределение токена поверх темы |
+| `ThemeSwitcher` | `ThemeSwitcher.tsx` | Переключение темы на лету |
+| `ScopedTheme` | `ScopedTheme.tsx` | Область действия темы: контент вне `scopeRef` её не видит |
 
 ---
 
-## Инварианты
+## История изменений
 
-- **`FC, не forwardRef`** — `ThemeProvider` ref не пробрасывает; ref на DOM передаётся через `scopeRef`.
-- **`scopeRef` обязателен** — без него `classList.add` не выполнится → стили не применятся.
-- **`scopeClassName` авто-генерируется** через `uniqueId("triplex-next-theme-")`, если не передан. Стабилен между рендерами (memo по `[scopeClassName]`).
-- **`useLayoutEffect` для вставки CSS** — критично, чтобы стили применились ДО первого paint'а детей. Не менять на `useEffect`.
-- **Cleanup `removeCSS`** при размонтировании — иначе утечки `<style>` тегов в `<head>`.
-- **Порядок `defaultsDeep` зафиксирован комментарием** — `tokensProps` идёт первым (приоритет), не менять без обсуждения.
-- **`prevScopeClassName: useRef`** — нужен для удаления старого класса при изменении `scopeClassName` (обычный сценарий — не возникает, но защита от смены через props).
-- **SSR не поддержан** — фоллбек на `console.log`. Реальная тема применится только после hydration на клиенте.
-- **Дефолтный контекст содержит `LIGHT` токены** (`DesignTokensCore + DesignTokensComponents`), не пустой объект. Компоненты вне `ThemeProvider` получают дефолтную светлую тему через `useToken`.
-- **Контекст имеет полные токены `TDesignTokens`**, а не `Partial` — `useToken` гарантированно возвращает все ключи.
+| Дата | Изменение |
+|---|---|
+| 2026-08-05 | Создан документ. AI-рефакторинг: JSDoc на props и экспортах, ключ тега стилей вынесен в хелпер, упрощён эффект `ThemeProviderView`, добавлены unit-тесты `ThemeProviderView` и `useToken`, stories переведены на modern pattern |
+| 2026-08-05 | `related` сокращён до `useToken`. Удалён неактуальный комментарий про относительный импорт в `ThemeProviderView` |
 
 ---
 
-## Использование
+## Примеры использования
+
+### Default
+
+`stories/ThemeProvider/examples/Default.tsx`
 
 ```tsx
-const App = () => {
-    const rootRef = useRef<HTMLDivElement>(null);
+import React, { useRef } from "react";
+import {
+    ThemeProvider,
+    ETriplexNextTheme,
+    Button,
+    EButtonTheme,
+    EComponentSize,
+    Text,
+    ETextSize,
+} from "@sberbusiness/triplex-next";
+
+export const Default = () => {
+    const scopeRef = useRef<HTMLDivElement>(null);
 
     return (
-        <div ref={rootRef}>
-            <ThemeProvider scopeRef={rootRef} theme={ETriplexNextTheme.DARK}>
-                <YourApp />
-            </ThemeProvider>
-        </div>
+        <ThemeProvider theme={ETriplexNextTheme.LIGHT} scopeRef={scopeRef}>
+            <div ref={scopeRef} style={{ display: "flex", flexDirection: "column", alignItems: "flex-start", gap: 16 }}>
+                <Text size={ETextSize.B1}>Светлая тема — значение по умолчанию.</Text>
+                <Button theme={EButtonTheme.GENERAL} size={EComponentSize.MD}>
+                    Button text
+                </Button>
+            </div>
+        </ThemeProvider>
     );
 };
+```
+
+### DarkTheme
+
+`stories/ThemeProvider/examples/DarkTheme.tsx`
 
-// Чтение токенов в компоненте:
-const { tokens, theme } = useToken();
+```tsx
+import React, { useRef } from "react";
+import {
+    ThemeProvider,
+    ETriplexNextTheme,
+    Button,
+    EButtonTheme,
+    EComponentSize,
+    CardStatic,
+    ECardContentPaddingSize,
+    Text,
+    ETextSize,
+} from "@sberbusiness/triplex-next";
+
+export const DarkTheme = () => {
+    const scopeRef = useRef<HTMLDivElement>(null);
+
+    return (
+        <ThemeProvider theme={ETriplexNextTheme.DARK} scopeRef={scopeRef}>
+            {/*
+                ThemeProvider задаёт только css-переменные и не красит подложку — фон под тёмную тему
+                даёт компонент с собственным токеном фона, иначе светлый текст темы будет не виден.
+            */}
+            <div ref={scopeRef}>
+                <CardStatic>
+                    <CardStatic.Content paddingSize={ECardContentPaddingSize.MD}>
+                        <div style={{ display: "flex", flexDirection: "column", alignItems: "flex-start", gap: 16 }}>
+                            <Text size={ETextSize.B1}>Тёмная тема.</Text>
+                            <Button theme={EButtonTheme.GENERAL} size={EComponentSize.MD}>
+                                Button text
+                            </Button>
+                            <Button theme={EButtonTheme.SECONDARY} size={EComponentSize.MD}>
+                                Button text
+                            </Button>
+                        </div>
+                    </CardStatic.Content>
+                </CardStatic>
+            </div>
+        </ThemeProvider>
+    );
+};
 ```
 
-Несколько `ThemeProvider` могут быть вложены — внутренний переопределяет
-внешний внутри своего scope.
+### CustomTokens
 
----
+`stories/ThemeProvider/examples/CustomTokens.tsx`
 
-## Accessibility
+```tsx
+import React, { useRef } from "react";
+import {
+    ThemeProvider,
+    ETriplexNextTheme,
+    Button,
+    EButtonTheme,
+    EComponentSize,
+    Text,
+    ETextSize,
+} from "@sberbusiness/triplex-next";
+
+// tokens сравнивается по ссылке — объект вынесен из рендера, чтобы style-тег не пересобирался.
+const CUSTOM_TOKENS = {
+    ColorBrand: {
+        50: { value: "blue" },
+    },
+};
 
-- ARIA не задействована — это инфраструктурный компонент.
-- При смене темы для контрастности и читаемости — обеспечивается дизайн-токенами; компонент только применяет их.
+export const CustomTokens = () => {
+    const scopeRef = useRef<HTMLDivElement>(null);
 
----
+    return (
+        <ThemeProvider theme={ETriplexNextTheme.LIGHT} tokens={CUSTOM_TOKENS} scopeRef={scopeRef}>
+            <div ref={scopeRef} style={{ display: "flex", flexDirection: "column", alignItems: "flex-start", gap: 16 }}>
+                <Text size={ETextSize.B1}>Токен ColorBrand.50 переопределён — кнопка перекрашена.</Text>
+                <Button theme={EButtonTheme.GENERAL} size={EComponentSize.MD}>
+                    Button text
+                </Button>
+            </div>
+        </ThemeProvider>
+    );
+};
+```
 
-## Связанные компоненты
+### ThemeSwitcher
 
-- `DesignTokens` (`DesignTokensCore`, `DesignTokensComponents`, `*ThemeDark` варианты, `DesignTokenUtils`) — источники значений.
-- Все компоненты дизайн-системы — потребители токенов через CSS-переменные `--triplex-next-*`.
+`stories/ThemeProvider/examples/ThemeSwitcher.tsx`
 
----
+```tsx
+import React, { useRef, useState } from "react";
+import {
+    ThemeProvider,
+    ETriplexNextTheme,
+    Button,
+    EButtonTheme,
+    EComponentSize,
+    CardStatic,
+    ECardContentPaddingSize,
+    Text,
+    ETextSize,
+} from "@sberbusiness/triplex-next";
+
+export const ThemeSwitcher = () => {
+    const scopeRef = useRef<HTMLDivElement>(null);
+    const [theme, setTheme] = useState(ETriplexNextTheme.LIGHT);
+
+    const handleToggleClick = () => {
+        setTheme((prevTheme) =>
+            prevTheme === ETriplexNextTheme.LIGHT ? ETriplexNextTheme.DARK : ETriplexNextTheme.LIGHT,
+        );
+    };
 
-## Stories
+    return (
+        <ThemeProvider theme={theme} scopeRef={scopeRef}>
+            {/* Подложку под тему даёт компонент с собственным токеном фона — ThemeProvider её не красит. */}
+            <div ref={scopeRef}>
+                <CardStatic>
+                    <CardStatic.Content paddingSize={ECardContentPaddingSize.MD}>
+                        <div style={{ display: "flex", flexDirection: "column", alignItems: "flex-start", gap: 16 }}>
+                            <Text size={ETextSize.B1}>
+                                Текущая тема: {theme === ETriplexNextTheme.LIGHT ? "светлая" : "тёмная"}
+                            </Text>
+                            <Button theme={EButtonTheme.GENERAL} size={EComponentSize.MD} onClick={handleToggleClick}>
+                                Переключить тему
+                            </Button>
+                        </div>
+                    </CardStatic.Content>
+                </CardStatic>
+            </div>
+        </ThemeProvider>
+    );
+};
+```
 
-Отдельных stories нет — оборачивает все остальные компоненты в Storybook на уровне preview.
+### ScopedTheme
 
----
+`stories/ThemeProvider/examples/ScopedTheme.tsx`
 
-## История изменений
+```tsx
+import React, { useRef } from "react";
+import {
+    ThemeProvider,
+    ETriplexNextTheme,
+    Button,
+    EButtonTheme,
+    EComponentSize,
+    CardStatic,
+    ECardContentPaddingSize,
+    Text,
+    ETextSize,
+} from "@sberbusiness/triplex-next";
+
+export const ScopedTheme = () => {
+    const darkScopeRef = useRef<HTMLDivElement>(null);
+
+    // Обе области — одинаковая разметка. Отличается только тема: вторая обёрнута в ThemeProvider.
+    const content = (label: string) => (
+        <CardStatic>
+            <CardStatic.Content paddingSize={ECardContentPaddingSize.MD}>
+                <div style={{ display: "flex", flexDirection: "column", alignItems: "flex-start", gap: 16 }}>
+                    <Text size={ETextSize.B1}>{label}</Text>
+                    <Button theme={EButtonTheme.SECONDARY} size={EComponentSize.MD}>
+                        Button text
+                    </Button>
+                </div>
+            </CardStatic.Content>
+        </CardStatic>
+    );
+
+    return (
+        <div style={{ display: "flex", flexDirection: "column", gap: 24 }}>
+            {content("Область вне ThemeProvider — тема приложения.")}
+
+            <ThemeProvider theme={ETriplexNextTheme.DARK} scopeRef={darkScopeRef}>
+                <div ref={darkScopeRef}>
+                    {content("Область с тёмной темой — css-переменные действуют только здесь.")}
+                </div>
+            </ThemeProvider>
+        </div>
+    );
+};
+```
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |