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

package/bundle/components/Amount.md

@@ -1,9 +1,7 @@
 ---
 component: Amount
-category: Display
-figma-node: ""
-figma-file: ""
-related: [AmountField, Typography]
+category: Amount
+related: [AmountField, Text, StatusTrackerSum, TableFooterSummaryAmount]
 tokens: []
 stories: stories/Amount/Amount.stories.tsx
 version: "1.0"
@@ -13,208 +11,171 @@ version: "1.0"
 
 ## Назначение
 
-Display-компонент для отображения денежной суммы. Форматирует число с разделителями
-групп (неразрывный пробел) и фиксированной дробной частью, опционально добавляет
-сокращение валюты справа и подсказку через `title`. Поддерживает адаптивное
-уменьшение шрифта при длинных значениях.
-
-Компонент **только визуализирует**, не принимает ввод — для поля ввода денежной
-суммы используй `AmountField`.
-
-Используй когда: нужно вывести сумму в тексте, таблице, детали карточки. Когда
-важна единая визуальная форма отображения чисел по всей библиотеке.
-Не используй когда: сумму нужно вводить (возьми `AmountField`); нужна произвольная
-числовая метка без валюты и форматирования (используй обычный `Text`).
+Отображение денежной суммы: строковое значение приводится к читаемому виду
+(`8967452.31` → `8 967 452,31`) и при необходимости дополняется сокращённым обозначением
+валюты. Компонент — inline-обёртка над `formatAmount` из `src/utils/amountUtils.ts`, без
+внутреннего состояния и эффектов. Базового собственного оформления у него нет: цвет, размер и
+начертание наследуются от родителя, поэтому в примерах он всегда стоит внутри `Text`.
+Единственное исключение — `adaptive={true}`, при котором компонент применяет собственный
+`styles.adaptive` с фиксированными `font-size` / `line-height` (см. «Как работает `adaptive`»).
+
+Используй когда: нужно вывести сумму «только на чтение» — в карточке, таблице, заголовке,
+подытоге.
+
+Не используй когда:
+- Сумму нужно вводить или редактировать — возьми `AmountField` (у него собственные парсер и
+  форматтер `AmountBaseInputParser` / `AmountBaseInputFormatter`).
+- Нужно отформатировать число не для вывода, а для расчётов или строкового сравнения —
+  вызывай `formatAmount` / `amountComparator` из `@sberbusiness/triplex-next` напрямую, без
+  компонента. Импортируй именно с корня пакета: subpath `./utils/*` в `exports` не попадает
+  (`scripts/generate-package-json.js`), поэтому импорт из
+  `@sberbusiness/triplex-next/utils/amountUtils` у потребителя упадёт с
+  `ERR_PACKAGE_PATH_NOT_EXPORTED`.
 
 ---
 
-## Файловая структура
-
-```text
-src/components/Amount/
-├── Amount.tsx                     # React.FC, НЕ forwardRef
-├── index.ts                       # Barrel export
-├── styles/Amount.module.less      # Только .adaptive класс
-└── __tests__/Amount.test.tsx
-```
+## Варианты и props
 
-Зависимости:
-- `@sberbusiness/triplex-next/utils/amountUtils` → `formatAmount` (использует `big.js`).
-- `@sberbusiness/triplex-next/consts/AmountConst` → константы разделителей
-  (`DecimalComma`, `DecimalPoint`, `GroupSeparator`).
+Компонент расширяет `React.HTMLAttributes<HTMLSpanElement>`: любой стандартный атрибут
+`<span>` (`id`, `style`, `title`, `data-*`, обработчики) уходит на корневой элемент через
+`...rest`.
 
----
+### Обязательные props
 
-## Варианты и props
+| Prop | Тип | Описание |
+|---|---|---|
+| `value` | `string` | Сумма строкой. Допустимы разделитель дробной части `.` или `,`, пробелы внутри числа и ведущий знак `+` / `-` |
 
