@olddevs/ui 0.0.0-stage → 4.0.1

package/docs/components/content/image.md

@@ -0,0 +1,114 @@
+---
+component: Image
+exports: [Image]
+category: content
+status: stable
+source: src/components/content/Image.tsx
+story: src/components/content/Image.stories.tsx
+---
+
+# Image
+
+## Кратко для AI
+
+`Image` — картинка со всеми тремя состояниями: грузится, загрузилась, не загрузилась. Стоит на обычном `<img>`; `next/image` не используется намеренно (ADR-0011).
+
+## Когда использовать
+
+- Везде, где в разметке появился бы `<img>`: плитки, превью, изображения объектов, строки списков.
+- Когда адрес приходит из данных и может оказаться битым или пустым — то есть почти всегда.
+
+## Когда не использовать
+
+- Для иконки — это `@olddevs/ui/icons`, там векторные иконки; имя иконки выбирают по смыслу действия (см. [иконки](../../icons.md)).
+- Для фотографии пользователя есть `Avatar`: у него `src` и `alt`, круг фиксированного размера и возврат к инициалам, а загрузку внутри ведёт тот же `Image`.
+- Для пустой коробки под будущее содержимое — это `AspectRatio` или `Skeleton`.
+
+## Минимальный пример
+
+```tsx
+import { Image } from "@olddevs/ui";
+
+<Image src={document.previewUrl} alt="" ratio={16 / 9} className="w-full rounded-xl" />;
+```
+
+## Public API
+
+Компонент рисует коробку (`span`) и картинку внутри неё. Коробке — размер, скругление и рамка, картинке — вписывание.
+
+| Prop           | По умолчанию | Значение                                                                                       |
+| -------------- | ------------ | ---------------------------------------------------------------------------------------------- |
+| `src`          | —            | Адрес. `null`, `undefined` и пустая строка означают «нечего показывать» → фолбэк.              |
+| `alt`          | —            | Обязателен. `""` — законное значение: «картинка декоративна».                                  |
+| `fit`          | `cover`      | `cover` заполняет коробку, `contain` вписывает целиком. При `sizing="intrinsic"` не действует. |
+| `sizing`       | `fill`       | `fill` — размер известен снаружи, `intrinsic` — размер у картинки (ниже, «Кто задаёт размер»). |
+| `ratio`        | —            | Соотношение сторон коробки числом (`16 / 9`). Без него высоту задаёт раскладка.                |
+| `fallback`     | иконка       | Свой узел вместо иконки; `null` оставляет пустую коробку.                                      |
+| `skeleton`     | `true`       | Скелетон под картинкой, пока она грузится.                                                     |
+| `eager`        | `false`      | Отключает отложенную загрузку — для картинки первого экрана.                                   |
+| `className`    | —            | Классы коробки: размер, скругление, рамка.                                                     |
+| `imgClassName` | —            | Классы самой картинки. Нужны редко.                                                            |
+| `imgStyle`     | —            | Инлайн-стиль самой картинки; нужен там, где визуальный элемент — она, а не коробка.            |
+
+Остальные атрибуты `<img>` (включая `onLoad`, `onError`, `draggable`, `onDoubleClick`) уходят на картинку; свои обработчики вызываются вместе с внутренними, а не вместо них.
+
+Отдельного пропа `radius` нет: коробка принимает `className`, а радиусов картинки в приложении-источнике семь разных — шкала из трёх ступеней здесь мешала бы. Та же причина, по которой `Skeleton` принимает числа.
+
+## Кто задаёт размер
+
+`fill` (умолчание) — размер известен снаружи: плитка в сетке, аватар, превью фиксированной высоты. Картинке проставлены `h-full w-full`, и она заполняет коробку по `fit`.
+
+`intrinsic` — размер у картинки, коробка её оборачивает. Так устроен просмотр картинки целиком: своей высоты у него нет, есть только потолок, и вешать его нужно на **картинку**:
+
+```tsx
+<Image
+  src={photoUrl}
+  alt={title}
+  sizing="intrinsic"
+  eager
+  imgClassName="max-h-[45vh] max-w-full rounded-lg"
+/>
+```
+
+Потолок на коробке (`className`) обрежет картинку вместо того, чтобы её уменьшить. А `fill` в такой раскладке сводит всё к нулю: `h-full` — это процент от коробки, у которой размера нет. Ленивая загрузка при этом не стартует вовсе, потому что показывать нечего.
+
+Скелетона в режиме `intrinsic` нет и быть не может: до загрузки коробке нечего оборачивать. Место под картинку держит вызывающий.
+
+## Состояния
+
+- **Грузится** — скелетон лежит **под** картинкой, а не вместо неё: браузер начинает загрузку, только когда `<img>` есть в дереве.
+- **Загрузилась** — скелетон снимается.
+- **Не загрузилась** — картинка заменяется фолбэком; состояние сбрасывается при смене `src`, иначе узел, переиспользованный виртуализованной сеткой под другую картинку, навсегда остался бы с фолбэком.
+
+## Доступность
+
+`alt` обязателен, и обязательность нужна не ради текста, а ради выбора: `alt=""` — решение («картинка декоративна»), а отсутствующий атрибут — забывчивость, после которой скринридер читает вслух имя файла.
+
+Скелетон декоративен всегда. Фолбэк наследует решение из `alt`: при пустом он декоративен, при непустом берёт подпись себе (`role="img"` с тем же именем) — иначе отказ загрузки превращал бы названный объект в пустое место, о котором скринридер не сообщает. Сам факт отказа не озвучивается: это не событие для пользователя, а отсутствие превью.
+
+## Антипаттерны
+
+```tsx
+// Плохо: своя обработка отказа поверх компонента, который это уже умеет.
+const [broken, setBroken] = useState(false);
+{
+  broken ? <Placeholder /> : <Image src={src} alt="" onError={() => setBroken(true)} />;
+}
+
+// Хорошо:
+<Image src={src} alt="" fallback={<Placeholder />} />;
+```
+
+```tsx
+// Плохо: картинка первого экрана откладывается браузером и ухудшает LCP.
+<Image src={hero} alt="" />
+
+// Хорошо:
+<Image src={hero} alt="" eager />
+```
+
+## Связанные исходники и Storybook
+
+- Исходник: `src/components/content/Image.tsx`
+- Stories: `src/components/content/Image.stories.tsx`
+- Тесты: `tests/image.test.tsx`

