@sberbusiness/triplex-next-mcp-server 1.44.0-beta → 1.45.0-beta

package/bundle/components/SliderExtended.md

@@ -3,23 +3,23 @@ component: SliderExtended
 category: Slider
 related: [Slider, SliderRange, KeyDownListener, Text]
 tokens:
-    - --triplex-next-Slider-Rail_Background
-    - --triplex-next-Slider-Rail_Background_Disabled
-    - --triplex-next-Slider-Track_Background_Default
-    - --triplex-next-Slider-Track_Background_Hover
-    - --triplex-next-Slider-Track_Background_Disabled
-    - --triplex-next-Slider-Dot_Background_Default
-    - --triplex-next-Slider-Dot_Background_Hover
-    - --triplex-next-Slider-Dot_Background_Select
-    - --triplex-next-Slider-Dot_Background_Disabled
-    - --triplex-next-Slider-Dot_Inner_Background
-    - --triplex-next-Slider-Dot_Inner_Background_Disabled
-    - --triplex-next-Slider-Dot_Focus
-    - --triplex-next-Slider-Mark_Dot_Background_Default
-    - --triplex-next-Slider-Mark_Dot_Background_Selected
-    - --triplex-next-Slider-Mark_Dot_Background_Selected_Disabled
-    - --triplex-next-Slider-Tooltip_Background
-    - --triplex-next-Slider-Tooltip_Color
+  - Slider.Rail_Background
+  - Slider.Rail_Background_Disabled
+  - Slider.Track_Background_Default
+  - Slider.Track_Background_Hover
+  - Slider.Track_Background_Disabled
+  - Slider.Dot_Background_Default
+  - Slider.Dot_Background_Hover
+  - Slider.Dot_Background_Select
+  - Slider.Dot_Background_Disabled
+  - Slider.Dot_Inner_Background
+  - Slider.Dot_Inner_Background_Disabled
+  - Slider.Dot_Focus
+  - Slider.Mark_Dot_Background_Default
+  - Slider.Mark_Dot_Background_Selected
+  - Slider.Mark_Dot_Background_Selected_Disabled
+  - Slider.Tooltip_Background
+  - Slider.Tooltip_Color
 stories: stories/Slider/SliderExtended.stories.tsx
 version: "1.0"
 ---
@@ -131,28 +131,31 @@ version: "1.0"
 
 ## Дизайн-токены
 
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/Slider.ts`.
+
 ```text