-### `IAmountProps extends React.HTMLAttributes<HTMLSpanElement>`
+### Опциональные props
 
 | 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>`. |
+| `fractionLength` | `0 \| 1 \| 2 \| 3 \| 4` | `2` (`AmountConst.FractionLength`) | Количество знаков после запятой |
+| `currency` | `string` | — | Сокращённое обозначение валюты, выводится после суммы через неразрывный пробел |
+| `currencyTitle` | `string` | — | Значение атрибута `title` на элементе валюты — расшифровка кода (`RUB` → «Российские рубли») |
+| `adaptive` | `boolean` | `false` | Уменьшает шрифт, если форматированная сумма длиннее порога |
+| `dataTestId` | `string` | — | Префикс тестовых атрибутов дочерних элементов |
+
+### Как обрабатывается `value`
+
+Всю логику форматирования выполняет `formatAmount(value, fractionLength)`; компонент только
+подменяет знак минуса (см. Accessibility). Существенные для потребителя следствия:
+
+- **Дробная часть обрезается, а не округляется** — внутри `formatAmount` выставлен
+  `Big.RM = 0`. `"1234.567"` при `fractionLength={2}` даёт `1 234,56`, а не `1 234,57`.
+- **Нечисловое значение не бросает исключение**, а превращается в ноль: `"abc"` → `0,00`.
+  Это осознанное поведение библиотеки — компонент не должен падать в рантайме у потребителя.
+- **Пустая строка даёт пустой вывод** — рендерятся пустые `<span>`, а не `0,00`. Если при этом
+  задан `currency`, выводятся неразрывный пробел и обозначение валюты: сумма пустая, а валюта
+  остаётся (ветка отрисовки валюты не смотрит на то, пуста ли сумма). Отсекать пустые значения,
+  если такой вывод нежелателен, нужно на стороне потребителя.
+- **Ведущий `+` сохраняется**, ведущий `-` заменяется на знак минуса.
+- Разделитель групп — неразрывный пробел `U+00A0` (`AmountConst.GroupSeparator`), разделитель
+  дробной части — запятая (`AmountConst.DecimalComma`). Оба не настраиваются через props,
+  локализация формата не поддерживается.
+
+### Как работает `adaptive`
+
+`adaptive` не задаёт размер напрямую, а включает класс `styles.adaptive`
+(`font-size: 10px`, `line-height: 12px`), когда длина **форматированной суммы** достигает
+`ADAPTIVE_AMOUNT_LENGTH = 14` символов. Нюансы:
+
+- Считается строка после форматирования, вместе с разделителями групп и дробной частью:
+  `"12 345 678,00"` — 13 символов, шрифт не уменьшается; `"123 456 789,00"` — 14, уменьшается.
+- Обозначение валюты в длину **не входит**.
+- Знак минуса в длину **входит** — она меряется уже после замены дефис-минуса. У одной и той
+  же суммы адаптив может включиться только из-за знака: `"12 345 678,00"` — 13 символов, без
+  адаптива, а `"−12 345 678,00"` — ровно 14, с адаптивом.
+- Размер фиксированный (10px) — промежуточных ступеней нет, от размера родительского `Text`
+  результат не зависит.
 
 ---
 
-## Ключевые особенности реализации
-
-### Компонент — `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 подставляет при
-сборке). Не удалять.
+Собственных токенов у компонента нет: `styles/Amount.module.less` содержит единственное
+правило `.adaptive` с литеральными `font-size` / `line-height`. Цвет и базовый размер шрифта
+задаёт родитель — обычно `Text` (`ETextSize`, `EFontType`), см. примеры в stories.
 
 ---
 
 ## Инварианты
 
-- **`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`
-  внутрь без профиля.
+- **`forwardRef` на корневой `<span>`** — не убирать. Ref указывает на тот же элемент, что
+  получает `className` и `...rest` (с 1.42.0).
+- **`data-tx` выставляется после `{...restProps}`** — поэтому потребитель не может его
+  перетереть через props. Позиции `className` и `ref` в JSX на поведение не влияют
+  (`className` деструктурирован и мерджится через `clsx`, `ref` в `restProps` попасть не может).
+- **Разметка фиксирована:** корневой `<span>` → `<span>` с суммой → (при наличии `currency`)
+  неразрывный пробел текстовым узлом → `<span>` с валютой. Валюта отдельным элементом нужна
+  для `title` и для тестового атрибута; неразрывный пробел — чтобы валюта не отрывалась от
+  суммы при переносе строки.
+- **Замена `-` на `−`** — accessibility-контракт, см. ниже. Не «упрощать» обратно
+  до дефиса.
+- **`dataTestId` — префикс, а не готовый атрибут.** На корневой элемент `data-test-id` не
+  ставится; дочерние получают `${dataTestId}__amount` и `${dataTestId}__currencyName`. Схема
+  именования — часть публичного контракта, на неё опираются e2e потребителей.
+- **`IAmountProps` — не только props этого компонента.** `StatusTrackerSum` строит из него
+  свой публичный интерфейс: `amountProps: IAmountProps` в `IStatusTrackerSumProps`
+  (`src/components/StatusTracker/components/StatusTrackerSum.tsx`). Любое изменение формы
+  `IAmountProps` автоматически меняет публичный API `StatusTracker`.
+- **`!important` в `.adaptive`** — достался исторически, причина в репозитории не
+  зафиксирована. Внутренние потребители кладут `Amount` внутрь `Title` / `Text`, а не
+  навешивают их класс на него, то есть сценария, требующего `!important`, внутри библиотеки
+  нет. Снимать — только вместе с прогоном visual-тестов.
+- **`displayName = "Amount"`** — используется в React DevTools.
 
 ---
 
 ## 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`
