@olddevs/ui 0.0.0-stage → 4.0.0

package/docs/components/navigation/pagination.en.md

@@ -0,0 +1,69 @@
+---
+component: Pagination
+exports: [Pagination, pageRange]
+category: navigation
+status: stable
+source: src/components/navigation/Pagination.tsx
+story: src/components/navigation/Pagination.stories.tsx
+sourceHash: 3202869626c7
+---
+
+# Pagination
+
+## Summary for AI
+
+`Pagination` is controlled pagination for a collection that is already split into pages.
+It takes a 1-based `page`, calls `onChange` with a 1-based number and does not
+render when `pageCount <= 1`. `pageRange` is a pure helper that applies the same
+rule for which page numbers to show.
+
+## When to use
+
+- Server-side or local results with a known number of pages.
+- You need to move to the adjacent, first or last page and to have a compact range of numbers around the current one.
+
+## When not to use
+
+- For an infinite feed or "Load more".
+- For navigating the steps of a form, use `Stepper`.
+- Do not show pagination when pageCount is unknown or is always 1.
+
+## Minimal example
+
+```tsx
+<Pagination page={page} pageCount={result.pageCount} onChange={setPage} />
+```
+
+## Public API
+
+`page`, `pageCount` and `onChange` are required. `siblings` sets the number of neighbors
+to the left and right of the current page and defaults to 1. `className` and `aria-label` are available;
+the default nav name is "Pages". If an invalid `page` is passed in, the component clamps
+the current number to the range from 1 to `pageCount`, and `onChange` receives the number of the neighboring page, computed from the clamped `page`.
+`pageRange(page, pageCount, siblings)` returns an array `(number | "gap")[]`; it always
+keeps the first and last pages and never hides exactly one page
+behind an ellipsis.
+
+## Accessibility and keyboard
+
+This is a `nav` with ordinary buttons: Tab moves through every available action.
+The current page has `aria-current="page"`; prev/next have accessible names and are
+disabled at the bounds. The ellipsis is hidden from screen readers and not clickable.
+See the [Pagination source](../../../src/components/navigation/Pagination.tsx).
+
+## Good examples
+
+- Reset `page` to 1 when the application changes a filter.
+- Pass `siblings={2}` for a long list that should show more neighboring pages.
+- Use `pageRange` only for a custom presentation with the same rules.
+
+## Anti-patterns
+
+- A 0-based `page` or `onChange`.
+- Clickable ellipses that reveal nothing.
+- Rendering pagination for a single page.
+
+## Related sources and Storybook
+
+- `src/components/navigation/Pagination.tsx`
+- `src/components/navigation/Pagination.stories.tsx`

package/docs/components/navigation/pagination.md

@@ -0,0 +1,69 @@
+---
+component: Pagination
+exports: [Pagination, pageRange]
+category: navigation
+status: stable
+source: src/components/navigation/Pagination.tsx
+story: src/components/navigation/Pagination.stories.tsx
+---
+
+# Pagination
+
+## Кратко для AI
+
+`Pagination` — controlled pagination для уже разбитой на страницы коллекции.
+Она принимает 1-based `page`, вызывает `onChange` с 1-based номером и не
+рендерится при `pageCount <= 1`. `pageRange` — чистый helper для того же
+правила отображения номеров.
+
+## Когда использовать
+
+- Серверная или локальная выдача с известным числом страниц.
+- Нужны переходы на соседнюю, первую и последнюю страницы и компактный диапазон номеров вокруг текущей.
+
+## Когда не использовать
+
+- Для бесконечной ленты или «Загрузить ещё».
+- Для навигации по шагам формы используйте `Stepper`.
+- Не показывайте pagination, когда pageCount неизвестен или всегда равен 1.
+
+## Минимальный пример
+
+```tsx
+<Pagination page={page} pageCount={result.pageCount} onChange={setPage} />
+```
+
+## Public API
+
+Нужны `page`, `pageCount`, `onChange`. `siblings` определяет количество соседей
+слева и справа от current page и по умолчанию равен 1. `className` и `aria-label` доступны;
+имя nav по умолчанию «Страницы». Если передан неверный `page`, компонент ограничивает
+текущий номер диапазоном от 1 до `pageCount`, а `onChange` получает номер соседней
+страницы, посчитанный от зажатого `page`.
+`pageRange(page, pageCount, siblings)` возвращает массив `(number | "gap")[]`;
+он всегда оставляет первую и последнюю страницы и не скрывает ровно одну страницу
+за многоточием.
+
+## Доступность и клавиатура
+
+Это `nav` с обычными button: Tab проходит по каждому доступному действию.
+Текущая страница имеет `aria-current="page"`; prev/next имеют доступные имена и
+disabled на границах. Многоточие скрыто от скринридера и не кликабельно.
+См. [исходник Pagination](../../../src/components/navigation/Pagination.tsx).
+
+## Хорошие примеры
+
+- Сбрасывать `page` в 1 при изменении фильтра на стороне приложения.
+- Передать `siblings={2}` для длинного списка, где нужно показывать больше соседних страниц.
+- Использовать `pageRange` лишь для собственного представления с теми же правилами.
+
+## Антипаттерны
+
+- 0-based `page` или `onChange`.
+- Кликабельные многоточия, которые ничего не раскрывают.
+- Выводить pagination для единственной страницы.
+
+## Связанные исходники и Storybook
+
+- `src/components/navigation/Pagination.tsx`
+- `src/components/navigation/Pagination.stories.tsx`

