altum 0.0.1

package/dist/utils/mergeStyles.js

@@ -0,0 +1 @@
+function n(t,i){if(!(!t&&!i))return t?i?{...t,...i}:t:i??void 0}export{n as mergeStyles};

package/dist/utils/overlayDismiss.js

@@ -0,0 +1 @@
+let e=!1;function i(){e=!0}function o(){requestAnimationFrame(()=>{requestAnimationFrame(()=>{e=!1})})}let n=!1;function r(){n||typeof window>"u"||(n=!0,window.addEventListener("blur",i),window.addEventListener("focus",o))}r();function u(){return r(),typeof document<"u"&&!document.hasFocus()?!0:e?(e=!1,!0):!1}function s(t){if(t)return()=>{u()||t()}}export{u as shouldIgnoreOverlayDismiss,s as wrapOverlayDismiss};

package/dist/utils/overlayEscapeStack.js

@@ -0,0 +1 @@
+let o=1;const c=[];function s(e){const n=o++;return c.push({id:n,onEscape:e}),n}function p(e,n){const t=c.find(a=>a.id===e);t&&(t.onEscape=n)}function i(e){const n=c.findIndex(t=>t.id===e);n>=0&&c.splice(n,1)}function l(e){const n=c[c.length-1];return n!=null&&n.id===e}export{l as isTopOverlayEscapeHandler,i as popOverlayEscapeHandler,s as pushOverlayEscapeHandler,p as updateOverlayEscapeHandler};

package/dist/utils/overlayPurpose.js

@@ -0,0 +1 @@
+const a={tooltip:"--altum-overlay-offset-tooltip",popover:"--altum-overlay-offset-popover",dropdown:"--altum-overlay-offset-dropdown",modal:"--altum-overlay-offset-modal",sheet:"--altum-overlay-offset-sheet",lightbox:"--altum-overlay-offset-lightbox",notification:"--altum-overlay-offset-notification"},e={tooltip:8,popover:8,dropdown:4,modal:0,sheet:0,lightbox:0,notification:0},r={tooltip:"var(--altum-g-z-tooltip)",popover:"var(--altum-g-z-dropdown)",dropdown:"var(--altum-g-z-dropdown)",modal:"var(--altum-g-z-modal)",sheet:"var(--altum-g-z-overlay)",lightbox:"var(--altum-g-z-lightbox)",notification:"var(--altum-g-z-notification)"};function i(o){if(typeof document>"u")return e[o];const l=getComputedStyle(document.documentElement).getPropertyValue(a[o]).trim(),t=parseFloat(l);return Number.isFinite(t)?t:e[o]}function n(o){return r[o]}export{i as resolveOverlayPurposeSideOffset,n as resolveOverlayPurposeZIndex};

package/dist/utils/overlayStack.js

@@ -0,0 +1 @@
+import{createContext as e,useContext as o}from"react";const r=e(void 0);function a(){return o(r)}const c=r.Provider;function u(t){return typeof t=="number"?String(t):t}function i(t,n="var(--altum-g-z-dropdown)"){if(!(t==null||t===""))return`max(${n}, calc(${u(t)} + 1))`}export{c as OverlayStackProvider,i as elevateAboveOverlayStack,a as useOverlayStackZIndex};

package/dist/utils/overlayZIndex.js

@@ -0,0 +1 @@
+const i={overlay:"var(--altum-g-z-overlay)",modal:"var(--altum-g-z-modal)",dropdown:"var(--altum-g-z-dropdown)",lightbox:"var(--altum-g-z-lightbox)",notification:"var(--altum-g-z-notification)"};function a(n,t){if(t!=null&&t!=="")return t;if(n!=null)return i[n]}const e="var(--altum-g-z-overlay)";function v(n,t,o){const l=a(n,t);if(o==null||o==="")return l;const u=typeof o=="number"?String(o):o,r=l??e;return`max(${typeof r=="number"?String(r):r}, calc(${u} + 1))`}export{e as OVERLAY_Z_INDEX_DEFAULT,a as resolveOverlayZIndex,v as resolveStackedOverlayZIndex};

package/dist/utils/portal.js

@@ -0,0 +1 @@
+import{createPortal as o}from"react-dom";function e(r,{container:t}={}){return typeof document>"u"?null:o(r,t??document.body)}export{e as createLibraryPortal};

package/dist/utils/renderChildren.js