-(не через токены). Это кандидат на рефакторинг с введением токенов.
+- **Знак минуса.** `formatAmount` возвращает отрицательные суммы с дефис-минусом `-`.
+  Как его озвучит скрин-ридер, зависит от контекста и настроек пунктуации: перед числом он
+  часто читается как «минус», но может и игнорироваться, и давать паузу. Типографский минус
+  `−` (U+2212) распознаётся однозначно, поэтому компонент подменяет символ — так озвучивание
+  перестаёт зависеть от AT и её настроек. Замена делается только для первого символа —
+  внутри числа дефисов не бывает.
+- **Неразрывный пробел** между суммой и валютой (`U+00A0`) удерживает их на одной строке.
+- Компонент неинтерактивен: не получает фокус, не обрабатывает клавиатуру, ARIA-ролей не
+  выставляет. Семантику («Итого», «Остаток») даёт окружающая разметка.
+- `currencyTitle` попадает в `title` — это подсказка по наведению, а не доступное имя.
+  Строка приходит от потребителя, компонент текст не хардкодит (библиотека мультиязычная).
+- Компонент не выставляет `aria-label` с суммой прописью: текстовое содержимое читается
+  скрин-ридером как есть.
 
 ---
 
 ## Связанные компоненты
 
-- `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"`.
+- `AmountField` (`src/components/AmountField/AmountField.tsx`) — поле ввода суммы.
+  Использует не `Amount`, а собственные `AmountBaseInputParser` / `AmountBaseInputFormatter`;
+  общего кода с `Amount` у него нет, кроме `AmountConst`.
+- `Text` (`src/components/Typography/Text.tsx`) — типовой родитель: задаёт размер, цвет
+  (`EFontType.BRAND` для прихода, `EFontType.ERROR` для расхода) и начертание.
+- `StatusTrackerSum` (`src/components/StatusTracker/components/StatusTrackerSum.tsx`) —
+  сумма в шапке статус-трекера, пробрасывает в `Amount` весь `amountProps`.
+- `TableFooterSummaryAmount` (`src/components/Table/TableFooter/components/TableFooterSummaryAmount.tsx`) —
+  подытог в подвале таблицы, рендерит `Amount` с `value` и `currency`.
+- `formatAmount` / `amountComparator` (`src/utils/amountUtils.ts`) — публичные утилиты; при
+  выводе суммы в разметке предпочитай компонент, при расчётах и сортировке — утилиты.
 
 ---
 
 ## Stories
 
-`stories/Amount/Amount.stories.tsx`
+Основные истории: `stories/Amount/Amount.stories.tsx`
 Файлы примеров: `stories/Amount/examples/`
 
 | Story | Example file | Что демонстрирует |
 |---|---|---|
-| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль всех props |
-| `Default` | `DefaultExample.tsx` | Базовое использование с RUB |
-| `Example` | `ShowcaseExample.tsx` | Расширенный пример (разные значения, знаки) |
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный подбор `value`, `fractionLength`, `currency`, `currencyTitle`, `adaptive` |
+| `Default` | `DefaultExample.tsx` | Минимальный вызов: сумма с валютой внутри `Text` |
+| `Adaptive` | `AdaptiveExample.tsx` | Уменьшение шрифта на длинной сумме (50 млрд) |
+| `Example` | `ShowcaseExample.tsx` | Витрина: разные `fractionLength`, знаки `+` / `-` с цветом, без валюты, акцент, адаптив |
+
+Скриншоты снимаются со стори `Default` и `Adaptive` (`amount--default--xs|xl.png`,
+`amount--adaptive--xs|xl.png`). `Playground` и `Example` исключены
+(`testRunner: { skip: true }`).
 
 ---
 
@@ -222,7 +183,7 @@ renderCurrencyName = () => [
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-08-12 | Создан документ. AI-рефакторинг: `Amount` переведён с `React.FC` на `forwardRef` — ref указывает на корневой `<span>`, то есть на тот же элемент, что получает `className` и `...rest` (аддитивное изменение, `IAmountProps` не менялся). Порядок импортов приведён к codestyle, константа `adaptiveAmountLength` переименована в `ADAPTIVE_AMOUNT_LENGTH`, магические символы вынесены в именованные константы `HYPHEN_MINUS` / `MINUS_SIGN` / `NON_BREAKING_SPACE`, нестрогое сравнение `==` заменено на `startsWith`, `let` заменён на `const`, inline-функция `renderCurrencyName` (возвращала массив React-узлов) заменена на фрагмент прямо в JSX, JSDoc props дополнен значениями по умолчанию, `!important` в `.adaptive` получил комментарий-обоснование. Unit-тесты расширены с 4 до 23 кейсов. Публичный API, DOM-разметка и визуальное отображение не изменены. |
 
 ---
 
@@ -243,6 +204,21 @@ export const DefaultExample = () => (
 );
 ```
 
+### Adaptive
+
+`stories/Amount/examples/AdaptiveExample.tsx`
+
+```tsx
+import React from "react";
+import { Amount, EFontType, ETextSize, Text } from "@sberbusiness/triplex-next";
+
+export const AdaptiveExample = () => (
+    <Text size={ETextSize.B2} type={EFontType.PRIMARY}>
+        <Amount value="50000000000.31" currency="RUB" currencyTitle="Российские рубли" fractionLength={2} adaptive />
+    </Text>
+);
+```
+
 ### Example
 
 `stories/Amount/examples/ShowcaseExample.tsx`