package/docs/components/navigation/section-header.en.md

@@ -0,0 +1,67 @@
+---
+component: SectionHeader
+exports: [SectionHeader]
+category: navigation
+status: stable
+source: src/components/navigation/SectionHeader.tsx
+story: src/components/navigation/SectionHeader.stories.tsx
+sourceHash: 1a1ce76c770c
+---
+
+# SectionHeader
+
+## Summary for AI
+
+`SectionHeader` is a heading inside a section or card: the title on the left, an auxiliary
+`right` node on the right. The semantic `level` is chosen by the document hierarchy,
+independently of the visual `size`.
+
+## When to use
+
+- A block heading inside a page or card, next to a counter, a link,
+  a period control or a small button.
+- You need a real h2/h3/h4, not a styled div.
+
+## When not to use
+
+- For the page's single `h1`, use `PageHeader`.
+- For a modal header, use `ModalHeader`.
+- Do not use `size` to fix the logical heading hierarchy.
+
+## Minimal example
+
+```tsx
+<SectionHeader title="Publication contents" level={2} right={<Button size="sm">Add</Button>} />
+```
+
+## Public API
+
+`title` is required and can be a ReactNode. `right` takes a ready-made ReactNode
+for an action/status. `size` is `sm` or `md` (the default): it is only the font size.
+`level` is `2 | 3 | 4`, 3 by default; it determines the actual HTML heading.
+The component also accepts native `div` props and a ref; the `div` `title` prop is excluded.
+
+## Accessibility and keyboard
+
+Choose `level` based on the previous heading: right after `PageHeader` (`h1`) you usually
+need `level={2}`; the default, h3, fits a section nested in another section.
+Do not change the level to get smaller text: use `size`. `right` has no
+special keyboard handling — nested controls must be accessible on their own.
+See the [SectionHeader source](../../../src/components/navigation/SectionHeader.tsx).
+
+## Good examples
+
+- `level={2}` under `PageHeader`, then `level={3}` in a card.
+- `right` with a link, a small `Button` or neutral metadata.
+- `title` with an icon and text as a ReactNode without a nested heading.
+
+## Anti-patterns
+
+- Leaving an h3 right under the h1 only because it is the default.
+- Nesting an `<h2>` in `title` and getting a heading inside a heading.
+- Using `SectionHeader` as a page-level layout component.
+
+## Related sources and Storybook
+
+- `src/components/navigation/SectionHeader.tsx`
+- `src/components/navigation/SectionHeader.stories.tsx`

package/docs/components/navigation/section-header.md