@@ -0,0 +1 @@
+import{isValidElement as i,cloneElement as c}from"react";import{composeRefs as f}from"./composeRefs.js";import{cn as d}from"./cn.js";function p({asChild:s,children:e,props:t,contentRef:r}){const l=u=>{typeof r=="function"?r(u):r!=null&&(r.current=u)};if(s){if(!i(e))throw new Error("renderChildren: asChild \u0442\u0440\u0435\u0431\u0443\u0435\u0442 \u0435\u0434\u0438\u043D\u0441\u0442\u0432\u0435\u043D\u043D\u044B\u0439 \u0434\u043E\u0447\u0435\u0440\u043D\u0438\u0439 React-\u044D\u043B\u0435\u043C\u0435\u043D\u0442");const u=e,n=u.props,o=t;return c(u,{...o,className:d(o.className,n.className),style:{...n.style,...o.style},ref:f(l,n.ref)})}if(typeof e!="function")throw new Error("renderChildren: \u0435\u0441\u043B\u0438 asChild \u0440\u0430\u0432\u0435\u043D false, children \u0434\u043E\u043B\u0436\u0435\u043D \u0431\u044B\u0442\u044C \u0444\u0443\u043D\u043A\u0446\u0438\u0435\u0439 (props, contentRef) => ReactNode");return e(t,l)}export{p as renderChildren};

package/dist/utils/slot.js

@@ -0,0 +1 @@
+import{forwardRef as c,isValidElement as f,cloneElement as p}from"react";import{composeRefs as d}from"./composeRefs.js";import{cn as y}from"./cn.js";import{mergeStyles as D}from"./mergeStyles.js";function t(u,o,r){const e=o.props,l=typeof u.className=="string"?u.className:void 0,m=typeof e.className=="string"?e.className:void 0,a=u.style,n=e.style,i=e.ref;return{...e,...u,className:y(l,m),style:D(n,a),ref:d(r,i)}}const s=c(function({children:u,...o},r){if(!f(u))throw new Error("Slot: asChild \u0442\u0440\u0435\u0431\u0443\u0435\u0442 \u0435\u0434\u0438\u043D\u0441\u0442\u0432\u0435\u043D\u043D\u044B\u0439 \u0434\u043E\u0447\u0435\u0440\u043D\u0438\u0439 React-\u044D\u043B\u0435\u043C\u0435\u043D\u0442");return p(u,t(o,u,r))});s.displayName="Slot";export{s as Slot,t as mergeSlotProps};

package/dist/utils/spacing.js

@@ -0,0 +1 @@
+const e={none:"0",xs:"var(--altum-g-space-1)",sm:"var(--altum-g-space-2)",md:"var(--altum-g-space-3)",lg:"var(--altum-g-space-4)",xl:"var(--altum-g-space-6)"};function s(a){return typeof a=="number"?`${a}px`:a in e?e[a]:a}export{e as SPACING_TOKEN_CSS,s as resolveSpacingCss};

package/dist/utils/transform.js

@@ -0,0 +1 @@
+function n(r){if(!r||r==="none")return 0;const t=r.match(/translateX\(([-\d.]+)px\)/);if(t)return Number.parseFloat(t[1]??"0");try{const e=typeof DOMMatrix<"u"?DOMMatrix:WebKitCSSMatrix;return new e(r).m41}catch{return 0}}export{n as getTranslateXFromTransform};

package/docs/COMPONENTS.md

