@pgcorp/ui-kit 0.13.0 → 0.15.0

package/docs/public-api.md

@@ -9,7 +9,7 @@
 
 - `layout/*` — каркас приложения, dock regions, stack и workbench layouts;
 - `shared/controls/*` — buttons, fields, inputs, selects, menus и selection controls;
-- `shared/containers/*` — panels, modal, drawer, popover и sidebars;
+- `shared/containers/*` — panels, modal, drawer, overlay host, popover и sidebars;
 - `shared/data-display/*` — badges, tables, code, JSON, progress, status и tooltips;
 - `shared/navigation/*` — tabs, breadcrumbs, catalog navigation и wizard steps;
 - `shared/database/*`, `shared/graph/*`, `shared/persona/*` — доменные сложные поверхности;
@@ -27,12 +27,39 @@ UI-kit-owned атрибуты `data-s-*` относятся к внутренн
 runtime-зависимости через layout конкретного package manager. Сборка использует
 `target/lib: ES2020`, совпадающий с baseline `@vue/tsconfig/tsconfig.dom.json`,
 и не требует скрытых полифиллов.
+Сборка Tailwind entrypoints использует Node ESM `dist/typography.js` с native
+`node:util`, полным upstream prose contract и options `className`/`target`
+для `modern | legacy`; browser Web Storage и DOM globals не требуются.
+`icons` публикует именованные tree-shakeable компоненты, включая `HardDrive`,
+`Usb`, `Disc`, `CalendarDays`, `ArrowUpRight`, `Paperclip`, `GitFork`, `ZoomIn`,
+`ZoomOut`, `RotateCw`, `Volume2`, `Radio`, `Pause`, `ChevronLeft` и `Zap`. `Zap`
+обозначает молнию для роли быстрой модели и сохраняет primary-only силуэт
+во всех цветовых режимах. `Pause`
+обозначает состояние паузы; `ChevronLeft` — переход влево. `Radio` обозначает сетевое вещание
+или фоновое уведомление, не radio input. `ZoomIn` и `ZoomOut` обозначают изменение
+масштаба; `RotateCw` — поворот по часовой стрелке; `Volume2` — звук с двумя
+волнами. Они используют общий icon
+contract с `classic | sputnig` наборами, `auto | duotone | monochrome` цветом
+и семантическим размером владельца control при передаче через icon slot.
 Типы таблицы импортируются из `shared/data-display/table`, типы графиков — из
 `shared/data-display/chart`, типы и чистая функция diff — из
 `shared/data-display/diff`. `SDiffViewer` принимает exact-text snapshots,
 показывает unified/split представление, виртуализирует строки и управляет
 вычислением в worker для больших входов. Смена source и unmount отменяют
 неактуальную работу; завершившийся устаревший результат не публикуется.
+`SProgressBar.shape="circular"` предоставляет 24/28/32 px numerical indicator
+через существующий progressbar owner. Determinate круг требует явный `value`
+0–100; `showValue` округляет только отображаемый процент, не `aria-valuenow`.
+`valueText` описывает предметное измерение. `accuracy="estimated"` требует
+`valueText` и видимую приблизительную отметку; явный `mode="unknown"` требует
+`valueText`, отвергает `value` и не создаёт numerical или animated state.
+Пассивная круговая форма допускает phrasing-композицию внутри кнопки в
+decorative mode; интерактивный owner и доступное имя остаются у кнопки.
+Штатная композиция использует `SButton.appearance="ghost"`, `iconOnly`,
+`shape="circle"`, `size="lg"` и `density="default"` с областью 48×48 px.
+Default linear/determinate и native range 0–100 сохраняются. Scoped default
+slot с точным value относится только к linear label; circular отклоняет этот
+slot и управляет числом и uncertainty marker через публичные props.
 `SChart` объединяет line/area/bar/pie/donut,
 responsive geometry, semantic palette и доступную таблицу данных. `SMetricCard`
 принимает компактный график через `#chart`. `SCodeBlock` сохраняет CodeMirror за
@@ -43,6 +70,27 @@ async boundary; `presentation="plain"` является lightweight read-only к
 `SActionListItem` держат primary activation и дополнительные controls
 sibling-элементами внутри одного chrome; `actionsLayout`/`trailingLayout`
 управляют inline, stacked и container-responsive раскладкой.
