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

package/bundle/components/Alert.md

@@ -0,0 +1,317 @@
+---
+component: Alert
+category: Alerts
+figma-node: ""
+figma-file: ""
+related: [Notification, Typography, ButtonIcon, Spoiler]
+tokens:
+  - --triplex-next-AlertContext-Error_Color
+  - --triplex-next-AlertContext-Info_Color
+  - --triplex-next-AlertContext-Warning_Color
+  - --triplex-next-AlertContext-System_Color
+  - --triplex-next-AlertProcess-Error_Background
+  - --triplex-next-AlertProcess-Info_Background
+  - --triplex-next-AlertProcess-Warning_Background
+  - --triplex-next-AlertProcess-System_Background
+  - --triplex-next-AlertProcess-Feature_Background
+stories:
+  - stories/Alerts/AlertContext.stories.tsx
+  - stories/Alerts/AlertProcess.stories.tsx
+version: "1.0"
+---
+
+# Alert
+
+## Назначение
+
+Компоненты для отображения статусных/предупреждающих сообщений. Папка `Alert` содержит
+две независимые реализации под разные сценарии:
+
+- **`AlertContext`** — короткое inline-сообщение в виде строки с иконкой (`<span>`).
+  Применяется рядом с полями форм, таблицами, виджетами для уточнения контекста.
+- **`AlertProcess`** — блочное предупреждение с фоном, заголовком, кнопкой закрытия
+  и опциональным спойлером для скрытия расширенного контента. Применяется как
+  самостоятельный информационный блок на странице.
+
+Оба компонента разделяют один набор семантических типов (`EAlertType`).
+
+Используй `AlertContext` когда: нужна короткая одна-две строки подсказки без фона
+(пример: сообщение об ошибке валидации рядом с полем).
+Используй `AlertProcess` когда: нужен заметный блок с фоном, многострочный контент,
+возможность закрытия или спойлер (пример: системное уведомление в начале страницы).
+Не используй когда: нужен toast/тост — используй `Notification`.
+
+---
+
+## Файловая структура
+
+```text
+src/components/Alert/
+├── EAlertType.ts                    # Enum общих типов (INFO, WARNING, ERROR, SYSTEM, FEATURE)
+├── AlertTypeUtils.tsx               # ALERT_TYPE_TO_CLASS_NAME_MAP — маппинг type → styles.alertType{Xxx}
+├── index.ts                         # Barrel: AlertContext, AlertProcess + Spoiler, EAlertType, EAlertProcessBorderRadius
+├── AlertContext/
+│   ├── AlertContext.tsx             # <span role="alert"> с иконкой и Text
+│   ├── styles/AlertContext.module.less
+│   └── __tests__/AlertContext.test.tsx
+└── AlertProcess/
+    ├── AlertProcess.tsx             # <div> с фоном, иконкой, закрытием, Object.assign({Spoiler})
+    ├── AlertProcessContext.ts       # Context для коммуникации AlertProcess ↔ AlertProcess.Spoiler
+    ├── enums.ts                     # EAlertProcessBorderRadius (MD, LG)
+    ├── components/AlertProcessSpoiler.tsx  # AlertProcess.Spoiler — раскрывающийся блок
+    ├── styles/AlertProcess.module.less
+    └── __tests__/AlertProcess.test.tsx
+```
+
+Особенности:
+- Два независимых компонента в одной папке — не объединять, у них разная структура,
+  семантика и визуал.
+- Общий enum `EAlertType` и утилита `ALERT_TYPE_TO_CLASS_NAME_MAP` намеренно вынесены
+  на уровень выше — это единственный переиспользуемый код между `AlertContext` и
+  `AlertProcess`.
+
+---
+
+## Варианты и props
+
+### Общий enum `EAlertType`
+
+| Значение | Цвет иконки (paletteIndex) | Поддерживает AlertContext | Поддерживает AlertProcess |
+|---|---|---|---|
+| `INFO` | `3` (синий) | Да | Да |
+| `WARNING` | `2` (жёлтый) | Да | Да |
+| `ERROR` | `1` (красный) | Да | Да |
+| `SYSTEM` | `4` (фиолетовый) | Да | Да |
+| `FEATURE` | `0` (neutral) | **Нет** — запрещён через `Exclude<EAlertType, EAlertType.FEATURE>` | Да (default icon = `DefaulticonStrokePrdIcon20`) |
+
+### `AlertContext` — `IAlertContextProps extends React.HTMLAttributes<HTMLSpanElement>`
+
+| Prop | Тип | Обязателен | Описание |
+|---|---|---|---|
+| `type` | `Exclude<EAlertType, EAlertType.FEATURE>` | Да | Семантический тип. FEATURE запрещён на уровне типов. |
+| `renderIcon` | `React.ReactNode` | Нет | Кастомная иконка. Если не передана — рендерится дефолтная 16px иконка, соответствующая `type`. |
+| `children` | `React.ReactNode` | Нет | Текст сообщения — заворачивается в `<Text size={B4} type={...}>`. |
+| `...HTMLSpanAttributes` | — | — | Все стандартные атрибуты `<span>`, включая `className`. |
+
+### `AlertProcess` — `IAlertProcessProps extends React.HTMLAttributes<HTMLDivElement>`
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `type` | `EAlertType` | — (обязателен) | Любой из пяти типов, включая `FEATURE`. |
+| `closable` | `boolean` | `false` | Если `true` — добавляется `ButtonIcon` с крестиком в правом верхнем углу. |
+| `onClose` | `() => void` | — | Коллбек при нажатии на крестик. AlertProcess сам скрывает себя (`closed` state). |
+| `renderIcon` | `React.ReactNode` | — | Кастомная иконка слева. По умолчанию — дефолтная 20px иконка по `type`. |
+| `borderRadius` | `EAlertProcessBorderRadius` | `MD` (12px) | `MD` = 12px, `LG` = 24px. |
+| `children` | `React.ReactNode` | — | **Без Typography не задаёт стили текста** — потребитель сам заворачивает текст в `Typography`-компоненты. Может содержать `AlertProcess.Spoiler`. |
+| `...HTMLDivAttributes` | — | — | Все стандартные атрибуты `<div>`. |
+
+### `AlertProcess.Spoiler` — `IAlertProcessSpoilerProps extends React.HTMLAttributes<HTMLDivElement>`
+
+Доступен через `Object.assign` как property компонента: `<AlertProcess.Spoiler>`.
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `open` | `boolean` | Контролируемое состояние раскрытия. Неконтролируемого режима нет. |
+| `onOpen` | `(open: boolean) => void` | Коллбек при клике на треугольник. Потребитель обязан обновить `open`. |
+| `children` | `React.ReactNode` | Скрываемый контент. |
+
+`EAlertProcessBorderRadius` — enum: `MD = "md"`, `LG = "lg"`.
+
+---
+
+## Ключевые особенности реализации
+
+### `ALERT_TYPE_TO_CLASS_NAME_MAP` принимает `styles` аргументом
+
+```ts
+[EAlertType.INFO]: (styles) => styles.alertTypeInfo
+```
+
+Маппинг — не прямой `type → "alertTypeInfo"`, а **функция `(styles) => string`**. Это
+потому что CSS-модули отдают хэшированные имена, и каждая локация (`AlertContext`,
+`AlertProcess`) импортирует свои стили. Передача `styles` в маппинг позволяет
+переиспользовать его без дублирования кода под разные CSS-модули.
+
+При добавлении нового `EAlertType` — добавляй ключ в `ALERT_TYPE_TO_CLASS_NAME_MAP`
+**и** соответствующий класс `.alertType{Xxx}` в оба LESS-файла
+(`AlertContext.module.less`, `AlertProcess.module.less`).
+
+### `AlertContext.tsx`: маппинг type → `EFontType` для Text
+
+```ts
+alertTypeToFontTypeMap = {
+    INFO: EFontType.INFO,
+    WARNING: EFontType.WARNING,
+    ERROR: EFontType.ERROR,
+    SYSTEM: EFontType.SECONDARY,  // ← SYSTEM использует SECONDARY, не SYSTEM
+}
+```
+
+`SYSTEM` маппится в `SECONDARY` намеренно — цвет текста для системных сообщений
+совпадает со вторичным текстом. Не менять без дизайнерского согласования.
+
+### `AlertProcess`: closed-state держится внутри компонента
+
+При клике на крестик AlertProcess устанавливает `closed=true` и возвращает `null`.
+Повторно показать тот же инстанс нельзя — потребитель должен либо перерендерить
+его с новым key, либо управлять видимостью снаружи (не через `closable`, а своим
+if/else). `onClose` здесь — сигнал "пользователь закрыл", а не контролируемое
+состояние.
+
+### `AlertProcessContext` и `Spoiler` ↔ `AlertProcess` коммуникация
+
+`AlertProcess.Spoiler` в `useEffect` устанавливает `hasSpoiler=true` в контексте
+при монтировании и сбрасывает при размонтировании. `AlertProcess` читает `hasSpoiler`
+и добавляет класс `.withSpoiler` (min-height: 40px), чтобы оставить место под
+кнопку раскрытия.
+
+Без `AlertProcess.Spoiler` внутри `AlertProcess` контекст не имеет эффекта —
+дефолтные значения (`hasSpoiler: false`, `setHasSpoiler: noop`) безопасны.
+
+### `Object.assign(forwardRef, { Spoiler })` для compound-компонента
+
+```tsx
+export const AlertProcess = Object.assign(
+    React.forwardRef(...),
+    { Spoiler: AlertProcessSpoiler },
+);
+```
+
+Делает `AlertProcess.Spoiler` доступным как property. Альтернативный паттерн
+(`AlertProcess.Spoiler = AlertProcessSpoiler` без Object.assign) не работает
+с forwardRef в TypeScript — теряется типизация Spoiler. Не упрощать.
+
+`displayName` и `Spoiler` устанавливаются **повторно** после Object.assign
+(`AlertProcess.displayName = ...`, `AlertProcess.Spoiler = ...`) — это тоже
+особенность из-за ограничений TS, не убирать.
+
+### `AlertProcessSpoiler`: анимация через max-height в LESS
+
+Максимальная высота = 1000px (`max-height: 1000px`) — жёсткий лимит. Контент
+выше 1000px будет обрезан. При необходимости — увеличить константу в LESS.
+
+### `data-tx={process.env.npm_package_version}`
+
+Оба компонента ставят `data-tx` с версией пакета — используется для аналитики
+и дебага "из какой версии библиотеки отрендерилось". Не удалять.
+
+---
+
+## Инварианты
+
+- **`AlertContext` — `<span role="alert">`**, не `<div>`. Инлайн-семантика важна:
+  компонент задуман как inline-блок рядом с полями форм.
+- **`AlertContext` type НЕ принимает `FEATURE`** — тип `Exclude<EAlertType, EAlertType.FEATURE>`.
+  Если нужен FEATURE-контекст — создавай отдельный компонент, не расширяй AlertContext.
+- **`AlertProcess` — `<div>`**, не `<section>` или `<aside>`. Семантическую роль
+  потребитель может задать через `role` в props.
+- **`forwardRef`** — обязателен на `AlertContext` и `AlertProcess`. Не убирать.
+- **`AlertProcessSpoiler` — обычный `React.FC`** без forwardRef. Исключение из
+  общего правила: компонент внутренний к `AlertProcess`, ref на его root не имеет
+  публичной ценности. Можно привести к forwardRef в рамках AI refactoring, но это
+  breaking — изменит сигнатуру типа `AlertProcess.Spoiler`.
+- **`EAlertType` значения** (`"info"`, `"warning"`, `"error"`, `"system"`, `"feature"`) —
+  публичное API, не переименовывать.
+- **`EAlertProcessBorderRadius`** (`"md"`, `"lg"`) — публичное API, не переименовывать.
+- **Toggle-логика `Spoiler`** — полностью controlled (`open` + `onOpen`). Не добавлять
+  uncontrolled fallback без согласования API.
+- **`paletteIndex` у иконок** — часть контракта с `@sberbusiness/icons-next`. Не
+  менять без согласования с дизайн-токенами цветовых палитр.
+- **`data-tx`** — использовать `process.env.npm_package_version` (Vite подставляет
+  во время сборки). Не хардкодить.
+
+---
+
+## Accessibility
+
+### AlertContext
+- **`role="alert"`** — объявление "alert" для screen reader. Screen reader прерывает
+  чтение и зачитывает новое содержимое при появлении элемента. Не убирать role.
+- **Полностью inline** — текст доступен как текст, иконка декоративна. Если нужно
+  явно скрыть иконку от screen reader — потребитель передаёт `renderIcon` с
+  `aria-hidden="true"`.
+
+### AlertProcess
+- **Нет `role`** по умолчанию — компонент трактуется как обычный блок контента.
+  Если сообщение критическое, потребитель обязан передать `role="alert"` или
+  `role="status"` через `...rest`.
+- **Кнопка закрытия (`ButtonIcon`)** не имеет встроенного `aria-label` — это
+  баг/пробел: потребитель должен знать, что ButtonIcon требует `aria-label` от него.
+  В текущей реализации `AlertProcess` НЕ пробрасывает возможность задать
+  `aria-label` на кнопку закрытия. При AI refactoring — добавить prop `closeAriaLabel`.
+- **Spoiler toggle** — `ButtonIcon` с иконкой каретки, тоже без `aria-expanded`
+  и `aria-label`. Тот же баг a11y, тот же план.
+- **Клавиатура**: `ButtonIcon` — нативный `<button>`, работает Tab/Enter/Space.
+  Никаких фокус-ловушек или кастомной навигации компонент не добавляет.
+
+---
+
+## Дизайн-токены
+
+**AlertContext** — только цвета текста:
+```
+--triplex-next-AlertContext-{Error|Info|Warning|System}_Color
+```
+У SYSTEM отдельного токена нет — используется цвет SECONDARY-типа из Typography.
+
+**AlertProcess** — только фон блока:
+```
+--triplex-next-AlertProcess-{Error|Info|Warning|System|Feature}_Background
+```
+
+Цвет текста внутри `AlertProcess` задаёт потребитель через `Typography`-компоненты,
+компонент-обёртка не хардкодит.
+
+---
+
+## Связанные компоненты
+
+- `Typography` (`Text`, `Title`) — `AlertContext` использует `Text` внутри;
+  `AlertProcess` ожидает Typography-компоненты в `children` от потребителя.
+- `ButtonIcon` (`src/components/Button/ButtonIcon.tsx`) — используется для кнопок
+  закрытия и раскрытия спойлера.
+- `@sberbusiness/icons-next` — источник дефолтных иконок
+  (`InfoStrokeStsIcon16/20`, `WarningStrokeStsIcon16/20`, `ErrorStrokeStsIcon16/20`,
+  `SystemStrokeStsIcon16/20`, `DefaulticonStrokePrdIcon20`, `CrossStrokeSrvIcon16`,
+  `CaretdownStrokeSrvIcon16`).
+- `Notification` (`src/components/Notification`) — похожий по назначению, но
+  toast-формат (поверх контента, авто-закрытие).
+- `Spoiler` (`src/components/Spoiler`) — отдельный компонент для сворачиваемого
+  контента. `AlertProcess.Spoiler` не использует его, реализация своя (проще).
+
+---
+
+## Stories
+
+`AlertContext`: `stories/Alerts/AlertContext.stories.tsx`
+Файлы примеров: `stories/Alerts/examples/AlertContext/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `type` и `children` |
+| `Default` | `DefaultExample.tsx` | Базовое использование с INFO |
+| `Types` | `TypesExample.tsx` | Все 4 типа (без FEATURE) |
+| `WithCustomIcon` | `WithCustomIconExample.tsx` | Переопределение иконки через `renderIcon` |
+
+`AlertProcess`: `stories/Alerts/AlertProcess.stories.tsx`
+Файлы примеров: `stories/Alerts/examples/AlertProcess/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `type`, `closable`, `borderRadius`, `children` |
+| `Default` | `DefaultExample.tsx` | Базовое использование |
+| `Types` | `TypesExample.tsx` | Все 5 типов (включая FEATURE) |
+| `BorderRadius` | `BorderRadiusExample.tsx` | MD (12px) vs LG (24px) |
+| `WithCustomIcon` | `WithCustomIconExample.tsx` | Кастомная иконка |
+| `Closable` | `ClosableExample.tsx` | Кнопка закрытия |
+| `WithButtonLink` | `WithButtonLinkExample.tsx` | Кнопка-ссылка в контенте |
+| `WithLink` | `WithLinkExample.tsx` | Обычная ссылка в контенте |
+| `WithSpoiler` | `WithSpoilerExample.tsx` | Использование `AlertProcess.Spoiler` |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/Amount.md