@@ -0,0 +1,66 @@
+---
+component: SectionHeader
+exports: [SectionHeader]
+category: navigation
+status: stable
+source: src/components/navigation/SectionHeader.tsx
+story: src/components/navigation/SectionHeader.stories.tsx
+---
+
+# SectionHeader
+
+## Кратко для AI
+
+`SectionHeader` — heading внутри section или card: title слева, вспомогательный
+узел `right` справа. Семантический `level` выбирайте по иерархии документа
+независимо от визуального `size`.
+
+## Когда использовать
+
+- Заголовок блока внутри страницы или карточки, рядом со счётчиком, ссылкой,
+  переключателем периода или небольшой кнопкой.
+- Требуется настоящий h2/h3/h4, а не стилизованный div.
+
+## Когда не использовать
+
+- Для единственного `h1` страницы используйте `PageHeader`.
+- Для шапки модального окна используйте `ModalHeader`.
+- Не используйте `size` для исправления логической иерархии heading.
+
+## Минимальный пример
+
+```tsx
+<SectionHeader title="Состав публикации" level={2} right={<Button size="sm">Добавить</Button>} />
+```
+
+## Public API
+
+`title` обязателен и может быть ReactNode. `right` содержит готовый ReactNode
+для action/status. `size` — `sm` или `md` (умолчание): это только кегль.
+`level` — `2 | 3 | 4`, по умолчанию 3; он определяет фактический HTML heading.
+Компонент также принимает native `div` props и ref; нативный `title` от `div` исключён.
+
+## Доступность и клавиатура
+
+Выберите `level` по предыдущему heading: сразу после `PageHeader` (`h1`) обычно
+нужен `level={2}`; h3 по умолчанию подходит для section внутри другого раздела.
+Не меняйте level ради меньшего текста: используйте `size`. У `right` нет
+особой обработки клавиатуры — вложенные контролы обязаны быть доступны сами.
+См. [исходник SectionHeader](../../../src/components/navigation/SectionHeader.tsx).
+
+## Хорошие примеры
+
+- `level={2}` под `PageHeader`, затем `level={3}` в карточке.
+- `right` со ссылкой, маленьким `Button` или нейтральными метаданными.
+- `title` с иконкой и текстом как ReactNode без вложенного heading.
+
+## Антипаттерны
+
+- Оставить h3 сразу под h1 только потому, что это default.
+- Вложить `<h2>` в `title` и получить heading внутри heading.
+- Использовать `SectionHeader` как компонент раскладки страницы.
+
+## Связанные исходники и Storybook
+
+- `src/components/navigation/SectionHeader.tsx`
+- `src/components/navigation/SectionHeader.stories.tsx`

package/docs/components/navigation/selection-bar.en.md

@@ -0,0 +1,83 @@
+---
+component: SelectionBar
+exports: [SelectionBar, useStickyOffset]
+category: navigation
+status: stable
+source: src/components/navigation/SelectionBar.tsx, src/hooks/useStickyOffset.ts
+story: src/components/navigation/SelectionBar.stories.tsx
+sourceHash: 1463db91349e
+---
+
+# SelectionBar and useStickyOffset
+
+## Summary for AI
+
+`SelectionBar` is a bulk-actions bar: "12 selected" and what can be done with them. The counter comes from the message catalog with plural forms for the locale; `countLabel` overrides it when you need to name the entity ("12 documents selected"). The bar sticks under the application's top bar and takes its actual height from a CSS variable. `useStickyOffset` is the same stickiness mechanism on its own, for your own bars.
+
+## When to use
+
+- A list or grid supports selecting several objects, and there are actions that apply to them.
+- There is more than one action: a single one is better shown right in the object's row.
+
+## When not to use
+
+- For actions on a **single** object, use the row menu (`Menu`) or buttons at the end of the row.
+- A filter bar does not fit: it has no count of selected items and no "clear selection".
+- For confirming a destructive action, use `ConfirmDialog`.
+
+## Minimal example
+
+```tsx
+import { Button, SelectionBar } from "@olddevs/ui";
+
+<SelectionBar
+  count={selected.size}
+  countLabel={(n) => `${n} ${n === 1 ? "document" : "documents"} selected`}
+  onClear={clearSelection}
+  secondary={<button onClick={selectAll}>Select all ({total})</button>}
+>
+  <Button size="sm" icon={<CalendarIcon />} onClick={schedule}>
+    Schedule
+  </Button>
+  <Button size="sm" variant="outline" tone="danger" icon={<DeleteIcon />} onClick={remove}>
+    Delete
+  </Button>
+</SelectionBar>;
+```
+
+## Public API
+
+| Prop         | Default                | Meaning                                                                   |
+| ------------ | ---------------------- | ------------------------------------------------------------------------- |
+| `count`      | —                      | How many are selected. At zero the bar is not rendered at all.            |
+| `countLabel` | `N selected`           | Your own label, for when you count domain entities and need plural forms. |
+| `onClear`    | —                      | Clear the selection. Without it there is no "Clear selection" button.     |
+| `children`   | —                      | Actions, usually `Button size="sm"`.                                      |
+| `secondary`  | —                      | The right edge: "Select all", a link to help.                             |
+| `sticky`     | `true`                 | Stick under the top bar.                                                  |
+| `offsetVar`  | `--topbar-h`           | The name of the variable with the bar's height.                           |
+| `aria-label` | `Actions on selection` | The group's name for the screen reader.                                   |
+
+Two slots, not one: `children` take all the free space and push `secondary` to the right edge, and on a narrow screen `secondary` moves up next to the counter while the actions wrap to a second row.
+
+At medium widths, when the actions do not fit on one line with the counter, they wrap as whole buttons within their part of the bar instead of shrinking: a button label never breaks onto two lines, and its icon is never squashed.
+
+The "render nothing at zero" rule belongs to the bar, not to the calling code: otherwise every call site would write its own `count > 0 &&`, and one of them would eventually forget it.
+
+## Stickiness contract
+
+The application publishes the real height of its top bar in a CSS variable (`--topbar-h` by default), and the bar reads it. A hard-coded number will not do: on narrow screens the top bar is shorter, and a gap is left through which the scrolling content shows. The decision and the rejected options are in ADR-0016.
+
+A missing variable is a legitimate state: the offset is zero, and the bar sticks to the top of the viewport.
+
+`useStickyOffset` returns `sentinelRef` (attached to an empty zero-height block **before** the sticky element) and `isStuck`. Once stuck, the bar loses its top rounded corners — otherwise the corners reveal the page background at the seam.
+
+## Accessibility
+
+The bar is a `role="group"` with an accessible name: for a screen reader it is a set of actions on the selection, not random buttons in the middle of the page. The counter comes first and is read together with the group name. The clear button is named "Clear selection" — without a name it would be an unnamed button, and axe flags it as `critical`.
+
+## Related sources and Storybook
+
+- Sources: `src/components/navigation/SelectionBar.tsx`, `src/hooks/useStickyOffset.ts`
+- Stories: `src/components/navigation/SelectionBar.stories.tsx`
+- Tests: `tests/selection-bar.test.tsx`, `tests/sticky-offset.test.tsx`, browser stickiness scenarios — `tests-visual/interactions.spec.ts`

