@pgcorp/ui-kit 0.12.0 → 0.14.0

package/README.md

@@ -23,6 +23,80 @@ complete workbench interfaces.**
 - Только явные package exports: wildcard и private source imports отсутствуют.
   Explicit package exports only, with no wildcards or private source imports.
 
+### Полные option-каталоги / Complete option catalogs
+
+`SListbox.virtualization` задаёт measured viewport над полным набором `options`:
+`{ viewportHeight, estimatedItemHeight, overscan? }`. Keyboard navigation, groups,
+clear, disabled и multiple selection работают по всему каталогу. Для external
+focus owner событие `active-descendant-change` передаёт ID смонтированной option
+в `STextarea.suggestions`. Полный контракт и примеры включены в пакет: `docs/listbox.md`.
+
+`SListbox.virtualization` provides a measured viewport over the complete option
+catalog. Keyboard navigation and selection use the full inventory; the
+`active-descendant-change` event supplies a mounted option ID to an external
+focus owner. The package includes the complete contract and examples in `docs/listbox.md`.
+
+### Измеряемый прогресс / Measured progress
+
+`SProgressBar` использует один numerical/accessibility owner для `shape="linear"`
+и `shape="circular"`. Линейная форма является default. Круговая форма имеет
+размеры `xs/sm/md = 24/28/32 px` и требует явный `value` от 0 до 100 в
+`mode="determinate"`. `showValue` выводит округлённое число в центре;
+`aria-valuenow` сохраняет точное значение, включая дробную часть.
+`valueText` передаёт доступное предметное описание, например tokens/limit.
+Существующий scoped default slot форматирует только linear label и получает
+точный `value`; circular label принадлежит владельцу и отклоняет default slot.
+
+`accuracy="estimated"` требует `valueText` и показывает приблизительность.
+`mode="unknown"` требует `valueText`, не принимает `value` и не сообщает
+`aria-valuenow`. Эти состояния статичны. `mode="indeterminate"` обозначает
+выполняющуюся операцию, не принимает `showValue` и учитывает reduced motion.
+`severity` управляет semantic palette, а не выводится из процента автоматически.
+
+```vue
+<SProgressBar
+  :accessibility="{ mode: 'label', label: 'Заполнение контекста' }"
+  shape="circular"
+  size="md"
+  :value="37.5"
+  value-text="37 500 из 100 000 токенов"
+  show-value
+  severity="info"
+/>
+<SProgressBar
+  :accessibility="{ mode: 'label', label: 'Заполнение контекста' }"
+  shape="circular"
+  mode="unknown"
+  value-text="Размер контекста недоступен"
+  show-value
+/>
+```
+
+Для действия показатель помещается в default slot `SButton` с
+`iconOnly`, `shape="circle"`, `size="lg"`, `density="default"` и
+`appearance="ghost"`: штатная
+контрольная область равна **48×48 px**, то есть не меньше 44 px. Внутренний
+показатель использует `accessibility.mode="decorative"`; действие, доступное
+имя с точным значением и tooltip bindings принадлежат внешней кнопке.
+Показатель не создаёт вложенный control или дополнительную остановку Tab.
+
+`SProgressBar` shares numerical and accessibility ownership across linear and
+circular shapes. Circular `xs/sm/md` sizes are 24/28/32 px. Determinate circular
+progress requires an explicit value in 0–100; central display rounds the
+percentage while `aria-valuenow` retains its exact precision. `valueText`
+supplies a domain description such as tokens/limit. Estimated progress requires
+`valueText` and a visible approximation marker. Explicit unknown progress
+requires `valueText`, rejects `value`, omits `aria-valuenow`, and remains static.
+Severity is consumer-selected rather than inferred from a percentage. The
+existing scoped default slot formats linear labels and receives the exact
+value. Circular labels are owner-controlled and reject a supplied default slot.
+
+For an actionable indicator, place decorative progress in the default slot of
+a circular `SButton` with `iconOnly`, `size="lg"`, default density, and
+`appearance="ghost"`: its target is
+48×48 px, not exactly 44 px. The inner progress is decorative; the button owns
+focus, the action, the accessible name, and tooltip bindings.
+
 ## Установка / Installation
 
 ```bash
@@ -45,6 +119,23 @@ npm install @pgcorp/ui-kit @vue/devtools-api vue pinia vue-router
 `vue`, `pinia`, `@vue/devtools-api`, and `vue-router` are peer dependencies. The consumer application
 owns their single runtime instances.
 
+Tailwind/PostCSS принадлежат build-контуру приложения и объявляются его прямыми
+dev dependencies. / Tailwind/PostCSS belong to the application's build pipeline
+and must be declared as its 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': {} } }
+```
+
+Контракт установки: [Tailwind CSS с PostCSS](https://tailwindcss.com/docs/installation/using-postcss).
+/ Setup contract: [Tailwind CSS with PostCSS](https://tailwindcss.com/docs/installation/using-postcss).
+
 ## Быстрый старт / Quick start
 
 Создайте корневой CSS entrypoint приложения. Интеграционный stylesheet подключает
@@ -177,6 +268,16 @@ link/resource/action effects возвращаются как typed intents. Link
 `current: true` выражает текущее назначение через `aria-current="page"`.
 Task lists, deletion, `keyboard`, sup/sub, disclosure и scoped footnotes имеют
 собственные serializable nodes; raw markup для этих семантик не требуется.
+Типизированный semantic profile включает hard breaks, inline/picture media,
+rich summary/header content, definitions, ruby и структурные таблицы с
+header associations, spans и footer. `STable`, `SDataGrid` и rich tables
+используют общих native table owners. Якоря и повторные сноски имеют локальный
+scope, раскрывают целевую секцию и переводят фокус без изменения истории.
+`heading.presentation: 'assistive'` сохраняет нативный уровень, содержимое,
+scoped anchors и IDREFs, визуально скрывая сам heading вне normal flow.
+Значение по умолчанию — `visible`; интерактивные потомки в assistive heading
+отклоняются с точным node path. GFM producer сохраняет скрытый heading сносок
+и его `describedBy` references, не передавая raw `class`.
 
 `SRichDocument` renders the closed, versioned `SRichDocumentV1` AST without raw
 HTML, VNodes, callbacks, or trust flags. External JSON is checked with
@@ -186,6 +287,26 @@ link/resource/action effects are emitted as typed intents. A link node with
 `current: true` exposes the current destination through `aria-current="page"`.
 Task lists, deletion, `keyboard`, sup/sub, disclosure, and scoped footnotes use
 dedicated serializable nodes; these semantics never require raw markup.
+The typed semantic profile includes hard breaks, inline/picture media, rich
+summary/header content, definitions, ruby, and structural tables with header
+associations, spans, and a footer. `STable`, `SDataGrid`, and rich tables share
+native table owners. Anchors and repeated footnotes are scoped locally, reveal
+their target disclosure, and move focus without changing browser history.
+`heading.presentation: 'assistive'` retains the native level, content, scoped
+anchors, and IDREFs while placing the heading outside normal flow. The default
+is `visible`; interactive descendants fail at their exact node path. A GFM
+producer preserves its hidden footnote heading and description references
+without passing raw classes.
+
+`SCheckbox presentation="inline"` и `SField contentFlow="phrasing"` сохраняют
+phrasing content model внутри текста. `SLink` предоставляет actual native
+`getElement()`/`focus()` и semantic props `domId`, `language`, `direction`,
+`ariaLabel`, `ariaLabelledby`, `ariaDescribedby`; IDREFs задаются непустыми DOM
+идентификаторами через один ASCII-пробел без автоматического исправления ввода.
+/ `SCheckbox presentation="inline"` and `SField contentFlow="phrasing"` preserve
+the phrasing content model inside text. `SLink` exposes the actual native
+`getElement()`/`focus()` and the semantic props listed above; IDREFs are explicit
+non-empty DOM identities separated by one ASCII space, without input repair.
 
 ```ts
 import SRichDocument from '@pgcorp/ui-kit/shared/data-display/SRichDocument.vue'
@@ -521,7 +642,124 @@ reserved for runtime catalog values and intentionally includes the complete
 registry.
 
 ```ts
-import { Bell, Cable, GitCompare, PanelLeftOpen } from '@pgcorp/ui-kit/icons'
+import {
+  ArrowUpRight, Bell, Cable, CalendarDays, Disc, GitCompare, GitFork,
+  ChevronLeft, HardDrive, PanelLeftOpen, Paperclip, Pause, Radio, RotateCw, Usb, Volume2, Zap, ZoomIn, ZoomOut,
+} from '@pgcorp/ui-kit/icons'
+```
+
+`HardDrive`, `Usb` и `Disc` обозначают локальный накопитель, USB-подключение
+и оптический диск; `CalendarDays` — дату, `ArrowUpRight` — переход или открытие.
+`Paperclip` обозначает прикрепление файла, `GitFork` — разветвление разговора;
+`ZoomIn`/`ZoomOut` — изменение масштаба изображения, `RotateCw` — поворот по
+часовой стрелке, `Volume2` — аудио. Поворот против часовой стрелки представлен
+отдельным `RotateCcw`, а не alias для `RotateCw`.
+`Radio` обозначает сетевое вещание или фоновое уведомление, не radio input.
+`Pause` обозначает состояние паузы задачи; `ChevronLeft` — переход влево.
+`Zap` обозначает молнию и подходит для роли быстрой модели. Это primary-only
+силуэт: duotone сохраняет одну цветовую роль, без дополнительного accent.
+Все используют общий icon contract: `iconSetMode` (`classic`, `sputnig`),
+`colorMode` (`auto`, `duotone`, `monochrome`), тему и tree-shakeable ESM exports.
+Внутри control иконка передаётся через его icon slot; размер и состояние
+задаёт control owner.
+
+`HardDrive`, `Usb`, and `Disc` represent a local drive, a USB connection, and
+an optical disc; `CalendarDays` represents a date, and `ArrowUpRight` represents
+navigation or opening. All share the icon contract: `iconSetMode` (`classic`, `sputnig`),
+`colorMode` (`auto`, `duotone`, `monochrome`), theme support, and tree-shakeable ESM
+exports. Pass an icon through a control's icon slot; the control owner defines
+its size and state.
+
+`Paperclip` represents file attachment and `GitFork` conversation branching.
+`ZoomIn`/`ZoomOut` represent image zoom, `RotateCw` clockwise rotation, and
+`Volume2` audio. Counterclockwise rotation has a distinct `RotateCcw` export;
+the two rotation actions are not aliases.
+`Radio` represents network broadcast or a background notification, not a radio input.
+`Pause` represents a paused task; `ChevronLeft` represents leftward navigation.
+`Zap` represents a lightning bolt and can identify the fast-model role. Its
+primary-only silhouette retains one color role in duotone, without an accent shape.
+
+```vue
+<SButton label="Выбрать локальный накопитель">
+  <template #leading-icon><HardDrive /></template>
+</SButton>
+```
+
+### Скачивание через ссылку / Native link downloads
+
+`SButton` и `SLink` поддерживают typed `download?: string | boolean` только в
+`href`-режиме. Filename передаётся native anchor буквально; `true`/`""` оставляют
+выбор имени браузеру, `false` не создаёт download attribute. Router `to` и action
+button не принимают этот prop. Consumer владеет полным Blob и object URL;
+ограниченный preview не становится источником скачивания. `SLink.disabled` и
+`SButton.disabled/loading` блокируют activation и удаляют `href`/`download`.
+
+`SButton` and `SLink` support typed `download?: string | boolean` in `href` mode
+only. The filename is passed verbatim to the native anchor; `true`/`""` let the
+browser choose it, and `false` omits the attribute. Router `to` and action buttons
+reject this prop. The consumer owns the complete Blob and its object URL; a
+limited preview is not the download source. `SLink.disabled` and
+`SButton.disabled/loading` block activation and remove `href`/`download`.
+
+Контракт, Blob lifecycle и ограничения браузера включены в пакет: `docs/link-download.md`.
+The package includes the contract, Blob lifecycle, and browser limitations in `docs/link-download.md`.
+
+### Подсказка на интерактивной поверхности / Tooltip on an interactive surface
+
+`SInteractiveSurface` принимает полный combined `trigger` от `STooltip` через
+prop `tooltipTrigger`. Binding относится к primary activation owner: кнопке
+для `surface.mode="action"` или ссылке для `surface.mode="link"`.
+Link surface принимает ровно один target: `href` либо Vue Router `to`.
+Для `to` приложение подключает Vue Router. `accessibleLabel` обязателен
+в обоих интерактивных режимах; static surface не принимает tooltip binding.
+Подсказка открывается по pointer/focus и закрывается через Escape.
+Дополнительные controls передаются в `#actions` и сохраняют собственные
+focus и activation независимо от primary owner.
+
+`showDelay` задаёт задержку открытия (120 мс), `hideDelay` — закрытия после
+выхода указателя и фокуса (80 мс). Указатель может переходить с target на
+пассивную панель подсказки: она остаётся видимой, не получает focus и не
+добавляет Tab stop. Escape закрывает открытую панель и отменяет pending
+открытие; pending-подсказка не забирает событие у меню или диалога.
+Blur окна, скрытие документа, disabled и освобождение target отменяют
+таймеры и слушатели. Новый вход указателя или получение фокуса открывает
+подсказку по действующему `showDelay`.
+
+`SInteractiveSurface` accepts the complete combined `STooltip` trigger through
+the `tooltipTrigger` prop. The binding belongs to the primary activation owner:
+a button for `surface.mode="action"` or a link for `surface.mode="link"`.
+A link surface accepts exactly one target: `href` or Vue Router `to`.
+The application installs Vue Router when using `to`. `accessibleLabel` is
+required in both interactive modes; a static surface rejects a tooltip binding.
+The tooltip opens on pointer/focus and closes with Escape. Additional controls
+use `#actions` and retain independent focus and activation.
+
+`showDelay` controls the opening delay (120ms); `hideDelay` controls closing
+after pointer hover and focus leave (80ms). The pointer can move from the
+target onto the passive tooltip panel: it remains visible, receives no focus,
+and adds no Tab stop. Escape closes the visible panel or cancels a pending
+opening; a pending tooltip does not consume the event from a menu or dialog.
+Window blur, a hidden document, disabled state, and released target identity
+cancel timers and listeners. Fresh pointer entry or acquired focus opens the
+tooltip according to its current `showDelay`.
+
+```vue
+<STooltip text="/workspace/repository" v-slot="{ trigger }">
+  <SInteractiveSurface
+    :surface="{
+      mode: 'link',
+      to: '/projects/repository',
+      accessibleLabel: 'Открыть проект',
+    }"
+    :tooltip-trigger="trigger"
+    actions-layout="responsive"
+  >
+    Проект Repository
+    <template #actions>
+      <SButton label="Параметры проекта" size="sm" />
+    </template>
+  </SInteractiveSurface>
+</STooltip>
 ```
 
 ### Подсказка на части действия / Tooltip for part of an action
@@ -567,6 +805,81 @@ the multiline textbox with a consumer-owned popup without private attributes.
 The textarea keeps its native role; `role="combobox"` is not assigned to this
 HTML element. Pixel bounds belong to the auto-resize contract.
 
+Слоты `empty-content` и `helper-content` располагаются обычным потоком внутри
+единой field surface. `empty-content` доступен при пустом тексте вне IME
+composition; native input скрывает его до подтверждения `v-model` родителем.
+`helper-content` не зависит от значения. Оба слота получают
+`STextareaContentContext`: `empty`, `disabled`, `readonly`, `invalid`, `composing`,
+`hasMultipleVisualLines` и `focus()`. Действия в слотах создаются через UI-kit controls; их доступность
+задаётся через `disabled`/`readonly` контекста. `focus()` возвращает фокус
+native textarea без изменения selection. `helpText` и `errorMessage` сохраняют
+свой supporting-text contract снаружи surface.
+
+При наличии content slots `minHeight`/`maxHeight` ограничивают всю surface:
+textarea, supporting regions, интервалы и внутренние поля. Редактор сохраняет
+место минимум для одной строки; длинный helper прокручивается в своей in-flow
+области, а его keyboard actions доступны Tab. Конфигурация, в которой
+`maxHeight` не вмещает editable line и обязательный surface chrome, отклоняется
+с `RangeError`. `rows` задаёт исходную высоту редактора, `maxRows` ограничивает
+редактируемые строки с учётом присутствующего supporting content. Content slots
+не требуют абсолютного позиционирования, consumer padding или дополнительного
+resize handler. Изменение естественной высоты slot-контента автоматически
+увеличивает или уменьшает surface в заданных пределах; самостоятельно
+обновляемые дочерние компоненты наблюдаются тем же resize owner.
+
+The `empty-content` and `helper-content` slots participate in normal flow inside
+the shared field surface. Empty content is visible only for an empty editor
+outside IME composition; native input hides it before a delayed parent model
+acknowledgement. Helper content is independent of the value. Both slots receive
+`STextareaContentContext` with editing-state flags and the native `focus()`
+method. Pixel bounds include the whole surface and preserve at least one
+editable line; oversized supporting content has its own bounded scroll region.
+Intrinsic slot-content changes automatically grow or shrink the surface within
+its bounds, including independently updated child components. Use UI-kit
+controls for slot actions, without consumer overlays, padding or resize calls.
+
+`hasMultipleVisualLines` описывает native текст с учётом переносов по текущей
+ширине: `false` — одна визуальная строка, `true` — несколько. `null` означает
+недоступную геометрию: SSR, скрытый editor или нулевую ширину. Пустое значение
+при доступной геометрии занимает одну строку; placeholder не определяет это
+состояние. Измерение обновляется для fixed и auto-resize полей, native ввода до
+подтверждения controlled модели, изменений ширины и типографики. Consumer
+задаёт политику показа helper через slot context, без доступа к private DOM:
+
+`hasMultipleVisualLines` describes native text wrapping at the current editor
+width: `false` is one visual line, `true` is multiple lines, and `null` denotes
+unavailable layout during SSR, hidden rendering or zero width. An empty value
+has one editable line once layout is available; placeholder text does not
+determine this state. Fixed and auto-resizing editors update the state for
+native input, delayed model acknowledgement, width and typography changes.
+Helper visibility is an explicit consumer policy expressed through slot state:
+
+```vue
+<STextarea v-model="message" label="Сообщение" :rows="1" auto-resize :min-height="64" :max-height="240">
+  <template #helper-content="{ hasMultipleVisualLines, composing, disabled, focus }">
+    <SButton
+      v-if="hasMultipleVisualLines === false && !composing && !disabled"
+      label="Справка по вводу"
+      size="sm"
+      appearance="text"
+      @click="focus()"
+    />
+  </template>
+</STextarea>
+```
+
+`minLength` и `maxLength` используют тот же строгий native contract, что и
+`SInputText`: принимают неотрицательные safe integers и требуют
+`minLength <= maxLength`. Ограничение применяется к пользовательскому вводу;
+controlled значение не усекается, поэтому серверный текст остаётся видимым и
+может быть исправлен явно.
+
+`minLength` and `maxLength` use the same strict native contract as
+`SInputText`: values are non-negative safe integers and require
+`minLength <= maxLength`. The limit applies to user input; the controlled value
+is never truncated, so server-provided text remains visible for explicit
+correction.
+
 ```vue
 <STextarea
   ref="composer"
@@ -575,6 +888,7 @@ HTML element. Pixel bounds belong to the auto-resize contract.
   :auto-resize="true"
   :min-height="64"
   :max-height="240"
+  :max-length="512"
   :suggestions="{
     controls: 'mention-listbox',
     activeDescendant: activeMentionId,
@@ -584,7 +898,128 @@ HTML element. Pixel bounds belong to the auto-resize contract.
   @focus="handleFocus"
   @blur="handleBlur"
   @paste="handlePaste"
-/>
+>
+  <template #empty-content="{ disabled, readonly, focus }">
+    <SButton
+      label="Прикрепить файл"
+      size="sm"
+      appearance="text"
+      :disabled="disabled || readonly"
+      @click="selectAttachment(); focus()"
+    />
+  </template>
+  <template #helper-content="{ focus }">
+    <SButton label="Справка по вводу" size="sm" appearance="text" @click="openInputHelp(); focus()" />
+  </template>
+</STextarea>
+```
+
+Контекстное меню native textarea подключается через
+`SContextMenu` slot `textInputTriggerProps`. Он содержит `aria-haspopup="menu"`,
+`aria-controls` смонтированного открытого меню и `onKeydown` для ContextMenu/Shift+F10. Фокус, ввод и
+selection принадлежат `STextarea`; меню владеет pointer/keyboard activation,
+позиционированием, Escape и возвратом фокуса. ArrowUp/Down сохраняют native
+редактирование. IME composition и отменённое keydown не открывают меню.
+Для действий-кнопок используется отдельный `triggerProps` с
+`aria-expanded`: [WAI-ARIA textbox](https://www.w3.org/TR/wai-aria-1.2/#textbox)
+этого состояния не поддерживает. Raw button-oriented `triggerProps` не
+передаётся в textarea, её HTML-роль не заменяется.
+
+`triggerProps` открывает контекстное меню через ContextMenu и Shift+F10;
+при `trigger="click"` или `"both"` также доступны ArrowDown/ArrowUp.
+Событие компонента `before-open` синхронно передаёт исходный
+`SContextMenuBeforeOpenEvent = MouseEvent | KeyboardEvent` до перехвата native
+действия, монтажа меню и перемещения фокуса. Обработчик сохраняет точный текст
+выделения и обновляет реактивный `items`. `event.preventDefault()` отменяет
+открытие. Меню применяет текущий список после Vue commit; consumer не вызывает
+`nextTick`, таймер или повторное событие. Отменённое событие, `enabled=false`
+и IME composition не запускают подготовку и не открывают меню. Неактивная
+граница сохраняет native propagation.
+
+Подготовленный запрос принадлежит конкретной boundary и вызывающему элементу.
+Повторная активация заменяет его; отключение, удаление вызывающего элемента
+или boundary, unmount и Escape во время подготовки отменяют его без позднего
+открытия и захвата фокуса. Вложенные активные boundaries обрабатывают событие
+только в ближайшем владельце. Позиционирование, выбор действия, Escape и
+возврат фокуса принадлежат общему menu owner.
+
+Полный `triggerProps` предназначен для кнопки-триггера. Пассивная область
+`role="group"` получает только поддерживаемую её семантикой `aria-controls`.
+Этот атрибут присутствует только при открытом смонтированном меню;
+`aria-expanded` и `aria-haspopup` кнопки группе не передаются. Boundary кита
+делегирует ContextMenu/Shift+F10 от реально сфокусированного потомка, сохраняя
+его владельцем фокуса. Обычные клавиши редактирования не перехватываются.
+Consumer не добавляет группе native contextmenu/keydown handlers и не меняет
+роль ради открытия меню.
+
+```vue
+<SContextMenu
+  :items="selectionActions"
+  boundary-layout="contents"
+  v-slot="{ triggerProps }"
+  @before-open="captureSelection"
+>
+  <div
+    role="group"
+    aria-label="Действия с выделенным текстом"
+    tabindex="0"
+    :aria-controls="triggerProps['aria-controls']"
+  >
+    <slot />
+  </div>
+</SContextMenu>
+```
+
+```ts
+import type { SContextMenuBeforeOpenEvent } from '@pgcorp/ui-kit/shared/controls/SContextMenu.vue'
+
+function captureSelection(event: SContextMenuBeforeOpenEvent): void {
+  const selection = window.getSelection()
+  if (!selection) throw new Error('Native selection is unavailable')
+  selectedText.value = selection.toString()
+  if (!selectedText.value) event.preventDefault()
+}
+```
+
+The synchronous `before-open` component event receives the original admitted
+`MouseEvent | KeyboardEvent` before interception, mounting or menu focus.
+Update reactive items in that handler; `preventDefault()` cancels opening.
+The kit commits current items and owns initial focus, dismissal and request
+cleanup. Disabled, already-cancelled and composing events do not prepare a menu.
+Passive groups bind only the optional mounted-menu `aria-controls` relationship;
+the kit boundary delegates ContextMenu/Shift+F10 from the actual focused
+descendant. No native consumer listeners, fabricated button role or timer are
+required. Full `triggerProps` belongs to a button; `textInputTriggerProps`
+preserves native textbox editing and selection semantics.
+
+При сочетании menu и suggestions `suggestions.active` явно выбирает участие
+suggestion popup; default — `true`. Активные suggestions задают
+`aria-haspopup`, `aria-autocomplete` и `aria-activedescendant`. При
+`active=false` `activeDescendant` запрещён, `aria-haspopup` принадлежит
+внешнему context-menu owner. `aria-controls` объединяет проверенные canonical
+ID обоих owners без потери связи. Native `aria-controls` принимает один DOM ID
+внешнего popup; `suggestions.controls` — один DOM ID suggestion popup.
+Кит не определяет активность по DOM, не меняет ID и не создаёт focusable wrapper.
+
+The `textInputTriggerProps` slot binds a context menu to the native textarea
+without button-only `aria-expanded` or arrow-key menu activation. ContextMenu
+and Shift+F10 use the shared menu owner; Escape restores the editing owner's
+focus and selection. `suggestions.active` explicitly selects the suggestion
+popup's ARIA participation, while validated control references are merged.
+
+```vue
+<SContextMenu :items="editingActions" v-slot="{ textInputTriggerProps }">
+  <STextarea
+    v-model="message"
+    v-bind="textInputTriggerProps"
+    label="Сообщение"
+    :suggestions="{
+      controls: 'mention-listbox',
+      active: suggestionsVisible,
+      ...(suggestionsVisible && activeMentionId ? { activeDescendant: activeMentionId } : {}),
+    }"
+  />
+</SContextMenu>
 ```
 
 ```ts
@@ -601,6 +1036,8 @@ function handleFocus(event: FocusEvent): void {
 }
 
 composer.value?.setSelection({ start, end, direction: 'forward' })
+composer.value?.selectAll()
+composer.value?.selectAll(false)
 composer.value?.replaceSelection('@file README.md')
 ```
 
@@ -616,6 +1053,26 @@ IME composition fails with an explicit diagnostic. The `selection-change`,
 `compositionstart`, `compositionupdate`, `compositionend`, and `state-change`
 events synchronize a popup without reading internal DOM.
 
+`selectAll(focusOwner?: boolean): void` выделяет весь текущий native API value
+вперёд через общий selection owner. По умолчанию запрашивается focus;
+`false` сохраняет внешний focus. Readonly-текст доступен для выделения;
+disabled и detached элементы соблюдают native eligibility фокуса.
+Метод использует длину текущего `textarea.value`, включая ввод до подтверждения
+controlled model, и не изменяет исходные CRLF/Unicode bytes, model или input
+history. HTML API value исключает CR; consumer не переписывает source и не
+считает native offsets через `source.length`. Unmounted/disposed owner и
+неboolean focus policy дают явную ошибку.
+
+`selectAll(focusOwner?: boolean): void` selects the complete current native
+API value forward through the shared selection owner. It requests focus by
+default; `false` preserves external focus. Readonly text remains selectable;
+disabled and detached elements follow native focus eligibility.
+The method uses the current `textarea.value.length`, including edits awaiting
+controlled-model acknowledgement, and does not change the source CRLF/Unicode
+bytes, model, or input history. The HTML API value excludes CR; consumers do not
+rewrite the source or calculate native offsets from `source.length`.
+An unmounted/disposed owner or non-boolean focus policy throws an explicit error.
+
 ### Карточки и строки выбора / Choice cards and rows
 
 `SChoiceCards` использует `appearance="cards"` для крупных плиток и
@@ -708,17 +1165,113 @@ contract applies only to textual types: `text`, `search`, `password`, `email`,
 
 ### Drawer placement
 
-`SDrawer` использует `placement="right"` по умолчанию. Нижняя панель задаётся
-`placement="bottom"`; semantic sizes соответствуют 50, 70 и 90 процентам
-dynamic viewport height. Body остаётся единственным scroll owner, а overlay,
-focus trap/restore, Escape, backdrop и nested layer stack совпадают с боковой
-панелью.
+`SDrawer.placement` принимает `left | right | bottom`, по умолчанию — `right`.
+`left` и `right` обозначают физическую сторону независимо от направления текста.
+Боковые панели используют общую шкалу `sm/md/lg`: максимальная ширина
+`30/36/44rem`, ограниченная viewport. При `scope="viewport"` нижняя панель
+`placement="bottom"` занимает `50/70/90` процентов dynamic viewport height.
+`mobileFullScreen` задаёт полноширинную боковую viewport-панель на узком экране;
+размещение, header/body/footer и доступность действий сохраняются.
+При `scrollBehavior="body"` body — единственный scroll owner. Все размещения
+используют общие viewport overlay, focus trap/restore, Escape, backdrop и nested
+layer stack.
+
+`SDrawer.placement` accepts `left | right | bottom`, defaulting to `right`.
+`left` and `right` are physical sides independent of text direction. Side
+drawers share the `sm/md/lg` scale: viewport-bounded maximum widths of
+`30/36/44rem`. With `scope="viewport"`, a `placement="bottom"` sheet occupies
+`50/70/90` percent of the dynamic viewport height. `mobileFullScreen` provides
+a full-width side viewport drawer on a narrow screen while preserving its
+placement, header/body/footer and reachable actions. With
+`scrollBehavior="body"`, the body is the sole scroll owner. All placements
+share viewport overlay, focus trap/restore, Escape, backdrop and the nested
+layer stack.
+
+`scope="contained"` требует ближайший `SOverlayHost`. Его default-слот содержит
+основную историю, `#overlay` — панель. Размеры `sm/md/lg` означают 50/70/90%
+доступной области по оси `placement`; `extent` принимает конечный процент больше
+0 и не больше 100. Для `left/right` это ширина host, для `bottom` — высота.
+`extent` применим только к contained-режиму. Размеры host
+принадлежат композиции страницы; размер и оформление панели принадлежат киту.
+`mobileFullScreen` не переводит contained-панель за границы host.
+`scope` меняется только при `open=false`; переход между владельцами не переносит
+открытый overlay lifetime.
+
+Contained drawer — немодальный `dialog`: composer и terminal вне host остаются
+доступны, global body lock и собственный Tab trap отсутствуют. Основное
+содержимое host имеет `inert` на время открытой панели и сохраняет DOM/прокрутку.
+Нативный диапазон выделения сохраняет text owner и координаты; видимое выделение
+следует браузерному `inert`-контракту и доступно после закрытия панели.
+Escape и нажатие backdrop обрабатываются внутри host; внешний ввод не закрывает
+панель и не получает отложенный возврат чужого фокуса. Вложенный `SModal`
+использует общий stack, глобальную модальность и свой focus trap.
+
+`scrollBehavior="body"` оставляет padded body единственным scroll owner.
+`scrollBehavior="content"` предоставляет растягиваемый слот без полей и второго
+скролла для `SVirtualList` или `SScrollViewport block-size="fill"`.
+Consumer обрабатывает `update:open`, в том числе при retirement host. Удаление,
+замена или ошибка host завершают его слои и pending focus/`opened`; повторное
+открытие — явный переход `open=false` → `true`. Новый host с новым drawer и
+`open=true` является новым запросом, а не продолжением предыдущего lifetime.
+
+`scope="contained"` requires the nearest `SOverlayHost`. Its default slot owns
+the main history, and `#overlay` owns the drawer. Sizes `sm/md/lg` mean
+50/70/90% of the available host extent along the placement axis; `extent` is a
+finite percentage greater than 0 and at most 100, valid only for contained
+drawers. The axis is host width for `left/right` and host height for `bottom`.
+Page composition owns host dimensions; the kit owns drawer geometry
+and presentation. `mobileFullScreen` does not move a contained drawer outside
+its host.
+`scope` changes only while `open=false`; changing owners does not transfer an
+open overlay lifetime.
+
+A contained drawer is a nonmodal dialog: external composer/terminal remain
+available, without global body locking or its own Tab trap. Host background
+content is inert while the drawer is open and retains its DOM/scroll position.
+Native selection ranges retain their text owner and offsets; visible selection
+follows the browser's inert contract and is available after the drawer closes.
+Escape and backdrop dismissal are host-scoped; external input neither closes
+the drawer nor receives a stale focus restoration. A nested `SModal` uses the
+same layer stack with global modality and its own focus trap.
+
+`scrollBehavior="body"` provides the padded body scroll owner.
+`scrollBehavior="content"` provides a stretching slot without padding or a
+second scroll container for `SVirtualList` or `SScrollViewport block-size="fill"`.
+The consumer handles `update:open`, including host retirement. Host removal,
+replacement, or failure retires its layers and pending focus/`opened`; reopen
+requires an explicit `open=false` → `true` transition. A new host and a new
+drawer with `open=true` represent a new request, not the previous lifetime.
+
+```vue
+<SDrawer
+  v-model:open="navigationOpen"
+  title="Проекты и чаты"
+  placement="left"
+  size="md"
+>
+  <ProjectChatNavigation />
+</SDrawer>
+```
 
-`SDrawer` uses `placement="right"` by default. Set `placement="bottom"` for a
-bottom sheet; semantic sizes map to 50, 70, and 90 percent of the dynamic
-viewport height. The body remains the sole scroll owner, while overlay,
-focus trap/restore, Escape, backdrop, and the nested layer stack are shared
-with the side drawer.
+```vue
+<SOverlayHost>
+  <ConversationHistory />
+  <template #overlay>
+    <SDrawer
+      v-model:open="historyOpen"
+      title="История подагента"
+      scope="contained"
+      placement="bottom"
+      size="lg"
+      scroll-behavior="content"
+    >
+      <VirtualSubagentHistory />
+    </SDrawer>
+  </template>
+</SOverlayHost>
+<Composer />
+<Terminal />
+```
 
 ```vue
 <SDrawer
@@ -758,6 +1311,110 @@ is required.
 </SDrawer>
 ```
 
+`SModal.size="4xl"` задаёт semantic maximum `56rem` между `3xl` (`48rem`) и
+`wide` (`72rem`) для журналов, shell output и широких форм. Surface остаётся
+responsive и сжимается до доступной ширины viewport. Если дочерний mount
+завершается ошибкой, modal освобождает body lock, layer registration и свои
+teleport nodes до передачи ошибки host-приложению.
+
+`SModal.size="4xl"` provides a semantic `56rem` maximum between `3xl` (`48rem`)
+and `wide` (`72rem`) for logs, shell output, and wide forms. The surface remains
+responsive and shrinks to the available viewport. If a child mount fails, the
+modal releases its body lock, layer registration, and owned teleport nodes
+before the error reaches the host application.
+
+### Управляемое открытие popover / Controlled popover opening
+
+`SPopover` поддерживает `v-model:open` и программные `open(triggerId?)`/`close()`.
+Запрос от trigger сохраняет его native anchor и исходный focus owner до
+подтверждения `open`, включая отложенное применение prop. Если фокус переведён
+во внешний редактор, появление панели не перехватывает его. Открытие напрямую
+через prop использует текущий focus owner. `close()` отменяет ожидающий запрос
+через `update:open=false`; закрытие восстанавливает фокус только из принадлежащей
+панели, не из внешнего поля. Каждый новый цикл использует актуального invoker.
+
+`SPopover` supports `v-model:open` and the programmatic `open(triggerId?)`/`close()`
+API. A trigger request preserves its native anchor and original focus owner
+through acknowledgement, including delayed prop application. A panel does not
+take focus from an external editor focused in the meantime. Direct prop-driven
+opening uses the current focus owner. `close()` cancels a pending request with
+`update:open=false`; closing restores focus only from the owned panel, not an
+external field. Each new cycle uses its current invoker.
+
+`width="trigger"` задаёт минимальную ширину anchor; `content` сохраняет
+intrinsic-ширину содержимого. `sm`, `md`, `lg` задают `20rem`, `28rem`, `36rem`
+с viewport-ограничением. Фон, тень и focus surface занимают полный dialog;
+`surface="transparent"` задаёт максимальную ширину всего dialog `90vw`;
+при `width="trigger"` минимальная ширина anchor имеет приоритет над этим максимумом.
+
+`width="trigger"` sets the anchor's minimum width; `content` keeps the content's
+intrinsic width. `sm`, `md`, and `lg` specify `20rem`, `28rem`, and `36rem`,
+bounded by the viewport. Background, shadow, and focus surface occupy the full
+dialog; `surface="transparent"` sets the entire dialog's maximum width to `90vw`.
+With `width="trigger"`, the anchor minimum takes precedence over this maximum.
+
+### Управляемое dropdown menu / Controlled dropdown menu
+
+`SDropdownMenu` поддерживает controlled `v-model:open`, начальное
+`defaultOpen`, размещение `auto | bottom | top` и `closeOnSelect`. Событие
+`select` публикуется до запроса закрытия; при `closeOnSelect=false` menu остаётся
+открытым для асинхронных операций и повторного выбора. `kind="group"` создаёт
+семантическую группу с видимой меткой, а `description` добавляет пункту
+доступное пояснение через `aria-describedby` без дополнительной tab stop.
+
+`SDropdownMenu` supports controlled `v-model:open`, initial `defaultOpen`,
+`auto | bottom | top` placement, and `closeOnSelect`. The `select` event is
+published before the close request; `closeOnSelect=false` keeps the menu open
+for asynchronous operations and repeated selection. `kind="group"` creates a
+semantic group with a visible label, while `description` adds an accessible
+item hint through `aria-describedby` without another tab stop.
+
+Dropdown, контекстные и вложенные меню автоматически ограничиваются доступной
+областью viewport. `placement` задаёт предпочтительную сторону; collision
+handling допускает переход на другую сторону. Полный список пунктов сохраняется,
+а высокий список прокручивается внутри menu surface с единым chrome и scroll
+owner. Высота учитывает размеры viewport и содержимого; consumer не задаёт
+`max-height` и не переоформляет внутренности меню. Arrow/Home/End раскрывают
+сфокусированный пункт в этом viewport без прокрутки фонового документа.
+Внутренняя прокрутка сохраняет открытое меню и его родительский layer.
+Home/End повторно раскрывают текущую строку после ручной прокрутки. Если ни одна
+inline-сторона не вмещает вложенную menu surface, общий collision owner выбирает
+доступную верхнюю или нижнюю сторону.
+Escape закрывает текущий уровень и возвращает фокус его trigger.
+
+Dropdown, context, and nested menus are automatically bounded by the available
+viewport. `placement` specifies the preferred side; collision handling can
+choose the opposite side. The complete item inventory is retained, while a
+tall list scrolls inside the menu surface with one chrome and scroll owner.
+Its height follows the viewport and content dimensions; consumers do not set
+`max-height` or restyle menu internals. Arrow/Home/End reveal the focused item
+inside this viewport without scrolling the background document. Internal
+scrolling preserves the open menu and its parent layer. Home/End reveal the
+current row after manual scrolling. If neither inline side can fit a submenu
+surface, the shared collision owner selects the available top or bottom side.
+Escape closes the current level and returns focus to its trigger.
+
+```vue
+<SDropdownMenu
+  v-model:open="workspaceMenuOpen"
+  :items="workspaceGroups"
+  placement="top"
+  :close-on-select="false"
+  menu-label="Ветки и рабочие папки"
+  @select="switchWorkspace"
+/>
+```
+
+### Плотность сворачиваемой панели / Collapsible panel density
+
+`SCollapsiblePanel.density="compact"` и `density="dense"` используют compact
+`SButton` disclosure hitbox высотой `32px`; `comfortable` сохраняет стандартную
+геометрию. Consumer не задаёт высоту, padding или внутренние selectors.
+
+`SCollapsiblePanel.density="compact"` and `density="dense"` use the compact
+`SButton` disclosure hitbox at `32px`; `comfortable` retains the default
+geometry. Consumers do not set height, padding, or internal selectors.
+
 ### Dialog open lifecycle
 
 `SModal` и `SDrawer` эмитят `opened` один раз для каждого подтверждённого цикла
@@ -775,12 +1432,28 @@ cancels the event; Escape, focus trapping, and focus restoration remain owned
 by the dialog surface.
 
 ```vue
-<SModal v-model:open="open" title="Исходный текст" @opened="selectAll">
+<SModal v-model:open="open" title="Исходный текст" @opened="textarea?.selectAll()">
   <STextarea ref="textarea" :model-value="source" label="Текст" readonly />
 </SModal>
 ```
 
-### Assistive live status
+### Status presentation and assistive announcements
+
+Видимый `SStatus` использует общую feedback-пару `tone`; `neutral` соответствует
+нейтральной `secondary`-паре. `appearance="soft"` владеет своим непрозрачным
+фоном и foreground. Текстовый статус внутри пассивного slot `SButton` использует
+foreground интерактивного владельца, включая solid, hover, active и focus;
+`tone`, текст и семантическая иконка сохраняются. `SCollapsiblePanel.summaryStatus`
+использует этот же контракт в compact/dense заголовке. Локальные color overrides
+для вложенных статусов не требуются.
+
+Visible `SStatus` uses the shared feedback `tone` pair; `neutral` maps to the
+neutral `secondary` pair. `appearance="soft"` owns its opaque background and
+foreground. A text status in an `SButton` passive slot uses the interactive
+owner's foreground across solid, hover, active, and focus states; `tone`, its
+label, and the semantic icon are preserved. `SCollapsiblePanel.summaryStatus`
+uses the same contract in compact/dense headers. Nested statuses require no
+local color overrides.
 
 `SStatus` с `visibility="assistive"` выводит всю status surface из layout,
 сохраняя текст сообщения в accessibility tree. `live="polite"` или
@@ -837,7 +1510,7 @@ snapshot can move between instances or be retained while switching chats.
   @viewport-change="viewport = $event"
 >
   <template #header>
-    <SButton variant="ghost" @click="loadPreviousPage">
+    <SButton appearance="ghost" @click="loadPreviousPage">
       Загрузить предыдущие
     </SButton>
   </template>
@@ -851,10 +1524,13 @@ snapshot can move between instances or be retained while switching chats.
 ```
 
 ```ts
-const snapshot = history.value?.captureViewport()
-await history.value?.restoreViewport(snapshot)
-history.value?.scrollToKey(messageId, 'center')
-history.value?.scrollToEnd({ follow: true })
+const historyOwner = history.value
+if (historyOwner) {
+  const snapshot = historyOwner.captureViewport()
+  await historyOwner.restoreViewport(snapshot)
+  historyOwner.scrollToKey(messageId, 'center')
+  historyOwner.scrollToEnd({ follow: true })
+}
 ```
 
 `viewport-change` сообщает keyed anchor, visible range, `nearStart`, `atEnd` и
@@ -866,6 +1542,11 @@ Paging, status и end-marker рендерятся через `header`/`footer`,
 синтетические элементы domain-списка. Home, End, Page и Arrow keys владеют
 viewport navigation только при focus самого `SVirtualList`; вложенный
 editable/control сохраняет свою keyboard-семантику.
+Строка с фактическим DOM-фокусом сохраняет keyed DOM identity при изменении
+измерений, viewport и rendered range. Вложенный редактор сохраняет focus и
+selection без программного перевода фокуса. Lease удерживает только одну
+дополнительную строку вне виртуального окна и снимается при focusout из строки,
+удалении её domain key или unmount. `header`/`footer` не входят в keyed lease.
 
 `viewport-change` reports the keyed anchor, visible range, `nearStart`, `atEnd`,
 and `pinnedToEnd`. An upward wheel, keyboard, or scrollbar gesture detaches
@@ -877,6 +1558,12 @@ Paging, status, and end markers belong in `header`/`footer`, not in the keyed
 domain items. Home, End, Page, and Arrow keys control the viewport only while
 `SVirtualList` itself owns focus; a nested editable/control retains its own
 keyboard semantics.
+The row containing actual DOM focus retains its keyed DOM identity across
+measurement, viewport, and rendered-range changes. A nested editor preserves
+focus and selection without programmatic refocusing. This lease retains only
+one additional row outside the virtual window and ends when focus leaves that
+row, its domain key is removed, or the list unmounts. `header`/`footer` regions
+do not own a keyed row lease.
 
 ## Темы и стили / Themes and styles
 
@@ -898,6 +1585,14 @@ application's own `@import "tailwindcss"`:
 typography plugin. `reference.css` is a compile-time `@reference` target for
 component styles.
 
+Оба CSS entrypoint используют полную сборку upstream typography plugin внутри
+пакета. Устанавливать `@tailwindcss/typography` или переопределять его transitive
+зависимости в consumer не требуется. Лицензии включённых модулей находятся в
+`dist/typography.LICENSE.txt`. / Both CSS entrypoints use the complete upstream
+typography plugin bundled in the package. Consumers do not need to install
+`@tailwindcss/typography` or override its transitive dependencies. The included
+module licenses are provided in `dist/typography.LICENSE.txt`.
+
 Для token-only интеграции доступен отдельный entrypoint:
 
 A separate entrypoint is available for token-only integration:
@@ -974,6 +1669,79 @@ separator по умолчанию использует `compact`, overlay handle
 Для 12-пиксельной границы workbench-панели используйте `standard`, не изменяя
 внутренние стили компонента.
 
+Pointer resize имеет отдельные `resize-end` и `resize-cancel`: завершение
+принимает конечную координату, отмена возвращает snapshot без сохранения
+preview. `SDockRegion` передаёт `hitbox` и поддерживает opt-in
+`collapseThreshold` с отдельным `collapse({ preferredSize })` intent.
+Клавиатурный Home остаётся установкой минимального размера. Типы, transaction
+ownership и примеры включены в пакет: `docs/resize.md`.
+
+### Сохранение скрытой рабочей панели / Hidden dock content retention
+
+`SDockRegion.keepMounted` — boolean с default `false`: скрытие освобождает
+slot owner. При `true` один slot owner сохраняется, включая начальное
+`visible=false`. Скрытый регион имеет нулевой layout, `hidden`/`inert`,
+не участвует в Tab, pointer или accessibility tree и не содержит resize handle.
+Скрытие во время drag отменяет resize через его общий lifecycle без terminal
+commit. Повторное отображение сохраняет экземпляр и native состояние содержимого,
+но не забирает focus у внешнего editor. Выключение retention у скрытого региона
+или unmount освобождает его содержимое.
+
+Вложенные UI-kit menu, listbox, popover, tooltip и dialog следуют `visible`,
+включая Teleport-поверхности: скрытие завершает открытые и ожидающие циклы,
+освобождает overlay leases/body lock и не возвращает focus скрытому trigger.
+Начальный hidden state запрещает открытие. Controlled `open=true` получает
+один close intent; для нового открытия требуется запрос `false → true`.
+Отображение retained content не возобновляет завершённый цикл. Вложенные dock
+сочетают visibility через логическое AND, независимые sibling overlays не
+затрагиваются. Произвольные consumer-owned portals остаются ответственностью
+consumer.
+
+Содержимое, transport и output buffer принадлежат consumer. Для imperative
+терминала экземпляр получает output и при скрытом регионе; `Terminal.open()`
+вызывается только для connected, видимого host с положительными размерами.
+UI-kit не импортирует xterm и не пересоздаёт PTY. Политика едина для
+`left | right | bottom` и `fixed | fill-on-narrow`.
+
+`SDockRegion.keepMounted` is a boolean defaulting to `false`: hiding disposes
+the slot owner. With `true`, the same owner remains mounted, including initial
+`visible=false`. The hidden region has zero layout footprint, is `hidden` and
+`inert`, participates in no Tab/pointer/accessibility navigation, and contains
+no resize handle. Hiding during a drag cancels the shared resize lifecycle
+without a terminal commit. Showing retains the instance and its native state
+without stealing focus from an external editor. Disabling retention while
+hidden or unmounting disposes the content.
+
+Nested UI-kit menus, listboxes, popovers, tooltips, and dialogs follow `visible`,
+including their Teleport surfaces. Hiding retires open and pending cycles,
+releases overlay leases/body locks, and never restores focus to a hidden trigger.
+Initially hidden content cannot open an overlay. Controlled `open=true` receives
+one close intent and requires a fresh `false → true` request. Showing retained
+content does not resurrect a retired cycle. Nested docks compose visibility with
+logical AND; independent sibling overlays are unaffected. Arbitrary
+consumer-owned portals remain the consumer's responsibility.
+
+Content, transport, and output buffers belong to the consumer. An imperative
+terminal can receive output while hidden; call `Terminal.open()` only for a
+connected, visible host with positive dimensions. The UI-kit does not import
+xterm or restart a PTY. The policy applies to `left | right | bottom` and
+`fixed | fill-on-narrow`.
+
+```vue
+<SDockRegion
+  placement="bottom"
+  :visible="terminalVisible"
+  keep-mounted
+  :size="terminalHeight"
+  :min-size="160"
+  :max-size="480"
+  resize-label="Высота терминала"
+  @resize="terminalHeight = $event"
+>
+  <TerminalViewport :visible="terminalVisible" />
+</SDockRegion>
+```
+
 ## Публичный контракт / Public contract
 
 `package.json#exports` — источник истины для импортов. Публичный контракт