+`SInteractiveSurface.tooltipTrigger` принимает полный combined `trigger` из
+default slot `STooltip` и связывает ARIA, pointer/focus events и element ref
+с primary activation owner в режимах action, link `href` и Vue Router `to`.
+Link surface требует ровно один target и доступное имя; `to` требует
+подключённого Vue Router. Static surface отклоняет tooltip binding.
+Sibling `#actions` сохраняет независимые focus/activation. Подсказка
+открывается по pointer/focus и закрывается через Escape.
+Пассивный visual portal исключён из самостоятельного AX-чтения через
+`aria-hidden`; полный rich content доступен как `aria-describedby` описание
+focus owner. Внешние description references сохраняются; имя, роль и Tab
+порядок owner не изменяются. Tooltip не принимает интерактивный контент.
+Пассивная tooltip panel поддерживает геометрический hover без focus или Tab stop
+и не перехватывает указатель у расположенных под ней действий. Выход из
+target и панели закрывает её через `hideDelay`. Escape отменяет pending
+`showDelay` без перехвата события у другого overlay. Blur, скрытие документа,
+disabled и освобождение target завершают activation lease и его слушатели.
+Binding допускает canonical focus owner в сохранённой скрытой секции.
+Активация требует подключённого, видимого и доступного владельца. Скрытие
+его ancestor отменяет pending-таймеры, сразу исключает visual portal из
+взаимодействия и снимает tooltip description; последующий reveal сохраняет
+тот же owner и допускает новое pointer/focus открытие.
 `SUiKitLocaleProvider` задаёт `en | ru | zh-CN | zh-TW` для одного Vue subtree,
 а `composables/useUiKitLocale` экспортирует readonly context, полный список
 локалей и типы messages/overrides/ключей. Provider не создаёт DOM owner и
@@ -62,23 +110,142 @@ callbacks и trust flags не входят в API.
 `sm/md/lg = 32/36/40 px` и label typography `12/14/14 px`; тот же
 `density="compact"` у `SInputText` даёт совместимую геометрию поля без
 consumer CSS.
+Foreground/background `SButton` применяются атомарно без color interpolation
+при disabled/loading → enabled и смене визуального состояния. Native
+activation, `href` и Tab availability следуют текущим props без ожидания
+декоративных shadow/transform transitions.
 `SInputText.minLength`/`maxLength` и `STextarea.minLength`/`maxLength` передают строгие
 неотрицательные safe integers нативному textual input; `minLength <= maxLength`
 проверяется до рендера, а numeric/temporal families отвергают этот контракт.
+`STextareaContentContext.hasMultipleVisualLines` передаёт `false` для одной
+native визуальной строки, `true` для нескольких и `null` при недоступном layout
+(SSR/hidden/zero width). Soft wrapping и hard newline учитываются общей
+editing/resize поверхностью; пустое значение при доступном layout имеет одну
+строку. Условный helper использует `=== false`, `composing` и `disabled`, без
+измерения private DOM; min/max ограничивают всю surface независимо от helper.
+`STextareaApi.selectAll(focusOwner?: boolean): void` выделяет
+`[0, currentNativeValue.length]` с direction `forward` через общий selection
+owner. Default `true` запрашивает native focus; `false` его не меняет.
+Readonly и non-rendered controls допускают selection; disabled/detached focus
+зависит от native eligibility. Исходные CRLF/Unicode bytes, model и input/history
+не меняются; текущий native value учитывает неподтверждённый controlled input.
+Unavailable/disposed owner и non-boolean policy завершаются явной ошибкой.
+`SDockRegion.keepMounted?: boolean` имеет default `false` и сохраняет
+default disposal при скрытии. `true` сохраняет тот же slot owner, включая
+initial hidden; `hidden`/`inert` исключают layout, Tab, pointer и accessibility,
+а resize handle освобождается с typed cancellation активного drag.
+Повторное отображение не перехватывает внешний focus. `true → false` при
+скрытии и unmount освобождают содержимое. Transport/imperative buffers принадлежат
+consumer; terminal `open()` требует visible connected host с positive extent.
+Вложенные UI-kit overlays, включая Teleport, следуют `visible`: скрытие
+завершает registered/pending cycles, освобождает leases/body lock и не
+возвращает focus скрытому trigger. Initial hidden запрещает opening;
+retired controlled `open=true` получает один close intent и требует свежего
+`false → true`. Вложенные dock сочетают admission через AND; независимые
+sibling overlays и consumer-owned arbitrary portals не затрагиваются.
 `SModal.headingLevel` и `SDrawer.headingLevel` принимают только `1 | 2 | 3 | 4 |
 5 | 6`, используют `2` по умолчанию и сохраняют связь видимого заголовка с
-dialog surface через `aria-labelledby`.
+dialog surface через `aria-labelledby`. Локальная шапка диалога содержит
+семантический heading и не создаёт page-level `banner`.
 `SModal.size="4xl"` задаёт responsive maximum `56rem`; при ошибке дочернего
 mount modal освобождает body lock, layer registration и owned teleport nodes.
+Viewport `SModal`/`SDrawer` владеют единственным нативным `dialog` в modal top
+layer, без `tabindex` на semantic root. Фон всех DOM namespaces исключён из
+pointer/focus interaction и accessibility tree. Дочерние UI-kit portals
+принадлежат actual dialog вне transform/scroll clipping; вложенный viewport
+dialog изолирует родителя. Retirement синхронно освобождает native blocking,
+сохраняя отдельный shared focus-return и visual leave lifecycle. Contained
+drawer ограничивает HTML inert lease своим host и не вызывает `showModal()`.
+Экспортируемый `useDialogOverlay` в viewport-режиме требует actual connected
+`HTMLDialogElement` через `setPanelElement` и exact direct-child portal через
+`setPortalElement`; contained-режим сохраняет HTMLElement surface внутри
+SOverlayHost. Native methods принадлежат composable, не consumer.
+Для custom viewport leaf `dialog` и portal находятся в одном Document;
+portal — непосредственный дочерний HTMLElement semantic root. Visible frame
+передаётся через `setDismissalElement`, его расположение не меняет native focus
+scope. Controlled `open` является единственным запросом открытия/закрытия;
+`showModal()`, `close()`, запись `open` и native `form method="dialog"` не являются
+consumer API. Завершение формы использует обычный submit и явное controlled
+намерение закрытия. Native `cancel` обрабатывается shared owner без потери
+контроля над `open`. Композиция в стороннем native modal внутри opaque closed
+shadow root требует отдельного host-owner контракта и не поддерживается этим API.
+Обычные background sources внутри closed shadow root покрывает native Document
+blocking. Контракт миграции custom leaf описан в [overlay-lifecycle.md](./overlay-lifecycle.md).
+`SDrawer.placement` принимает `left | right | bottom` с default `right`.
+Боковые размещения физические, не зависят от text direction и используют
+общий size/scroll/focus owner; `left` зеркалирует сторону панели и её chrome.
+В contained-режиме `extent` задаёт ширину для `left/right` и высоту для `bottom`.
+`SOverlayHost` предоставляет default content и `#overlay` siblings.
+`SDrawer.scope="contained"` требует этот host, оставляет внешний ввод доступным
+и не объявляется глобально модальным. `extent` — конечный процент `(0,100]`
+доступной области; без него `size=sm/md/lg` задаёт `50/70/90` процентов по оси
+placement. `extent` запрещён для viewport-режима. `scrollBehavior="content"`
+делегирует прокрутку дочернему viewport без второго scroll owner/полей.
+Закрытие/retirement завершают дочерние overlay leases в общем stack; consumer
+обрабатывает `update:open`, повторное открытие требует явного нового open-cycle.
+Открытие через `SDropdownMenu` переносит exact current focus intent от
+временного menuitem к dialog и сохраняет устойчивый menu trigger как цель
+возврата, включая trigger вне contained host. Внешний focus отменяет pending
+admission и stale return; contained Escape boundary остаётся локальной.
+`SPopover` сохраняет native anchor и исходного focus owner trigger-запроса до
+подтверждения controlled `open`, без перехвата последующего внешнего фокуса.
+Программный `close()` отменяет ожидающий запрос через `update:open=false`.
+Удаление или disabled текущего focused action не является outside-переходом:
+панель остаётся открытой, принятое закрытие через Escape возвращает focus
+доступному registered trigger.
+Явный blur доступного элемента и внешний focus сохраняют outside-политику.
+`SDrawer`, `SPopover`, `STooltip`, `SContextMenu` и
+`SControlledToastViewport` сохраняют `opacity: 1` content при enter/leave:
+transform motion не меняет прозрачность выбранной surface, backdrop анимируется отдельно.
+Ширина `trigger` является минимальной шириной anchor, `content` — intrinsic,
+`sm/md/lg` — viewport-bounded `20/28/36rem`. Chrome и focus owner используют
+единые bounds; прозрачная поверхность задаёт всему dialog максимум `90vw`,
+при `width="trigger"` минимальная ширина anchor имеет приоритет.
 `SDropdownMenu` публикует controlled `open`, `defaultOpen`, размещение
 `auto | bottom | top`, `closeOnSelect`, semantic group entries и доступные
-описания пунктов. `SCollapsiblePanel` связывает compact/dense density с
+описания пунктов. Dropdown, контекстные и вложенные меню используют доступную
+область viewport и собственную прокрутку полной коллекции. Размещение задаёт
+предпочтительную сторону с collision/flip; keyboard focus раскрывает строку
+внутри menu surface без прокрутки документа. Внутренний scroll сохраняет
+открытое меню и parent layer; высота учитывает viewport и содержимое без
+consumer `max-height` или дочерних CSS-переопределений.
+Home/End раскрывают строку после ручной прокрутки; при отсутствии места по обеим
+inline-сторонам вложенное меню использует доступную верхнюю/нижнюю сторону общего
+collision owner.
+`SCollapsiblePanel` связывает compact/dense density с
 32-пиксельной disclosure geometry через публичный API `SButton`.
+`contentRole="region"` обозначает самостоятельный landmark и является значением
+по умолчанию; `contentRole="group"` задаёт именованную локальную группу для
+повторяемых или вложенных сведений. Обе роли связаны с видимым summary через
+`aria-labelledby`; trigger сохраняет `aria-expanded` и `aria-controls`.
+Raw `role` attrs не разрешены, неизвестный `contentRole` отклоняется без coercion.
+`lazy` монтирует slot при первом принятом раскрытии и сохраняет его после
+collapse/reopen в controlled и uncontrolled режимах, включая анимацию.
+Controlled `open` эмитит `update:open` intent до prop acknowledgement;
+uncontrolled режим изменяет собственное состояние без этого события.
+Принятое сворачивание сразу исключает content из Tab/AX через inert и
+aria-hidden, сохраняя mounted slot и завершающую анимацию. Owned focus
+возвращается доступному trigger; внешний focus не перехватывается.
+Отсутствие height transition завершает motion сразу; stale completion
+не влияет на повторное раскрытие или изменённую высоту.
+`SStatus` использует общую feedback tone-пару; `neutral` соответствует
+`secondary`. Текстовый статус в passive content `SButton` использует foreground
+интерактивной поверхности во всех доступных состояниях. `appearance="soft"`
+владеет собственной фоновой/текстовой парой. `tone`, подпись, иконка и live
+semantics сохраняются; `SCollapsiblePanel.summaryStatus` использует тот же путь
+без consumer color overrides.
 `shared/data-display/SScrollViewport.vue` владеет accessible scroll region,
 разрешёнными осями, semantic block size, root-only keyboard navigation и
 ResizeObserver lifecycle. `shared/data-display/scrollViewport` экспортирует
 сериализуемое physical/semantic state и exposed API `focus`,
 `scrollToBoundary`, `reveal` без доступа к внутреннему DOM.
+`focusPolicy="always"` — default; `overflow` добавляет region и Tab stop только
+при переполнении разрешённой оси. Ровно один из `accessibleLabel` и
+`accessibleLabelledby` задаёт имя. `blockSize="content"` сохраняет естественную
+высоту, `maxBlockSize="none|sm|md|lg"` задаёт semantic limit. Канонический table
+frame композирует этот owner, сохраняя native table semantics и nested controls.
+При исчезновении overflow focused root сохраняет `tabindex="-1"` до native blur
+без дополнительной остановки Tab или программного переноса focus.
 
 ## English
 
@@ -89,7 +256,7 @@ Primary groups:
 
 - `layout/*` — application shells, dock regions, stacks, and workbench layouts;
 - `shared/controls/*` — buttons, fields, inputs, selects, menus, and selection controls;
-- `shared/containers/*` — panels, modal, drawer, popover, and sidebars;
+- `shared/containers/*` — panels, modal, drawer, overlay host, popover, and sidebars;
 - `shared/data-display/*` — badges, tables, code, JSON, progress, status, and tooltips;
 - `shared/navigation/*` — tabs, breadcrumbs, catalog navigation, and wizard steps;
 - `shared/database/*`, `shared/graph/*`, `shared/persona/*` — complex domain surfaces;
@@ -107,12 +274,39 @@ Consumer type checkers do not compile internal SFCs or resolve their runtime
 dependencies through a package-manager-specific layout. The build uses the
 `target/lib: ES2020` baseline from `@vue/tsconfig/tsconfig.dom.json` and does not
 require implicit polyfills.
+Tailwind entrypoints use the Node ESM `dist/typography.js` artifact with
+native `node:util`, the complete upstream prose contract, and `className`/
+`target` options for `modern | legacy`, without browser Web Storage or DOM globals.
+`icons` exports named tree-shakeable components, including `HardDrive`, `Usb`,
+`Disc`, `CalendarDays`, `ArrowUpRight`, `Paperclip`, `GitFork`, `ZoomIn`, `ZoomOut`,
+`RotateCw`, `Volume2`, `Radio`, `Pause`, `ChevronLeft`, and `Zap`. `Zap` represents
+a lightning bolt for the fast-model role and retains its primary-only silhouette
+in every color mode. `Pause` represents
+a paused state; `ChevronLeft` represents leftward navigation. `Radio` represents network broadcast or a
+background notification, not a radio input. `ZoomIn` and `ZoomOut` represent zoom actions,
+`RotateCw` clockwise rotation, and `Volume2` a speaker with two sound waves.
+They share the icon contract with
+`classic | sputnig` sets, `auto | duotone | monochrome` color modes, and the
+control owner's semantic sizing when passed through an icon slot.
 Table types are imported from `shared/data-display/table`; chart types are
 imported from `shared/data-display/chart`; diff types and its pure computation
 function are imported from `shared/data-display/diff`. `SDiffViewer` accepts
 exact-text snapshots, renders unified or split presentation, virtualizes lines,
 and manages worker computation for large inputs. Source replacement and unmount
 cancel obsolete work, and a completed stale result is never published.