---triplex-next-Slider-Rail_Background
---triplex-next-Slider-Rail_Background_Disabled
---triplex-next-Slider-Track_Background_Default
---triplex-next-Slider-Track_Background_Hover
---triplex-next-Slider-Track_Background_Disabled
---triplex-next-Slider-Dot_Background_Default
---triplex-next-Slider-Dot_Background_Hover
---triplex-next-Slider-Dot_Background_Select
---triplex-next-Slider-Dot_Background_Disabled
---triplex-next-Slider-Dot_Inner_Background
---triplex-next-Slider-Dot_Inner_Background_Disabled
---triplex-next-Slider-Dot_Focus
---triplex-next-Slider-Mark_Dot_Background_Default
---triplex-next-Slider-Mark_Dot_Background_Selected
---triplex-next-Slider-Mark_Dot_Background_Selected_Disabled
---triplex-next-Slider-Tooltip_Background
---triplex-next-Slider-Tooltip_Color
+Slider.Rail_Background
+Slider.Rail_Background_Disabled
+Slider.Track_Background_Default
+Slider.Track_Background_Hover
+Slider.Track_Background_Disabled
+Slider.Dot_Background_Default
+Slider.Dot_Background_Hover
+Slider.Dot_Background_Select
+Slider.Dot_Background_Disabled
+Slider.Dot_Inner_Background
+Slider.Dot_Inner_Background_Disabled
+Slider.Dot_Focus
+Slider.Mark_Dot_Background_Default
+Slider.Mark_Dot_Background_Selected
+Slider.Mark_Dot_Background_Selected_Disabled
+Slider.Tooltip_Background
+Slider.Tooltip_Color
 ```
 
-Токены общие для всего семейства слайдеров и названы с префиксом `Slider-`, а не
-`SliderExtended-`: `Slider` и `SliderRange` — это тот же `SliderExtended` внутри.
+Токены общие для всего семейства слайдеров и лежат в группе `Slider`, а не
+`SliderExtended`: `Slider` и `SliderRange` — это тот же `SliderExtended` внутри.
 Размеры (высота полосы, диаметры ползунка и точек меток) заданы литералами в
 `.module.less`, z-index'ы — LESS-переменными `@slider-dot-z-index` и
 `@slider-track-z-index` из `src/helpers/less/z-indexes.less`.

package/bundle/components/SmallInput.md

@@ -1,15 +1,13 @@
 ---
 component: SmallInput
-category: Form Controls (internal)
-figma-node: ""
-figma-file: ""
-related: [TextField]
+category: TextFields
+related: [DocumentNumberEdit, TextField]
 tokens:
-  - --triplex-next-SmallInput-Background
-  - --triplex-next-SmallInput-Color
-  - --triplex-next-SmallInput-PlaceholderColor
-  - --triplex-next-SmallInput-Shadow
-stories: ""
+  - SmallInput.Background
+  - SmallInput.Color
+  - SmallInput.PlaceholderColor
+  - SmallInput.Shadow
+stories: stories/SmallInput/SmallInput.stories.tsx
 version: "1.0"
 ---
 
@@ -17,80 +15,131 @@ version: "1.0"
 
 ## Назначение
 
-Примитивное уменьшенное поле ввода (`<input type="text">`) без рамки, для
-использования внутри составных компонентов шапки/панелей (исторически —
-`HeaderPage`). Все props — стандартные `React.InputHTMLAttributes<HTMLInputElement>`
-плюс `className`.
+Компактное однострочное текстовое поле ввода высотой 20px. Тонкая обёртка над `<input type="text">`:
+свой CSS-модуль и своя группа дизайн-токенов, ничего больше — ни лейбла, ни статусов, ни префиксов,
+ни обвязки семейства `FormField`. Ширина всегда 100% контейнера, поэтому размер задаётся снаружи.
 
-Используй когда: нужен компактный input внутри другого контейнера, где
-полноценный `TextField` избыточен. В формах использовать `TextField` /
-`TextareaField`.
+Используй когда: нужно инлайн-редактирование короткого значения в плотной вёрстке, где полноценное
+поле формы не помещается — например, номер документа в шапке страницы (`DocumentNumberEdit`).
 
-Не используй когда: нужен valid/error-стейт, label, floating label, префиксы/
-суффиксы — для этого есть `TextField`.
+Не используй когда:
+- Поле живёт в форме и ему нужны лейбл, статус (error/warning/disabled), описание, счётчик или
+  кнопка очистки — возьми `TextField` (или `FormGroup` + `FormField` для нестандартной композиции).
+- Нужен нетекстовый ввод (`number`, `password`, `email`, `checkbox`): `type` захардкожен, см. «Инварианты».
+- Нужен ввод по маске (`MaskedField`), сумма (`AmountField`), дата (`DateField`).
+- Нужно готовое редактирование номера документа целиком, вместе с кнопкой «Изменить» и
+  переключением режимов — это уже `DocumentNumberEdit`.
 
 ---
 
-## Файловая структура
+## Варианты и props
 
-```text
-src/components/SmallInput/
-├── SmallInput.tsx    # forwardRef<HTMLInputElement, ISmallInputProps>
-├── index.ts          # Barrel
-└── styles/SmallInput.module.less
-```
+Собственных props у компонента нет. `ISmallInputProps` расширяет
+`React.InputHTMLAttributes<HTMLInputElement>` и ничего к нему не добавляет, поэтому принимаются
+все стандартные атрибуты `<input>`: `value` / `defaultValue`, `onChange`, `placeholder`,
+`maxLength`, `disabled`, `readOnly`, `autoFocus`, `aria-*`, `data-*` и остальные.
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `className` | `string` | — | Мерджится через `clsx` с собственным классом на корневом `<input>` |
+| `...InputHTMLAttributes` | — | — | Все стандартные атрибуты `<input>`, попадают на корневой элемент |
+| `type` | — | `"text"` | Захардкожен и **не переопределяется**: атрибут выставляется после `{...rest}` |
+
+### Особенности поведения
+
+- Компонент полностью stateless: контролируемость (`value` + `onChange`) или неконтролируемость
+  (`defaultValue`) выбирает потребитель, как у нативного `<input>`.
+- Ширина `100%`, высота `20px`, `box-sizing: border-box` — габариты задаёт контейнер.
+  Собственного `min-width` нет, при узком контейнере поле схлопывается.
+- Собственных стилей `:hover`, `:focus`, `:disabled` у компонента нет. `outline` снят
+  (`outline: none`), рамка нарисована постоянным `box-shadow`, поэтому визуально disabled,
+  readOnly и сфокусированное поле не отличаются от обычного.
+- Нативный крестик очистки IE/Edge скрыт (`&::-ms-clear { display: none; }`).
+- В Firefox плейсхолдер принудительно непрозрачный (`opacity: 1`), иначе браузер делает его
+  полупрозрачным поверх токена цвета.
 
 ---
 
-## Варианты и props
+## Дизайн-токены
 
-### `ISmallInputProps`
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/SmallInput.ts`.
 
-```ts
-extends React.InputHTMLAttributes<HTMLInputElement>
+```text
+SmallInput.Background
+SmallInput.Color
+SmallInput.PlaceholderColor
+SmallInput.Shadow
 ```
 
-Нет собственных props — полностью прозрачная обёртка над `<input>`:
-
-| Prop | Источник | Описание |
-|---|---|---|
-| `type` | — | **Всегда `"text"`** (хардкод, любой переданный игнорируется). |
-| `className` | React | Мёржится с внутренним `styles.smallInput` через `clsx`. |
-| `ref` | forwardRef | `HTMLInputElement`. |
-| `...rest` | HTMLInputAttributes | Прокидываются как есть (`value`, `onChange`, `placeholder`, `disabled`, ...). |
+`SmallInput.Shadow` — это inset-`box-shadow`, играющий роль рамки поля; он одинаков в светлой
+и тёмной теме и не меняется по состояниям.
 
 ---
 
 ## Инварианты
 
-- **`forwardRef<HTMLInputElement>`** — не убирать; потребители зависят от ref.
-- **`type="text"`** захардкожен — другие типы не поддерживаются.
-- **Нет собственного state** — всегда управляемый через внешний `value`/`onChange`
-  (или стандартный uncontrolled через `defaultValue`).
-- **Стили минимальны** — компонент рассчитан на вложение в контейнеры,
-  которые диктуют размер.
+- **`forwardRef`** — обязателен, не убирать. `ref` указывает на корневой (и единственный) `<input>`.
+- **Корневой DOM-элемент — `<input>`**, без обёрток. Потребители (`DocumentNumberEdit`) верстают
+  его внутри своих контейнеров и рассчитывают на `width: 100%` без внешних отступов.
+- **`type="text"` выставляется после `{...rest}`** и поэтому перекрывает переданный извне `type`.
+  Менять порядок или удалять хардкод — изменение наблюдаемого поведения, только отдельной задачей
+  с записью в release notes.
+- **Имена `SmallInput`, `ISmallInputProps`** и `displayName` — часть публичного API,
+  экспортируются из barrel `src/components/SmallInput/index.ts` и из корневого
+  `src/components/index.ts`.
+- **`ISmallInputProps` не должен обрастать собственными props без необходимости** — ценность
+  компонента в том, что это ровно нативный `<input>` с фирменными токенами.
+- **Группа токенов `SmallInput.*`** — публичный контракт темизации, переименование ломает
+  `ThemeProvider` у потребителей.
 
 ---
 
 ## Accessibility
 
-- Стандартный `<input>`, наследует accessibility поведения браузера.
-- Потребитель обязан обеспечить `aria-label` / `aria-labelledby`, если вход
-  используется без видимого `<label>` рядом.
+- Компонент не задаёт доступное имя: нет лейбла, `aria-label` и `aria-labelledby` не хардкодятся.
+  **Доступное имя обязан передать потребитель** — `aria-label`, `aria-labelledby` или внешний
+  `<label htmlFor>` со своим `id` (библиотека мультиязычная, тексты в неё не зашиваются).
+- Своей клавиатурной логики нет — поведение стандартного `<input type="text">`.
+- Видимого индикатора фокуса нет: `outline: none`, а `box-shadow` постоянный. Если поле
+  используется как самостоятельный элемент управления, а не как часть компонента со своим
+  focus-состоянием, фокус-стиль нужно добавлять снаружи через `className`.
+- `disabled` и `readOnly` ведут себя по-разному и взаимозаменяемыми не являются:
+  `disabled` выключает поле целиком — оно не попадает в таб-обход и не получает фокус;
+  `readOnly` фокус получает и остаётся в таб-обходе, но не даёт изменить значение.
+  Визуально оба состояния не отличаются от обычного — различие обеспечивает потребитель.
 
 ---
 
 ## Связанные компоненты
 
-- `TextField` — полноценный input с label/error/hint.
-- `Header` / `HeaderPage` — исторические потребители SmallInput.
+- `DocumentNumberEdit` (`src/components/DocumentNumberEdit/DocumentNumberEdit.tsx`) — единственный
+  потребитель внутри библиотеки и готовое решение для сценария «номер документа»:
+  `IDocumentNumberEditProps` наследует `ISmallInputProps`, а сам компонент рендерит `SmallInput`
+  в режиме редактирования, добавляя лейбл, ссылку «Изменить», фильтрацию цифр и `maxLength`.
+  Изменение props или поведения `SmallInput` отражается на нём напрямую.
+- `TextField` (`src/components/TextField/TextField.tsx`) — полноформатное однострочное поле
+  на семействе `FormField`: лейбл, статусы, префикс/постфикс, описание, счётчик. Альтернатива
+  для всего, что сложнее инлайн-редактирования короткого значения.
 
 ---
 
 ## Stories
 
-Отдельных stories нет — компонент внутренний, демонстрируется через stories
-потребителей (Header и т.п.).
+Основные истории: `stories/SmallInput/SmallInput.stories.tsx`
+Файлы примеров: `stories/SmallInput/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль `placeholder`, `maxLength`, `disabled`, `readOnly` |
+| `Default` | `Default.tsx` | Минимальное контролируемое поле с плейсхолдером |
+| `Disabled` | `Disabled.tsx` | Отключённое поле с заполненным значением |
+| `ReadOnly` | `ReadOnly.tsx` | Поле только для чтения |
+| `Production` | `Production.tsx` | Production-композиция (`Example: production`): подпись «Документ №» и инлайн-ввод номера с фильтрацией цифр |
+| `VisualTests` | `VisualTests.tsx` | Скриншот-регрессия: плейсхолдер, заполненное, disabled, readOnly, переполнение, растягивание по ширине, инлайн-выравнивание |
+
+Скриншоты снимает только `VisualTests`: состояния самого поля она покрывает целиком,
+поэтому документационные стори исключены через `testRunner: { skip: true }`.
 
 ---
 