package/docs/components/content/keyboard.en.md

@@ -0,0 +1,129 @@
+---
+component: KeyboardAccessibility
+exports: [Keyboard, VisuallyHidden]
+category: content
+status: stable
+source: src/components/content/Keyboard.tsx, src/components/content/VisuallyHidden.tsx
+story: src/components/content/Keyboard.stories.tsx, src/components/content/VisuallyHidden.stories.tsx
+sourceHash: 35adb64d94db
+---
+
+# Keyboard and VisuallyHidden
+
+## Summary for AI
+
+`Keyboard` is a controlled on-screen keyboard for an existing text field: it edits
+the string and the selection through handlers, and does not receive the field's
+DOM ref. `VisuallyHidden` keeps text in the accessibility tree but does not show
+it visually. It is not a way to hide content from everyone.
+
+## When to use
+
+- `Keyboard` — when a screen has to offer pointer or touch text editing and the
+  owner can store `value`, `selection` and the current layout. `SearchControl`
+  already knows how to integrate it through its keyboard API.
+- `VisuallyHidden` — to supplement a clear visible name with details for the
+  screen reader, for example a count next to a heading.
+
+## When not to use
+
+- `Keyboard` is an on-screen keyboard, not a way to show a keyboard shortcut.
+  "Ctrl+K" is rendered with `Kbd`, and the overview of shortcuts is `ShortcutsHelp`
+  ([page](../overlays/shortcuts-help.md)).
+- Do not use `Keyboard` as the only way to enter text: it is a supplement to a
+  real text control, not a replacement for it.
+- Do not try to edit the field through a ref or an artificial DOM event: pass the
+  state and update it through `onChange` and `onSelectionChange`.
+- Do not use `VisuallyHidden` to remove text from the accessibility tree: `display: none`,
+  `visibility: hidden` and an element hidden from assistive technology have
+  different semantics.
+- Do not hide the only accessible label of an interactive control: a user without
+  a screen reader must also be able to tell what the control does.
+
+## Minimal example
+
+```tsx
+import { Keyboard, type KeyboardSelection } from "@olddevs/ui";
+
+const [value, setValue] = useState("");
+const [selection, setSelection] = useState<KeyboardSelection>({ start: 0, end: 0 });
+const [layout, setLayout] = useState<"ru" | "en">("ru");
+
+<Keyboard
+  value={value}
+  selection={selection}
+  onChange={setValue}
+  onSelectionChange={setSelection}
+  layout={layout}
+  onLayoutChange={setLayout}
+  onSubmit={submitSearch}
+  onRequestClose={closeKeyboard}
+/>;
+```
+
+```tsx
+<Heading level={2}>
+  Drafts<VisuallyHidden elementType="span"> — eight of them</VisuallyHidden>
+</Heading>
+```
+
+`elementType="span"` is **required** when `VisuallyHidden` sits inside running text: by default the component
+renders a `<div>`, and in a heading or paragraph that is invalid nesting — React
+reports a hydration error, and the browser splits the paragraph. For a hidden
+subtree that is a block of its own, the default fits.
+
+## Public API
+
+### `Keyboard`
+
+| Prop                            | Purpose and constraints                                                                                                                                                                                             |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`                         | The current controlled string.                                                                                                                                                                                      |
+| `selection`                     | The current range of UTF-16 positions `{ start, end }` in `value`; it must be updated together with the value.                                                                                                      |
+| `onChange`, `onSelectionChange` | Required handlers. Pressing a key inserts its character at the selection, replacing the selected text; Backspace deletes the previous Unicode code point.                                                           |
+| `layout`, `onLayoutChange`      | The required layout, `ru` or `en`, and a controlled switch.                                                                                                                                                         |
+| `onSubmit`                      | An optional confirmation; called without creating an artificial DOM submit event.                                                                                                                                   |
+| `disabled`                      | Disables all keys, the move handle and the close button.                                                                                                                                                            |
+| `preserveFocus`                 | When working with a pointer, it does not take focus away from the external text field; this is an integration choice.                                                                                               |
+| `label`                         | The panel's accessible name; from the message catalog by default (`keyboard.label`): "Russian keyboard" or "English keyboard" without a provider, "Русская клавиатура" / "Английская клавиатура" with `locales/ru`. |
+| `closeLabel`, `onRequestClose`  | The accessible name and the handler of the close button. Without the handler the close button is not rendered.                                                                                                      |
+
+Exported types: `KeyboardLayout` (`"en" | "ru"`), `KeyboardSelection`,
+`KeyboardProps`.
+
+### `VisuallyHidden`
+
+`VisuallyHidden` is re-exported from `react-aria-components` together with the
+`VisuallyHiddenProps` type. Wrap the subtree to be hidden in the component; it
+does not change the subtree's text semantics, it only makes it visually hidden.
+
+## Behavior and accessibility
+
+- The panel has an accessible name, the buttons have accessible names, and Shift
+  and the symbols mode reflect their state through `aria-pressed`.
+- The arrow keys, Home and End move focus between the panel's keys; the on-screen Enter key
+  on the panel calls `onSubmit` if a handler is passed.
+- The panel is visible from the `md` width up; on a narrow screen it is not there.
+- The move handle moves the panel with the mouse and the arrow keys.
+- Shift, the symbols mode and Caps Lock are the panel's internal state. The
+  field's content and the layout stay with the owner; the panel only requests a
+  layout switch through `onLayoutChange`.
+- `VisuallyHidden` stays in the accessibility tree. Unlike `display: none`, a
+  screen reader reads the text.
+
+## Anti-patterns
+
+```tsx
+// Bad: the new value is saved, but the cursor position stays the old one.
+<Keyboard value={value} selection={selection} onChange={setValue} onSelectionChange={() => {}} … />
+
+// Good: both values belong to the same state owner.
+<Keyboard value={value} selection={selection} onChange={setValue} onSelectionChange={setSelection} … />
+```
+
+## Related sources and Storybook
+
+- Sources: `src/components/content/Keyboard.tsx`, `src/components/content/VisuallyHidden.tsx`.
+- Stories: `src/components/content/Keyboard.stories.tsx`, `src/components/content/VisuallyHidden.stories.tsx`.
+- Editing, navigation and accessible names are tested in
+  `tests/keyboard.test.tsx`; the hidden text — in `tests/wave7-layout.test.tsx`.

package/docs/components/content/keyboard.md

@@ -0,0 +1,129 @@
+---
+component: KeyboardAccessibility
+exports: [Keyboard, VisuallyHidden]
+category: content
+status: stable
+source: src/components/content/Keyboard.tsx, src/components/content/VisuallyHidden.tsx
+story: src/components/content/Keyboard.stories.tsx, src/components/content/VisuallyHidden.stories.tsx
+---
+
+# Keyboard и VisuallyHidden
+
+## Кратко для AI
+
+`Keyboard` — контролируемая экранная клавиатура для уже существующего
+текстового поля: она редактирует строку и выделение через обработчики, а не
+получает DOM-ref поля. `VisuallyHidden` оставляет текст в дереве доступности,
+но не показывает его визуально. Это не способ скрыть содержимое от всех.
+
+## Когда использовать
+
+- `Keyboard` — когда экран должен дать редактирование текста указателем или
+  касанием и владелец может хранить `value`, `selection` и текущую раскладку.
+  `SearchControl` уже умеет интегрировать её через свой keyboard API.
+- `VisuallyHidden` — чтобы дополнить понятное видимое название деталями для
+  скринридера, например количеством рядом с заголовком.
+
+## Когда не использовать
+
+- `Keyboard` — это экранная клавиатура, а не способ показать сочетание клавиш.
+  «Ctrl+K» рисуется `Kbd`, а свод сочетаний — `ShortcutsHelp`
+  ([страница](../overlays/shortcuts-help.md)).
+- Не используйте `Keyboard` как единственный способ ввода: это дополнение к
+  настоящему текстовому контролу, не его замена.
+- Не пытайтесь редактировать поле через ref или искусственный DOM-event:
+  передавайте состояние и обновляйте его через `onChange` и
+  `onSelectionChange`.
+- Не применяйте `VisuallyHidden` для удаления текста из доступности:
+  `display: none`, `visibility: hidden` и элемент, скрытый от вспомогательных
+  технологий, имеют другую семантику.
+- Не скрывайте единственную доступную подпись интерактивного контрола:
+  пользователь без скринридера тоже должен видеть, что делает контрол.
+
+## Минимальный пример
+
+```tsx
+import { Keyboard, type KeyboardSelection } from "@olddevs/ui";
+
+const [value, setValue] = useState("");
+const [selection, setSelection] = useState<KeyboardSelection>({ start: 0, end: 0 });
+const [layout, setLayout] = useState<"ru" | "en">("ru");
+
+<Keyboard
+  value={value}
+  selection={selection}
+  onChange={setValue}
+  onSelectionChange={setSelection}
+  layout={layout}
+  onLayoutChange={setLayout}
+  onSubmit={submitSearch}
+  onRequestClose={closeKeyboard}
+/>;
+```
+
+```tsx
+<Heading level={2}>
+  Черновики<VisuallyHidden elementType="span"> — восемь штук</VisuallyHidden>
+</Heading>
+```
+
+`elementType="span"` внутри строки **обязателен**: по умолчанию компонент рисует
+`<div>`, и в заголовке или абзаце это невалидная вложенность — React сообщает об
+ошибке гидрации, а браузер разрывает абзац. Для скрываемого поддерева, стоящего
+отдельным блоком, умолчание подходит.
+
+## Public API
+
+### `Keyboard`
+
+| Prop                            | Назначение и ограничения                                                                                                                                                                              |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`                         | Текущая контролируемая строка.                                                                                                                                                                        |
+| `selection`                     | Текущий диапазон позиций UTF-16 `{ start, end }` в `value`; обязан обновляться вместе со значением.                                                                                                   |
+| `onChange`, `onSelectionChange` | Обязательные обработчики. Нажатие клавиши вставляет её символ на место выделения, заменяя выделенный текст; Backspace удаляет предыдущий Unicode code point.                                          |
+| `layout`, `onLayoutChange`      | Обязательная раскладка `ru` или `en` и контролируемое переключение.                                                                                                                                   |
+| `onSubmit`                      | Необязательное подтверждение; вызывается без создания искусственного DOM-события submit.                                                                                                              |
+| `disabled`                      | Отключает все клавиши, ручку перемещения и кнопку закрытия.                                                                                                                                           |
+| `preserveFocus`                 | При работе указателем не уводит фокус с внешнего текстового поля; это выбор интеграции.                                                                                                               |
+| `label`                         | Доступное имя панели; по умолчанию из каталога сообщений (`keyboard.label`): «Русская клавиатура» / «Английская клавиатура» в `locales/ru`, без провайдера — «Russian keyboard» / «English keyboard». |
+| `closeLabel`, `onRequestClose`  | Доступное имя и обработчик кнопки закрытия. Без обработчика кнопка закрытия не рендерится.                                                                                                            |
+
+Экспортируемые типы: `KeyboardLayout` (`"en" | "ru"`), `KeyboardSelection`,
+`KeyboardProps`.
+
+### `VisuallyHidden`
+
+`VisuallyHidden` реэкспортируется из `react-aria-components` вместе с типом
+`VisuallyHiddenProps`. Оберните скрываемое поддерево в компонент; он не меняет
+его текстовую семантику, а только делает его визуально скрытым.
+
+## Поведение и доступность
+
+- Панель имеет доступное имя, кнопки — доступные названия, а Shift и режим
+  символов отражают состояние через `aria-pressed`.
+- Стрелки, Home и End переводят фокус между клавишами панели; экранная клавиша Enter
+  на панели вызывает `onSubmit`, если обработчик передан.
+- Панель видна от ширины `md`; на узком экране её нет.
+- Ручка перемещения двигает панель мышью и стрелками.
+- Shift, режим символов и Caps Lock — внутреннее состояние панели. Содержимое
+  поля и раскладка остаются у владельца; переключение раскладки панель только
+  запрашивает через `onLayoutChange`.
+- `VisuallyHidden` остаётся в дереве доступности. В отличие от `display: none`,
+  текст будет прочитан скринридером.
+
+## Антипаттерны
+
+```tsx
+// Плохо: новое значение сохраняется, но позиция курсора остаётся старой.
+<Keyboard value={value} selection={selection} onChange={setValue} onSelectionChange={() => {}} … />
+
+// Хорошо: оба значения принадлежат одному владельцу состояния.
+<Keyboard value={value} selection={selection} onChange={setValue} onSelectionChange={setSelection} … />
+```
+
+## Связанные исходники и Storybook
+
+- Исходники: `src/components/content/Keyboard.tsx`, `src/components/content/VisuallyHidden.tsx`.
+- Stories: `src/components/content/Keyboard.stories.tsx`, `src/components/content/VisuallyHidden.stories.tsx`.
+- Редактирование, навигация и доступные названия проверяет
+  `tests/keyboard.test.tsx`; скрытый текст — `tests/wave7-layout.test.tsx`.

package/docs/components/content/layout-primitives.en.md

@@ -0,0 +1,105 @@
+---
+component: LayoutPrimitives
+exports: [Separator, ScrollArea, AspectRatio, Kbd]
+category: content
+status: stable
+source: src/components/content/Separator.tsx, src/components/content/ScrollArea.tsx, src/components/content/AspectRatio.tsx, src/components/content/Kbd.tsx
+story: src/components/content/Separator.stories.tsx, src/components/content/ScrollArea.stories.tsx, src/components/content/AspectRatio.stories.tsx, src/components/content/Kbd.stories.tsx
+sourceHash: 798d3151bb67
+---
+
+# Layout primitives: `Separator`, `ScrollArea`, `AspectRatio`, `Kbd`
+
+## Summary for AI
+
+These are low-level building blocks, not a full layout system. A grid of equal
+columns comes from [`Grid`](grid.md); the package still does not export `Stack`
+and `Inline` — the screen's context sets a stack or a row with a gap. Use the
+primitives here only for a semantic boundary, scrolling, a fixed aspect ratio
+and key labels.
+
+## When to use
+
+- `Separator` — for a semantic boundary between groups; horizontal or vertical.
+- `ScrollArea` — for a self-contained fragment with native scrolling,
+  for example a list of filters.
+- `AspectRatio` — for a preview container with a ratio such as `16 / 9`, `1` or
+  `9 / 16`.
+- `Kbd` — for a text label for a key or key combination that the user presses.
+
+## When not to use
+
+- Do not place a `Separator` just for decoration: it announces the `separator`
+  role, and a screen reader reports a boundary between groups. For decoration,
+  hide the line from the accessibility tree.
+- Do not give `ScrollArea` a region role without a name: pass `label` only to a
+  self-contained section that needs a name.
+- Do not pass `AspectRatio ratio="16:9"`: the API takes the number `16 / 9`.
+- Do not render a shortcut as a plain `span`; the semantic `Kbd` exists for it.
+- The overview of all the shortcuts on a screen is not a scattering of `Kbd` elements in
+  arbitrary markup, but `ShortcutsHelp` ([page](../overlays/shortcuts-help.md)).
+
+## Minimal example
+
+```tsx
+import { AspectRatio, Kbd, ScrollArea, Separator } from "@olddevs/ui";
+
+<ScrollArea label="Sections" className="h-48">
+  <SectionList />
+</ScrollArea>
+<Separator spacing="md" />
+<AspectRatio ratio={16 / 9}><DocumentPreview /></AspectRatio>
+<span>Open search <Kbd>⌘</Kbd><Kbd>K</Kbd></span>
+```
+
+## Public API
+
+### `Separator`
+
+| Prop          | Default      | Meaning                                                                                                     |
+| ------------- | ------------ | ----------------------------------------------------------------------------------------------------------- |
+| `orientation` | `horizontal` | A horizontal or vertical line. Inside a `Toolbar` without its own value, it runs across the toolbar's axis. |
+| `spacing`     | `none`       | Outer margins `none`, `sm`, `md`; if the parent layout sets the distance, leave `none`.                     |
+
+### `ScrollArea`
+
+| Prop             | Default    | Meaning                                                                                                                        |
+| ---------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `orientation`    | `vertical` | `vertical` turns on vertical native scrolling, `horizontal` turns on horizontal.                                               |
+| `label`          | —          | The accessible name of a self-contained area. When present, the component sets `role="region"`.                                |
+| `div` attributes | —          | In particular, limit the height or width through `className`; the component does not make an area scrollable without overflow. |
+
+### `AspectRatio`
+
+| Prop    | Default  | Meaning                                                                          |
+| ------- | -------- | -------------------------------------------------------------------------------- |
+| `ratio` | `16 / 9` | A numeric CSS `aspect-ratio`; compute the fraction with a JavaScript expression. |
+
+### `Kbd`
+
+| Prop   | Default | Meaning                                                             |
+| ------ | ------- | ------------------------------------------------------------------- |
+| `size` | `sm`    | `sm` — inside a menu, `md` — in a standalone shortcuts cheat sheet. |
+
+`Kbd` renders the Apple modifier symbols (`⌘ ⌥ ⇧ ⌃`) in a string label in a
+proportional font and everything else in a monospace one. The kit's monospace
+stack has no `⇧` symbol: the fallback glyph came out thin next to `⌘` and the
+letter. The label text does not change because of this; a label passed as markup
+rather than a string stays as it is. The shortcut on `Menu` and `ContextMenu`
+items renders these symbols the same way.
+
+## Accessibility
+
+- `Separator` uses the semantic react-aria separator; the vertical version gets
+  `aria-orientation="vertical"`.
+- `ScrollArea` is always keyboard-accessible (`tabIndex=0`); otherwise
+  scrollable content cannot be reached without a mouse.
+- `Kbd` renders the HTML `kbd` tag, so it marks user input, not just monospace
+  text.
+
+## Related sources and Storybook
+
+- Sources: `src/components/content/Separator.tsx`, `src/components/content/ScrollArea.tsx`,
+  `src/components/content/AspectRatio.tsx`, `src/components/content/Kbd.tsx`.
+- Stories: `src/components/content/Separator.stories.tsx`, `src/components/content/ScrollArea.stories.tsx`, `src/components/content/AspectRatio.stories.tsx`, `src/components/content/Kbd.stories.tsx`.
+- The scrolling semantics and focus are tested in `tests/wave7-layout.test.tsx`.

package/docs/components/content/layout-primitives.md

@@ -0,0 +1,104 @@
+---
+component: LayoutPrimitives
+exports: [Separator, ScrollArea, AspectRatio, Kbd]
+category: content
+status: stable
+source: src/components/content/Separator.tsx, src/components/content/ScrollArea.tsx, src/components/content/AspectRatio.tsx, src/components/content/Kbd.tsx
+story: src/components/content/Separator.stories.tsx, src/components/content/ScrollArea.stories.tsx, src/components/content/AspectRatio.stories.tsx, src/components/content/Kbd.stories.tsx
+---
+
+# Layout primitives: `Separator`, `ScrollArea`, `AspectRatio`, `Kbd`
+
+## Кратко для AI
+
+Это низкоуровневые строительные блоки, а не полноценная система раскладки.
+Сетку равных колонок даёт [`Grid`](grid.md); `Stack` и `Inline` пакет
+по-прежнему не экспортирует — стопку и строку с зазором задаёт контекст экрана.
+Используйте здесь только смысловую границу, прокрутку, фиксированное отношение
+сторон и обозначение клавиш.
+
+## Когда использовать
+
+- `Separator` — для смысловой границы между группами; горизонтальной или
+  вертикальной.
+- `ScrollArea` — для самостоятельного фрагмента с нативной
+  прокруткой, например списка фильтров.
+- `AspectRatio` — для контейнера превью с отношением вроде `16 / 9`, `1` или
+  `9 / 16`.
+- `Kbd` — для текстового обозначения пользовательской клавиши или сочетания.
+
+## Когда не использовать
+
+- Не ставьте `Separator` ради украшения: он объявляет роль `separator`, и
+  скринридер сообщит о границе группы. Для украшения скройте черту от дерева
+  доступности.
+- Не давайте `ScrollArea` роль региона без имени: передайте `label` только
+  самостоятельному разделу, который нужно назвать.
+- Не передавайте `AspectRatio ratio="16:9"`: API принимает число `16 / 9`.
+- Не рисуйте сочетание клавиш обычным `span`; для него есть семантический `Kbd`.
+- Свод всех сочетаний экрана — не россыпь `Kbd` в произвольной разметке, а
+  `ShortcutsHelp` ([страница](../overlays/shortcuts-help.md)).
+
+## Минимальный пример
+
+```tsx
+import { AspectRatio, Kbd, ScrollArea, Separator } from "@olddevs/ui";
+
+<ScrollArea label="Разделы" className="h-48">
+  <SectionList />
+</ScrollArea>
+<Separator spacing="md" />
+<AspectRatio ratio={16 / 9}><DocumentPreview /></AspectRatio>
+<span>Открыть поиск <Kbd>⌘</Kbd><Kbd>K</Kbd></span>
+```
+
+## Public API
+
+### `Separator`
+
+| Prop          | По умолчанию | Значение                                                                                                 |
+| ------------- | ------------ | -------------------------------------------------------------------------------------------------------- |
+| `orientation` | `horizontal` | Горизонтальная либо вертикальная черта. Внутри `Toolbar` без своего значения ложится поперёк оси панели. |
+| `spacing`     | `none`       | Внешние отступы `none`, `sm`, `md`; если расстояние задаёт родительская раскладка, оставьте `none`.      |
+
+### `ScrollArea`
+
+| Prop           | По умолчанию | Значение                                                                                                              |
+| -------------- | ------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `orientation`  | `vertical`   | `vertical` включает вертикальную, `horizontal` — горизонтальную нативную прокрутку.                                   |
+| `label`        | —            | Доступное имя самостоятельной области. При наличии компонент задаёт `role="region"`.                                  |
+| атрибуты `div` | —            | В частности, ограничьте высоту/ширину через `className`; компонент не делает область прокручиваемой без переполнения. |
+
+### `AspectRatio`
+
+| Prop    | По умолчанию | Значение                                                             |
+| ------- | ------------ | -------------------------------------------------------------------- |
+| `ratio` | `16 / 9`     | Числовое CSS `aspect-ratio`; вычисляйте дробь JavaScript-выражением. |
+
+### `Kbd`
+
+| Prop   | По умолчанию | Значение                                                    |
+| ------ | ------------ | ----------------------------------------------------------- |
+| `size` | `sm`         | `sm` — внутри меню, `md` — в отдельной шпаргалке сочетаний. |
+
+`Kbd` рисует знаки модификаторов Apple (`⌘ ⌥ ⇧ ⌃`) в строковой подписи
+пропорциональным шрифтом, остальное — моноширинным. В моноширинном стеке кита
+знака `⇧` нет: запасной глиф выходил тонким рядом с `⌘` и буквой. Текст подписи
+от этого не меняется; подпись, переданная разметкой, а не строкой, остаётся как есть. Сочетание
+у пунктов `Menu` и `ContextMenu` рисует эти знаки так же.
+
+## Доступность
+
+- `Separator` использует семантический react-aria separator; вертикальная
+  версия получает `aria-orientation="vertical"`.
+- `ScrollArea` всегда доступна с клавиатуры (`tabIndex=0`): иначе без мыши до
+  прокручиваемого содержимого не добраться.
+- `Kbd` рендерит HTML-тег `kbd`, поэтому обозначает пользовательский ввод, а не
+  просто моноширинный текст.
+
+## Связанные исходники и Storybook
+
+- Исходники: `src/components/content/Separator.tsx`, `src/components/content/ScrollArea.tsx`,
+  `src/components/content/AspectRatio.tsx`, `src/components/content/Kbd.tsx`.
+- Stories: `src/components/content/Separator.stories.tsx`, `src/components/content/ScrollArea.stories.tsx`, `src/components/content/AspectRatio.stories.tsx`, `src/components/content/Kbd.stories.tsx`.
+- Семантика и фокус прокрутки проверяются в `tests/wave7-layout.test.tsx`.