+`SProgressBar.shape="circular"` exposes 24/28/32 px measured progress through
+the existing numerical/accessibility owner. Circular determinate progress
+requires an explicit value in 0–100. `showValue` rounds only the displayed
+percentage, retaining precise `aria-valuenow`; `valueText` provides a domain
+description. Estimated accuracy requires `valueText` and a visible approximation
+marker. Explicit unknown mode requires `valueText`, rejects `value`, and omits
+the numerical value and animation. The passive circular root supports phrasing
+composition in a button with decorative accessibility; the button owns the
+action and accessible name. The public recipe uses `SButton.appearance="ghost"`,
+`iconOnly`, `shape="circle"`, `size="lg"`, and default density for a 48×48 px
+target. Default linear/determinate behavior is preserved;
+its scoped default slot receives the exact value. Circular progress rejects a
+supplied default slot and owns central numerical and uncertainty display.
 `SChart` unifies
 line/area/bar/pie/donut charts, responsive geometry, the semantic palette, and
 an accessible data table. `SMetricCard` accepts a compact chart through
@@ -124,6 +318,23 @@ the editor runtime. `SChip.surface` owns action/link semantics, while
 compositions keep primary activation and additional controls as siblings inside
 one chrome; `actionsLayout`/`trailingLayout` control inline, stacked, and
 container-responsive layout.
+`SInteractiveSurface.tooltipTrigger` accepts the complete combined `trigger`
+from the `STooltip` default slot and binds ARIA, pointer/focus events, and the
+element ref to the primary activation owner for action, link `href`, and Vue
+Router `to`. A link surface requires exactly one target and an accessible name;
+`to` requires Vue Router installed in the application. A static surface rejects
+the tooltip binding. Sibling `#actions` retain independent focus and activation.
+The tooltip opens on pointer/focus and closes with Escape.
+The passive tooltip panel supports geometric hover without focus or a Tab stop
+and does not intercept pointer activation of underlying actions. Leaving
+the target and panel closes it after `hideDelay`. Escape cancels a pending
+`showDelay` without consuming another overlay's event. Blur, a hidden document,
+disabled state, and target release terminate the activation lease and listeners.
+Binding accepts a canonical focus owner in a retained hidden section.
+Activation requires a connected, visible, available owner. Hiding its
+ancestor cancels pending timers, immediately retires the visual portal from
+interaction and removes the tooltip description. Revealing the section
+retains the same owner and permits fresh pointer/focus activation.
 `SUiKitLocaleProvider` selects `en | ru | zh-CN | zh-TW` for one Vue subtree,
 while `composables/useUiKitLocale` exports the readonly context, the complete
 locale list, and message/override/key types. The provider renders no DOM owner
@@ -144,20 +355,138 @@ and trust flags are not part of the API.
 `sm/md/lg = 32/36/40 px` with `12/14/14 px` label typography. The matching
 `SInputText.density="compact"` exposes the same field geometry without consumer
 CSS.
+The `SButton` foreground/background pair changes atomically, without color
+interpolation, when disabled/loading actions become enabled or presentation
+changes. Native activation, `href`, and Tab availability follow current props
+without waiting for decorative shadow/transform transitions.
 `SInputText.minLength`/`maxLength` and `STextarea.minLength`/`maxLength` pass strict non-negative safe
 integers to the native textual input. `minLength <= maxLength` is validated
 before rendering, and numeric/temporal families reject this contract.
+`STextareaContentContext.hasMultipleVisualLines` is `false` for one native
+visual line, `true` for multiple lines, and `null` when layout is unavailable
+(SSR/hidden/zero width). The editing/resize owner measures soft wrapping and
+hard newlines; an empty value has one line once layout is available. Conditional
+helpers use `=== false`, `composing` and `disabled`, without private DOM
+measurement. Min/max bounds include the complete surface independently of the
+helper visibility policy.
+`STextareaApi.selectAll(focusOwner?: boolean): void` selects
+`[0, currentNativeValue.length]` forward through the shared selection owner.
+The default `true` requests native focus; `false` leaves it unchanged.
+Readonly and non-rendered controls support selection; disabled/detached focus
+follows native eligibility. Source CRLF/Unicode bytes, model, and input/history
+are unchanged; the current native value includes unacknowledged controlled input.
+An unavailable/disposed owner or non-boolean policy throws an explicit error.
+`SDockRegion.keepMounted?: boolean` defaults to `false`, preserving disposal
+on hide. `true` retains the same slot owner, including initially hidden content;
+`hidden`/`inert` exclude layout, Tab, pointer, and accessibility, while the
+resize handle retires with typed cancellation of an active drag.
+Showing does not steal external focus. Hidden `true → false` and unmount
+dispose the content. Transport/imperative buffers remain consumer-owned;
+terminal `open()` requires a visible, connected host with positive extent.
+Nested UI-kit overlays, including Teleports, follow `visible`: hiding retires
+registered/pending cycles, releases leases/body locks, and never restores focus
+to a hidden trigger. Initially hidden content cannot open overlays; retired
+controlled `open=true` receives one close intent and needs a fresh `false → true`
+request. Nested docks compose admission with AND; independent sibling overlays
+and arbitrary consumer-owned portals are unaffected.
 `SModal.headingLevel` and `SDrawer.headingLevel` accept `1 | 2 | 3 | 4 | 5 | 6`
 only, default to `2`, and preserve the visible-title relationship with the
-dialog surface through `aria-labelledby`.
+dialog surface through `aria-labelledby`. Local dialog chrome contains the
+semantic heading without creating a page-level `banner` landmark.
 `SModal.size="4xl"` provides a responsive `56rem` maximum; a failed child mount
 releases body lock, layer registration, and owned teleport nodes.
+Viewport `SModal`/`SDrawer` own one native `dialog` in the modal top layer, with
+no `tabindex` on the semantic root. All background DOM namespaces leave
+pointer/focus interaction and the accessibility tree. Descendant UI-kit portals
+belong to the actual dialog outside transforms and scroll clipping; a nested
+viewport dialog isolates its parent. Retirement releases native blocking
+synchronously while preserving the shared focus-return and visual leave
+lifecycles. A contained drawer limits an HTML inert lease to its host and does
+not call `showModal()`.
+The exported `useDialogOverlay` requires an actual connected `HTMLDialogElement`
+through `setPanelElement` and its exact direct-child portal through
+`setPortalElement` in viewport mode. Contained mode retains an HTMLElement
+surface inside SOverlayHost. The composable owns native methods, not consumers.
+The custom viewport leaf binds its visible frame through `setDismissalElement`
+and applies `portalStyle` to its direct-child portal. Controlled `open` is the
+only opening/closing request; direct native lifecycle calls, `open` writes and
+`form method="dialog"` exits are not consumer APIs. Regular form submission
+uses an explicit parent close intent. Nesting inside a foreign native modal in
+an opaque closed shadow root requires a separate host-owner contract.
+See [overlay-lifecycle.md](./overlay-lifecycle.md) for the custom-leaf migration.
+`SDrawer.placement` accepts `left | right | bottom`, defaulting to `right`.
+Side placements are physical, independent of text direction, and share the
+size/scroll/focus owner; `left` mirrors the panel edge and its chrome.
+Contained `extent` specifies width for `left/right` and height for `bottom`.
+`SOverlayHost` provides default content and `#overlay` sibling regions.
+`SDrawer.scope="contained"` requires that host, keeps external input available,
+and is not globally modal. `extent` is a finite percentage `(0,100]` of the
+available region; without it, `size=sm/md/lg` specifies `50/70/90` percent along
+the placement axis. Viewport mode rejects `extent`. `scrollBehavior="content"`
+delegates scrolling to a child viewport without a second scroll owner/padding.
+Close/retirement retires descendant overlay leases in the shared stack; the
+consumer handles `update:open` and an explicit new open-cycle controls reopening.
+Opening through `SDropdownMenu` transfers the exact current focus intent
+from a transient menu item to the dialog and retains its stable menu trigger
+for restoration, including triggers outside a contained host. External focus
+cancels pending admission and stale restoration; contained Escape remains local.
+`SPopover` preserves the native anchor and original focus owner of a trigger
+request through controlled `open` acknowledgement without taking subsequent
+external focus. Programmatic `close()` cancels a pending request with
+`update:open=false`.
+Removing or disabling the currently focused action is not an outside move:
+the panel stays open, and an accepted Escape close restores the available
+registered trigger.
+Explicit blur of an available element and external focus retain the outside policy.
+`SDrawer`, `SPopover`, `STooltip`, `SContextMenu`, and
+`SControlledToastViewport` keep content at `opacity: 1` during entry/exit:
+transform motion preserves the selected surface translucency, and backdrop animation is independent.
+The `trigger` width is the anchor minimum, `content` is intrinsic, and
+`sm/md/lg` are viewport-bounded `20/28/36rem`. Chrome and focus owner share
+the same bounds; a transparent surface sets the entire dialog's maximum to `90vw`.
+With `width="trigger"`, the anchor minimum takes precedence.
 `SDropdownMenu` exposes controlled `open`, `defaultOpen`,
 `auto | bottom | top` placement, `closeOnSelect`, semantic group entries, and
-accessible item descriptions. `SCollapsiblePanel` maps compact/dense density to
+accessible item descriptions. Dropdown, context, and nested menus use the
+available viewport and own scrolling of the complete inventory. Placement
+specifies a preferred side with collision/flip; keyboard focus reveals its row
+inside the menu surface without scrolling the document. Internal scrolling
+preserves the open menu and parent layer; height follows the viewport and
+content without consumer `max-height` or child CSS overrides.
+Home/End reveal the current row after manual scrolling; when neither inline
+side fits a submenu, it uses the available top/bottom side of the shared
+collision owner.
+`SCollapsiblePanel` maps compact/dense density to
 the 32px disclosure geometry through the public `SButton` API.
+`contentRole="region"` marks an independently navigable landmark and is the
+default; `contentRole="group"` provides a named local group for repeated or
+nested details. Both roles are labelled by the visible summary through
+`aria-labelledby`; the trigger retains `aria-expanded` and `aria-controls`.
+Raw `role` attrs are not admitted; unknown `contentRole` values fail without
+coercion. `lazy` mounts its slot on the first accepted opening and retains it
+across collapse/reopen in controlled and uncontrolled modes, including animation.
+Controlled `open` emits `update:open` intent before prop acknowledgement;
+uncontrolled mode updates its owned state without that event.
+Accepted collapse immediately excludes content from Tab/AX using inert
+and aria-hidden, retaining the mounted slot and closing visual transition.
+Owned focus returns to an available trigger; external focus is not taken.
+An absent height transition settles motion immediately; stale completion
+does not affect reopening or an updated content height.
+`SStatus` uses the shared feedback tone pair; `neutral` maps to `secondary`.
+A text status in `SButton` passive content uses the interactive surface's
+foreground across its available states. `appearance="soft"` owns its
+background/text pair. Tone, label, icon, and live semantics are preserved;
+`SCollapsiblePanel.summaryStatus` uses the same path without consumer color
+overrides.
 `shared/data-display/SScrollViewport.vue` owns the accessible scroll region,
 enabled axes, semantic block size, root-only keyboard navigation, and
 ResizeObserver lifecycle. `shared/data-display/scrollViewport` exports
 serializable physical and semantic state plus the `focus`, `scrollToBoundary`,
 and `reveal` exposed API without access to internal DOM.
+`focusPolicy="always"` is the default; `overflow` adds a region and Tab stop
+only when an enabled axis overflows. Exactly one of `accessibleLabel` and
+`accessibleLabelledby` supplies the name. `blockSize="content"` retains intrinsic
+height, and `maxBlockSize="none|sm|md|lg"` supplies a semantic limit. The canonical
+table frame composes this owner, retaining native table semantics and nested controls.
+After overflow disappears, a focused root retains `tabindex="-1"` until native
+blur, without an additional Tab stop or programmatic focus move.

package/docs/resize.md