package/docs/components/navigation/selection-bar.md

@@ -0,0 +1,83 @@
+---
+component: SelectionBar
+exports: [SelectionBar, useStickyOffset]
+category: navigation
+status: stable
+source: src/components/navigation/SelectionBar.tsx, src/hooks/useStickyOffset.ts
+story: src/components/navigation/SelectionBar.stories.tsx
+---
+
+# SelectionBar и useStickyOffset
+
+## Кратко для AI
+
+`SelectionBar` — полоса массовых действий: «Выбрано 12» и что с этим можно сделать. Счётчик идёт из каталога сообщений со склонением по локали; `countLabel` переопределяет его, когда нужно назвать сущность («Выбрано 12 документов»). Полоса липнет под верхней панелью и берёт её фактическую высоту из CSS-переменной. `useStickyOffset` — тот же механизм липкости отдельно, для своих полос.
+
+## Когда использовать
+
+- Список или сетка поддерживают выделение нескольких объектов, и над ними есть действия.
+- Действий больше одного: одно-единственное уместнее показать прямо в строке объекта.
+
+## Когда не использовать
+
+- Для действий над **одним** объектом используйте меню строки (`Menu`) или кнопки в её конце.
+- Для панели фильтров не подходит: там нет счётчика выбранного и нет «снять выделение».
+- Для подтверждения разрушительного действия используйте `ConfirmDialog`.
+
+## Минимальный пример
+
+```tsx
+import { Button, SelectionBar } from "@olddevs/ui";
+
+// pluralize — ваша функция склонения по числу, в кит она не входит.
+<SelectionBar
+  count={selected.size}
+  countLabel={(n) => `Выбрано ${n} ${pluralize(n, ["документ", "документа", "документов"])}`}
+  onClear={clearSelection}
+  secondary={<button onClick={selectAll}>Выбрать все ({total})</button>}
+>
+  <Button size="sm" icon={<CalendarIcon />} onClick={schedule}>
+    В расписание
+  </Button>
+  <Button size="sm" variant="outline" tone="danger" icon={<DeleteIcon />} onClick={remove}>
+    Удалить
+  </Button>
+</SelectionBar>;
+```
+
+## Public API
+
+| Prop         | По умолчанию             | Значение                                                                     |
+| ------------ | ------------------------ | ---------------------------------------------------------------------------- |
+| `count`      | —                        | Сколько выбрано. При нуле полоса не рендерится вовсе.                        |
+| `countLabel` | `Выбрано N`              | Своя подпись — там, где счёт идёт в предметных единицах и требует склонения. |
+| `onClear`    | —                        | Снять выделение. Без него кнопки «Снять выделение» нет.                      |
+| `children`   | —                        | Действия, обычно `Button size="sm"`.                                         |
+| `secondary`  | —                        | Правый край: «Выбрать все», ссылка на справку.                               |
+| `sticky`     | `true`                   | Липнуть под верхней панелью.                                                 |
+| `offsetVar`  | `--topbar-h`             | Имя переменной с высотой панели.                                             |
+| `aria-label` | `Действия над выбранным` | Имя группы для скринридера.                                                  |
+
+Два слота, а не один: `children` занимают всё свободное место и прижимают `secondary` к правому краю, а на узком экране `secondary` уезжает наверх к счётчику, и действия переносятся во вторую строку.
+
+На средней ширине, когда действия не влезают в одну строку со счётчиком, они переносятся целыми кнопками внутри своей части полосы, а не ужимаются: подпись кнопки не ломается на две строки, иконка не сплющивается.
+
+Правило «при нуле ничего не рендерить» принадлежит полосе, а не вызывающему коду: иначе в каждом месте пришлось бы писать свой `count > 0 &&`, и где-то его однажды забыли бы.
+
+## Контракт липкости
+
+Приложение публикует настоящую высоту своей верхней панели в CSS-переменной (`--topbar-h` по умолчанию); полоса её читает. Зашитое число не годится: на узких экранах панель ниже по высоте, и остаётся просвет, сквозь который видно уезжающий контент. Решение и отвергнутые варианты — ADR-0016.
+
+Отсутствие переменной — законное состояние: смещение равно нулю, полоса липнет к верху окна браузера.
+
+`useStickyOffset` возвращает `sentinelRef` (вешается на пустой блок нулевой высоты **перед** липким элементом) и `isStuck`. Прижавшись, полоса теряет верхние скругления — иначе они приоткрывают фон страницы уголками на стыке.
+
+## Доступность
+
+Полоса — `role="group"` с доступным именем: для скринридера это набор действий над выбранным, а не случайные кнопки посреди страницы. Счётчик стоит первым и читается вместе с именем группы. У кнопки сброса есть имя «Снять выделение» — без него это была бы безымянная кнопка, и axe отметит это как `critical`.
+
+## Связанные исходники и Storybook
+
+- Исходники: `src/components/navigation/SelectionBar.tsx`, `src/hooks/useStickyOffset.ts`
+- Stories: `src/components/navigation/SelectionBar.stories.tsx`
+- Тесты: `tests/selection-bar.test.tsx`, `tests/sticky-offset.test.tsx`, браузерные сценарии липкости — `tests-visual/interactions.spec.ts`