@@ -0,0 +1,225 @@
+---
+component: Amount
+category: Display
+figma-node: ""
+figma-file: ""
+related: [AmountField, Typography]
+tokens: []
+stories: stories/Amount/Amount.stories.tsx
+version: "1.0"
+---
+
+# Amount
+
+## Назначение
+
+Display-компонент для отображения денежной суммы. Форматирует число с разделителями
+групп (неразрывный пробел) и фиксированной дробной частью, опционально добавляет
+сокращение валюты справа и подсказку через `title`. Поддерживает адаптивное
+уменьшение шрифта при длинных значениях.
+
+Компонент **только визуализирует**, не принимает ввод — для поля ввода денежной
+суммы используй `AmountField`.
+
+Используй когда: нужно вывести сумму в тексте, таблице, детали карточки. Когда
+важна единая визуальная форма отображения чисел по всей библиотеке.
+Не используй когда: сумму нужно вводить (возьми `AmountField`); нужна произвольная
+числовая метка без валюты и форматирования (используй обычный `Text`).
+
+---
+
+## Файловая структура
+
+```text
+src/components/Amount/
+├── Amount.tsx                     # React.FC, НЕ forwardRef
+├── index.ts                       # Barrel export
+├── styles/Amount.module.less      # Только .adaptive класс
+└── __tests__/Amount.test.tsx
+```
+
+Зависимости:
+- `@sberbusiness/triplex-next/utils/amountUtils` → `formatAmount` (использует `big.js`).
+- `@sberbusiness/triplex-next/consts/AmountConst` → константы разделителей
+  (`DecimalComma`, `DecimalPoint`, `GroupSeparator`).
+
+---
+
+## Варианты и props
+
+### `IAmountProps extends React.HTMLAttributes<HTMLSpanElement>`
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `value` | `string` | — (обязателен) | Числовое значение как строка. Может содержать `.` или `,`, пробелы, знак `+`/`-`. Внутри форматируется через `big.js` → устойчиво к floating-point. |
+| `fractionLength` | `0 \| 1 \| 2 \| 3 \| 4` | `2` (из `AmountConst.FractionLength`) | Количество знаков после запятой. Тип **литерал-union** — нельзя передать произвольный `number`. Для `0` потребитель обязан передать **именно `0`**, не `null`/`undefined` (undefined даст дефолт 2). |
+| `currency` | `string` | — | Если указан — справа от суммы добавляется `\u00A0{currency}` (неразрывный пробел + строка). Не задано → валюта не отображается. |
+| `currencyTitle` | `string` | — | Подсказка (title-атрибут) для валюты — обычно полное название ("Российские рубли" для "RUB"). Применяется к `<span>`, обёрнутому вокруг currency. |
+| `adaptive` | `boolean` | `false` | Если `true` и длина форматированной строки ≥ 14 — добавляется класс `.adaptive` (font-size: 10px, line-height: 12px через `!important`). |
+| `dataTestId` | `string` | — | **Кастомный prop**, не пробрасывается на root `<span>`. Используется только для `data-test-id` на внутренние `<span>` (суффиксы `__amount`, `__currencyName`). |
+| `className` | `string` | — | Объединяется с `.adaptive` через `clsx`. |
+| `...HTMLSpanAttributes` | — | — | Всё остальное спредится на root `<span>`. |
+
+---
+
+## Ключевые особенности реализации
+
+### Компонент — `React.FC`, НЕ `forwardRef`
+
+```tsx
+export const Amount: React.FC<IAmountProps> = ({ ... }) => { ... }
+```
+
+Это **исключение из правила библиотеки про обязательный forwardRef**. Причина
+исторически неизвестна; при AI refactoring компонент должен быть переведён на
+`React.forwardRef<HTMLSpanElement, IAmountProps>`. Это non-breaking изменение.
+До рефакторинга — не добавлять ref-логику, она не пройдёт TypeScript.
+
+### `dataTestId` — НЕ `data-testid`
+
+Имя prop — camelCase `dataTestId`. Пропускается через проп-деструктуризацию и
+применяется только к внутренним спанам:
+- `{dataTestId}__amount` — на спан с самим числом.
+- `{dataTestId}__currencyName` — на спан с валютой.
+
+На root `<span>` `dataTestId` не попадает автоматически — потребитель, если нужно,
+передаёт `data-test-id` через `...restProps`. Это намеренная двухуровневая
+структура для тестов.
+
+### Замена дефис-минуса на настоящий знак минус
+
+```ts
+if (formattedAmount[0] == "-") {
+    formattedAmount = formattedAmount.replace("\u002D", "\u2212");
+}
+```
+
+`\u002D` — ASCII hyphen-minus, `\u2212` — Unicode MINUS SIGN. Screen reader
+корректно произносит `\u2212` как "минус", а `\u002D` обычно читается как "дефис"
+или пропускается. **Не убирать** — это осознанная a11y-особенность.
+
+Замена применяется ТОЛЬКО в первой позиции — если минус в середине (например,
+разделитель диапазона "100–200"), он не будет заменён.
+
+### Неразрывный пробел перед валютой
+
+```tsx
+renderCurrencyName = () => [
+    "\u00A0",  // NBSP
+    <span ...>{currency}</span>,
+]
+```
+
+Между числом и валютой вставляется NBSP (`\u00A0`), не обычный пробел. Это
+предотвращает перенос валюты на следующую строку при переполнении.
+
+### Адаптивный шрифт через `!important`
+
+`.adaptive { font-size: 10px !important; line-height: 12px !important; }` —
+`!important` нужен, чтобы перебить родительский Typography-стиль. Если потребитель
+хочет переопределить размер — `className` с более специфичным селектором тоже
+должен использовать `!important`. Это компромисс ради надёжного поведения
+в контексте таблиц/карточек.
+
+Порог `adaptiveAmountLength = 14` — длина именно **форматированной** строки (после
+вставки разделителей групп). Не равна количеству значащих цифр.
+
+### `formatAmount` — большая часть логики вне компонента
+
+`Amount.tsx` — тонкая обёртка. Вся сложность форматирования в `utils/amountUtils.ts`:
+- Использует `big.js` для чисел (устойчиво к floating-point).
+- `Big.RM = 0` — режим без округления (truncate).
+- Принимает запятую и точку как десятичный разделитель.
+- Поддерживает знак "+" (сохраняется в выводе).
+- Поддерживает `separateGroups` и `fillFraction` — но **Amount не прокидывает эти
+  флаги**. Для customизации форматирования нужно расширить Amount или использовать
+  `formatAmount` напрямую.
+
+### `data-tx={process.env.npm_package_version}`
+
+На root `<span>` выставляется `data-tx` с версией пакета (Vite подставляет при
+сборке). Не удалять.
+
+---
+
+## Инварианты
+
+- **`IAmountProps extends React.HTMLAttributes<HTMLSpanElement>`** — не менять на
+  `HTMLDivElement`. Компонент inline по дизайну.
+- **`value` только `string`** — не `number`, не `Big`. Компонент не принимает
+  `number` напрямую (в отличие от `formatAmount`, который принимает `string | Big`).
+  Потребитель должен сам привести число к строке.
+- **`fractionLength` литеральный union `0 \| 1 \| 2 \| 3 \| 4`** — не расширять
+  до `number`, это ограничение защищает от визуально уродливых значений (20 знаков).
+- **Замена `\u002D` → `\u2212` в минусе** — не удалять. A11y.
+- **NBSP (`\u00A0`) перед валютой** — не заменять на обычный пробел.
+- **`dataTestId` как camelCase prop** — не переименовывать в `data-testid` без
+  breaking-change согласования.
+- **`.adaptive` с `!important`** — не убирать `!important` без параллельной
+  правки потребителей (которые полагаются на его работу в таблицах).
+- **`adaptiveAmountLength = 14`** — константа внутри файла, не выносить в props
+  без дизайнерского согласования.
+- **`formatAmount` вызов не мемоизируется** — если это станет bottleneck (большие
+  таблицы), оборачивай Amount в `React.memo` снаружи. Не добавлять `useMemo`
+  внутрь без профиля.
+
+---
+
+## Accessibility
+
+- **Замена дефиса на настоящий минус (`\u2212`)** — screen reader корректно
+  озвучивает знак "минус". Это ключевая a11y-особенность компонента.
+- **`currency` как отдельный `<span>`** внутри — позволяет потребителю, при
+  необходимости, добавить `aria-label` через children override.
+- **`title={currencyTitle}`** — при наведении курсора показывает полное название
+  валюты (например, "Российские рубли" для "RUB"). Screen reader читает title
+  как дополнительное описание.
+- **Нет `aria-label` по умолчанию** — если нужно озвучить значение целиком с валютой
+  ("восемь миллионов девятьсот шестьдесят семь тысяч четыреста пятьдесят два рубля
+  тридцать одна копейка"), потребитель должен сформировать его сам и передать
+  через `aria-label` в `...restProps`. Автоматического склонения названия валюты
+  компонент не делает.
+
+---
+
+## Дизайн-токены
+
+Нет — компонент не хардкодит цветов и использует наследуемый от родителя шрифт.
+Единственное исключение — класс `.adaptive` с фиксированными `10px/12px`
+(не через токены). Это кандидат на рефакторинг с введением токенов.
+
+---
+
+## Связанные компоненты
+
+- `AmountField` (`src/components/AmountField`) — input-аналог для ввода суммы.
+  Использует тот же `formatAmount` и ту же знак-замену.
+- `Typography` — Amount наследует шрифт от родителя; обычно оборачивается в
+  `Text` / `Title` нужного размера.
+- `formatAmount` / `amountComparator` (`src/utils/amountUtils.ts`) — утилиты,
+  которые Amount использует внутри, но также могут быть использованы напрямую
+  потребителем для консистентного форматирования в местах, где Amount-компонент
+  не подходит.
+- `AmountConst` (`src/consts/AmountConst`) — источник констант:
+  `FractionLength=2`, `DecimalComma=","`, `DecimalPoint="."`, `GroupSeparator="\u00A0"`.
+
+---
+
+## Stories
+
+`stories/Amount/Amount.stories.tsx`
+Файлы примеров: `stories/Amount/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль всех props |
+| `Default` | `DefaultExample.tsx` | Базовое использование с RUB |
+| `Example` | `ShowcaseExample.tsx` | Расширенный пример (разные значения, знаки) |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |