@pgcorp/ui-kit 0.12.0 → 0.14.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/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,36 @@ UI-kit-owned атрибуты `data-s-*` относятся к внутренн
 runtime-зависимости через layout конкретного package manager. Сборка использует
 `target/lib: ES2020`, совпадающий с baseline `@vue/tsconfig/tsconfig.dom.json`,
 и не требует скрытых полифиллов.
+`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 +67,17 @@ 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.
+Пассивная tooltip panel поддерживает hover без focus или Tab stop; выход из
+target и панели закрывает её через `hideDelay`. Escape отменяет pending
+`showDelay` без перехвата события у другого overlay. Blur, скрытие документа,
+disabled и освобождение target завершают activation lease и его слушатели.
 `SUiKitLocaleProvider` задаёт `en | ru | zh-CN | zh-TW` для одного Vue subtree,
 а `composables/useUiKitLocale` экспортирует readonly context, полный список
 локалей и типы messages/overrides/ключей. Provider не создаёт DOM owner и
@@ -62,12 +97,78 @@ callbacks и trust flags не входят в API.
 `sm/md/lg = 32/36/40 px` и label typography `12/14/14 px`; тот же
 `density="compact"` у `SInputText` даёт совместимую геометрию поля без
 consumer CSS.
-`SInputText.minLength` и `SInputText.maxLength` передают строгие
+`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`.
+`SModal.size="4xl"` задаёт responsive maximum `56rem`; при ошибке дочернего
+mount modal освобождает body lock, layer registration и owned teleport nodes.
+`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.
+`SPopover` сохраняет native anchor и исходного focus owner trigger-запроса до
+подтверждения controlled `open`, без перехвата последующего внешнего фокуса.
+Программный `close()` отменяет ожидающий запрос через `update:open=false`.
+Ширина `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 и доступные
+описания пунктов. 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`.
+`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` экспортирует
@@ -83,7 +184,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;
@@ -101,12 +202,36 @@ 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.
+`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
@@ -118,6 +243,17 @@ 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 hover without focus or a Tab stop; 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.
 `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
@@ -138,12 +274,80 @@ 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.
-`SInputText.minLength` and `SInputText.maxLength` pass strict non-negative safe
+`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`.
+`SModal.size="4xl"` provides a responsive `56rem` maximum; a failed child mount
+releases body lock, layer registration, and owned teleport nodes.
+`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.
+`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`.
+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. 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.
+`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