package/docs/components/navigation/stepper.en.md

@@ -0,0 +1,78 @@
+---
+component: Stepper
+exports: [Stepper]
+category: navigation
+status: stable
+source: src/components/navigation/Stepper.tsx
+story: src/components/navigation/Stepper.stories.tsx
+sourceHash: 845a941e963e
+---
+
+# Stepper
+
+## Summary for AI
+
+`Stepper` shows the order of a wizard's steps; the parent sets the current index (controlled). It does not
+control moving forward, validation or showing the form panels. If you pass
+`onStepClick`, only steps already completed become buttons for going back.
+
+## When to use
+
+- A linear wizard, import, checkout or onboarding with a known number of steps.
+- You need to show the current position and allow going back to a completed step.
+- A small screen needs `orientation="vertical"`.
+
+## When not to use
+
+- For peer sections with no order, use `Tabs`.
+- For collapsible details, use `Accordion`.
+- Do not use it instead of pagination: a step is not a page of results.
+
+## Minimal example
+
+```tsx
+<Stepper
+  steps={[
+    { id: "source", label: "Source" },
+    { id: "review", label: "Review" },
+  ]}
+  current={currentStep}
+  onStepClick={setCurrentStep}
+/>
+```
+
+## Public API
+
+`steps` is an array of `{ id, label, hint? }`, `current` is a 0-based index. The optional
+`onStepClick(index)` allows going back only to `index < current`; future steps and
+the current step do not become clickable. Without the callback no step is
+clickable. `orientation` is `horizontal` (the default) or `vertical`; `className`
+and `aria-label` are available (the default is "Steps").
+
+## Accessibility and keyboard
+
+The component uses a `nav` and an ordered list, so a screen reader knows
+the order and number of steps. The current item has `aria-current="step"`; a completed
+step with a callback is a real button and reachable by Tab. The circle with the number or
+checkmark is hidden from assistive technology; the meaning comes from the list and two
+mechanisms. The current step has `aria-current="step"`. Completed and not-yet-started
+steps have visually hidden text from the message catalog (`stepper.state`):
+"completed" and "not started" in the default English catalog.
+See the [Stepper source](../../../src/components/navigation/Stepper.tsx).
+
+## Good examples
+
+- Do not pass `onStepClick` for an irreversible payment or import.
+- Pass a short `hint` for extra context under the label.
+- Keep `current` in sync with the form displayed in the parent.
+
+## Anti-patterns
+
+- Passing a 1-based current.
+- Treating `onStepClick` as permission to jump to a future unfilled form.
+- Using a changing array index instead of a stable `Step.id`.
+
+## Related sources and Storybook
+
+- `src/components/navigation/Stepper.tsx`
+- `src/components/navigation/Stepper.stories.tsx`