@@ -0,0 +1,158 @@
+# Изменение размеров панелей
+
+`SResizeHandle` владеет native `button` с `role="separator"`, pointer capture,
+клавиатурой, hitbox и interaction lease для cursor/selection. `SDockRegion`
+композирует этот leaf и определяет семантический результат dock gesture.
+Consumer хранит размер и его persistent preference; собственные pointer
+listeners и расчёт pointer delta не требуются.
+
+## Публичные типы
+
+```ts
+import type {
+  SResizeHandleCancel,
+  SResizeHandleCancelReason,
+  SResizeHandleCompletion,
+  SResizeHandleHitbox,
+  SDockRegionCollapse,
+} from '@pgcorp/ui-kit/layout/types'
+```
+
+Эти типы доступны также в корневом type export пакета. `SResizeHandle` сохраняет
+type exports через путь своего компонента.
+
+`hitbox` принимает `compact` (6 px), `standard` (12 px) или `spacious` (32 px).
+По умолчанию inline separator использует `compact`, overlay — `spacious`.
+`SDockRegion.hitbox` передаёт ту же семантическую ступень native владельцу.
+
+## Pointer transaction
+
+| Событие | Payload | Контракт |
+| --- | --- | --- |
+| `resize-start` | `PointerEvent` | Начало pointer preview |
+| `resize` | `number` | Preview, ограниченный текущим `min/max` |
+| `resize-end` | `number`, `SResizeHandleCompletion` | Принятие конечной координаты `pointerup` |
+| `resize-cancel` | `SResizeHandleCancel` | Отмена без `resize-end` |
+
+`SResizeHandleCompletion` содержит `source: 'pointer'`, `startValue` и
+`unclampedValue`. Логический intent вычисляется leaf-компонентом с axis,
+`valueDirection` и `pointerScale` gesture. Ограничение применяется по актуальному
+`min/max`; `pointerup` учитывается даже без предшествующего `pointermove`.
+
+`SResizeHandleCancel` содержит `initialValue`, последний ограниченный
+`latestValue` и точную `reason`: `pointercancel`, `lostpointercapture`,
+`window-blur`, `disabled`, `superseded` или `unmount`. Все listeners, capture и
+interaction lease освобождаются при завершении и отмене. Отмена соответствует
+[Pointer Events: pointercancel и lostpointercapture](https://www.w3.org/TR/pointerevents3/).
+
+Consumer применяет `resize` к preview. В `resize-end` он принимает размер и
+сохраняет preference. `initialValue` — отображаемый размер на старте, а не
+сохранённая preference: адаптивная рабочая область может ограничивать её своим
+диапазоном. В `resize-cancel` consumer восстанавливает отображаемый snapshot в
+актуальной host geometry; persistence preference восстанавливается из его
+собственного transaction snapshot, не из `initialValue`. Отменённый preview
+не сохраняется. На время pointer transaction persistent watcher должен быть
+отделён от preview state.
+
+## Клавиатурное завершение
+
+Arrow/Home/End применяют одно дискретное изменение: `resize(value)`, затем
+`resize-end(value)` без `SResizeHandleCompletion`. Отсутствие completion
+обозначает клавиатурный источник; pointer completion всегда содержит
+`source: 'pointer'`. Клавиатура не открывает pointer transaction и не выдаёт
+`resize-start` или `resize-cancel`.
+
+Значение ограничивается текущими `min/max`. На границе диапазона, для
+ортогональной стрелки, при `disabled` или во время активного pointer gesture
+события изменения и завершения не выдаются. Если обработчик `resize` удаляет
+native owner, завершение после его disposal не выдаётся.
+
+Consumer может хранить preview в `resize` и сохранять preference в
+`resize-end` для обоих источников. Если составной owner уже атомарно сохраняет
+клавиатурный `resize`, terminal notification не выполняет повторную запись:
+обработчик явно разделяет источники по completion. Pointer commit требует
+собственной живой transaction, а не разрешается при её отсутствии.
+
+```ts
+function finishSizeChange(value: number, completion?: SResizeHandleCompletion): void {
+  if (completion === undefined) {
+    commitKeyboardSize(value)
+    return
+  }
+  commitPointerSize(value, completion)
+}
+```
+
+```vue
+<SDockRegion
+  placement="left"
+  :visible="visible"
+  :size="size"
+  :min-size="200"
+  :max-size="maxSize"
+  hitbox="standard"
+  @resize-start="beginSizeTransaction"
+  @resize="previewSize"
+  @resize-end="finishSizeChange"
+  @resize-cancel="cancelSizeTransaction"
+>
+  <ProjectPanel />
+</SDockRegion>
+```
+
+Размер, min/max, step и pointerScale должны быть конечными числами; размер
+находится в min/max, `min <= max`, `step > 0` и `pointerScale > 0`. Consumer
+передаёт согласованный диапазон при изменении рабочей области. Некорректный
+диапазон отклоняется с `RangeError`; компонент не исправляет входные данные.
+
+## Сворачивание dock
+
+`SDockRegion.collapseThreshold` включает сворачивание только для committed
+pointer release. Порог — конечное число `0 <= collapseThreshold < minSize`.
+Preview остаётся ограниченным `minSize`; временно непригодная узкая панель не
+рендерится.
+
+Если конечный `unclampedValue` строго ниже порога, dock эмитит только
+`collapse({ preferredSize: startValue })`, без конкурирующего `resize-end`.
+В остальных случаях он передаёт `resize-end` и completion. Consumer закрывает
+панель по `collapse` и сохраняет `preferredSize` для повторного открытия.
+Pointer cancellation не вызывает `collapse`. Keyboard Home устанавливает
+`minSize` и не сворачивает панель.
+
+```vue
+<SDockRegion
+  placement="left"
+  :visible="visible"
+  :size="size"
+  :min-size="200"
+  :max-size="maxSize"
+  :collapse-threshold="80"
+  hitbox="standard"
+  @resize-start="beginSizeTransaction"
+  @resize="previewSize"
+  @resize-end="finishSizeChange"
+  @resize-cancel="cancelSizeTransaction"
+  @collapse="collapseSizeTransaction"
+>
+  <ProjectPanel />
+</SDockRegion>
+```
+
+Без `collapseThreshold` dock не сворачивается при перетаскивании. Для правой
+панели можно оставить `minSize=240`, динамический `maxSize` и отключённый порог.
+
+## Составные владельцы
+
+`SSidebarGroup` хранит pointer geometry preview локально. `update-sections`
+передаёт принятую controlled preference после commit, а не на каждом move.
+Отмена восстанавливает snapshot всей участвующей группы без persistence
+события. Удаление секции освобождает её активную transaction. Клавиатура
+передаёт дискретное изменение через `update-sections`.
+
+`SWorkbenchPanelShell` восстанавливает secondary size через тот же cancel
+payload; его диапазон принадлежит текущей рабочей области. Consumers используют
+эти owners, а не создают собственный drag engine.
+
+Storybook: `SResizeHandle/KeyboardCommitPersistence`,
+`SResizeHandle/PointerTouchAndConcurrentLifecycle` и
+`SDockRegion/CompanionDocks`, `CompanionDocksDark`, `CompanionDocksNarrow`.