@olddevs/ui 0.0.0-stage → 4.0.0

package/docs/components/inputs/color-picker.en.md

@@ -0,0 +1,126 @@
+---
+component: ColorPicker
+exports: [ColorPicker]
+category: inputs
+status: stable
+source: src/components/inputs/ColorPicker.tsx
+story: src/components/inputs/ColorPicker.stories.tsx
+sourceHash: 12e0cabcacce
+---
+
+# ColorPicker
+
+## Summary for AI
+
+`ColorPicker` picks an arbitrary color: a saturation area, a hue strip, a format field and optional presets. **It lives in its own entry point `@olddevs/ui/color`, not in the barrel.** The value is a string, not an object.
+
+```tsx
+import { ColorPicker } from "@olddevs/ui/color";
+```
+
+## When to use
+
+- The user names their own color: a label, a status, a tenant's brand color, a category highlight.
+- The value goes into data and comes back from there as a string.
+
+## Minimal example
+
+The import is **not from the root** — that is the main feature of the component:
+
+```tsx
+import { ColorPicker } from "@olddevs/ui/color";
+
+<ColorPicker value={brand} onChange={setBrand} label="Brand color" />;
+```
+
+## When not to use
+
+- The choice is from a fixed set — that is `Select` or `ToggleGroup` with swatches.
+- The color is set by the theme — use a token, not a picker.
+
+## Why a separate entry point
+
+The color subsystem of `react-aria-components` costs **61 kB gzip**: it is seven
+components the kit used nowhere else. For comparison: the whole rest of the kit
+fits in 62 kB.
+
+The kit's own budget does not see this: in `npm run size` react-aria is declared
+external together with the other peer dependencies, and the consumer fixture page
+does not import color. A gate that is green whatever the decision checks nothing.
+
+A separate entry point makes 61 kB visible in the import line itself. The kit
+has a precedent for the same reason: the locale catalogs live as
+`@olddevs/ui/locales/ru`, "so they are not pulled into the bundle without an
+import". The decision and the numbers are in
+ADR-0038.
+
+A consequence accepted on purpose: `import * as ui from "@olddevs/ui"` does not
+give you color, and you need a second import. That is the point of the decision.
+
+## Public API
+
+- `value` and `onChange` take a **string**: `#4f7df3`, `rgb(...)`, `hsl(...)`. The library's `Color` object is not exposed: it would drag the react-aria type into the consumer's state and signatures.
+- `label` is required — it is the name of the control. It is always on the button, including when `children` replace its content: otherwise an icon in place of a label would leave the button nameless.
+- `outputFormat`: `hex` (default), `rgb`, `hsl` — the format of the **string in `onChange`**. The input field always stays hexadecimal, and the prop name says so: `rgb` and `hsl` are three channel fields, that is, a different control, not a different format of the same one. So the field label is also always `HEX`: labeling it "HSL" when it accepts hex would be lying to the user right on the screen.
+- `presets` — a row of presets. **There is no default on purpose**: a set of "brand" colors is the consumer's domain, and whoever knows which of the theme tokens apply to their entity should be the one to put them here. An unrecognized preset is **skipped**; it does not crash the render — see below.
+- `children` replace the trigger content when a swatch with a label is not enough.
+- `disabled` keeps the panel from opening.
+
+## An unrecognized preset is skipped, an unrecognized value is not
+
+The asymmetry is deliberate. The consumer stores the **value** and passes it on,
+so a string in `value` that is not recognized becomes black (the reason is in the
+next section), and the kit does not step in.
+
+A **preset** is decoration. On a string it does not recognize, the library
+**throws**, and in the render phase at that, so it takes down the whole consumer
+subtree; a component must not fall over because of decoration. And what breaks is
+not an exotic case: `rebeccapurple` is a legal CSS color that the library does not
+accept, and keeping a brand palette as names is natural. Presets that are
+not recognized are not rendered; if none is recognized, there is no row at
+all.
+
+## An unrecognized value becomes black
+
+This is react-aria behavior, and the kit does not intercept it: replacing the
+consumer's value silently is the same as silently repairing it. It is worth knowing the
+consequence: the very first move of the slider passes black to `onChange`, that is,
+it replaces the unrecognized value with a recognized one. Checking the string
+is the consumer's job, since the consumer is the one who built it.
+
+## A wrapper over `react-aria-components`
+
+The kit does not do color math itself. Color space conversions, string parsing, accessible shade descriptions for the
+screen reader and the keyboard handling of the two-dimensional area — all of this
+is already in `react-aria-components` (generally available since 1.4.0). The component
+adds only the token vocabulary on top and the layout.
+
+## The component produces a color outside the token system
+
+This is its purpose, not an oversight. Everything else in the kit takes color from
+the theme; here the user names their own — and the result by design follows
+neither the theme nor the brand.
+
+This also means the kit does **not** check the contrast of the chosen color, and
+cannot, because it does not know what the color will end up on. Responsibility for legibility stays with the consumer.
+
+"Custom color…" in
+[`RichTextEditor`](./rich-text-editor.md#свой-цвет) takes on this responsibility:
+`ColorPicker` sits in a popover, and next to it the contrast of the chosen color against the Editor
+background of the current theme is computed and a warning is shown (4.5:1). The
+Editor loads it lazily — the react-aria color subsystem stays out of the
+`@olddevs/ui/editor` entry point.
+
+## Keyboard
+
+- The trigger is a regular button: Enter and Space open the panel, Escape closes it and returns focus.
+- The two-dimensional saturation and brightness area is one control with two axes: arrow keys move along both; `Home` and `End` jump to the ends of the current axis.
+- The hue strip and the format field are separate tab stops; the row of presets is traversed with arrow keys as a single group.
+- All of the above comes from react-aria together with the accessible shade descriptions; the kit writes no keyboard handling of its own here.
+
+## Accessibility and semantics
+
+- The controls of the saturation area and the hue strip are described in the "Keyboard" section; roles, bounds and keyboard handling come from react-aria.
+- The library itself localizes the color channel names and the accessible shade descriptions — the kit adds no message catalog keys of its own for them.
+- The label of the presets row comes from the message catalog (`colorPicker.presets`).
+- See `src/color.ts`, `src/components/inputs/ColorPicker.tsx`, `src/components/inputs/ColorPicker.stories.tsx`, `tests/color-picker.test.tsx`.

package/docs/components/inputs/color-picker.md

@@ -0,0 +1,122 @@
+---
+component: ColorPicker
+exports: [ColorPicker]
+category: inputs
+status: stable
+source: src/components/inputs/ColorPicker.tsx
+story: src/components/inputs/ColorPicker.stories.tsx
+---
+
+# ColorPicker
+
+## Кратко для AI
+
+`ColorPicker` — выбор произвольного цвета: область насыщенности, полоса тона, поле формата и необязательные заготовки. **Живёт отдельным входом `@olddevs/ui/color`, не в barrel.** Значение — строка, а не объект.
+
+```tsx
+import { ColorPicker } from "@olddevs/ui/color";
+```
+
+## Когда использовать
+
+- Пользователь называет свой цвет: метка, статус, фирменный цвет арендатора, подсветка категории.
+- Значение уходит в данные и возвращается оттуда строкой.
+
+## Минимальный пример
+
+Импорт **не из корня** — это и есть главная особенность компонента:
+
+```tsx
+import { ColorPicker } from "@olddevs/ui/color";
+
+<ColorPicker value={brand} onChange={setBrand} label="Фирменный цвет" />;
+```
+
+## Когда не использовать
+
+- Выбор идёт из фиксированного набора — это `Select` или `ToggleGroup` с образцами.
+- Цвет задан темой — берите токен, а не поле выбора.
+
+## Почему отдельный вход
+
+Цветовая подсистема `react-aria-components` стоит **61 кБ gzip**: это семь
+компонентов, которых кит не использовал больше нигде. Для сравнения: весь
+остальной кит укладывается в 62 кБ.
+
+Собственный бюджет кита этого не видит: в `npm run size` react-aria объявлен
+внешним вместе с остальными peer-зависимостями, а страница фикстуры потребителя
+цвет не импортирует. Гейт, который зелёный при любом решении, ничего не проверяет.
+
+Отдельный вход делает 61 кБ видимыми в самой строке импорта.
+Прецедент в ките заведён по той же причине: каталоги локалей живут как
+`@olddevs/ui/locales/ru`, «чтобы не тянуться в бандл без импорта». Решение и
+числа — ADR-0038.
+
+Следствие, принимаемое сознательно: `import * as ui from "@olddevs/ui"` цвета не
+даст, и понадобится второй импорт. Это и есть смысл решения.
+
+## Public API
+
+- `value` + `onChange` — **строка**: `#4f7df3`, `rgb(...)`, `hsl(...)`. Объект `Color` библиотеки наружу не выходит: он протащил бы тип react-aria в состояние потребителя и в его сигнатуры.
+- `label` обязателен — это имя контрола. Оно стоит на кнопке всегда, в том числе когда `children` заменяют её содержимое: иначе иконка вместо подписи оставляла бы кнопку безымянной.
+- `outputFormat`: `hex` (по умолчанию), `rgb`, `hsl` — формат **строки в `onChange`**. Поле ввода остаётся шестнадцатеричным всегда, и это названо в имени пропа: `rgb` и `hsl` — это три поля каналов, то есть другой контрол, а не другой формат того же. Подпись поля поэтому тоже всегда `HEX`: подписать его «HSL», когда оно принимает hex, значило бы врать пользователю прямо на экране.
+- `presets` — ряд заготовок. **Умолчания нет намеренно**: набор «фирменных» цветов — это домен потребителя, и подставить сюда значения токенов темы должен тот, кто знает, какие из них применимы к его сущности. Нераспознанная заготовка **пропускается** и не роняет рендер — см. ниже.
+- `children` заменяют содержимое триггера, если образца с подписью мало.
+- `disabled` не даёт панели раскрыться.
+
+## Нераспознанная заготовка пропускается, а нераспознанное значение — нет
+
+Асимметрия намеренная. **Значение** потребитель хранит и отдаёт дальше,
+поэтому нераспознанная строка в `value` становится чёрным (причина — в
+следующем разделе), а кит в это не вмешивается.
+
+**Заготовка** — оформление. Библиотека на нераспознанной строке **бросает**, причём в
+фазе рендера, то есть уносит поддерево потребителя целиком; падать из-за
+оформления компонент не должен. Ломается при этом не экзотика: `rebeccapurple` —
+законный CSS-цвет, которого библиотека не берёт, а фирменную палитру
+естественно держать именами. Нераспознанные заготовки просто не рисуются; если
+не распознана ни одна, ряда нет вовсе.
+
+## Нераспознанное значение становится чёрным
+
+Так ведёт себя react-aria, и кит это не перехватывает: подменять значение
+потребителя молча — то же самое, что молча его чинить. Последствие стоит знать: первое же
+движение ползунка отдаст в `onChange` чёрный, то есть заменит нераспознанное значение
+распознанным. Проверять строку — обязанность потребителя, он же её и сформировал.
+
+## Обёртка над `react-aria-components`
+
+Кит не считает цвет сам. Преобразования пространств, разбор строк, доступные описания оттенков для
+скринридера и клавиатура двумерной области — всё это уже есть в
+`react-aria-components` (общедоступно с 1.4.0). Здесь только словарь токенов
+сверху и раскладка.
+
+## Компонент выдаёт цвет мимо системы токенов
+
+Это его назначение, а не недосмотр. Всё остальное в ките берёт цвет из темы;
+здесь пользователь называет свой — и результат по самому устройству не подчиняется
+ни теме, ни бренду.
+
+Отсюда следует и то, чего кит **не** делает: контраст выбранного цвета он не
+проверяет и проверить не может, потому что не знает, на чём этот цвет окажется.
+Ответственность за читаемость остаётся у потребителя.
+
+Эту ответственность берёт на себя «Свой цвет…» в
+[`RichTextEditor`](./rich-text-editor.md#свой-цвет): `ColorPicker` стоит в
+поповере, а рядом считается контраст выбранного цвета против фона Редактора
+текущей темы и выводится предупреждение (4.5:1). Редактор грузит его лениво —
+цветовая подсистема react-aria не попадает в вход `@olddevs/ui/editor`.
+
+## Клавиатура
+
+- Триггер — обычная кнопка: Enter и Space раскрывают панель, Escape закрывает и возвращает фокус.
+- Двумерная область насыщенности и яркости — один контрол с двумя осями: стрелки ведут по обеим, `Home` и `End` уводят на края текущей оси.
+- Полоса тона и поле формата — отдельные табстопы; ряд заготовок обходят стрелками как единую группу.
+- Всё перечисленное приходит из react-aria вместе с доступными описаниями оттенков; кит своей клавиатуры здесь не пишет.
+
+## Доступность и семантика
+
+- Контролы области насыщенности и полосы тона описаны в разделе «Клавиатура»; роли, границы и клавиатура приходят из react-aria.
+- Названия каналов цвета и доступные описания оттенков локализует сама библиотека — своих ключей каталога сообщений кит на них не заводит.
+- Подпись ряда заготовок берётся из каталога сообщений (`colorPicker.presets`).
+- См. `src/color.ts`, `src/components/inputs/ColorPicker.tsx`, `src/components/inputs/ColorPicker.stories.tsx`, `tests/color-picker.test.tsx`.

package/docs/components/inputs/combobox.en.md

@@ -0,0 +1,62 @@
+---
+component: Combobox
+exports: [Combobox]
+category: inputs
+status: stable
+source: src/components/inputs/Combobox.tsx
+story: src/components/inputs/Combobox.stories.tsx
+sourceHash: 21faf75caa5a
+---
+
+# Combobox
+
+## Summary for AI
+
+`Combobox` combines free text input with a list of options. Picking from the list helps, but the value may not match `items`; this is what fundamentally sets it apart from `Select`.
+
+## When to use
+
+- The user may type a new tag, address, name or other valid text.
+- You need a list of options and filtering while typing.
+
+## When not to use
+
+- You need a strictly closed vocabulary — `Select`, including with `searchable`.
+- You need to enter several tags — `TagInput`.
+
+## Minimal example
+
+```tsx
+<Combobox
+  aria-label="City"
+  items={[{ id: "msk", label: "Moscow" }]}
+  inputValue={city}
+  onInputChange={setCity}
+  allowsCustomValue
+/>
+```
+
+## Public API
+
+- `items` is an array of `{ id, label, meta? }`; `meta` is shown in the right column.
+- The other supported props come from React Aria ComboBox: use controlled `inputValue`/`onInputChange`, and `selectedKey`/`onSelectionChange` only when the scenario needs it.
+- `menuTrigger` is `focus` by default, so the list of options is visible on entering the field; `notFoundText` configures the empty list.
+- `placeholder` belongs to the field, `className` to the root.
+
+## Accessibility and keyboard
+
+- **The hint and error of `FormField` are announced together with the field.** The
+  description arrives through context, and `aria-describedby` is set on the input;
+  an `aria-describedby` passed by the consumer is not overridden but extended with
+  the form description. Before kit version 3.0.0 the react-aria components did
+  not pick up the form description — it was on the screen
+  but did not reach the screen reader
+  (ADR-0031).
+- React Aria provides the combobox behavior, filtering and `aria-activedescendant`.
+- **Inside `Dialog` and `Drawer` an option can be selected with the mouse.** The list
+  lives in a react-aria portal under `<body>`, where the Radix modal layer disables
+  pointer events; the kit gives it back to the overlay with a rule in
+  `@olddevs/ui/styles.css`. Before this fix an option could be selected only from
+  the keyboard.
+- Provide an accessible name through `aria-label` or an associated label.
+- See `src/components/inputs/Combobox.tsx`, `src/components/inputs/Combobox.stories.tsx`, `tests/combobox.test.tsx`.

package/docs/components/inputs/combobox.md

@@ -0,0 +1,58 @@
+---
+component: Combobox
+exports: [Combobox]
+category: inputs
+status: stable
+source: src/components/inputs/Combobox.tsx
+story: src/components/inputs/Combobox.stories.tsx
+---
+
+# Combobox
+
+## Кратко для AI
+
+`Combobox` сочетает свободный текстовый ввод со списком вариантов. Выбор из списка помогает, но значение может не совпадать с `items`; это принципиально отличает его от `Select`.
+
+## Когда использовать
+
+- Пользователь может ввести новый тег, адрес, название или другой допустимый текст.
+- Нужен список вариантов и фильтрация во время набора.
+
+## Когда не использовать
+
+- Нужен строго закрытый словарь — `Select`, в том числе с `searchable`.
+- Нужен ввод нескольких тегов — `TagInput`.
+
+## Минимальный пример
+
+```tsx
+<Combobox
+  aria-label="Город"
+  items={[{ id: "msk", label: "Москва" }]}
+  inputValue={city}
+  onInputChange={setCity}
+  allowsCustomValue
+/>
+```
+
+## Public API
+
+- `items` — массив `{ id, label, meta? }`; `meta` выводится правой колонкой.
+- Остальные поддерживаемые пропы наследуются от React Aria ComboBox: используйте controlled `inputValue`/`onInputChange`, `selectedKey`/`onSelectionChange`, только когда это нужно сценарию.
+- `menuTrigger` по умолчанию `focus`, чтобы список вариантов был виден при входе в поле; `notFoundText` настраивает пустой список.
+- `placeholder` относится к полю, `className` — к корню.
+
+## Доступность и клавиатура
+
+- **Пояснение и ошибка `FormField` объявляются вместе с полем.** Описание
+  приходит контекстом, `aria-describedby` ставится на поле ввода; переданный
+  потребителем `aria-describedby` не заменяется, а дополняется описанием формы.
+  До версии кита 3.0.0 компоненты на react-aria описание формы не забирали — на экране оно было, скринридеру не доставалось
+  (ADR-0031).
+- Поведение combobox, фильтрацию и `aria-activedescendant` берёт на себя React Aria.
+- **Внутри `Dialog` и `Drawer` вариант выбирается мышью.** Список живёт в
+  портале react-aria под `<body>`, у которого модальный слой Radix отключает
+  указатель; кит возвращает его оверлею правилом в `@olddevs/ui/styles.css`.
+  До этой починки вариант выбирался только с клавиатуры.
+- Передайте доступное имя через `aria-label` либо связанный label.
+- См. `src/components/inputs/Combobox.tsx`, `src/components/inputs/Combobox.stories.tsx`, `tests/combobox.test.tsx`.

package/docs/components/inputs/file-dropzone.en.md

@@ -0,0 +1,51 @@
+---
+component: FileDropzone
+exports: [FileDropzone]
+category: inputs
+status: stable
+source: src/components/inputs/FileDropzone.tsx
+story: src/components/inputs/FileDropzone.stories.tsx
+sourceHash: 689567ce58ae
+---
+
+# FileDropzone
+
+## Summary for AI
+
+`FileDropzone` accepts files through drag-and-drop or a file selection button. It checks the type and size, rejects more than one file when `multiple={false}`, shows the reasons for rejection and returns the accepted `File[]` to the consumer.
+
+## When to use
+
+- You need an accessible upload area with mouse and keyboard support.
+- You need the client-side limits `accept`, `maxSize`, `multiple` and an explanation of rejections.
+
+## When not to use
+
+- Do not show the upload state of already chosen files in the area — that is `UploadQueue`. The area supplies files; the queue shows what happened to them.
+- Do not treat `FileDropzone` as an upload implementation: networking, progress, retries and server-side validation stay with the consumer.
+- For a single plain file input without a drop zone, a native `<input type="file">` is enough.
+
+## Minimal example
+
+```tsx
+<FileDropzone
+  accept="image/*"
+  maxSize={10 * 1024 * 1024}
+  onFiles={enqueueFiles}
+  onReject={showRejected}
+  hint="PNG or JPEG up to 10 MB"
+/>
+```
+
+## Public API
+
+- `onFiles` is required and receives only the accepted files; `onReject` receives `{ name, reason }[]`.
+- `accept` uses the syntax of the `accept` attribute of a file input (`image/*`, `.jpg,.png`), `multiple` is true by default, `maxSize` is in bytes.
+- `label` sets the accessible name of the DropZone; `hint` sets the text under the label, `disabled` disables the area, `className` changes the look of the root element.
+- Folders, a wrong type, a file that is too large and extra files with `multiple={false}` each get a rejection reason.
+
+## Accessibility and forms
+
+- Do not remove the "Choose files" button: it lets keyboard users choose files.
+- A rejection is shown in a live region `role="alert"`; do not discard files silently.
+- See `src/components/inputs/FileDropzone.tsx`, `src/components/inputs/FileDropzone.stories.tsx`, `tests/file-dropzone.test.tsx`.

package/docs/components/inputs/file-dropzone.md

@@ -0,0 +1,50 @@
+---
+component: FileDropzone
+exports: [FileDropzone]
+category: inputs
+status: stable
+source: src/components/inputs/FileDropzone.tsx
+story: src/components/inputs/FileDropzone.stories.tsx
+---
+
+# FileDropzone
+
+## Кратко для AI
+
+`FileDropzone` принимает файлы через drag-and-drop или кнопку выбора. Он проверяет тип и размер, не принимает больше одного файла при `multiple={false}`, показывает причины отказа и возвращает принятые `File[]` потребителю.
+
+## Когда использовать
+
+- Нужна доступная область загрузки с поддержкой мыши и клавиатуры.
+- Нужны клиентские ограничения `accept`, `maxSize`, `multiple` и объяснение отказов.
+
+## Когда не использовать
+
+- Не показывайте в области состояние загрузки уже выбранных файлов — это `UploadQueue`. Область даёт файлы, очередь показывает, что с ними стало.
+- Не считайте `FileDropzone` реализацией загрузки: сеть, прогресс, повторные попытки и серверная проверка остаются у потребителя.
+- Для единственного простого file input без зоны перетаскивания достаточно нативного `<input type="file">`.
+
+## Минимальный пример
+
+```tsx
+<FileDropzone
+  accept="image/*"
+  maxSize={10 * 1024 * 1024}
+  onFiles={enqueueFiles}
+  onReject={showRejected}
+  hint="PNG или JPEG до 10 МБ"
+/>
+```
+
+## Public API
+
+- `onFiles` обязателен и получает только принятые файлы; `onReject` получает `{ name, reason }[]`.
+- `accept` использует синтаксис input accept (`image/*`, `.jpg,.png`), `multiple` по умолчанию true, `maxSize` — байты.
+- `label` формирует доступное имя DropZone; `hint` задаёт пояснение под подписью, `disabled` выключает область, `className` меняет вид корневого элемента.
+- Папки, неподходящий тип, слишком большой файл и лишние файлы при `multiple={false}` получают причину отказа.
+
+## Доступность и форма
+
+- Не убирайте кнопку «Выбрать файлы»: по ней выбирают файлы с клавиатуры.
+- Отказ выводится в живой области `role="alert"`; не отбрасывайте файлы молча.
+- См. `src/components/inputs/FileDropzone.tsx`, `src/components/inputs/FileDropzone.stories.tsx`, `tests/file-dropzone.test.tsx`.

package/docs/components/inputs/form-layout.en.md

@@ -0,0 +1,99 @@
+---
+component: FormLayout
+exports: [FormLayout, FieldRow]
+category: inputs
+status: stable
+source: src/components/inputs/FormLayout.tsx
+story: src/components/inputs/FormLayout.stories.tsx
+sourceHash: 65fb57b5d989
+---
+
+# FormLayout and FieldRow
+
+## Summary for AI
+
+Form layout: `columns` (1 or 2) and `labels` (`top` or `side`), plus
+`FieldRow` for a full-width field. Only the position of nodes — no validation,
+no field composition, no state. Side labels are supported only by `FormField`:
+it renders the label.
+
+## When to use
+
+- A form with several fields: settings, editing an entity, registration.
+- You need labels in a left column or two columns of fields.
+
+## When not to use
+
+- For submitting and locking during a request — that is `Form`; the two are used together.
+- For a group of fields with a shared heading — the native `<fieldset>` and `<legend>`.
+  The kit has no separate `Fieldset` on purpose: a wrapper around them would add
+  nothing but a name in the exports.
+
+## Minimal example
+
+```tsx
+import { FieldRow, FormField, FormLayout, TextControl } from "@olddevs/ui";
+
+<FormLayout columns={2} labels="side" labelWidth="8rem">
+  <FormField label="First name" htmlFor="name">
+    <TextControl id="name" shellClassName="w-full" />
+  </FormField>
+  <FormField label="Last name" htmlFor="surname">
+    <TextControl id="surname" shellClassName="w-full" />
+  </FormField>
+  <FieldRow>
+    <FormField label="Address" htmlFor="address">
+      <TextControl id="address" shellClassName="w-full" />
+    </FormField>
+  </FieldRow>
+</FormLayout>;
+```
+
+## Props
+
+| Prop         | Default | Purpose                                                       |
+| ------------ | ------- | ------------------------------------------------------------- |
+| `columns`    | `1`     | Number of columns. On narrow screens there is always one.     |
+| `labels`     | `"top"` | Where field labels go: above the field or in the left column. |
+| `labelWidth` | `12rem` | Width of the label column — any CSS length.                   |
+
+`FieldRow` has no props: it is a `div` with `col-span-full`.
+
+## A CSS grid, not a JS calculation
+
+A single column on narrow screens is switched on by a media query (`sm:grid-cols-2`),
+not by `matchMedia`. A layout that depends on JS is wrong before
+hydration, and the first frame of the form is exactly that moment.
+
+`FieldRow` takes **all** the columns (`col-span-full`), not a fixed two:
+`col-span-2` in a one-column layout would create an implicit second column, and
+the form would fall out of alignment where nothing was changed.
+
+## `labels="side"` applies to `FormField`, not to arbitrary children
+
+This follows from the field rendering its own label: the layout cannot move it
+into the left column, and only passes the axis through context
+(ADR-0025).
+
+The layout sets the position for **any** child — a bare `<input>`, a field from
+another library, a whole block. But it knows nothing about their labels, and
+`labels="side"` silently changes nothing for them. An explicit `layout` on the
+field wins over the layout.
+
+The column width lives in the `--form-label-w` variable; `labelWidth` is the dedicated
+prop for setting it, and it wins over the same variable passed through `style`.
+
+## What the component does not do
+
+No validation, no field composition, no state — `Form` deliberately gave up its own
+validation, and the layout does not revisit that. A boundary violation can be
+recognized by a test: a prop that affects not the position of nodes but their composition.
+
+## Related sources and tests
+
+- Implementation: `src/components/inputs/FormLayout.tsx`, the label axis is in
+  `src/components/inputs/FormField.tsx`.
+- Tests: `tests/form-layout.test.tsx` — both axes, priority of the field prop,
+  `FieldRow` in both layouts, children from outside the kit; `tests/form-field.test.tsx` —
+  identical field markup without the axis.
+- Showcase stories: `src/components/inputs/FormLayout.stories.tsx`.