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

package/bundle/components/DocumentNumberEdit.md

@@ -0,0 +1,280 @@
+---
+component: DocumentNumberEdit
+category: Form
+figma-node: ""
+figma-file: ""
+related: [SmallInput, Link, Typography]
+tokens: []
+stories: stories/DocumentNumberEdit/DocumentNumberEdit.stories.tsx
+version: "1.0"
+---
+
+# DocumentNumberEdit
+
+## Назначение
+
+Инлайн-виджет "номер документа" в режиме **просмотра** (подпись + текст)
+/ **редактирования** (SmallInput c числовой маской). Используется
+типично в формах создания документов, где номер по умолчанию
+присваивается автоматически, но пользователь может его изменить.
+
+Три состояния:
+1. **Нет значения + не в режиме edit** — текст `emptyNumberLabel` +
+   ссылка `emptyNumberButtonLabel` ("Задать номер").
+2. **Есть значение + не в режиме edit** — текст `{numberLabel} {value}`
+   + ссылка `buttonLabel` ("Изменить").
+3. **В режиме edit** — текст `numberLabel` + SmallInput (цифры, ≤6
+   символов).
+
+Используй когда: форма документа с редактируемым номером и placeholder-логикой.
+Не используй для: произвольного числового поля — бери `SmallInput` или
+`NumberField`.
+
+---
+
+## Файловая структура
+
+```text
+src/components/DocumentNumberEdit/
+├── DocumentNumberEdit.tsx                  # FC, НЕ forwardRef
+├── index.ts                                # Barrel
+└── styles/DocumentNumberEdit.module.less   # .label (inline-block + 8px right), .inputEditWrapper (68px)
+```
+
+Особенности:
+- **НЕ `forwardRef`** — FC. Известный AI-ready debt.
+- **Внутренний state `editingMode`** — компонент сам управляет
+  переключением "просмотр ↔ редактирование". Внешнего управления нет.
+- **`value`** — controlled-only (без defaultValue).
+- **Нет `__tests__`** — покрытие через `SmallInput`-тесты косвенно.
+- **Нет `data-tx`** — не ставит атрибут версии.
+
+---
+
+## Варианты и props
+
+### `IDocumentNumberEditProps extends ISmallInputProps`
+
+**DocumentNumberEdit-specific:**
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `value` | `React.ReactText` (`string \| number`) | — | Текущий номер. Falsy → empty-state. |
+| `numberLabel` | `string` | — (обязателен) | Префикс текста в view-mode ("Документ №"). |
+| `emptyNumberLabel` | `string` | — (обязателен) | Полный текст в empty-state ("Номер документа будет присвоен автоматически"). |
+| `buttonLabel` | `string` | — (обязателен) | Текст ссылки в view-mode ("Изменить"). |
+| `emptyNumberButtonLabel` | `string` | — (обязателен) | Текст ссылки в empty-state ("Задать номер"). |
+| `maxLength` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `6` | Максимум цифр. Влияет на `placeholder` (`"0"*maxLength`) и `SmallInput.maxLength`. |
+
+**Остальные:** все пропсы `ISmallInputProps` (включая `onChange`,
+`onBlur`, `onKeyDown`, `className`, `...`).
+
+### `labelText` — вычисляемый
+
+```ts
+const labelText = useMemo(() => {
+    if (editingMode) return numberLabel;        // только "Документ №"
+    if (value) return `${numberLabel} ${value}`; // "Документ № 12345"
+    return emptyNumberLabel;                     // "Номер ... будет присвоен автоматически"
+}, [value, numberLabel, emptyNumberLabel, editingMode]);
+```
+
+---
+
+## Ключевые особенности реализации
+
+### State `editingMode` — внутренний uncontrolled switch
+
+```ts
+const [editingMode, setEditingMode] = useState(false);
+```
+
+**Включается:** клик по ссылке (`handleButtonClick`, `preventDefault()`).
+**Выключается:** Enter в input (`handleInputKeyDown`) или blur input
+(`handleInputBlur`).
+
+**Нет `controlled` варианта** — потребитель не может извне открыть
+редактирование. Если нужно — оборачивать в свою логику.
+
+### Фильтрация цифр + сохранение позиции курсора
+
+```ts
+const handleInputChange = (event) => {
+    const caret = getCaretPosition(event.target);
+    const value = getFilteredValue(event.target.value);
+    const caretShift = value.length - event.target.value.length;
+
+    event.target.value = value;
+    setCaretPosition(event.target, caret + caretShift);
+
+    onChange?.(event);
+};
+
+const getFilteredValue = (value: string) => {
+    const buffer: string[] = [];
+    for (let i = 0; i < value.length; i++) {
+        if (StringUtils.isDigit(value[i])) buffer.push(value[i]);
+    }
+    return buffer.join("");
+};
+```
+
+**Зачем `caretShift`:** если пользователь вставил "12a3" → фильтр
+вернёт "123", длина уменьшилась на 1. Курсор должен сдвинуться на `-1`
+относительно момента вставки, чтобы остаться на правильном месте.
+Без этого курсор "прыгнет" в конец.
+
+**`StringUtils.isDigit`** — проверка по регулярке (0-9). Не
+поддерживает юникод-цифры, только ASCII.
+
+**Мутация `event.target.value` напрямую** — это анти-паттерн, но
+React принимает это, так как мы работаем с uncontrolled SmallInput
+под капотом (controlled через onChange). Вариант: принять внешний
+onChange(filteredValue), но тогда `value` не обновится моментально
+до ре-рендера.
+
+### `autoFocus={true}` на SmallInput
+
+При переключении в edit-mode input появляется **с фокусом**. Важно
+для UX — пользователь кликнул "Изменить" и сразу может вводить.
+
+### Ссылка — `Link` с `href="#"` + preventDefault
+
+```tsx
+<Link href="#" onClick={handleButtonClick}>
+    {value ? buttonLabel : emptyNumberButtonLabel}
+</Link>
+```
+
+**`href="#"`** — чтобы ссылка была "настоящей" (правильный фокус,
+подчёркивание). `preventDefault` в обработчике клика предотвращает
+прыжок страницы наверх.
+
+**Альтернатива — `<button>`**, но дизайн требует ссылочного вида.
+Компромисс: семантика button + визуал Link.
+
+### Выход из edit-mode: Enter или blur
+
+```ts
+if (isKey(event.code, "ENTER")) setEditingMode(false);
+// + onBlur → setEditingMode(false)
+```
+
+**Esc не выходит** — это UX-решение. Если нужно — потребитель может
+сам обработать в `onKeyDown` и програмно вызвать blur.
+
+### Placeholder — `"0".repeat(maxLength)`
+
+`inputPlaceholder = "0".repeat(maxLength)` → "000000" для maxLength=6.
+Визуально показывает сколько символов ожидается. Меняется с maxLength.
+
+### Ширина input — 68px (hardcoded)
+
+```less
+.inputEditWrapper { width: 68px; }
+```
+
+**Hardcoded** и рассчитана под 6 цифр в SmallInput. Если изменить
+`maxLength`, input может не помещать значение — 68px могут быть
+слишком широки или узки. **Потребители с кастомным maxLength ≠ 6
+должны переопределять ширину через className/style на wrapper**
+(но wrapper — внутренний, override невозможен без хака).
+
+**Это известное ограничение**: компонент заточен под 6-значный номер.
+
+### `inline-block` разметка
+
+```less
+.label { display: inline-block; margin-right: 8px; }
+.inputEditWrapper { width: 68px; display: inline-block; }
+```
+
+Label и кнопка/input стоят **в одну строку** (inline-block). Без
+grid/flex. Это требование дизайна — "в одну строку".
+
+### Рендер: всегда label + один из (renderButton / renderInput)
+
+```tsx
+<div className={styles.documentNumberEdit}>
+    <Text className={styles.label}>{labelText}</Text>
+    {editingMode ? renderInput() : renderButton()}
+</div>
+```
+
+**Без анимации перехода** — моментальная замена.
+
+---
+
+## Инварианты
+
+- **`editingMode` — внутренний state**. Нет controlled-варианта.
+- **`value` — controlled only** (через проп). Нет defaultValue.
+- **`maxLength: 0..6`** — жёсткое ограничение в типе. Расширять только
+  с обновлением `.inputEditWrapper.width` в LESS.
+- **Фильтрация только ASCII-цифр** через `StringUtils.isDigit`.
+- **`caretShift` в `handleInputChange`** — не удалять. Сохраняет
+  позицию курсора при фильтрации.
+- **Ссылка `Link href="#" + preventDefault`** — семантичная кнопка
+  визуально, без button-стилей. Не заменять на button без
+  дизайн-согласования.
+- **Enter и blur выходят из edit-mode**, Esc — нет. Не менять.
+- **Placeholder = "0".repeat(maxLength)** — генерируется из maxLength.
+- **`autoFocus=true`** на SmallInput — обязателен для UX.
+- **`.inputEditWrapper` 68px** — hardcoded под 6 цифр.
+- **НЕТ forwardRef** — известный debt.
+- **НЕТ `data-tx`** — наследованный пропуск.
+
+---
+
+## Accessibility
+
+- **Link с href="#"** — семантически ссылка, обнаруживается screen
+  reader'ом, фокусируется Tab'ом. Минус — href="#" может быть
+  нежелательным для SEO (не актуально для form-виджетов).
+- **Input** — SmallInput со своими ARIA (`aria-label` если передан
+  через `...rest`).
+- **Transition между view/edit** — визуальный, не объявляется screen
+  reader'у отдельно. Пользователь видит / слышит новую разметку.
+- **Нет live-region** — если input появился асинхронно (а не по
+  клику), screen reader может пропустить. В текущем сценарии это
+  реакция на клик, поэтому не критично.
+- **Placeholder "000000"** — может сбить с толку, если пользователь
+  читает screen reader'ом. Лучше полагаться на `aria-label` через
+  rest.
+
+---
+
+## Дизайн-токены
+
+**Нет собственных.** Все стили от `SmallInput`, `Link`, `Typography.Text`.
+
+---
+
+## Связанные компоненты
+
+- `SmallInput` (`src/components/SmallInput`) — input в edit-mode.
+- `Link` (`src/components/Link`) — кнопка-ссылка.
+- `Typography.Text` — label перед номером.
+- `NumberField` — альтернатива для более "обычных" числовых полей
+  (без specific "edit / view" UX).
+
+---
+
+## Stories
+
+`stories/DocumentNumberEdit/DocumentNumberEdit.stories.tsx`
+Примеры: `stories/DocumentNumberEdit/examples/`
+
+Типовые stories:
+- `Default` — с числом
+- `Empty` — без числа (empty-state UI)
+- `MaxLengths` — разные длины
+- `Playground` — интерактив
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |