@olddevs/ui 0.0.0-stage → 4.0.0

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

@@ -0,0 +1,76 @@
+---
+component: Accordion
+exports: [Accordion, AccordionItem]
+category: navigation
+status: stable
+source: src/components/navigation/Accordion.tsx
+story: src/components/navigation/Accordion.stories.tsx
+sourceHash: 9dc1af0da5f0
+---
+
+# Accordion
+
+## Summary for AI
+
+`Accordion` is a set of expandable sections built on react-aria. State and keys
+are inherited from `DisclosureGroupProps`; `multiple={false}` by default keeps
+one section open. Create every section through `AccordionItem` with
+a unique `id`.
+
+## When to use
+
+- A long page with self-contained sections that are read one at a time.
+- An FAQ, settings or details, when closed blocks save vertical space.
+- Comparing several sections at once — with `multiple`.
+
+## When not to use
+
+- For navigation between panels of one context, use `Tabs`.
+- For mandatory steps of a process, use `Stepper`.
+- Do not use it for a single permanent section: a plain heading is clearer.
+
+## Minimal example
+
+```tsx
+<Accordion expandedKeys={expanded} onExpandedChange={setExpanded}>
+  <AccordionItem id="delivery" title="Delivery">
+    Delivery terms
+  </AccordionItem>
+  <AccordionItem id="payment" title="Payment">
+    Payment methods
+  </AccordionItem>
+</Accordion>
+```
+
+## Public API
+
+`Accordion` accepts `multiple`, `className`, `children` and the rest of react-aria's
+`DisclosureGroupProps`, including controlled/uncontrolled keys. Do not
+pass `allowsMultipleExpanded`: the component's public prop is `multiple`.
+`AccordionItem` requires `id` and `title`; it also accepts `disabled`, `className`,
+`children`. `id` is used in `expandedKeys`, so it must stay stable across re-renders.
+
+## Accessibility and keyboard
+
+React Aria creates the trigger button, `aria-expanded`, the association with the panel, and hides
+collapsed content from screen readers. The trigger sits inside a heading, so
+a screen reader finds the section when navigating by heading. Do not render a second interactive control
+in `title`; put it in the panel. See the
+[Accordion source](../../../src/components/navigation/Accordion.tsx).
+
+## Good examples
+
+- The default `multiple={false}` for sequential reading.
+- `multiple` for comparing specifications.
+- A disabled item instead of a section removed without explanation: it shows that the section is unavailable.
+
+## Anti-patterns
+
+- Passing a plain `div` instead of `AccordionItem`.
+- Using an unstable array index as `id` in a mutable list.
+- Expanding all sections by default when they are not being compared.
+
+## Related sources and Storybook
+
+- `src/components/navigation/Accordion.tsx`
+- `src/components/navigation/Accordion.stories.tsx`

package/docs/components/navigation/accordion.md

@@ -0,0 +1,75 @@
+---
+component: Accordion
+exports: [Accordion, AccordionItem]
+category: navigation
+status: stable
+source: src/components/navigation/Accordion.tsx
+story: src/components/navigation/Accordion.stories.tsx
+---
+
+# Accordion
+
+## Кратко для AI
+
+`Accordion` — набор раскрываемых секций на react-aria. Состояние и keys
+наследуются из `DisclosureGroupProps`; `multiple={false}` по умолчанию оставляет
+открытой одну секцию. Создавайте каждую секцию через `AccordionItem` с
+уникальным `id`.
+
+## Когда использовать
+
+- Длинная страница с самостоятельными разделами, которые читают по очереди.
+- FAQ, настройки или подробности, когда закрытые блоки экономят вертикальное место.
+- Сравнение нескольких секций одновременно — с `multiple`.
+
+## Когда не использовать
+
+- Для навигации между панелями одного контекста используйте `Tabs`.
+- Для обязательных этапов процесса используйте `Stepper`.
+- Не используйте для одной постоянной секции: обычный heading яснее.
+
+## Минимальный пример
+
+```tsx
+<Accordion expandedKeys={expanded} onExpandedChange={setExpanded}>
+  <AccordionItem id="delivery" title="Доставка">
+    Условия доставки
+  </AccordionItem>
+  <AccordionItem id="payment" title="Оплата">
+    Способы оплаты
+  </AccordionItem>
+</Accordion>
+```
+
+## Public API
+
+`Accordion` принимает `multiple`, `className`, `children` и остальные
+`DisclosureGroupProps` react-aria, включая controlled/uncontrolled keys. Не
+передавайте `allowsMultipleExpanded`: публичный prop компонента — `multiple`.
+`AccordionItem` требует `id` и `title`; также принимает `disabled`, `className`,
+`children`. `id` участвует в `expandedKeys`, поэтому должен быть стабилен при ререндере.
+
+## Доступность и клавиатура
+
+React Aria создаёт кнопку trigger, `aria-expanded`, связь с панелью и скрывает
+свёрнутый контент от скринридера. Trigger находится внутри heading, поэтому
+скринридер находит секцию при навигации по заголовкам. Не рендерите второй интерактивный контрол
+в `title`; поместите его в panel. См.
+[исходник Accordion](../../../src/components/navigation/Accordion.tsx).
+
+## Хорошие примеры
+
+- Умолчание `multiple={false}` для последовательного чтения.
+- `multiple` для сравнения характеристик.
+- Disabled item вместо секции, удалённой без объяснения: так видно, что секция недоступна.
+
+## Антипаттерны
+
+- Передавать обычный `div` вместо `AccordionItem`.
+- Использовать нестабильный индекс массива как `id` при изменяемом списке.
+- Раскрывать все секции по умолчанию, если они не сравниваются.
+
+## Связанные исходники и Storybook
+
+- `src/components/navigation/Accordion.tsx`
+- `src/components/navigation/Accordion.stories.tsx`

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

@@ -0,0 +1,73 @@
+---
+component: Breadcrumbs
+exports: [Breadcrumbs]
+category: navigation
+status: stable
+source: src/components/navigation/Breadcrumbs.tsx
+story: src/components/navigation/Breadcrumbs.stories.tsx
+sourceHash: 7f0b528fbe8c
+---
+
+# Breadcrumbs
+
+## Summary for AI
+
+`Breadcrumbs` shows the path to the current page. Pass the chain of crumbs as `items`;
+the last visible item becomes the current page, not a link. A long
+path collapses automatically into the first crumb, an ellipsis and the last two;
+a chain of three crumbs or fewer never collapses, whatever `maxItems` is.
+
+## When to use
+
+- A deep hierarchy where the user benefits from getting back to a parent quickly.
+- Every path level of the page already has its own URL.
+
+## When not to use
+
+- For a linear wizard, use `Stepper`.
+- For short top-level navigation, use links or `Tabs`.
+- Do not use it as the only name of the current page: a page heading is needed.
+
+## Minimal example
+
+```tsx
+<Breadcrumbs
+  items={[
+    { label: "Library", href: "/library" },
+    { label: "Collections", href: "/collections" },
+    { label: "Sunsets" },
+  ]}
+/>
+```
+
+## Public API
+
+`items` is required: a `Crumb` has a `label` and an optional `href`. Usually the
+last item has no `href`; even if one is passed, the last visible crumb
+is still not rendered as a link. `maxItems` is 4 by default; `className`
+and `aria-label` are passed to the container. Without `aria-label` the name comes from the message
+catalog (`breadcrumbs.label`) — see [i18n](../../i18n.md).
+
+## Accessibility and keyboard
+
+The component creates a `nav` with an ordered list; the current crumb has
+`aria-current="page"`. The ellipsis is not a link and is hidden from screen readers.
+Links remain ordinary keyboard-focusable links. See the
+[Breadcrumbs source](../../../src/components/navigation/Breadcrumbs.tsx).
+
+## Good examples
+
+- Give every ancestor an `href` and the current item only a `label`.
+- Lower `maxItems` when the header is narrow (this does not collapse a chain of three crumbs or fewer).
+- Use short labels that stay clear when truncated.
+
+## Anti-patterns
+
+- Linking the last crumb to the current URL.
+- Making the ellipsis a button when the hidden levels cannot be expanded.
+- Passing an empty chain instead of not rendering breadcrumbs.
+
+## Related sources and Storybook
+
+- `src/components/navigation/Breadcrumbs.tsx`
+- `src/components/navigation/Breadcrumbs.stories.tsx`

package/docs/components/navigation/breadcrumbs.md

@@ -0,0 +1,72 @@
+---
+component: Breadcrumbs
+exports: [Breadcrumbs]
+category: navigation
+status: stable
+source: src/components/navigation/Breadcrumbs.tsx
+story: src/components/navigation/Breadcrumbs.stories.tsx
+---
+
+# Breadcrumbs
+
+## Кратко для AI
+
+`Breadcrumbs` показывает путь до текущей страницы. Передайте цепочку `items`;
+последний видимый crumb становится текущей страницей, а не ссылкой. Длинный
+путь автоматически сворачивается в первый crumb, многоточие и последние два;
+цепочка из трёх crumb и короче не сворачивается ни при каком `maxItems`.
+
+## Когда использовать
+
+- Глубокая иерархия, где пользователю полезно быстро вернуться к родителю.
+- У каждого уровня пути уже есть свой URL.
+
+## Когда не использовать
+
+- Для линейного мастера используйте `Stepper`.
+- Для короткой верхнеуровневой навигации используйте links или `Tabs`.
+- Не используйте как единственное имя текущей страницы: нужен page heading.
+
+## Минимальный пример
+
+```tsx
+<Breadcrumbs
+  items={[
+    { label: "Библиотека", href: "/library" },
+    { label: "Коллекции", href: "/collections" },
+    { label: "Закаты" },
+  ]}
+/>
+```
+
+## Public API
+
+`items` обязателен: `Crumb` имеет `label` и опциональный `href`. Обычно у
+последнего crumb нет `href`; даже если он передан, последний видимый crumb
+всё равно рендерится не ссылкой. `maxItems` равен 4 по умолчанию; `className`
+и `aria-label` передаются контейнеру. Без `aria-label` имя берётся из каталога
+сообщений (`breadcrumbs.label`) — см. [i18n](../../i18n.md).
+
+## Доступность и клавиатура
+
+Компонент создаёт `nav` с упорядоченным списком; текущий crumb имеет
+`aria-current="page"`. Многоточие — не ссылка и скрыто от скринридера.
+Ссылки остаются обычными keyboard-focusable links. См.
+[исходник Breadcrumbs](../../../src/components/navigation/Breadcrumbs.tsx).
+
+## Хорошие примеры
+
+- Каждому предку назначить `href`, а текущему crumb — только `label`.
+- Уменьшить `maxItems`, когда в header мало места по ширине (цепочку из трёх crumb и короче это не сворачивает).
+- Использовать короткие labels, которые остаются понятны при truncate.
+
+## Антипаттерны
+
+- Делать последний crumb ссылкой на текущий URL.
+- Делать многоточие кнопкой, если скрытые уровни нельзя раскрыть.
+- Передавать пустую цепочку вместо того, чтобы не выводить breadcrumbs.
+
+## Связанные исходники и Storybook
+
+- `src/components/navigation/Breadcrumbs.tsx`
+- `src/components/navigation/Breadcrumbs.stories.tsx`

package/docs/components/navigation/contextual-save-bar.en.md

@@ -0,0 +1,104 @@
+---
+component: ContextualSaveBar
+exports: [ContextualSaveBar]
+category: navigation
+status: stable
+source: src/components/navigation/ContextualSaveBar.tsx
+story: src/components/navigation/ContextualSaveBar.stories.tsx
+sourceHash: 87d7081dd3f9
+---
+
+# ContextualSaveBar
+
+## Summary for AI
+
+A bar for unsaved changes: it appears with the first edit of a form, shows "there are unsaved changes" (or their count) and two buttons — save and cancel. It sticks to the bottom edge of the viewport — above the application's bottom bar, if there is one (`--bottombar-h`). It knows nothing about the form data: it takes a flag for unsaved edits (`visible`), the number of edits and two handlers. The bar appearing and the progress of saving are announced to the screen reader, not just rendered.
+
+## When to use
+
+- A long form or settings page where edits accumulate and are submitted at once.
+- Editing is possible right in a list or table, and saving is shared by all the edits.
+- The user needs to see that something is unsaved, even when the changed field has scrolled out of view.
+
+## When not to use
+
+- **For selecting objects**, use `SelectionBar`: "12 selected" and actions on them.
+- **For application state** ("maintenance in progress", "subscription is expiring"), use `Banner`: it survives navigation and does not belong to the current form.
+- **For a message about something that has already happened** ("saved"), use a `toast`.
+- For a form with a single "Submit" button at the bottom: the bar would duplicate it.
+
+In short: `SelectionBar` is about selection, `Banner` is about the application, `ContextualSaveBar` is about the current form.
+
+## Minimal example
+
+```tsx
+import { ContextualSaveBar } from "@olddevs/ui";
+
+export function GroupSettings() {
+  const [value, setValue] = useState(saved);
+  const dirty = value !== saved;
+
+  return (
+    <form>
+      {/* form fields */}
+      <ContextualSaveBar
+        visible={dirty}
+        onSave={() => save(value)}
+        onCancel={() => setValue(saved)}
+      />
+    </form>
+  );
+}
+```
+
+## Props
+
+| Prop                        | Type                          | Meaning                                                                                              |
+| --------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `visible`                   | `boolean`                     | Whether anything is unsaved. When `false` the bar is not rendered                                    |
+| `count`                     | `number`                      | The number of edits. Without it, "there are unsaved changes"; with it, the count is shown            |
+| `message`                   | `ReactNode`                   | Your own wording instead of the default. Replaces `count` as well                                    |
+| `onSave`                    | `() => void`                  | Required: the bar exists for it                                                                      |
+| `onCancel`                  | `() => void`                  | Cancel. **Without a handler there is no button at all**                                              |
+| `saving`                    | `boolean`                     | Saving is in progress: the button shows progress, cancel is disabled                                 |
+| `error`                     | `ReactNode`                   | The text of a failure. Shown in the bar and announced                                                |
+| `saveLabel` / `cancelLabel` | `ReactNode`                   | Your own button labels                                                                               |
+| `sticky`                    | `boolean` (`true` by default) | Stick to the bottom of the viewport                                                                  |
+| `offsetVar`                 | `string` (`"--bottombar-h"`)  | The variable holding the bottom bar height: the bar is offset above the viewport edge by that height |
+
+The component does not store form state. What counts as an edit is the consumer's decision: a comparison with the original value, a field-touch counter or a server response.
+
+## Why at the bottom, not the top
+
+The bar sticks to the bottom edge of the **nearest scroll area**: the browser window, if the page scrolls, and the container, if the work area has its own `overflow` — as in most admin panels. This is ordinary `position: sticky` semantics, and you should know it: an ancestor with `overflow: auto` that does not itself scroll cancels stickiness to the window.
+
+The application header and `SelectionBar` already sit at the top, and both measure stickiness from `--topbar-h` (ADR-0016, ADR-0019). A third sticky layer at the top would need a second height variable and a revision of the contract — a price out of proportion to the task. The bottom is free, and users are used to seeing such a bar there in admin panels.
+
+## Above the phone's bottom bar
+
+On a phone the bottom edge of the viewport is taken by `MobileTabBar` in the `bottomBar` slot of `AppShell`. The shell publishes the slot height as `--bottombar-h` (at `md` and wider there is no bar and the value is `0px`), and the bar sticks that far above the viewport edge — the same way `SelectionBar` measures its stickiness from `--topbar-h`. There is no need to offset the bar with `max-md:bottom-14` by eye: a hard-coded number drifts from the real bar height (notch inset, wrapped labels).
+
+`offsetVar` changes the variable name if the shell publishes it under a different name (`bottomBarHeightVar` on `AppShell`) or the application publishes the bottom bar itself. The offset is a class that reads this variable, not an inline `bottom`, so a `className` with `bottom-*` overrides it: your own bottom bar outside `AppShell` sets the offset the same way as with an inline `bottom`. With no published variable the offset is `0px`.
+
+## Accessibility and keyboard
+
+- The bar has the `group` role and an accessible name: for a screen reader it is a set of actions on the form, not buttons in the middle of the page.
+- The bar appearing, the progress of saving and a failure are announced by a `role="status"` live region. The region is always mounted and only its content is swapped: a live region inserted into the tree together with its text is announced unreliably.
+- The role is `status`, not `alert`, even on failure: the failure comes with visible text in the bar itself, and there is no need to interrupt speech.
+- The buttons are ordinary `Button` components: Tab, Enter, Space. While saving, cancel is disabled and the save button shows progress.
+
+**A known cost.** The bar's text gets into the accessibility tree twice: as a visible line and as a live region. In browse mode it is read twice in a row. The trade-off is deliberate: if the bar's appearance is announced unreliably, that is worse than an extra repeat. The same question is open for `MaskedInput` (ADR-0026) and is closed by one run with NVDA and VoiceOver — for both components at once.
+
+## Anti-patterns
+
+- **Intercepting navigation away from the page inside the kit.** The bar knows nothing about the router and should not; a warning about leaving the page is the application's business.
+- **Keeping a third and fourth button in the bar.** The bar is about one decision: save or cancel. Everything else belongs in the form.
+- **Showing the bar always, with a disabled button.** A permanent bar stops meaning "something is unsaved" and takes space from the content.
+- **Replacing a page-level error message with the bar.** A save failure is fine; for an unavailable service, use `Banner`.
+
+## Links
+
+- Source: [`src/components/navigation/ContextualSaveBar.tsx`](../../../src/components/navigation/ContextualSaveBar.tsx)
+- Tests: [`tests/contextual-save-bar.test.tsx`](../../../tests/contextual-save-bar.test.tsx)
+- Story: [`src/components/navigation/ContextualSaveBar.stories.tsx`](../../../src/components/navigation/ContextualSaveBar.stories.tsx)
+- Neighbors at the boundary: [SelectionBar](selection-bar.md), [Banner](../actions/feedback.md)

package/docs/components/navigation/contextual-save-bar.md

@@ -0,0 +1,103 @@
+---
+component: ContextualSaveBar
+exports: [ContextualSaveBar]
+category: navigation
+status: stable
+source: src/components/navigation/ContextualSaveBar.tsx
+story: src/components/navigation/ContextualSaveBar.stories.tsx
+---
+
+# ContextualSaveBar
+
+## Кратко для AI
+
+Полоса несохранённых изменений: появляется с первой правкой формы, показывает «есть несохранённые изменения» (или их число) и две кнопки — сохранить и отменить. Липнет к нижнему краю окна браузера — над нижней панелью приложения, если она есть (`--bottombar-h`). Данных формы не знает: принимает признак несохранённых правок (`visible`), число правок и два обработчика. Появление и ход сохранения объявляются скринридеру, а не только выводятся на экран.
+
+## Когда использовать
+
+- Длинная форма или страница настроек, где правки копятся и отправляются разом.
+- Правка возможна прямо в списке или таблице, и сохранение общее для всех правок.
+- Пользователю нужно видеть, что несохранённое есть, даже если изменённое поле уехало из кадра.
+
+## Когда не использовать
+
+- **Для выбора объектов** используйте `SelectionBar`: «Выбрано 12» и действия над ними.
+- **Для состояния приложения** («идут работы», «подписка истекает») используйте `Banner`: он переживает навигацию и не относится к текущей форме.
+- **Для сообщения об уже случившемся** («сохранено») используйте `toast`.
+- Для формы с единственной кнопкой «Отправить» внизу: полоса дублировала бы её.
+
+Граница коротко: `SelectionBar` — про выбор, `Banner` — про приложение, `ContextualSaveBar` — про текущую форму.
+
+## Минимальный пример
+
+```tsx
+import { ContextualSaveBar } from "@olddevs/ui";
+
+export function GroupSettings() {
+  const [value, setValue] = useState(saved);
+  const dirty = value !== saved;
+
+  return (
+    <form>
+      {/* поля формы */}
+      <ContextualSaveBar
+        visible={dirty}
+        onSave={() => save(value)}
+        onCancel={() => setValue(saved)}
+      />
+    </form>
+  );
+}
+```
+
+## Props
+
+| Проп                        | Тип                             | Смысл                                                                                       |
+| --------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------- |
+| `visible`                   | `boolean`                       | Есть ли несохранённое. При `false` полоса не рендерится                                     |
+| `count`                     | `number`                        | Число правок. Без него — «есть несохранённые изменения»; с ним называется число             |
+| `message`                   | `ReactNode`                     | Своя формулировка вместо умолчания. Вытесняет и `count`                                     |
+| `onSave`                    | `() => void`                    | Обязателен: ради него полоса и существует                                                   |
+| `onCancel`                  | `() => void`                    | Отмена. **Без обработчика кнопки нет вовсе**                                                |
+| `saving`                    | `boolean`                       | Идёт сохранение: кнопка показывает ход, отмена выключена                                    |
+| `error`                     | `ReactNode`                     | Текст отказа. Показывается в полосе и объявляется                                           |
+| `saveLabel` / `cancelLabel` | `ReactNode`                     | Свои подписи кнопок                                                                         |
+| `sticky`                    | `boolean` (по умолчанию `true`) | Липнуть к низу области просмотра                                                            |
+| `offsetVar`                 | `string` (`"--bottombar-h"`)    | Переменная с высотой нижней панели: полоса встаёт на эту высоту выше края области просмотра |
+
+Состояние формы компонент не хранит. Что считать правкой — решение потребителя: сравнение с исходным значением, счётчик касаний поля или ответ сервера.
+
+## Почему внизу, а не вверху
+
+Полоса липнет к нижнему краю **ближайшей области прокрутки**: окна браузера, если прокручивается страница, и контейнера, если у рабочей области свой `overflow` — как в большинстве админок. Это обычная семантика `position: sticky`, и знать её стоит: предок с `overflow: auto`, который сам не прокручивается, отменяет липкость к окну.
+
+Наверху уже стоят шапка приложения и `SelectionBar`, и обе отсчитывают липкость от `--topbar-h` (ADR-0016, ADR-0019). Третий липкий слой сверху потребовал бы второй переменной высоты и пересмотра контракта — цена, несопоставимая с задачей. Внизу свободно, и там пользователи привыкли видеть такую полосу в админках.
+
+## Над нижней панелью телефона
+
+На телефоне нижний край области просмотра занимает `MobileTabBar` в слоте `bottomBar` у `AppShell`. Каркас публикует высоту слота в `--bottombar-h` (на `md` и шире панели нет, значение `0px`), а полоса прилипает на эту высоту выше края области просмотра — так же, как `SelectionBar` отсчитывает липкость от `--topbar-h`. Задавать полосе отступ `max-md:bottom-14` на глаз не нужно: зашитое число расходится с настоящей высотой панели (вырез экрана, перенос подписей).
+
+`offsetVar` меняет имя переменной, если каркас публикует её под другим (`bottomBarHeightVar` у `AppShell`) или нижнюю панель публикует само приложение. Отступ — класс, читающий эту переменную, а не инлайновый `bottom`, поэтому `className` с `bottom-*` его перекрывает: своя нижняя панель вне `AppShell` задаёт отступ так же, как при инлайновом `bottom`. Если переменная не опубликована, отступ `0px`.
+
+## Доступность и клавиатура
+
+- У полосы роль `group` и доступное имя: для скринридера это набор действий над формой, а не кнопки посреди страницы.
+- Появление, ход сохранения и отказ объявляются живой областью `role="status"`. Область смонтирована всегда, содержимое подменяется: живая область, вставленная в дерево вместе со своим текстом, объявляется ненадёжно.
+- Роль `status`, а не `alert`, даже при отказе: отказ сопровождается видимым текстом в самой полосе, и перебивать речь незачем.
+- Кнопки — обычные `Button`: Tab, Enter, пробел. Во время сохранения отмена выключена, а кнопка сохранения показывает ход.
+
+**Известная цена.** Текст полосы попадает в дерево доступности дважды: видимой строкой и живой областью. В режиме обзора он читается два раза подряд. Размен сознательный: если появление полосы объявляется ненадёжно, это хуже лишнего повтора. Тот же вопрос открыт у `MaskedInput` (ADR-0026) и закрывается одним прогоном с NVDA и VoiceOver — на оба компонента разом.
+
+## Антипаттерны
+
+- **Перехватывать уход со страницы внутри кита.** Полоса не знает маршрутизатора и знать не должна; предупреждение об уходе — дело приложения.
+- **Держать в полосе третью и четвёртую кнопку.** Полоса про одно решение: сохранить или отменить. Остальное — в форме.
+- **Показывать полосу всегда, с выключенной кнопкой.** Постоянная полоса перестаёт значить «есть несохранённое» и отнимает место у содержимого.
+- **Заменять полосой сообщение об ошибке уровня страницы.** Отказ сохранения — да; для недоступного сервиса используйте `Banner`.
+
+## Ссылки
+
+- Исходник: [`src/components/navigation/ContextualSaveBar.tsx`](../../../src/components/navigation/ContextualSaveBar.tsx)
+- Тесты: [`tests/contextual-save-bar.test.tsx`](../../../tests/contextual-save-bar.test.tsx)
+- История: [`src/components/navigation/ContextualSaveBar.stories.tsx`](../../../src/components/navigation/ContextualSaveBar.stories.tsx)
+- Соседи по границе: [SelectionBar](selection-bar.md), [Banner](../actions/feedback.md)

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

@@ -0,0 +1,71 @@
+---
+component: PageHeader
+exports: [PageHeader]
+category: navigation
+status: stable
+source: src/components/navigation/PageHeader.tsx
+story: src/components/navigation/PageHeader.stories.tsx
+sourceHash: 251f8566db5a
+---
+
+# PageHeader
+
+## Summary for AI
+
+`PageHeader` is the single page header with an `h1`, an optional description and
+action nodes. Use it once per page; do not choose a size — the component
+has no size scale and should not have one.
+
+## When to use
+
+- The top of a page, with its main title.
+- Primary actions are needed next to it: create, upload, open filters.
+- On mobile the actions can wrap under the title automatically.
+
+## When not to use
+
+- For a heading inside a card/section, use `SectionHeader`.
+- For a modal title, use `Dialog`/`ModalHeader`.
+- Do not use more than one `PageHeader` on one semantic page.
+
+## Minimal example
+
+```tsx
+<PageHeader
+  title="Library"
+  subtitle="3,527 photos"
+  actions={<Button tone="accent">Upload</Button>}
+/>
+```
+
+## Public API
+
+`title` is required and accepts a `ReactNode`; it is rendered in an `h1`. `subtitle` and
+`actions` are also of type `ReactNode`. The component accepts the other native `div` props,
+including `className` and `ref`; the native `title` prop is deliberately excluded so that it does not
+conflict with the required heading. On desktop the header lays its content out
+in a row, on a narrow layout in a column; actions can wrap.
+
+## Accessibility and keyboard
+
+The heading is always an `h1`, so the `title` text must be the name of the current
+page, not an action verb. each action in `actions` must be an accessible control on its own;
+`PageHeader` does not add an aria-label or handlers to them. See the
+[PageHeader source](../../../src/components/navigation/PageHeader.tsx).
+
+## Good examples
+
+- `title` as text or icon + text in one ReactNode.
+- The primary action in `actions`, secondary actions next to it.
+- `subtitle` with a count or a short description of the page.
+
+## Anti-patterns
+
+- A `title` with a nested heading, even though `PageHeader` already creates the `h1`.
+- Overriding the `PageHeader` title through the DOM `title` attribute.
+- Using actions as a place for unrelated global navigation.
+
+## Related sources and Storybook
+
+- `src/components/navigation/PageHeader.tsx`
+- `src/components/navigation/PageHeader.stories.tsx`

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

@@ -0,0 +1,70 @@
+---
+component: PageHeader
+exports: [PageHeader]
+category: navigation
+status: stable
+source: src/components/navigation/PageHeader.tsx
+story: src/components/navigation/PageHeader.stories.tsx
+---
+
+# PageHeader
+
+## Кратко для AI
+
+`PageHeader` — единственная шапка страницы с `h1`, опциональным пояснением и
+узлами действий. Используйте один раз на page; не выбирайте размер — у компонента
+нет и не должно быть шкалы размеров.
+
+## Когда использовать
+
+- Верх страницы с главным заголовком.
+- Рядом нужны основные действия: создать, загрузить, открыть фильтры.
+- На mobile действия могут переноситься под заголовок автоматически.
+
+## Когда не использовать
+
+- Для заголовка внутри card/section используйте `SectionHeader`.
+- Для title модального окна используйте `Dialog`/`ModalHeader`.
+- Не используйте несколько `PageHeader` на одной семантической странице.
+
+## Минимальный пример
+
+```tsx
+<PageHeader
+  title="Библиотека"
+  subtitle="3 527 фото"
+  actions={<Button tone="accent">Загрузить</Button>}
+/>
+```
+
+## Public API
+
+`title` обязателен и принимает `ReactNode`; он рендерится в `h1`. `subtitle` и
+`actions` также ReactNode. Компонент принимает остальные native `div` props,
+включая `className` и `ref`; native `title` prop намеренно исключён, чтобы не
+конфликтовать с обязательным heading. На desktop шапка располагает содержимое
+по строке, в узкой раскладке — колонкой; actions могут переноситься.
+
+## Доступность и клавиатура
+
+Заголовок всегда `h1`, поэтому текст `title` должен быть названием текущей
+страницы, а не глаголом действия. каждое действие в `actions` должно быть доступным
+контролом само по себе; `PageHeader` не добавляет им aria-label или обработчики. См.
+[исходник PageHeader](../../../src/components/navigation/PageHeader.tsx).
+
+## Хорошие примеры
+
+- `title` как текст или иконка с текстом в одном ReactNode.
+- Основное действие в `actions`, вторичные действия рядом.
+- `subtitle` с количеством или коротким пояснением страницы.
+
+## Антипаттерны
+
+- `title` с вложенным heading, хотя `PageHeader` уже создаёт `h1`.
+- Подменять `PageHeader` title через DOM `title` attribute.
+- Использовать actions как место для несвязанной глобальной навигации.
+
+## Связанные исходники и Storybook
+
+- `src/components/navigation/PageHeader.tsx`
+- `src/components/navigation/PageHeader.stories.tsx`