package/docs/components/navigation/stepper.md

@@ -0,0 +1,77 @@
+---
+component: Stepper
+exports: [Stepper]
+category: navigation
+status: stable
+source: src/components/navigation/Stepper.tsx
+story: src/components/navigation/Stepper.stories.tsx
+---
+
+# Stepper
+
+## Кратко для AI
+
+`Stepper` показывает порядок шагов мастера; текущий индекс задаёт родитель (controlled). Он не
+управляет переходом вперёд, валидацией или показом панелей с формами. Если передать
+`onStepClick`, только уже пройденные шаги станут кнопками возврата.
+
+## Когда использовать
+
+- Линейный мастер, импорт, checkout или onboarding с понятным количеством шагов.
+- Нужно показать текущую позицию и дать вернуться к пройденному шагу.
+- На небольшом экране нужен `orientation="vertical"`.
+
+## Когда не использовать
+
+- Для равноправных разделов без порядка используйте `Tabs`.
+- Для сворачиваемых деталей используйте `Accordion`.
+- Не используйте вместо pagination: шаг не равен странице выдачи.
+
+## Минимальный пример
+
+```tsx
+<Stepper
+  steps={[
+    { id: "source", label: "Источник" },
+    { id: "review", label: "Проверка" },
+  ]}
+  current={currentStep}
+  onStepClick={setCurrentStep}
+/>
+```
+
+## Public API
+
+`steps` — массив `{ id, label, hint? }`, `current` — 0-based индекс. Опциональный
+`onStepClick(index)` разрешает возврат только на `index < current`; будущие и
+текущий шаг не становятся кликабельными. Без callback не кликабелен ни один
+шаг. `orientation` — `horizontal` (умолчание) или `vertical`; есть `className`
+и `aria-label` (умолчание «Шаги»).
+
+## Доступность и клавиатура
+
+Компонент использует `nav` и упорядоченный список, поэтому скринридер знает
+порядок и число шагов. Текущий item имеет `aria-current="step"`; пройденный
+шаг с callback — настоящий button и доступен Tab. Кружок с номером или
+галочкой скрыт от вспомогательных технологий; смысл передают список и два
+механизма. У текущего шага это `aria-current="step"`. У пройденных и ещё не
+начатых шагов есть скрытый текст из каталога сообщений (`stepper.state`):
+«пройден» и «не начат» в русском каталоге.
+См. [исходник Stepper](../../../src/components/navigation/Stepper.tsx).
+
+## Хорошие примеры
+
+- Не передавать `onStepClick` для необратимой оплаты или импорта.
+- Передать короткий `hint` для дополнительного контекста под label.
+- Синхронизировать `current` с отображаемой формой в родителе.
+
+## Антипаттерны
+
+- Передавать 1-based current.
+- Считать `onStepClick` разрешением перейти в будущую незаполненную форму.
+- Использовать меняющийся индекс массива вместо стабильного `Step.id`.
+
+## Связанные исходники и Storybook
+
+- `src/components/navigation/Stepper.tsx`
+- `src/components/navigation/Stepper.stories.tsx`