@sberbusiness/triplex-next-mcp-server 1.46.0-beta → 1.48.0-beta

package/bundle/components/Slider.md

@@ -1,8 +1,6 @@
 ---
 component: Slider
-category: Form Controls
-figma-node: ""
-figma-file: ""
+category: Slider
 related: [SliderExtended, SliderRange]
 tokens: []
 stories: stories/Slider/Slider.stories.tsx
@@ -13,145 +11,439 @@ version: "1.0"
 
 ## Назначение
 
-Готовый слайдер с **одним** ползунком: фиксированная компоновка
-`SliderExtended` (`Rail` → `Dot` → `Track` → `Marks`), tooltip над dot'ом
-если передан `renderTooltipContent`. Под капотом — `SliderExtended` с
-ровно одним `Dot`.
+Слайдер с одним ползунком — готовая сборка `SliderExtended`: полоса, ползунок, трек и метки
+уже собраны, потребителю остаётся задать диапазон, шаг, метки и владеть значением.
 
-Используй когда: нужно выбрать одно числовое значение в диапазоне
-`min..max`. Для двух точек (диапазон) — `SliderRange`. Для нестандартной
-компоновки (свой Tooltip, отдельные Marks) — `SliderExtended`.
+Используй когда: пользователь выбирает одно число из диапазона и точность ввода не важна —
+сумма, срок, процент, громкость.
 
----
-
-## Файловая структура
+Не используй когда:
 
-```text
-src/components/Slider/
-├── Slider.tsx        # FC; склейка SliderExtended + Dot + Tooltip + Marks
-├── index.ts          # Barrel
-└── __tests__/
-```
+- Нужен выбор диапазона двумя ползунками — возьми `SliderRange`.
+- Нужен нестандартный состав частей (без меток, без трека, своё содержимое ползунка) или
+  собственная разметка подсказки — собери слайдер из `SliderExtended`.
+- Нужно ввести точное число — слайдер не заменяет `NumberField` / `AmountField`; при крупных
+  диапазонах их обычно ставят рядом со слайдером.
+- Ползунку нужна текстовая подпись для скринридера — `Slider` её передать не позволяет
+  (см. Accessibility), собирай из `SliderExtended`.
 
 ---
 
 ## Варианты и props
 
-### `ISliderProps`
+### Обязательные props
 
-```ts
-extends Omit<ISliderExtendedProps, "onChange" | "step">
-extends Pick<ISliderExtendedDotProps, "onChange" | "value">
-```
+| Prop | Тип | Описание |
+|---|---|---|
+| `min` | `number` | Минимальное значение диапазона |
+| `max` | `number` | Максимальное значение диапазона |
+| `size` | `EComponentSize.MD \| EComponentSize.LG` | Размер. `SM` не поддерживается |
+| `value` | `number` | Текущее значение ползунка |
+| `onChange` | `(value: number) => void` | Вызывается со значением шага, на который переместился ползунок |
+| `marks` | `ISliderMark[]` | Метки под полосой: `{ value: number; label: React.ReactNode }` |
 
