@pgcorp/ui-kit 0.14.0 → 0.15.0

package/docs/overlay-lifecycle.md

@@ -0,0 +1,195 @@
+# Жизненный цикл overlay / Overlay lifecycle
+
+## Русский
+
+`SModal` и viewport `SDrawer` используют один native dialog owner. Публичные
+props, slots и events этих компонентов не требуют consumer DOM API.
+Составные окна, меню, поля выбора, popover и tooltip используют принадлежащий
+окну portal. Global toast остаётся background notification owner; modal-local
+controlled toast принадлежит окну, в котором он объявлен.
+
+### Custom leaf через `useDialogOverlay`
+
+Контракт `composables/useDialogOverlay` предназначен для leaf, который владеет
+полной semantic, visual и accessibility поверхностью своего диалога.
+Приложения используют готовые `SModal`/`SDrawer`, если их props и slots выражают
+нужную композицию.
+
+Миграция `0.15` относится к собственным viewport leaf, использующим
+экспортируемый composable: semantic surface — `HTMLDialogElement`, а portal —
+его непосредственный дочерний HTMLElement. Публичные props, slots и events
+готовых `SModal`/`SDrawer` сохраняются; contained leaf сохраняет HTMLElement
+surface и `SOverlayHost`.
+
+Для viewport leaf:
+
+1. Передать controlled boolean `open`, boolean `closable` и callback
+   `requestClose`. Callback формирует намерение, а состояние задаёт parent.
+2. Рендерить один подключённый `HTMLDialogElement` через `renderOpen` и связать
+   его ref с `setPanelElement`. Не задавать `open`, `autofocus` или `tabindex`
+   semantic root. Lifecycle native methods принадлежит composable.
+3. Создать прямой дочерний HTMLElement portal, связать его ref с
+   `setPortalElement` и применить `portalStyle`. Portal находится вне transform,
+   overflow clipping и visual scrolling frame.
+4. Связать visible frame с `setDismissalElement`; применить `backdropStyle` и
+   `surfaceStyle` к соответствующим принадлежащим leaf visual surfaces.
+5. Установить доступное имя диалога через heading/`aria-labelledby` либо
+   `aria-label`. Footer/submit completion запрашивает controlled close.
+
+### Исполняемый typed binding
+
+Полная композиция — export `NativeOwnerContract` в
+[`SModal.stories.ts`](https://github.com/pglyanenko/sputnig/blob/master/packages/ui-kit/src/components/shared/containers/SModal.stories.ts).
+В Storybook она называется **«Публичный владелец нативного диалога»**,
+story ID — `ui-kit-контейнеры-smodal--native-owner-contract`.
+Тип `DialogOverlayController` импортируется из публичного
+`@pgcorp/ui-kit/composables/useDialogOverlay`; native ref binding типизирован
+как `DialogOverlayController['setPanelElement']`.
+
+| Владелец в story | Binding | Контракт |
+| --- | --- | --- |
+| Родительское состояние | `open`, `closable`, `requestClose` | Callback формирует close intent; parent подтверждает его изменением `open` |
+| Native root | `controller.renderOpen.value`, `bindSubject` → `controller.setPanelElement` | Единственный подключённый `<dialog>`; root без `open`, `autofocus` и `tabindex` |
+| Доступное имя | `aria-labelledby="native-owner-title"`, `<h2 id="native-owner-title">` | Видимый heading именует semantic root |
+| Backdrop | `controller.backdropStyle.value` | Собственная поверхность leaf, `aria-hidden="true"`, отдельная от content |
+| Контейнер размещения и прокрутки | `controller.surfaceStyle.value` | Paint band visual frame; portal не является потомком scroll/transform owner |
+| Видимая frame | `controller.setDismissalElement` | Точная граница pointer dismissal; semantic focus scope остаётся native root |
+| Native portal | `controller.setPortalElement`, `controller.portalStyle.value` | Прямой дочерний HTMLElement dialog, sibling visual surfaces, `display: contents` |
+| Кнопка завершения | `SButton` → `requestClose` | Обычное UI-kit действие без native `dialog.close()` |
+| Явное освобождение | `controller.dispose()` | Retirement без запроса возврата focus |
+
+В source приведены полные стили semantic root, backdrop, positioner и frame,
+включая focus-visible frame. Native methods вызываются только shared owner.
+Кнопки изменения admission, `beforetoggle` probes и неподдержанное завершение
+формы — диагностические действия regression story, а не требования к consumer.
+Этот же export исполняется в
+[`ui-kit-native-dialog-isolation.visual.spec.ts`](https://github.com/pglyanenko/sputnig/blob/master/lvs/frontend/tests/storybook/ui-kit-native-dialog-isolation.visual.spec.ts):
+проверяются подтверждённое закрытие, no-ACK, `closable=false`, explicit dispose,
+отменённый focus intent, reentrant retirement и сохранение source attributes в
+Chromium, Firefox и WebKit.
+
+`opened` вызывается после подтверждённого initial focus claim самого semantic
+root. Initial controlled child menu/popover имеет самостоятельного focus owner;
+его доступность не требует initial focus permission родителя.
+`dispose()` явно освобождает cycle без запроса возврата фокуса. Обычный unmount
+использует shared guarded return к доступному launcher, захваченному из
+фактического native focus. Pointer activation сама по себе не гарантирует
+фокус кнопки во всех браузерах. Скрытый retained dock
+отменяет admission и не возвращает focus скрытому trigger. Возврат видимости
+не открывает отменённое окно: требуется новое явное изменение `open` с `false`
+на `true`. Содержимое retained dock сохраняет свой экземпляр и состояние.
+
+`scope="contained"` сохраняет HTMLElement surface внутри exact `SOverlayHost`
+portal и локальный HTML inert lease. Native `showModal()` в этом режиме не
+вызывается; внешние controls остаются доступными.
+
+### Граница lifecycle
+
+Consumer не вызывает native `showModal()`/`close()`, не меняет `open` attribute
+и не использует `form method="dialog"` как обход controlled состояния.
+Для завершения формы предусмотрены обычный submit и явное намерение parent.
+Уже отменённый submit не создаёт close intent. Native `cancel` не закрывает
+controlled окно без обновления `open`; `closable=false` запрещает dismissal.
+
+Native Document blocking охватывает HTML, SVG, MathML и background sources
+внутри closed shadow root. Открытый дочерний native dialog изолирует предыдущие
+native owners и их portal-содержимое на весь свой lifecycle. Их временные inert
+leases освобождаются после native close до shared guarded focus return;
+исходные атрибуты и независимые изменения host сохраняются.
+Сторонний native modal внутри opaque closed shadow
+root не входит в поддерживаемую nesting-композицию без exact host-owner
+capability. Прямое вмешательство host в принадлежащий cycle или его временные
+modality guards нарушает owner boundary.
+
+### Браузерная проверка
+
+`make -C lvs frontend-browser-install` устанавливает browser revisions из
+зафиксированного Playwright workspace. Команда не запускает quality gates.
+`LVS_STORYBOOK_NATIVE_DIALOG_ENGINES=1 make -C lvs check-frontend-storybook-proof
+PLAYWRIGHT_STORYBOOK_ARGS="tests/storybook/ui-kit-native-dialog-isolation.visual.spec.ts"`
+проверяет native lifecycle в Chromium, Firefox и WebKit.
+
+## English
+
+`SModal` and viewport `SDrawer` share one native dialog owner. Their public
+props, slots and events require no consumer DOM lifecycle calls. Owned floating
+surfaces use the dialog's portal; global notifications remain background-owned.
+
+The `0.15` migration applies to custom viewport leaves using the exported
+composable: the semantic surface is an `HTMLDialogElement`, and its portal is a
+direct-child HTMLElement. The ready-made `SModal`/`SDrawer` retain their public
+props, slots, and events. Contained leaves retain their HTMLElement surface and
+`SOverlayHost` contract.
+
+Custom `useDialogOverlay` viewport leaves provide one connected
+`HTMLDialogElement` through `setPanelElement`, an exact direct-child portal
+through `setPortalElement`, and the visible dismissal frame through
+`setDismissalElement`. Render from `renderOpen`; apply the controller's
+`backdropStyle`, `surfaceStyle` and `portalStyle` to their exact visual owners.
+The semantic root has an accessible name and no `open`, `autofocus` or
+`tabindex` assignment. Controlled `open` owns the lifecycle; `requestClose`
+is an intent, not permission to mutate native state.
+
+### Executable typed binding
+
+The complete composition is the `NativeOwnerContract` export in
+[`SModal.stories.ts`](https://github.com/pglyanenko/sputnig/blob/master/packages/ui-kit/src/components/shared/containers/SModal.stories.ts).
+Its Storybook name is **«Публичный владелец нативного диалога»** and its story ID
+is `ui-kit-контейнеры-smodal--native-owner-contract`. `DialogOverlayController`
+is imported from the public `@pgcorp/ui-kit/composables/useDialogOverlay`; the
+native ref binding uses `DialogOverlayController['setPanelElement']`.
+
+| Story owner | Binding | Contract |
+| --- | --- | --- |
+| Parent state | `open`, `closable`, `requestClose` | The callback produces a close intent; the parent acknowledges it by updating `open` |
+| Native root | `controller.renderOpen.value`, `bindSubject` → `controller.setPanelElement` | One connected `<dialog>` without `open`, `autofocus`, or `tabindex` assignments |
+| Accessible name | `aria-labelledby="native-owner-title"`, `<h2 id="native-owner-title">` | The visible heading names the semantic root |
+| Backdrop | `controller.backdropStyle.value` | An owned leaf surface with `aria-hidden="true"`, separate from content |
+| Placement and scrolling container | `controller.surfaceStyle.value` | The visual frame's paint band; the portal is outside scroll/transform ownership |
+| Visible frame | `controller.setDismissalElement` | The exact pointer dismissal boundary; native root retains semantic focus scope |
+| Native portal | `controller.setPortalElement`, `controller.portalStyle.value` | A direct-child HTMLElement dialog portal, sibling to visual surfaces, with `display: contents` |
+| Completion button | `SButton` → `requestClose` | A regular UI-kit action without native `dialog.close()` |
+| Explicit disposal | `controller.dispose()` | Retirement without a focus-return request |
+
+The source includes complete semantic-root, backdrop, positioner, and frame
+styles, including the focus-visible frame. Only the shared owner calls native
+methods. Admission controls, `beforetoggle` probes, and unsupported form
+completion are regression-story diagnostics, not consumer requirements.
+The same export is exercised by
+[`ui-kit-native-dialog-isolation.visual.spec.ts`](https://github.com/pglyanenko/sputnig/blob/master/lvs/frontend/tests/storybook/ui-kit-native-dialog-isolation.visual.spec.ts):
+acknowledged close, no-ACK, `closable=false`, explicit disposal, cancelled focus
+intent, reentrant retirement, and preserved source attributes are verified in
+Chromium, Firefox, and WebKit.
+
+`opened` follows the root's successful initial focus claim. Initially open
+child layers retain their own focus ownership. Explicit `dispose()` requests
+no return; ordinary unmount uses the shared guarded return to the available
+launcher captured from actual native focus. Pointer activation does not
+guarantee button focus in every browser. Hiding a retained dock revokes admission
+without returning focus to its hidden trigger. Revealing the dock does not revive
+the cancelled window: a fresh explicit `open` change from `false` to `true` is
+required. The retained dock keeps its content instance and state.
+Contained scope retains its local HTMLElement/`SOverlayHost` contract and does
+not call native `showModal()`.
+
+Direct `showModal()`, `close()`, `open` writes and `form method="dialog"` exits
+are outside the controlled API. Use regular form submission and an explicit
+parent close intent. Native cancel respects controlled state and dismissal
+permission. Already cancelled submissions produce no close intent.
+
+Native Document blocking covers HTML, SVG, MathML and ordinary closed-shadow
+background sources. An open child native dialog isolates previous native owners
+and their portal content for its entire lifecycle. Temporary inert leases release
+after native close and before the shared guarded focus return; original attributes
+and independent host writes are preserved.
+Nesting inside a foreign native modal in an opaque closed
+shadow root requires a separate exact host-owner capability. Host mutation of
+the owned native cycle or its temporary modality guards violates ownership.
+
+### Browser verification
+
+`make -C lvs frontend-browser-install` installs the browser revisions required
+by the locked Playwright workspace; it does not run quality gates.
+`LVS_STORYBOOK_NATIVE_DIALOG_ENGINES=1 make -C lvs check-frontend-storybook-proof
+PLAYWRIGHT_STORYBOOK_ARGS="tests/storybook/ui-kit-native-dialog-isolation.visual.spec.ts"`
+verifies the native lifecycle in Chromium, Firefox and WebKit.

package/docs/public-api.md

@@ -27,6 +27,9 @@ 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`
@@ -74,10 +77,20 @@ Link surface требует ровно один target и доступное и
 подключённого Vue Router. Static surface отклоняет tooltip binding.
 Sibling `#actions` сохраняет независимые focus/activation. Подсказка
 открывается по pointer/focus и закрывается через Escape.
-Пассивная tooltip panel поддерживает hover без focus или Tab stop; выход из
+Пассивный 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 и
@@ -97,6 +110,10 @@ 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 отвергают этот контракт.
@@ -128,9 +145,32 @@ retired controlled `open=true` получает один close intent и тре
 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.
@@ -143,9 +183,20 @@ placement. `extent` запрещён для viewport-режима. `scrollBehavi
 делегирует прокрутку дочернему 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`,
@@ -163,6 +214,20 @@ 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"`
@@ -174,6 +239,13 @@ semantics сохраняются; `SCollapsiblePanel.summaryStatus` исполь
 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
 
@@ -202,6 +274,9 @@ 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
@@ -250,10 +325,16 @@ 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 hover without focus or a Tab stop; leaving
+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
@@ -274,6 +355,10 @@ 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.
@@ -306,9 +391,29 @@ 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.
@@ -321,10 +426,21 @@ 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`.
@@ -342,6 +458,20 @@ 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
@@ -353,3 +483,10 @@ 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

@@ -52,8 +52,36 @@ Consumer применяет `resize` к preview. В `resize-end` он прини
 актуальной host geometry; persistence preference восстанавливается из его
 собственного transaction snapshot, не из `initialValue`. Отменённый preview
 не сохраняется. На время pointer transaction persistent watcher должен быть
-отделён от preview state. Клавиатурные Arrow/Home/End являются
-дискретным `resize` без pointer transaction, `resize-end` или `resize-cancel`.
+отделён от 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
@@ -65,7 +93,7 @@ Consumer применяет `resize` к preview. В `resize-end` он прини
   hitbox="standard"
   @resize-start="beginSizeTransaction"
   @resize="previewSize"
-  @resize-end="commitSizeTransaction"
+  @resize-end="finishSizeChange"
   @resize-cancel="cancelSizeTransaction"
 >
   <ProjectPanel />
@@ -102,7 +130,7 @@ Pointer cancellation не вызывает `collapse`. Keyboard Home устан
   hitbox="standard"
   @resize-start="beginSizeTransaction"
   @resize="previewSize"
-  @resize-end="commitSizeTransaction"
+  @resize-end="finishSizeChange"
   @resize-cancel="cancelSizeTransaction"
   @collapse="collapseSizeTransaction"
 >
@@ -125,5 +153,6 @@ Pointer cancellation не вызывает `collapse`. Keyboard Home устан
 payload; его диапазон принадлежит текущей рабочей области. Consumers используют
 эти owners, а не создают собственный drag engine.
 
-Storybook: `SResizeHandle/PointerTouchAndConcurrentLifecycle` и
+Storybook: `SResizeHandle/KeyboardCommitPersistence`,
+`SResizeHandle/PointerTouchAndConcurrentLifecycle` и
 `SDockRegion/CompanionDocks`, `CompanionDocksDark`, `CompanionDocksNarrow`.

package/docs/scroll-viewport.md

@@ -26,9 +26,11 @@ import type {
 
 | Prop | Contract |
 | --- | --- |
-| `accessibleLabel` | Обязательное непустое имя `region`. / Required non-empty name of the `region`. |
+| `accessibleLabel` / `accessibleLabelledby` | Ровно один источник имени: непустая строка либо exact single-space DOM IDREF-list. / Exactly one name source: non-empty text or an exact single-space DOM IDREF list. |
 | `axis` | `'x' \| 'y' \| 'both'`; default `y`. Запрещённая ось не прокручивается и недоступна API. / A disabled axis neither scrolls nor accepts API commands. |
-| `blockSize` | `'sm' \| 'md' \| 'lg' \| 'fill'`; semantic token, raw CSS length запрещён. / Semantic token; raw CSS lengths are rejected. |
+| `blockSize` | `'sm' \| 'md' \| 'lg' \| 'fill' \| 'content'`; default `md`. `content` сохраняет естественный flow. / Semantic size; `content` preserves natural flow. Raw CSS lengths are rejected. |
+| `maxBlockSize` | `'none' \| 'sm' \| 'md' \| 'lg'`; default `none`. Семантический верхний предел высоты. / Semantic maximum block size. |
+| `focusPolicy` | `'always' \| 'overflow'`; default `always`. `overflow` добавляет named region и остановку Tab только при переполнении разрешённой оси. / `overflow` adds a named region and Tab stop only during enabled-axis overflow. |
 | `focusable` | Включает root tab stop и `focus()`; default `true`. / Enables the root tab stop and `focus()`; defaults to `true`. |
 | `keyboardNavigation` | Управление корнем с клавиатуры; требует `focusable=true`. / Root keyboard control; requires `focusable=true`. |
 | `overscrollBehavior` | `'auto' \| 'contain' \| 'none'`; default `contain`. |
@@ -39,6 +41,21 @@ classes и `data-s-*` не являются selector API.
 Consumer-owned `data-*` are supported on the root region for tour and test
 hooks. Internal classes and `data-s-*` are not selector APIs.
 
+`focusable` разрешает root focus; `focusPolicy="overflow"` учитывает фактический
+scroll range только разрешённых осей. При исчезновении переполнения component
+удаляет Tab stop и named region, не перемещая существующий focus: focused root
+сохраняет `tabindex="-1"` до native blur, после которого атрибут снимается. `focus()` в
+этом состоянии завершается явной ошибкой. Содержимое таблиц использует такой
+контракт через общий canonical table owner; native table name и ElementApi
+сохраняются.
+
+`focusable` permits root focus; `focusPolicy="overflow"` checks the actual range
+of enabled axes. When overflow disappears, the component removes the Tab stop
+and named region without moving existing focus: a focused root retains
+`tabindex="-1"` until native blur removes the attribute. `focus()` fails explicitly in
+that state. Canonical table composition uses this policy while retaining the
+native table name and ElementApi.
+
 ## Состояние / State
 
 `scroll-state` эмитится после mount, прокрутки, resize viewport/content и
@@ -130,14 +147,18 @@ into view.
 
 ## Lifecycle
 
-Один `ResizeObserver` отслеживает root viewport и content owner. Passive scroll
-listener и observer освобождаются при unmount; callback после teardown не
-публикует state. Компонент не создаёт global listener и не использует polling.
+Один `ResizeObserver` отслеживает viewport, content owner и его непосредственные
+дочерние элементы. Scoped content `MutationObserver` обновляет intrinsic
+геометрию и наблюдаемый набор; capture load listener учитывает размеры ресурсов.
+Observers/listeners освобождаются при unmount; callback после teardown не
+публикует state. Global document observer/listener и polling не используются.
 
-One `ResizeObserver` tracks the root viewport and content owner. The passive
-scroll listener and observer are released on unmount, and callbacks after
-teardown publish no state. The component creates no global listener and uses no
-polling.
+One `ResizeObserver` tracks the viewport, content owner and direct content
+element children. A scoped content `MutationObserver` updates intrinsic
+geometry and the observed child set; a content capture load listener covers
+resource dimensions. Observers/listeners are released on unmount, and callbacks
+after teardown publish no state. The component creates no document-global
+observer/listener and uses no polling.
 
 ## Пример / Example
 
@@ -164,4 +185,3 @@ const position = ref<SScrollViewportState | null>(null)
   </SScrollViewport>
 </template>
 ```
-