@pgcorp/ui-kit 0.13.0 → 0.15.0

package/docs/getting-started.md

@@ -12,6 +12,22 @@ UI-kit поставляется как собранные Vue 3 ESM-модули
 Vite-based приложений. Consumer отвечает за единственные экземпляры `vue`,
 `pinia`, `@vue/devtools-api` и `vue-router`.
 
+Build-инструменты Tailwind/PostCSS объявляются прямыми dev dependencies
+приложения:
+
+```bash
+npm install -D tailwindcss@^4.3.3 @tailwindcss/postcss@^4.3.3 postcss@^8.5.28
+```
+
+`postcss.config.mjs`:
+
+```js
+export default { plugins: { '@tailwindcss/postcss': {} } }
+```
+
+Это контракт [интеграции Tailwind с PostCSS](https://tailwindcss.com/docs/installation/using-postcss).
+Зависимости UI-kit не заменяют прямые imports build-контура приложения.
+
 ### Подключение
 
 UI-kit публикует собранные component-модули и использует Tailwind 4 utilities.
@@ -29,6 +45,10 @@ UI-kit публикует собранные component-модули и испо
 source root приложения задаётся явно, сохраните его на собственном
 `@import "tailwindcss" source("…")`.
 
+Typography plugin включён в пакет как полная upstream-сборка. Отдельная
+установка `@tailwindcss/typography` и consumer overrides его зависимостей не
+требуются. Лицензии включённых модулей находятся в `dist/typography.LICENSE.txt`.
+
 ```ts
 import { createApp } from 'vue'
 import { createPinia } from 'pinia'
@@ -155,6 +175,21 @@ The UI kit is distributed as built Vue 3 ESM modules and declaration files for
 Vite-based applications. The consumer owns the single `vue`, `pinia`,
 `@vue/devtools-api`, and `vue-router` instances.
 
+Declare the application's Tailwind/PostCSS build tools as direct dev dependencies:
+
+```bash
+npm install -D tailwindcss@^4.3.3 @tailwindcss/postcss@^4.3.3 postcss@^8.5.28
+```
+
+`postcss.config.mjs`:
+
+```js
+export default { plugins: { '@tailwindcss/postcss': {} } }
+```
+
+This follows the [Tailwind PostCSS integration contract](https://tailwindcss.com/docs/installation/using-postcss).
+UI-kit dependencies do not replace direct imports owned by the application's build pipeline.
+
 ### Setup
 
 The UI kit publishes built component modules and uses Tailwind 4 utilities.
@@ -172,6 +207,10 @@ line is required and resolves relative to this CSS file. Consumers do not need
 a `reference.css` import. If the application uses an explicit source root, keep
 it on its own `@import "tailwindcss" source("…")`.
 
+The package bundles the complete upstream typography plugin. No separate
+`@tailwindcss/typography` installation or consumer dependency overrides are
+required. Included module licenses are provided in `dist/typography.LICENSE.txt`.
+
 ```ts
 import { createApp } from 'vue'
 import { createPinia } from 'pinia'

package/docs/link-download.md

@@ -0,0 +1,114 @@
+# Скачивание вложений / Attachment downloads
+
+`SButton` и `SLink` принимают `download` только вместе с `href`. В этом режиме
+activation owner — обычный `HTMLAnchorElement`. UI-kit сохраняет native default
+action для pointer click и Enter; обработчик consumer `@click` может отменить его
+через `event.preventDefault()`. Router `to` и action button отвергают `download`
+при типизации и во время работы, включая явно переданное `false`.
+
+`SButton` and `SLink` accept `download` with `href` only. The activation owner is
+a native `HTMLAnchorElement`. The kit preserves its pointer-click and Enter
+default actions; a consumer `@click` listener can cancel the action with
+`event.preventDefault()`. Router `to` and action buttons reject `download` both
+in types and at runtime, including an explicitly supplied `false`.
+
+Публичный модуль `@pgcorp/ui-kit/shared/controls/SLink` экспортирует `LinkDownload`,
+`HrefDownloadDestination` и `DownloadLinkDestination`. Они описывают capability
+`SButton/SLink`; обычный `LinkDestination` и модели menu/breadcrumb/bottom-nav
+download не принимают. Это не отдельный control и не иной activation owner.
+
+The public module `@pgcorp/ui-kit/shared/controls/SLink` exports `LinkDownload`,
+`HrefDownloadDestination`, and `DownloadLinkDestination`. These express the
+`SButton/SLink` capability; ordinary `LinkDestination` and menu/breadcrumb/bottom-nav
+models do not accept downloads. They do not introduce a separate control or
+activation owner.
+
+| Значение / Value | Native intent |
+| --- | --- |
+| `"Полное вложение — профиль.bin"` | Имя передаётся буквально / The filename is passed verbatim |
+| `true` или / or `""` | `download=""`; имя определяет браузер / The browser chooses the filename |
+| `false` или отсутствие / or omission | Атрибут отсутствует / No download attribute |
+
+`download` является рекомендацией браузеру, а не обходом его политики безопасности.
+Для cross-origin HTTP-ресурса сервер управляет `Content-Disposition: attachment`;
+server filename и ограничения файловой системы могут влиять на сохранённое имя.
+Кит не изменяет строку filename, не проверяет origin эвристиками и не обещает
+скачивание любого стороннего URL. Контракт следует
+[HTML downloading resources](https://html.spec.whatwg.org/multipage/links.html#downloading-resources).
+
+`download` expresses browser intent, not a security-policy override. For
+cross-origin HTTP resources the server controls `Content-Disposition: attachment`;
+server filenames and filesystem restrictions may affect the saved name. The kit
+does not transform the filename, infer origin policy, or guarantee downloads of
+arbitrary remote URLs. See the
+[HTML download contract](https://html.spec.whatwg.org/multipage/links.html#downloading-resources).
+
+## Полный Blob и ограниченный просмотр / Complete Blob and limited preview
+
+Consumer владеет полным `Blob`, его object URL и временем жизни. Просмотр может
+показывать часть файла; `href` для скачивания должен указывать на полный исходный
+Blob. Компоненты не читают, не сериализуют и не обрезают его содержимое.
+
+The consumer owns the complete `Blob`, its object URL, and its lifetime. A preview
+may display only part of the file; the download `href` must reference the complete
+original Blob. Neither component reads, serializes, or truncates that content.
+
+```vue
+<script setup lang="ts">
+import { onBeforeUnmount, onMounted, shallowRef } from 'vue'
+import SButton from '@pgcorp/ui-kit/shared/controls/SButton.vue'
+import SLink from '@pgcorp/ui-kit/shared/controls/SLink.vue'
+
+// One immutable attachment per mounted view; replace the view for another file.
+const { attachment, filename } = defineProps<{
+  attachment: Blob
+  filename: string
+}>()
+const attachmentUrl = shallowRef<string>()
+
+onMounted(() => {
+  attachmentUrl.value = URL.createObjectURL(attachment)
+})
+onBeforeUnmount(() => {
+  if (attachmentUrl.value !== undefined) URL.revokeObjectURL(attachmentUrl.value)
+})
+</script>
+
+<template>
+  <SButton
+    v-if="attachmentUrl"
+    :href="attachmentUrl"
+    :download="filename"
+    label="Скачать полное вложение"
+  />
+  <SLink v-if="attachmentUrl" :href="attachmentUrl" :download="filename">
+    Скачать оригинал
+  </SLink>
+</template>
+```
+
+Создание object URL находится в `onMounted`, поэтому SSR не обращается к Blob URL
+API. Ссылка остаётся действительной всё время, пока действие доступно. Не
+отзывайте URL и не уничтожайте его владельца в click listener до запуска native
+скачивания. [File API](https://w3c.github.io/FileAPI/#creating-revoking) определяет
+отзыв URL и ошибку последующего доступа к нему.
+
+Creating the URL in `onMounted` keeps Blob URL APIs out of SSR. Keep the URL alive
+while its action remains available. Do not revoke it or destroy its owner in a
+click listener before the native download starts. The
+[File API](https://w3c.github.io/FileAPI/#creating-revoking) defines revocation and
+the failure of subsequent access.
+
+## Недоступные состояния / Unavailable states
+
+`SLink.disabled` и `SButton.disabled/loading` удаляют native `href` и `download`,
+выставляют `aria-disabled` и исключают ссылку из Tab order. Они отменяют click
+default action и не эмитят `click`. Снятие состояния восстанавливает исходные
+`href` и filename. Для загрузки `SButton` также предоставляет `aria-busy` и
+собственный индикатор. Нового download callback или hidden DOM owner нет.
+
+`SLink.disabled` and `SButton.disabled/loading` remove native `href` and `download`,
+set `aria-disabled`, and remove the link from the Tab order. They cancel click
+default actions and do not emit `click`. Clearing the state restores the original
+`href` and filename. A loading `SButton` also exposes `aria-busy` and its indicator.
+There is no separate download callback or hidden DOM owner.

package/docs/listbox.md

@@ -0,0 +1,129 @@
+# SListbox: полный каталог и виртуальное окно
+
+`SListbox` владеет единым контрактом выбора, keyboard navigation и доступности.
+`SSelect` и `SCombobox` используют его как общий selection-компонент. Потребитель
+передаёт полный `options`, а не видимый срез каталога.
+
+## Типизированная виртуализация
+
+```ts
+interface SListboxVirtualization {
+  viewportHeight: number
+  estimatedItemHeight: number
+  overscan?: number
+}
+```
+
+`virtualization` необязателен. При отсутствии свойства все options находятся в
+DOM. Он поддерживается для `variant="select"`; цветовая grid-композиция требует
+другой геометрии и отвергает этот контракт.
+
+`viewportHeight` — высота viewport в CSS px. `estimatedItemHeight` — оценочная
+высота строки до измерения `ResizeObserver`. Оба значения должны быть конечными
+числами в диапазоне `[1, 100000]`. `overscan` — число дополнительных строк с каждой
+стороны окна, целое число `[0, 1000]`, штатное значение `8`. Неизвестные поля,
+`null`, отрицательные значения и несовместимый variant вызывают точную ошибку.
+
+Общий private geometry-owner используется также `SVirtualList`: stable keys,
+измеренные высоты, prefix offsets, поиск диапазона и выравнивание строки.
+`SListbox` сохраняет собственную семантику `ul`/`li`, `role="listbox"`, именованные
+группы и option leaves; `SVirtualList` сохраняет list/log и viewport lifecycle.
+
+```vue
+<SListbox
+  v-model="selectedFile"
+  :options="allFiles"
+  label="Файлы проекта"
+  :virtualization="{ viewportHeight: 240, estimatedItemHeight: 36, overscan: 4 }"
+/>
+```
+
+В DOM находится окно viewport + overscan, активная/focused option и необходимые
+подписи групп. У каждой смонтированной option `aria-posinset` и `aria-setsize`
+описывают весь каталог: clear-option входит в набор, group labels не входят.
+Смонтированная группа содержит хотя бы одну option и собственное доступное имя.
+
+## Identity, выбор и навигация
+
+`value` каждой option — уникальный непустой string или конечное number. Числовой
+`1` и строковый `'1'` являются разными ключами. Option DOM ID выводится из её
+stable typed key, а не из позиции, поэтому prepend/reorder не меняют identity.
+
+Arrow keys, Home/End, `moveActive()` и typeahead работают по полному inventory,
+включая offscreen options, и пропускают disabled. Переход монтирует и прокручивает
+целевую строку. Навигация не изменяет `modelValue`: выбор происходит через
+Enter/Space/click или `selectActive()`.
+
+`readonly` допускает навигацию, но не выбор. `disabled` блокирует оба действия.
+У disabled виртуального списка viewport остаётся доступен через Tab для обычной
+прокрутки клавишами PageUp/PageDown; focus не переходит на options и выбор
+недоступен.
+`selectionMode="multiple"` сохраняет порядок controlled выбранных ключей.
+`clearOptionLabel` доступен только в single режиме. Невалидный selected/active
+key, отсутствующий в каталоге, отвергается; kit не подменяет его другой option.
+
+## Внешний focus owner: STextarea
+
+`focusMode="activedescendant"` поддерживает single selection и требует
+`activeValue: TKey | null`. Focus остаётся в поле; options не становятся Tab stops
+и pointer selection не переносит focus из поля.
+
+Методы `initializeActive()`, `moveActive('next' | 'previous' | 'first' | 'last')`
+и `selectActive()` управляют активной option. Событие `update:activeValue`
+публикует typed key. Компонент удерживает последний requested cursor, пока
+родитель подтверждает controlled значение; последовательные действия не должны
+ждать перерисовку родителя.
+
+Clear-option имеет отдельную cursor identity: после её запроса и подтверждения
+`activeValue=null` она остаётся активной, а `selectActive()` очищает selection.
+Метод `resetActive()` снимает активный cursor и публикует `activeValue=null`,
+не выбирая clear-option и не меняя selection. Он служит явным reset-намерением,
+в том числе когда clear-option уже подтверждена значением `null`.
+Исходный `activeValue=null` без запроса clear-option означает отсутствие cursor.
+Внешнее изменение `activeValue` без ожидающего запроса применяет переданное
+controlled значение. Escape в composition вызывает `resetActive()`;
+последующие Home/End и Arrow keys продолжают навигацию по полному каталогу.
+Reset хранится в той же очереди typed запросов: запоздалое подтверждение
+предыдущей option не восстанавливает снятый cursor.
+
+`active-descendant-change(id: string | null)` сообщает DOM ID только после
+монтирования целевой option. Exposed `activeOptionId` содержит то же значение.
+При ручной прокрутке активная option остаётся смонтированной; `null` означает
+отсутствие доступной mounted active target. При уничтожении списка связь
+сбрасывается. Потребитель передаёт это событие в `STextarea.suggestions`, а не
+вычисляет ID самостоятельно.
+
+```vue
+<STextarea
+  v-model="message"
+  label="Сообщение"
+  :suggestions="{
+    controls: 'files',
+    ...(activeOptionId ? { activeDescendant: activeOptionId } : {}),
+  }"
+/>
+<SListbox
+  id="files"
+  ref="fileList"
+  v-model="selectedFile"
+  v-model:active-value="activeFile"
+  :options="allFiles"
+  label="Файлы проекта"
+  focus-mode="activedescendant"
+  :virtualization="{ viewportHeight: 240, estimatedItemHeight: 36 }"
+  @active-descendant-change="activeOptionId = $event"
+/>
+```
+
+Приложение владеет командами composer и вызывает методы списка из своего
+`STextarea` keyboard handler. Оно не перехватывает IME, обычные caret keys или
+модифицированные chords, не относящиеся к открытому suggestions-сценарию.
+Строки списка, DOM поиск и локальные стили controls не нужны.
+
+## Проверочные состояния
+
+Storybook: `VirtualCatalog`, `VirtualGrouped`, `VirtualMultiple`,
+`VirtualReadonly`, `VirtualDisabled`, `VirtualExternalFocus`. Полный каталог
+содержит 10000 options; внешняя композиция использует реальный `STextarea`.
+Browser proof проверяет narrow/dark, ARIA target lifetime, offscreen focus,
+выбор, scroll geometry, группы и accessibility.

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.