-| Prop | Тип | Default | Описание |
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `value` | `number` | — | Текущее значение dot'а. |
-| `onChange` | `(value: number) => void` | — | Изменение значения. |
-| `marks` | `ISliderMark[]` | — | Метки под полосой (`{ value, label }`). |
-| `step?` | `number \| number[]` | `1` | Длина шага или явный массив значений. |
-| `renderTooltipContent?` | `(value: number) => ReactNode` | — | Если передан — рендерится `Tooltip` над dot'ом. |
-| `size` | `EComponentSize.MD \| LG` | — (обязателен из ISliderExtendedProps) | Только MD/LG. |
-| `min` / `max` | `number` | — | От SliderExtended. |
-| `disabled?` / `reverse?` | `boolean` | — | От SliderExtended. |
-| `children?` | `never` | — | Запрещено. |
-
-### `ISliderMark`
-
-```ts
-{ value: number; label: ReactNode }
-```
+| `step` | `number \| number[]` | `1` | Длина шага либо массив значений шагов. В массиве первое значение равно `min`, последнее — `max` |
+| `reverse` | `boolean` | `false` | Значения возрастают справа налево |
+| `disabled` | `boolean` | `false` | Слайдер не активен: части не реагируют на курсор и выпадают из табуляции |
+| `renderTooltipContent` | `(value: number) => React.ReactNode` | — | Содержимое подсказки над ползунком. Без этого prop подсказка не рендерится вовсе |
+
+Остальные атрибуты `React.HTMLAttributes<HTMLDivElement>` (включая `className`, `id`,
+`aria-*`, `data-*`) уходят на **корневой `div`** слайдера. `children` запрещён
+(`children?: never`): разметку собирает сам компонент.
+
+### Особенности поведения
+
+- **Значение контролируемое.** Компонент не хранит значение: он рисует позицию по `value` и
+  сообщает новое значение через `onChange`. Без обновления `value` снаружи ползунок не
+  двигается — включая `disabled`-слайдер, где источник правды тем более остаётся у
+  потребителя.
+- **`step` числом строит шаги как `[...range(min, max, step), max]`.** Последний шаг всегда
+  равен `max`, даже если он не кратен шагу: при `min: 0, max: 10, step: 3` шаги равны
+  `0, 3, 6, 9, 10`.
+- **`step` массивом задаёт произвольную шкалу.** Шаги равны визуально, а не по значению —
+  так делается шкала сумм с укрупняющимся шагом (см. story `Amounts`). Массив, собранный
+  инлайн в JSX, пересчитывает шаги на каждом рендере потребителя; вынеси его в константу.
+- **Пустой массив шагов (`step: []`) не рендерит ничего** — `SliderExtended` возвращает `null`.
+- **Значение вне диапазона не отбрасывается, а зажимается** при расчёте позиции: ползунок
+  встаёт на край. В `onChange` при этом уходят только значения из массива шагов.
+- **Клик по полосе и по метке двигает ползунок** на ближайший шаг / на значение метки.
+- **`marks` не обязаны совпадать с шагами.** Метка со значением вне `[min, max]` прижимается
+  к краю полосы; `value` метки используется как React-ключ, поэтому дубли значений дадут
+  предупреждение о неуникальных ключах. Подпись рендерится через `Text` (`B3` для `LG`,
+  `B4` для `MD`).
+- **Подсказка видна только при `:hover` и `:focus` ползунка** — управляется стилями, не
+  props. Постоянно видимой подсказки нет, поэтому текущее значение обычно дублируют рядом со
+  слайдером (так сделано во всех stories).
+- **Ширину и внешние отступы задаёт потребитель.** Своей ширины у слайдера нет; собственные
+  вертикальные отступы (под ползунок и под метки) он добавляет сам.
 
-`value` должен быть в `[min, max]`.
+---
 
-### `step`
+## Дизайн-токены
 
-- **`number`** — обычный шаг: для `min=0, max=100, step=1` — 100 шагов.
-- **`number[]`** — явный массив возможных значений, **первый = `min`**, **последний = `max`** (контракт).
+Собственных токенов у компонента нет: своих стилей `Slider` не имеет и целиком состоит из
+`SliderExtended`. Внешний вид настраивается токенами группы `Slider` — их список и порядок
+переопределения см. в `SliderExtended-ai.md` → «Дизайн-токены». Значения по умолчанию —
+`src/components/DesignTokens/components/Slider.ts`.
 
 ---
 
-## Ключевые особенности реализации
+## Инварианты
 
-### Жёстко зашитая структура
+- **`Slider` пробрасывает `ref` на корневой `div`:** обёрнут в `React.forwardRef`, `ref`
+  уходит в `SliderExtended`, который вешает его на свой корень. `forwardRef` не убирать —
+  это публичный контракт. У `SliderExtended` и всех его частей `forwardRef` есть — тоже не
+  убирать. Исключение в семействе — `SliderRange`: это class-компонент, и `ref` на нём даёт
+  инстанс класса, а не корневой `div`.
+- **`ISliderProps` наследуется от `ISliderExtendedProps` и `ISliderExtendedDotProps`**
+  (`Omit<..., "onChange" | "step">` + `Pick<..., "onChange" | "value">`). Переименование
+  props в `SliderExtended` ломает публичный API `Slider` — менять только вместе.
+- **Порядок частей в разметке (`Rail` → `Dot` → `Track` → `Marks`) и наличие `Rail`
+  обязательны.** Позиции клика и перетаскивания считаются от DOM-узла полосы; без `Rail`
+  работает только клавиатура. `Tooltip` обязан лежать внутри `Dot`.
+- **`renderTooltipContent` вызывается на каждом рендере** с текущим `value` — держи её
+  дешёвой и без side effects.
+- **`children?: never`** — часть публичного API: состав слайдера фиксирован, расширяется он
+  только через `SliderExtended`.
+- Реализация остаётся React 17-совместимой (без `useId`, `useSyncExternalStore` и прочих
+  React 18-only API): код синхронизируется в `release-0`.
 
-```tsx
-<SliderExtended step={step} size={size} {...rest}>
-    <SliderExtended.Rail />
-    <SliderExtended.Dot value={value} onChange={onChange}>
-        {renderTooltipContent && <SliderExtended.Tooltip ...>{renderTooltipContent(value)}</SliderExtended.Tooltip>}
-    </SliderExtended.Dot>
-    <SliderExtended.Track />
-    <SliderExtended.Marks>
-        {marks.map(m => <SliderExtended.Mark key={m.value} value={m.value}>{m.label}</SliderExtended.Mark>)}
-    </SliderExtended.Marks>
-</SliderExtended>
-```
+---
+
+## Accessibility
 
-- Порядок: Rail → Dot → Track → Marks. Изменение порядка — менять `Slider.tsx`.
-- Tooltip — вложен в Dot, рендерится только при `renderTooltipContent`.
+- **Ползунок — `role="slider"`** с `aria-valuemin`, `aria-valuenow`, `aria-valuemax` из
+  `min` / `value` / `max` (рендерится `SliderExtended.Dot`).
+- **Подпись ползунку `Slider` передать нельзя.** Все лишние props уходят на корневой `div`,
+  а не на ползунок, поэтому `aria-label` / `aria-labelledby` окажутся на контейнере без роли.
+  Если подпись или `aria-valuetext` (нелинейная шкала, суммы, единицы измерения) обязательны —
+  собирай слайдер из `SliderExtended` и передавай атрибуты прямо в `SliderExtended.Dot`.
+- **Клавиатура:** `ArrowLeft` / `ArrowDown` — шаг назад, `ArrowRight` / `ArrowUp` — шаг
+  вперёд. Обработчики вызывают `preventDefault`, чтобы страница не скроллилась.
+  `Home` / `End` / `PageUp` / `PageDown` не поддерживаются.
+- **Трек в табуляцию не попадает:** перетаскивание трека клавиатурой имеет смысл только для
+  двух ползунков, а у `Slider` он один.
+- **Метки кликабельны, но не фокусируются** и не читаются как элементы управления: это
+  ускоритель для мыши, дублирующий клавиатурное перемещение по шагам.
+- **Подсказка не связана с ползунком через `aria`** — она показывается по `:hover`/`:focus`
+  и для скринридера бесполезна; значение доступно через `aria-valuenow`.
+- **`disabled` только визуальный и мышиный.** Части получают `pointer-events: none` и
+  `tabIndex -1`, но нативного `disabled` у `span` нет: программно установленный фокус
+  оставляет клавиатурное перемещение работающим. Источником правды остаётся `value`
+  потребителя.
 
-### `step` default `1`
+---
 
-- Если потребитель не передал — `1`.
+## Связанные компоненты
 