@@ -0,0 +1,207 @@
+# Компоненты altum-ui
+
+Краткий справочник публичного API. Установка и точки входа — [README](../README.md). Токены — [THEMING.md](./THEMING.md). Раскладка — [LAYOUT.md](./LAYOUT.md). Иконки — [ICONS.md](./ICONS.md).
+
+**Button / Link `asChild`:** единственный потомок получает стили и обработчики через Slot.
+
+Оверлеи: кнопки — в `Modal.Footer` / `Modal.FormFooter` / `Sheet.Footer`, sibling к `Body`, не внутри скролла.
+
+---
+
+## Действия
+
+| Компонент | Описание |
+|-----------|----------|
+| **ButtonBase** | Примитив кнопки: `variant` (`primary` / `tinted` / `secondary` / `ghost` / `link`) × `status` (`default` / `danger`), `size`, опциональный `active`. |
+| **Button** | Кнопка на **ButtonBase**: иконки, `loading`, `fullWidth`, `shortcut`. |
+| **ButtonIcon** | Иконка-кнопка на **ButtonBase**; `circle` / `square`; по умолчанию `variant="ghost"`. |
+| **ButtonGroup** | Составная группа (`ButtonGroup` + `ButtonGroup.Item`): высота = `--altum-control-height-*`; `width` `auto` \| `full` (full — колонка формы); `variant` / `status` / `size` / `borderless` на Root; переключение через `active` на Item; циклический клавиатурный фокус. |
+| **SegmentedControl** | Переключатель сегментов (на **SelectionGroup**): `itemFit` `equal` \| `content`; варианты `primary` / `tinted` / `secondary` / `ghost` / `plain`. |
+| **SelectionGroup** | Составной (`Root` / `List` / `Item` / `Panel`): взаимоисключающий выбор + циклический клавиатурный фокус; `value` / `onChange`. База для SegmentedControl и Tabs. |
+| **OverflowActions** | Составной: видимые действия + лишние в `Dropdown` (⋯). `visibleCount`, `display` (`icon` \| `icon-label`), `showOverflowTrigger`, `Item`. |
+| **ActionList** | Клавиатурный список действий на **Listbox** + **SearchField**: группы, сочетание клавиш, `onAction`. |
+| **OverflowGroup** | Лишние потомки по ширине уходят за ⋯ в `Dropdown`. `fit` `content` \| `container`, `gap`, `size`, `maxVisible`. |
+| **ActionSheetTrigger** | Долгое нажатие → OverflowActions; `showOverflowTrigger` (по умолчанию `false`) — на touch+mobile ⋯ скрыт; пульс при срабатывании. |
+
+---
+
+## Формы
+
+| Компонент | Описание |
+|-----------|----------|
+| **FieldBase** | Составная оболочка полей: `Root` / `Label` / `Prefix` / `Control` / `Postfix` / `Button` / `Icon` / `Clear` / `Helper` / `Error`. `Clear` рендерится внутри `Postfix`. |
+| **TextField** | Однострочное поле на **FieldBase**. |
+| **PasswordField** | Пароль на базе TextField: показать/скрыть, опциональный индикатор сложности. |
+| **SearchField** | Обёртка над `TextField` с `labelPlacement="none"` по умолчанию и иконкой поиска (`onClear` от TextField). |
+| **TextareaField** | Многострочное поле на **FieldBase**; авто-рост высоты. |
+| **NumberField** | Числовой ввод на базе `TextField` с кнопками +/-. |
+| **MaskedField** | Поле с маской ввода (телефон, дата и т.п.) на базе `TextField`; опционально `maskAsPlaceholder`. Не переопределяйте `padding` / `font-size` на inner `input`. |
+| **PinInput** | PIN / OTP (2FA, код из SMS). |
+| **Rating** | Оценка звёздами. |
+| **FormMessage** / **FieldError** | Подсказка / ошибка / успех под полем; `variant`; `FieldError` = `variant="error"`. |
+| **Listbox** | Список опций с клавиатурой и группами; база для Select / CustomSelect / SuggestField / ActionList. |
+| **CustomSelect** | Составной примитив select/combobox (`Root` / `Filter` / `List` / `Shell`): Dropdown + Listbox; `groups` + `groupId`; `selectionMode`: `single` \| `multiple` \| `path`; `value` / `onChange`. |
+| **Select** | Составной select на CustomSelect: `Root` / `Trigger` / `Panel` / `Filter` / `List`; `value` / `onChange`; множественный выбор — `Chips` / `Chip`. |
+| **SuggestField** | Автодополнение на TextField; chrome от **`FieldBaseProps`** (`label`, `onClear`, `prefix`, …). |
+| **Checkbox** | `size`, `labelSide`, `indeterminate`, `mode` (`default` \| `task`), `align` (`start` \| `center`; для task по умолчанию `start`), `labelVisibility` (`visible` \| `hidden` + обязательный `aria-label` / `aria-labelledby`). |
+| **Switch** | `size`, `labelSide`. |
+| **CheckboxGroup** | Группа чекбоксов с управляемым `value: string[]`. |
+| **Radio** / **RadioGroup** | Радиокнопка и группа взаимоисключающих опций. |
+| **Slider** | Ползунок: `value: number` или диапазон `value: [from, to]` (два thumb). |
+| **DatePicker** | Выбор даты: MaskedField + календарь; по умолчанию prefix — `FieldBase.Icon` + календарь; chrome от **`FieldBaseProps`**. |
+| **DateRangePicker** | Диапазон дат (`value`/`onChange` как `{ start?, end? }` / `DateRangeValue`); `layout` `single` / `split`. |
+| **TimePicker** / **TimePickerField** | Панель времени + поле с маской `HH:MM`; по умолчанию prefix — `FieldBase.Icon` + часы. |
+| **Calendar** | Составной: `Provider` / `Root` / `Header` / `Title` / `Nav` / `Body`. `selectionMode` `single` \| `range` на Provider. Контекст: `view` / `setView` (`CalendarViewMode`). |
+| **DayStripCalendar** | Горизонтальная полоса дней (недельный chrome): `daysCount`, предыдущий/следующий, `value` / `onChange`, `renderDay`. |
+| **ColorSwatchGroup** | Выбор цвета из набора цветных точек. |
+| **UploadZone** | Зона перетаскивания файлов для загрузки. |
+| **Fieldset** | Составной: `Inner` / `Legend` / `Description` / `Hint` / `Content` / `Footer`; варианты `default` / `card` / `plain`. |
+| **FieldLabel** | Лейбл + контент: `layout` vertical / horizontal; `align` start / center / baseline; `justify` start / between. |
+
+---
+
+## Оверлеи
+
+| Компонент | Описание |
+|-----------|----------|
+| **Overlay** | Примитив позиционирования без chrome: `variant` `modal` / `floating` / `sheet` / `popover` / `dropdown`. Видимость: `open` / `onOpenChange` / `onClose`. Портал + появление/скрытие; z-index / offset — `purpose` (см. [THEMING.md](./THEMING.md)). |
+| **Backdrop** | Затемнение под оверлеем: `variant` `default` / `strong`, `blur`, клик закрывает слой. |
+| **Modal** | Составной на **`Overlay`** (`variant="modal"`): `Header` / `Title` / `Close` / `Body` / `Footer` / **`FormFooter`**. |
+| **ConfirmDialog** | Готовый диалог на **`Modal`**: отмена + подтверждение, `confirmLabel`, `secondaryAction`, `status="danger"`, `onClose`. |
+| **Sheet** | Панель на **`Overlay`** (`variant="sheet"`): `Header` / `Title` / `Close` / `Body` / `Footer`; `mode` / `direction` / `backdrop` / `showHandle`. |
+| **ImageLightbox** | Полноэкранный просмотр на **`Overlay`** (`variant="modal"`, `purpose="lightbox"`, сильный Backdrop); внутри `ImageGallery`. |
+| **Dropdown** | Выпадающая панель на **`Overlay`** (`variant="dropdown"`). Составной: `Dropdown` + `Dropdown.Trigger` + `Dropdown.Content`. Trigger без лишней DOM-обёртки (`asChild` / render-prop). На мобильных — нижний Sheet. |
+| **DropdownMenu** | Готовое меню по клику: Dropdown (`menu`) + ActionList. |
+| **ContextMenu** | Контекстное меню по правому клику (ActionList у курсора). |
+| **Tooltip** | Подсказка на **`Overlay`** (`variant="popover"`, `triggerMode="hover"`); триггер через `renderChildren` (`asChild` / render-prop); `openDelay` / `closeDelay`, wrap, arrow. Мьютекс наведения: не больше одной подсказки одновременно при быстром переходе между триггерами. |
+| **Popover** | Плавающий слой на **`Overlay`** (`variant="popover"`). Составной: `Trigger` (`asChild` / render-prop) + `Content` (`panel`/`tooltip`/`plain`, `arrow`); `trigger` click/hover/manual. |
+| **CommandPalette** | Палитра Cmd+K: явный `ActionList` в `List` (без автосбора команд). |
+
+---
+
+## Навигация
+
+| Компонент | Описание |
+|-----------|----------|
+| **Pagination** | Составной: `Summary` («N–M из K»), `Controls`, `PageSize`; многоточие при многих страницах. |
+| **Sidebar** | Составной: `Root`, `Header`, `Title`, `Collapse`, `Content`, `Group`, `GroupLabel`, `Item`, `Footer`, `MobileTrigger`; `value` / `onChange`; десктопный rail + мобильный Sheet. |
+| **Steps** | Мастер: горизонтальный/вертикальный, статус шага, `onStepClick`. |
+| **Tabs** | Составные вкладки: `Tabs.List` / `Tabs.Trigger` / `Tabs.Panel`; `value` / `defaultValue` / `onChange`; `line` / `pill`, горизонтальные/вертикальные и бейдж на Trigger. |
+
+---
+
+## Отображение данных
+
+| Компонент | Описание |
+|-----------|----------|
+| **Table** | Составной: `Root` / `Toolbar` / `Content` / `Loading` / `Empty` / `Footer` / `RowActions`. `Content` содержит сортировку (клиент/сервер), выбор строк, раскрытие, липкие колонки, `density`, resize и действия строки; loading, empty и пагинация собираются sibling-слотами. |
+| **Timeline** | Вертикальный/горизонтальный, сворачиваемые подробности, `currentId`. |
+| **Card** | `variant` outlined/elevated/ghost; составной `Header` / `Media` / `Body` / `Actions`; `loading`. |
+| **Accordion** | Составной: `Item` / `Trigger` / `Content`; `bordered` (зазор + Box) / `flush` (разделители); `multiple`, отключённый пункт. |
+| **Badge** | `size` sm/md, `position` overlay/standalone, `variant` включая `error`; overlay — `--altum-badge-overhang`. Числовой `label` / `BadgeCounter` ограничивается через `max`; `children` — якорь overlay. |
+| **Avatar** / **AvatarGroup** | Размеры `xs`…`xl`, кольцо статуса, запасная иконка; группа с наложением. |
+| **Chip** | Тег / фильтр: `mode` `chip` \| `tag`, `size`, `active`, `onRemove` / `onClick`. **`ChipGroup`**: `layout` `wrap` \| `scrollX`. |
+| **StatBadge** | Компактный блок статистики: число + подпись; `variant` `default` / `success` / `warning` / `error`; `size` `md` / `sm`. |
+| **EmptyState** | Пустое состояние: иконка (`--altum-color-empty-icon`), заголовок, описание, действие; `size` для вложенных панелей. |
+| **DescriptionList** | Список «ключ — значение» (`stacked` / `inline`, колонки). |
+| **RelativeTime** | Относительное время («2 ч назад»). |
+| **SortableList** | Перетаскивание любой модели `{id}`: `renderItem`, `variant` (`default` / `plain` для Item / SwipeToAction), `handleOnly`, перестановка с клавиатуры. |
+| **CalendarBoard** | Составной: `Provider` / `Root` / `Header` / `Title` / `Nav` / `ViewSwitch` / `Body` / `Month` / `Week` / `Day` / `Year` / `TaskChip`. |
+| **VirtualList** | Виртуализированный список: `items`, `height`, `estimateSize`, `scrollToIndex`, `onRangeChange`. |
+
+---
+
+## Типографика
+
+| Компонент | Описание |
+|-----------|----------|
+| **Title** | Заголовки уровней `h1`–`h4`; цвет `--altum-color-type` (адаптация в `Box`). |
+| **Text** | Текстовый примитив (`--altum-type-*`). Дефолт `as="span"` (inline); для блочного copy — `as="p"` / `as="div"`, иначе соседние `Text` склеятся в одну строку. |
+| **Link** | Ссылка: `variant` `primary`\|`secondary`\|`muted`, `status` `danger`, `size` `xs`–`xl` (или inherit), `--altum-color-link-*`. |
+| **Kbd** / **KbdGroup** | Отображение клавиш и сочетаний клавиатуры. |
+
+---
+
+## Раскладка
+
+| Компонент | Описание |
+|-----------|----------|
+| **Layout** | Панель: скролл на корне; `Header` / `Footer` sticky; алиасы `Stack` / `Inline` / `Split` / `ControlRow` / `Item` / `Grid`. |
+| **Stack** / **Inline** / **Split** / **ControlRow** / **LayoutItem** | Flex-примитивы (вертикаль / чипы / края / ряд контролов / `grow`). |
+| **Grid** / **GridItem** | CSS Grid; `GRID_BREAKPOINTS`. |
+| **Container** / **Page** | Колонка с max-width (`sm`…`xl` / `full`) и оболочка страницы. |
+| **Box** | Поверхность (`outlined` / `elevated` / `floating` / `tinted` / `secondary` / `muted` / `glass` / `overlay` / `ghost` / `plain`). |
+| **Collapse** | Плавное сворачивание по высоте. |
+| **Separator** (`Spacer`) | Разделитель: `orientation` horizontal \| vertical, текст (`children`), отступы `start` / `end`. |
+| **Item** | Составная строка: `Media` / `Content` / `Title` / `Description` / `Actions`; поверхность — `Box`. |
+| **AspectRatio** | Обёртка с `aspect-ratio` (16:9 / 1:1). |
+| **Media** | img/video-превью на базе **AspectRatio**. |
+| **ScrollArea** | Стилизованный скролл (`orientation` y/x/both). |
+
+---
+
+## Медиа
+
+| Компонент | Описание |
+|-----------|----------|
+| **ImageGallery** | Составная галерея: `Root` + `Viewport` / `Image` / `Prev` / `Next` / `Thumbnails` / `Thumb` / `Counter` / `Empty`. |
+| **ImageCrop** | Обрезка изображения. |
+| **FileList** | Список загрузок на **`Attachment`**: progress / retry / remove через `FileList.Item`. |
+| **Attachment** | Карточка файла/изображения (compound `Media` / `Content` / `Title` / `Description` / `Actions`). |
+
+---
+
+## Графики
+
+| Компонент | Описание |
+|-----------|----------|
+| **LineChart** | SVG-линейный график без внешних chart-библиотек. |
+| **BarChart** | Столбчатый SVG-график; `showHoverValue`. |
+| **DonutChart** | Кольцевая диаграмма + легенда; `hoverExpand`. |
+
+---
+
+## Переписка / AI-лента
+
+| Компонент | Описание |
+|-----------|----------|
+| **Bubble** | Пузырь сообщения: `variant` default/outgoing/incoming/system, `align`, `group`, `reactions`, `collapsible`. |
+| **Marker** | Системная заметка / status / bordered row / labeled separator (`Marker.Icon` + `Marker.Content`). |
+
+---
+
+## Mobile
+
+| Компонент | Описание |
+|-----------|----------|
+| **SafeArea** | Отступы под notch / home-indicator (`env(safe-area-inset-*)`). |
+| **PullToRefresh** | Жест «потянуть, чтобы обновить» для контейнера с прокруткой. |
+| **GrabHandle** | Ручка захвата в стиле iOS. |
+| **SwipeToAction** | Сенсорная обёртка: свайп раскрывает действия (iOS). |
+
+---
+
+## Обратная связь
+
+| Компонент | Описание |
+|-----------|----------|
+| **Spinner** | Индикатор загрузки: `spin` \| `dots` \| `pulse` \| `typing`; размеры `sm` \| `md` \| `lg`. |
+| **Skeleton** | Плейсхолдер + пресеты `.Text` / `.Avatar` / `.Card` / `.Table`. |
+| **Progress** / **ProgressCircle** | `size`, `variant` (auto → success при 100%), `showValueText`, indeterminate, labels; у круга `diameter` перекрывает токен размера. |
+| **Alert** | Составной: `Icon`, `Body` (`Title`, `Content`, `Actions`), `Close`; `variant`, `size`, `layout` block/inline. |
+| **Notification** | Составной тост: `Provider`, `Viewport`, `Root`, `Title`, `Description`, `Actions`, `Close`. `variant` `info` / `success` / `warning` / `error`. Императивно: `NotificationProvider` + `notify()`. |
+
+---
+
+## Инфраструктура
+
+| Экспорт | Описание |
+|---------|----------|
+| **ThemeProvider** | Светлая/тёмная тема. `applyTo` и контролируемая тема — [THEMING.md](./THEMING.md). |
+| **LocaleProvider** | Локаль и переводы встроенных строк (`locale="ru" \| "en"`, опциональный `messages`). |
+| **useLocale** / **useT** | Хук `{ locale, messages, t }` / только `t`. |
+| **ru** / **en** | Встроенные словари. |
+| **useTheme** | Хук `{ theme, setTheme, toggleTheme }` внутри `ThemeProvider`. |
+| **FocusTrap** | Ловушка фокуса для доступности в модальных окнах. |
+| **VisuallyHidden** | Контент только для скринридеров (скрыт визуально). |
+| **SkipLink** | «Перейти к содержимому» (виден при фокусе). |

package/docs/ICONS.md

@@ -0,0 +1,22 @@
+# Иконки в altum-ui
+
+Компоненты принимают иконку как `ReactNode` — свой SVG или элемент из набора библиотеки.
+
+```tsx
+import {ButtonIcon} from 'altum-ui';
+import {IconSearch} from 'altum-ui/icons';
+
+<ButtonIcon aria-label="Поиск" icon={<IconSearch />} />
+```
+
+Набор **не** входит в главный barrel — только `altum-ui/icons`. Просмотр: Storybook → **Icons**.
+
+### Контракт для кастомных SVG
+
+| Правило | Значение |
+|---------|----------|
+| Размер | `width` / `height` или проп `size` (16–24 px для кнопок) |
+| Цвет | `fill="currentColor"` |
+| Доступность | На `ButtonIcon` всегда `aria-label` |
+
+Продуктовые иконки лучше держать в приложении — так не раздувается бандл, если набор `altum-ui/icons` не нужен целиком.

package/docs/LAYOUT.md

@@ -0,0 +1,282 @@
+# Layout-компоненты altum-ui
+
+Гайд: **что выбрать** и **зачем**, для панели `Layout` и flex-примитивов (`Stack`, `Inline`, `Split`, `ControlRow`, `LayoutItem`).
+
+Стили — CSS Modules + токены `--altum-g-space-*` (8pt).
+
+```tsx
+import {
+  Layout,
+  Stack,
+  Inline,
+  Split,
+  ControlRow,
+  LayoutItem,
+  Box,
+  Grid,
+  Container,
+  Page,
+} from 'altum-ui';
+```
+
+Связанные: **FieldBase** — см. [COMPONENTS.md](./COMPONENTS.md).
+
+---
+
+## Быстрый выбор
+
+| Задача | Компонент |
+|--------|-----------|
+| Панель: шапка + скролл корня + футер (Modal / Sheet / страница) | **Layout** + Header / Content / Footer |
+| Блоки друг под другом (форма, секции) | **Stack** |
+| Чипы / теги / мелкие кнопки в ряд с переносом | **Inline** |
+| Слева заголовок, справа действия | **Split** |
+| Поля + Chip + Button в одной строке фильтров | **ControlRow** |
+| Одному ребёнку — `flex: 1` или «не сжимать» | **LayoutItem** (`ControlRow.Item` / `Layout.Item`) |
+| Колонки сетки | **Grid** / `Layout.Grid` |
+| Оболочка input (label / prefix / clear) | **FieldBase** |
+
+---
+
+## Общие токены
+
+| Тип | Значения | Назначение |
+|-----|----------|------------|
+| `LayoutGap` | `none` \| `xs` \| `sm` \| `md` \| `lg` \| `xl` | Промежуток → `--altum-g-space-*` |
+| `LayoutAlign` | `start` \| `center` \| `end` \| `baseline` \| `stretch` | Поперечная ось |
+| `LayoutJustify` | `start` \| `center` \| `end` \| `between` \| `around` \| `evenly` | Главная ось (у **Split** фиксирован `space-between`) |
+
+Не задавайте `gap` в px — только шкала токенов.
+
+---
+
+## Layout (панель)
+
+Корневая **колонка** для Modal, Sheet, Sidebar, страницы: **скролл на `Layout`**, шапка/футер опционально липкие.
+
+### Состав
+
+| Часть | Роль | Ключевые пропсы |
+|-------|------|-----------------|
+| `Layout` | Корень-scrollport (`overflow-y: auto`, flex-колонка) | `as` (по умолчанию `div`) |
+| `Layout.Header` | Шапка | `sticky`, `as="header"` |
+| `Layout.Content` | Середина (без собственного overflow) | `as` |
+| `Layout.Footer` | Низ с действиями | `sticky`, `align` (`start` \| `center` \| `end` \| `space-between`), `as="footer"` |
+
+`sticky` — элемент остаётся у края при скролле **`Layout`**. Без `sticky` Header/Footer уезжают вместе с контентом.
+
+### Когда использовать
+
+- диалог / sheet / sidebar с заголовком и кнопками внизу;
+- страница-оболочка с фиксированной шапкой и скроллом тела.
+
+### Когда не использовать
+
+- только вертикальный ритм полей → **Stack**;
+- toolbar «слева / справа» без панели → **Split**;
+- сетка колонок → **Grid**.
+
+### Пример (sticky chrome)
+
+```tsx
+<Layout>
+  <Layout.Header sticky>
+    <Split>
+      <h2>Настройки</h2>
+      <ButtonIcon aria-label="Закрыть" />
+    </Split>
+  </Layout.Header>
+  <Layout.Content>
+    <Stack gap="md">
+      {/* поля */}
+    </Stack>
+  </Layout.Content>
+  <Layout.Footer sticky>
+    <Split>
+      <Button variant="secondary">Отмена</Button>
+      <Button variant="primary">Сохранить</Button>
+    </Split>
+  </Layout.Footer>
+</Layout>
+```
+
+### Namespace
+
+На `Layout` также висят алиасы: `Layout.Stack`, `.Inline`, `.Split`, `.ControlRow`, `.Item`, `.Grid`, `.GridItem`.
+
+В приложении предпочтительны **именованные импорты**; `Layout.*` удобен, когда вы уже внутри панели.
+
+Также экспортируются: `LayoutRoot`, `LayoutHeader`, `LayoutContent`, `LayoutFooter`.
+
+---
+
+## Stack
+
+Вертикальный flex-стек с токенным `gap`. Всегда `width: 100%` родителя — ширину ограничивает родитель.
+
+| Проп | По умолчанию | Смысл |
+|------|--------------|--------|
+| `gap` | `md` | Вертикальный ритм |
+| `align` | `stretch` | Поперечная ось |
+| `justify` | `start` | Главная ось |
+| `as` | `div` | `div` \| `section` \| `ul` \| `ol` \| `nav` |
+
+**Использовать:** поля формы друг под другом; секции с одинаковым вертикальным шагом; колонка в `Layout.Content`.
+
+**Не использовать:** одна линия → Inline / ControlRow / Split; колонки → Grid.
+
+```tsx
+<Stack gap="md" align="stretch">
+  <TextField label="Имя" width="full" />
+  <TextField label="Эл. почта" width="full" />
+  <Button variant="primary">Сохранить</Button>
+</Stack>
+```
+
+---
+
+## Inline
+
+Горизонтальный **кластер с переносом** (чипы, теги, бейджи, мелкие кнопки). Всегда `width: 100%` родителя.
+
+| Проп | По умолчанию |
+|------|--------------|
+| `gap` | `sm` |
+| `align` | `center` |
+| `justify` | `start` |
+| `wrap` | `true` |
+
+**Использовать:** группы чипов/тегов; label + badge + icon; естественный wrap на узкой ширине.
+
+**Не использовать:** заголовок слева / действия справа → **Split**; ряд полей формы → **ControlRow**; вертикальный список → **Stack**.
+
+```tsx
+<Inline gap="sm">
+  <Chip>Дизайн</Chip>
+  <Chip>Разработка</Chip>
+  <Chip>QA</Chip>
+</Inline>
+```
+
+---
+
+## Split
+
+Горизонтальный ряд с **`justify-content: space-between`** (края контейнера). Всегда `width: 100%` родителя.
+
+| Проп | По умолчанию | Примечание |
+|------|--------------|------------|
+| `gap` | `md` | Между левой и правой группами при сжатии |
+| `align` | `center` | |
+| `justify` | — | Нет: всегда space-between |
+
+Обычно **два** ребёнка (левая и правая группы); внутри часто **Inline**.
+
+| **Использовать:** заголовок страницы (title + действия); строка списка (имя + меню); футер «Отмена \| Сохранить» по краям.
+
+**Не использовать:** группа кнопок без «разъезда» к краям → **Inline**; ряд полей → **ControlRow**.
+
+```tsx
+<Split>
+  <Inline gap="sm" align="center">
+    <Text as="h1">Проекты</Text>
+    <Badge>12</Badge>
+  </Inline>
+  <Inline gap="sm">
+    <Button variant="secondary">Экспорт</Button>
+    <Button variant="primary">Создать</Button>
+  </Inline>
+</Split>
+```
+
+---
+
+## ControlRow
+
+Ряд **смешанных контролов** формы и фильтров (TextField + Chip + Button + Select). Всегда `width: 100%` родителя. По умолчанию `role="group"`.
+
+| Проп | По умолчанию | Смысл |
+|------|--------------|--------|
+| `gap` | `sm` | Между контролами |
+| `align` | `center` | `center` — Chip/Button; `end` — рядом с floating-label; `baseline` — по тексту |
+| `justify` | `start` | |
+| `wrap` | `true` | |
+
+Ячейка с ростом: **`ControlRow.Item`** (= `LayoutItem`).
+
+**Использовать:** панель фильтров; Select + «Сброс»; несколько контролов в линию с общим выравниванием по высоте контрола.
+
+**Не использовать:** только чипы → **Inline**; заголовок/действия по краям → **Split**; вертикальная форма → **Stack**.
+
+```tsx
+<ControlRow align="end" gap="sm">
+  <ControlRow.Item grow>
+    <TextField label="Поиск" width="full" />
+  </ControlRow.Item>
+  <Button variant="secondary">Сброс</Button>
+</ControlRow>
+```
+
+---
+
+## LayoutItem
+
+Flex-ячейка внутри Stack / Inline / Split / ControlRow.
+
+| Проп | По умолчанию | Смысл |
+|------|--------------|--------|
+| `grow` | `false` | `flex: 1` — занять оставшееся место |
+| `shrink` | `true` | `false` — кнопка/чип не сжимаются |
+
+Алиасы: `ControlRow.Item`, `Layout.Item`.
+
+**Использовать:** поле поиска растягивается, кнопка — по контенту; иконка/чип с `shrink={false}`.
+
+**Не нужен:** для обычных детей, которым не нужны `grow` / `shrink`.
+
+```tsx
+<ControlRow>
+  <LayoutItem grow>
+    <SearchField label="Поиск" width="full" />
+  </LayoutItem>
+  <LayoutItem shrink={false}>
+    <Button>Найти</Button>
+  </LayoutItem>
+</ControlRow>
+```
+
+---
+
+## Типичные композиции
+
+### Тулбар страницы
+
+```tsx
+<Stack gap="lg">
+  <Split>
+    <Text as="h1">Команда</Text>
+    <Button variant="primary">Пригласить</Button>
+  </Split>
+  <ControlRow>
+    <ControlRow.Item grow>
+      <SearchField label="Поиск" width="full" />
+    </ControlRow.Item>
+    <Inline gap="sm">
+      <Chip active>Все</Chip>
+      <Chip>Активные</Chip>
+    </Inline>
+  </ControlRow>
+</Stack>
+```
+
+---
+
+## Частые ошибки
+
+| Ошибка | Как правильно |
+|--------|----------------|
+| `Inline` для «заголовок \| действия» | **Split** |
+| `Stack` для чипов в ряд | **Inline** |
+| `div` + `display:flex` + px `gap` | **Stack** / **Inline** с токенами |
+| Оборачивать всё в `LayoutItem` | Только где нужны `grow` / `shrink` |
+| Путать `Layout` и `FieldBase` | `Layout` — панель UI; `FieldBase` — оболочка поля ввода |