@@ -98,4 +147,98 @@ extends React.InputHTMLAttributes<HTMLInputElement>
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-09-02 | Создан документ (TRI-80). AI-рефакторинг: уточнён JSDoc компонента, добавлен комментарий о хардкоде `type`, добавлены unit-тесты, созданы stories по modern pattern. Публичный API не изменён |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/SmallInput/examples/Default.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { SmallInput } from "@sberbusiness/triplex-next";
+
+export const Default = () => {
+    const [value, setValue] = useState("");
+
+    const handleChange: React.ChangeEventHandler<HTMLInputElement> = (event) => {
+        setValue(event.target.value);
+    };
+
+    return (
+        <div style={{ width: "120px" }}>
+            <SmallInput value={value} placeholder="000000" aria-label="Номер документа" onChange={handleChange} />
+        </div>
+    );
+};
+```
+
+### Disabled
+
+`stories/SmallInput/examples/Disabled.tsx`
+
+```tsx
+import React from "react";
+import { SmallInput } from "@sberbusiness/triplex-next";
+
+export const Disabled = () => (
+    <div style={{ width: "120px" }}>
+        <SmallInput defaultValue="000123" placeholder="000000" aria-label="Номер документа" disabled />
+    </div>
+);
+```
+
+### ReadOnly
+
+`stories/SmallInput/examples/ReadOnly.tsx`
+
+```tsx
+import React from "react";
+import { SmallInput } from "@sberbusiness/triplex-next";
+
+export const ReadOnly = () => (
+    <div style={{ width: "120px" }}>
+        <SmallInput defaultValue="000123" aria-label="Номер документа" readOnly />
+    </div>
+);
+```
+
+### Production
+
+`stories/SmallInput/examples/Production.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { SmallInput, Text, ETextSize, EFontType } from "@sberbusiness/triplex-next";
+
+const DOCUMENT_NUMBER_MAX_LENGTH = 6;
+
+export const Production = () => {
+    const [documentNumber, setDocumentNumber] = useState("000123");
+
+    const handleChange: React.ChangeEventHandler<HTMLInputElement> = (event) => {
+        setDocumentNumber(event.target.value.replace(/\D/g, ""));
+    };
+
+    return (
+        <div style={{ display: "flex", alignItems: "center", gap: "8px" }}>
+            <Text tag="span" size={ETextSize.B3} type={EFontType.SECONDARY}>
+                Документ №
+            </Text>
+            <div style={{ width: "80px" }}>
+                <SmallInput
+                    value={documentNumber}
+                    placeholder="000000"
+                    maxLength={DOCUMENT_NUMBER_MAX_LENGTH}
+                    aria-label="Номер документа"
+                    onChange={handleChange}
+                />
+            </div>
+        </div>
+    );
+};
+```
+