-### `Tooltip` — над **самим** dot'ом, не на hover
+- `SliderExtended` (`src/components/SliderExtended/`) — составной слайдер, из которого
+  собран `Slider`. Нужен, когда состава `Slider` не хватает: свой набор частей, своя
+  подсказка, `aria`-атрибуты на ползунке.
+- `SliderRange` (`src/components/SliderRange/`) — тот же слайдер на два ползунка: принимает
+  `values` парой, следит за их порядком и прокидывает `draggableTrack`.
 
-- Рендерится при наличии `renderTooltipContent`. По UX — обычно показывается всегда (см. SliderExtendedTooltip-логику).
+---
 
-### **`children: never`**
+## Stories
 
-- Внутрь Slider'а нельзя положить кастомные элементы — для этого использовать SliderExtended.
+Основные истории: `stories/Slider/Slider.stories.tsx`
+Файлы примеров: `stories/Slider/examples/Slider/`
 
-### **`FC, не forwardRef`**
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный подбор `min`, `max`, `step`, `marks`, `size`, `disabled`, `reverse` |
+| `Default` | `Default.tsx` | Слайдер с метками и шагом по умолчанию |
+| `Sizes` | `Sizes.tsx` | Размеры MD и LG |
+| `WithTooltip` | `WithTooltip.tsx` | Подсказка над ползунком через `renderTooltipContent` |
+| `WithCustomSteps` | `WithCustomSteps.tsx` | Шаги заданы массивом значений |
+| `Disabled` | `Disabled.tsx` | Неактивный слайдер |
+| `Reverse` | `Reverse.tsx` | Значения возрастают справа налево |
+| `Amounts` | `Amounts.tsx` | Production-like шкала сумм с неравномерным шагом: слайдер работает с индексами шкалы |
+| `VisualTests` | `VisualTests.tsx` | Размеры, шаги массивом, реверс и неактивное состояние; `play` ставит фокус на первый ползунок, чтобы в кадр попали обводка фокуса и подсказка |
 
-- Ref не пробрасывается.
+`Playground` исключён из скриншот-тестов. `WithTooltip` тоже исключён: подсказка скрыта, пока
+ползунок не в фокусе, поэтому её кадр повторяет `Default`.
 
 ---
 
-## Инварианты
+## История изменений
 
-- **Один Dot, фиксированная структура** — Rail/Dot/Track/Marks. Менять только через SliderExtended.
-- **`step` default `1`**.
-- **`marks: ISliderMark[]`** — обязателен, может быть `[]`.
-- **`renderTooltipContent?`** — опционально; без него Tooltip не рендерится.
-- **`size: MD | LG`** — `SM` не поддерживается.
-- **`children: never`**.
-- **`value` ∈ `[min, max]`** — потребитель ответственен (валидации нет).
-- **Если `step` — массив**, первое значение = `min`, последнее = `max`.
-- **`FC, не forwardRef`**.
+| Дата | Изменение |
+|---|---|
+| 2026-09-11 | Создан документ. AI-рефакторинг (TRI-77): добавлен `displayName`, props задокументированы JSDoc, из разметки убран избыточный проброс `size` (значение приходит тем же spread'ом). Публичный API props, интерфейсов и barrel-экспортов не изменён. Добавлены unit-тесты, stories переведены на modern pattern. |
+| 2026-09-14 | Правки по ревью (TRI-77): `Slider` обёрнут в `React.forwardRef` и пробрасывает `ref` на корневой `div` — раньше был `React.FC` и `ref` терялся. Тип компонента изменился на `React.ForwardRefExoticComponent`, запись в release notes 1.47.0. |
 
 ---
 
-## Accessibility
+## Примеры использования
 
-- Наследуется от `SliderExtended.Dot` (см. SliderExtended-AI; обычно `<span>` с `tabIndex`).
-- Keyboard navigation — стрелки (детали в SliderExtendedDot).
+### Default
 
----
+`stories/Slider/examples/Slider/Default.tsx`
 
-## Дизайн-токены
+```tsx
+import React, { useState } from "react";
+import { EComponentSize, Slider } from "@sberbusiness/triplex-next";
+
+const MARKS = [
+    { value: 0, label: "0" },
+    { value: 35, label: "35" },
+    { value: 66, label: "66" },
+    { value: 100, label: "100" },
+];
+
+export const Default = () => {
+    const [value, setValue] = useState(35);
+
+    return (
+        <div style={{ maxWidth: "750px", padding: "30px" }}>
+            <div>value = {value}</div>
+            <br />
+            <Slider min={0} max={100} size={EComponentSize.MD} marks={MARKS} value={value} onChange={setValue} />
+        </div>
+    );
+};
+```
 
-Нет собственных — наследуются от `SliderExtended`.
+### Sizes
 
----
+`stories/Slider/examples/Slider/Sizes.tsx`
 
-## Связанные компоненты
+```tsx
+import React, { useState } from "react";
+import { EComponentSize, Slider } from "@sberbusiness/triplex-next";
+
+const MARKS = [
+    { value: 0, label: "0" },
+    { value: 50, label: "50" },
+    { value: 100, label: "100" },
+];
+
+interface ISizeItemProps {
+    size: EComponentSize.MD | EComponentSize.LG;
+}
+
+const SIZES: ISizeItemProps["size"][] = [EComponentSize.MD, EComponentSize.LG];
+
+const SizeItem = ({ size }: ISizeItemProps) => {
+    const [value, setValue] = useState(35);
+
+    return (
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>{size.toUpperCase()}</div>
+            <Slider min={0} max={100} size={size} marks={MARKS} value={value} onChange={setValue} />
+        </div>
+    );
+};
+
+export const Sizes = () => (
+    <div style={{ maxWidth: "750px", padding: "30px", display: "flex", flexDirection: "column", gap: "24px" }}>
+        {SIZES.map((size) => (
+            <SizeItem key={size} size={size} />
+        ))}
+    </div>
+);
+```
 
-- `SliderExtended` — низкоуровневая основа (slots).
-- `SliderRange` — два ползунка.
+### WithTooltip
 
----
+`stories/Slider/examples/Slider/WithTooltip.tsx`
 
-## Stories
+```tsx
+import React, { useState } from "react";
+import { EComponentSize, Slider } from "@sberbusiness/triplex-next";
+
+const MARKS = [
+    { value: 0, label: "0" },
+    { value: 35, label: "35" },
+    { value: 66, label: "66" },
+    { value: 100, label: "100" },
+];
+
+export const WithTooltip = () => {
+    const [value, setValue] = useState(35);
+
+    return (
+        <div style={{ maxWidth: "750px", padding: "30px" }}>
+            <div>value = {value}</div>
+            <br />
+            <Slider
+                min={0}
+                max={100}
+                size={EComponentSize.MD}
+                marks={MARKS}
+                value={value}
+                onChange={setValue}
+                renderTooltipContent={(tooltipValue) => `${tooltipValue} %`}
+            />
+        </div>
+    );
+};
+```
 
-`stories/Slider/Slider.stories.tsx`
-Примеры: `stories/Slider/examples/`
+### WithCustomSteps
 
----
+`stories/Slider/examples/Slider/WithCustomSteps.tsx`
 
-## История изменений
+```tsx
+import React, { useState } from "react";
+import { EComponentSize, Slider } from "@sberbusiness/triplex-next";
+
+// Массив шагов вынесен из JSX: инлайновый массив пересчитывает шаги на каждом рендере.
+const STEPS = [0, 25, 50, 75, 100];
+
+const MARKS = STEPS.map((step) => ({ value: step, label: String(step) }));
+
+export const WithCustomSteps = () => {
+    const [value, setValue] = useState(50);
+
+    return (
+        <div style={{ maxWidth: "750px", padding: "30px" }}>
+            <div>value = {value}</div>
+            <br />
+            <Slider
+                min={0}
+                max={100}
+                step={STEPS}
+                size={EComponentSize.MD}
+                marks={MARKS}
+                value={value}
+                onChange={setValue}
+            />
+        </div>
+    );
+};
+```
+
+### Disabled
+
+`stories/Slider/examples/Slider/Disabled.tsx`
+
+```tsx
+import React from "react";
+import { EComponentSize, Slider } from "@sberbusiness/triplex-next";
+
+const MARKS = [
+    { value: 0, label: "0" },
+    { value: 35, label: "35" },
+    { value: 66, label: "66" },
+    { value: 100, label: "100" },
+];
+
+export const Disabled = () => (
+    <div style={{ maxWidth: "750px", padding: "30px" }}>
+        <Slider min={0} max={100} size={EComponentSize.MD} marks={MARKS} value={35} onChange={() => {}} disabled />
+    </div>
+);
+```
+
+### Reverse
+
+`stories/Slider/examples/Slider/Reverse.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { EComponentSize, Slider } from "@sberbusiness/triplex-next";
+
+const MARKS = [
+    { value: 0, label: "0" },
+    { value: 35, label: "35" },
+    { value: 66, label: "66" },
+    { value: 100, label: "100" },
+];
+
+export const Reverse = () => {
+    const [value, setValue] = useState(35);
+
+    return (
+        <div style={{ maxWidth: "750px", padding: "30px" }}>
+            <div>value = {value}</div>
+            <br />
+            <Slider
+                min={0}
+                max={100}
+                size={EComponentSize.MD}
+                marks={MARKS}
+                value={value}
+                onChange={setValue}
+                reverse
+            />
+        </div>
+    );
+};
+```
+
+### Amounts
+
+`stories/Slider/examples/Slider/Amounts.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { EComponentSize, Slider } from "@sberbusiness/triplex-next";
+
+/** Возвращает значения от from до to (не включая), с шагом step. */
+const range = (from: number, to: number, step: number): number[] => {
+    const values: number[] = [];
+
+    for (let value = from; value < to; value += step) {
+        values.push(value);
+    }
+
+    return values;
+};
+
+/**
+ * Шкала сумм с неравномерным шагом: чем больше сумма, тем крупнее шаг.
+ * Слайдер работает с индексами шкалы, поэтому шаги равны визуально.
+ */
+const AMOUNTS = [
+    0,
+    10000,
+    ...range(20000, 240000, 20000),
+    ...range(240000, 1000000, 40000),
+    ...range(1000000, 2150000, 50000),
+    ...range(2150000, 2600000, 75000),
+    ...range(2600000, 3000000, 100000),
+    ...range(3000000, 3800000, 200000),
+    ...range(3800000, 9000000, 400000),
+    ...range(9000000, 10000000, 500000),
+    ...range(10000000, 25000000, 2500000),
+    ...range(25000000, 40000000, 5000000),
+    ...range(40000000, 90000001, 10000000),
+    100000000,
+];
+
+const amountFormat = new Intl.NumberFormat("ru-RU");
+
+const MARKS = [
+    { value: 0, label: "0 млн" },
+    { value: AMOUNTS.indexOf(1000000), label: "1 млн" },
+    { value: AMOUNTS.indexOf(3000000), label: "3 млн" },
+    { value: AMOUNTS.length - 1, label: "100 млн" },
+];
+
+export const Amounts = () => {
+    const [amountIndex, setAmountIndex] = useState(AMOUNTS.indexOf(1000000));
+
+    return (
+        <div style={{ maxWidth: "750px", padding: "30px" }}>
+            <div>{amountFormat.format(AMOUNTS[amountIndex])}</div>
+            <br />
+            <Slider
+                min={0}
+                max={AMOUNTS.length - 1}
+                size={EComponentSize.MD}
+                marks={MARKS}
+                value={amountIndex}
+                onChange={setAmountIndex}
+                renderTooltipContent={(value) => amountFormat.format(AMOUNTS[value])}
+            />
+        </div>
+    );
+};
+```
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |