npm - @feugene/granularity - Versions diffs - 0.13.0 → 0.16.0 - Mend

@feugene/granularity 0.13.0 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1223) hide show

package/dist/types/src/composables/internal/inert.d.ts ADDED Viewed

@@ -0,0 +1,35 @@
+/**
+ * `inert` для чужих поддеревьев.
+ *
+ * Визуального перекрытия мало: без `inert` таб уходит в форму, которую
+ * пользователь уже не видит, а скринридер читает её как обычную. `inert`
+ * снимает поддерево целиком — фокус, события указателя и дерево доступности.
+ *
+ * Два правила, из-за которых это отдельный модуль, а не пара строк на месте:
+ *
+ *  - **чужой `inert` не снимаем.** Элемент мог быть инертен и до нас;
+ *  - **счётчик на элемент.** Два открытых оверлея пометят один и тот же фон, и
+ *    закрытие первого не должно возвращать его в таб-порядок под вторым.
+ */
+/** Помечает элементы инертными и возвращает снятие пометки. */
+export declare function markInert(elements: HTMLElement[]): () => void;
+/**
+ * Что гасить, пока открыт модальный слой.
+ *
+ * Правило одно: **инертно всё, кроме ветки, в которой живёт оверлей**. Идём от
+ * него вверх до `<body>` и на каждом уровне помечаем соседей. Наивное «все дети
+ * `body`, кроме портала» сломалось бы на `portalTarget` внутри контейнера
+ * приложения: `inert` наследуется вниз, и помеченный предок убил бы сам оверлей.
+ *
+ * Корни других оверлеев пропускаются (`data-gr-overlay-root`): тост обязан
+ * оставаться видимым и озвученным поверх открытой модалки — ради этого он и
+ * сидит на самом верхнем слое шкалы, — а панель селекта, открытая изнутри окна,
+ * принадлежит тому же слою. Порядок между самими оверлеями решает стек слоёв
+ * (`isTopmost`), а не этот модуль.
+ *
+ * По той же причине пропускается хост объявителя (`data-gr-live-region`):
+ * `inert` выбрасывает поддерево из дерева доступности, и общий живой регион
+ * замолчал бы ровно под открытым диалогом — там, где «сохранено» и «ошибка
+ * сети» и нужны.
+ */
+export declare function inertableOutside(root: HTMLElement | null | undefined): HTMLElement[];

package/dist/types/src/composables/internal/overlayStack.d.ts ADDED Viewed

@@ -0,0 +1,60 @@
+/**
+ * Единый стек слоёв оверлеев: модалки, drawer'ы, просмотрщик, панели селектов,
+ * дропдауны, подсказки — всё, что открывается поверх страницы.
+ *
+ * Список один, и порядок регистрации совпадает с порядком открытия, но из него
+ * выводятся **две разные вершины**:
+ *
+ *  - **Esc** → последний слой любого рода. Дропдаун, открытый внутри модалки,
+ *    обязан закрыться первым — пользователь видит верхним именно его.
+ *  - **`inert`** → ставится на модальные слои ниже последнего **модального**.
+ *    Немодальный слой сверху модалку не понижает: иначе окно ушло бы в `inert`
+ *    вместе со своим же открытым дропдауном и перестало отвечать.
+ *
+ * Вести эти две вершины в двух независимых реестрах нельзя: реестры описывают
+ * один и тот же порядок и расходятся молча — достаточно оверлея, который
+ * зарегистрировался в одном и забыл про другой.
+ *
+ * Ловушку фокуса стек не реализует сам, но питает её (`useFocusTrap`): он
+ * видит слои из **разных деревьев рендера** (диалоги `useDialogService`
+ * монтируются отдельным `render()` в `body`) и знает их корни.
+ */
+export interface OverlayLayer {
+    /** Уникальный id зарегистрированного слоя. */
+    id: number;
+    /**
+     * Модальный слой: блокирует страницу и участвует в вычислении `inert`.
+     * Немодальные (поповеры, меню, подсказки) — только в очереди Esc.
+     */
+    modal: boolean;
+    /** Закрывать ли слой по Esc (реактивный геттер: `closeOnEsc` и подобные). */
+    shouldClose: () => boolean;
+    /** Закрыть слой. */
+    close: () => void;
+    /** Уведомление «этот модальный слой сейчас верхний». Только для `modal`. */
+    setTopmost?: (isTopmost: boolean) => void;
+    /**
+     * Корень слоя. Ловушка фокуса нижнего слоя обязана считать его своим:
+     * панель селекта, открытого внутри модалки, телепортирована в `body` и лежит
+     * вне DOM-поддерева окна, но для пользователя это тот же слой.
+     */
+    root?: () => HTMLElement | null;
+}
+/** Регистрирует слой как верхний и возвращает его id. */
+export declare function pushOverlayLayer(layer: Omit<OverlayLayer, 'id'>): number;
+/** Снимает слой со стека (при закрытии или размонтировании). */
+export declare function removeOverlayLayer(id: number): void;
+/**
+ * Корни слоёв, открытых **поверх** данного.
+ *
+ * Ими ловушка фокуса дополняет свой контейнер: всё, что открыто изнутри слоя
+ * (панель селекта, меню, подсказка), лежит в `body` отдельным поддеревом, и
+ * без этого списка ловушка утаскивала бы из него фокус обратно в окно.
+ */
+export declare function layerRootsAbove(id: number): HTMLElement[];
+/** Корни всех зарегистрированных слоёв. */
+export declare function allLayerRoots(): HTMLElement[];
+/** Сколько слоёв открыто. Для тестов и диагностики. */
+export declare function overlayStackSize(): number;
+/** Тестовая/служебная очистка стека. */
+export declare function resetOverlayStack(): void;

package/dist/types/src/composables/internal/portalRoot.d.ts ADDED Viewed

@@ -0,0 +1,27 @@
+/**
+ * Единая точка монтирования оверлеев.
+ *
+ * До неё каждый оверлей телепортировался в `body` сам по себе, и правило
+ * `inert` держалось на договорённости «все оверлеи лежат ровно на один уровень
+ * ниже `body`». Один контейнер даёт управляемую точку монтирования (своё
+ * приложение в контейнере, микрофронтенд, shadow DOM), одну точку очистки и
+ * порядок, совпадающий с порядком открытия.
+ *
+ * **У корня не должно быть ни стилей, ни классов.** `transform`, `filter`,
+ * `contain`, `perspective` и `will-change` создают containing block для
+ * `position: fixed`, и тогда панели `useFloating` начинают позиционироваться
+ * относительно портала, а не вьюпорта — с виду это «панель прилипла не туда»,
+ * и ищется такое долго.
+ */
+export declare const GR_PORTAL_ID = "gr-portal";
+/**
+ * Создаёт корень портала при первом обращении и возвращает его.
+ *
+ * `null` на сервере: DOM там трогать нечем, а телепорт всё равно выключен до
+ * монтирования (см. `useTeleportEnabled`).
+ */
+export declare function ensurePortalRoot(): HTMLElement | null;
+/** Текущий корень портала, если он уже создан. */
+export declare function getPortalRoot(): HTMLElement | null;
+/** Тестовая/служебная очистка: убирает корень из документа. */
+export declare function resetPortalRoot(): void;

package/dist/types/src/composables/internal/useAddonMeasurement.d.ts CHANGED Viewed

@@ -1,7 +1,7 @@
 import type { Ref } from 'vue';
 /**
  * Измерение фактической ширины prefix/suffix add-on'ов через `ResizeObserver`.
- * Общая логика GrInput/GrNumberInput (раньше дублировалась ~60 строк в каждом).
+ * Общая логика GrInput/GrNumberInput.
  *
  * Потребитель вешает возвращённые `prefixEl`/`suffixEl` на DOM-элементы аддонов
  * и передаёт реактивные `hasPrefix`/`hasSuffix` (обычно — наличие слотов).

package/dist/types/src/composables/internal/useComboboxNavigation.d.ts ADDED Viewed

@@ -0,0 +1,51 @@
+import type { ComputedRef, Ref } from 'vue';
+/**
+ * Активный элемент списка комбобокса (`aria-activedescendant`-паттерн).
+ *
+ * Одна и та же механика — activeIndex, циклический кламп, id активного, скролл
+ * к нему, инициализация при открытии — была написана в пакете четырежды
+ * (Select, Autocomplete, CommandPalette, частично Dropdown) и уже расходилась
+ * до P1: Enter в Select активировал не тот элемент, что был подсвечен.
+ * «Кто активен» обязан быть один на всех.
+ *
+ * Осознанно **не** обобщается активация: Enter/Tab/typeahead/Space — доменная
+ * логика компонента (у Select — `add|option|fallback`, у палитры —
+ * `selectItem`). Примитив отдаёт состояние и механические клавиши
+ * (`handleNavigationKeys`), активацию компонент делает сам по `activeItem`.
+ */
+export interface UseComboboxNavigationOptions<TItem> {
+    /** Навигируемые элементы (без disabled) в порядке отображения. */
+    items: () => readonly TItem[];
+    /** Открыт ли комбобокс — `activeDescendantId` существует только при открытом. */
+    open: () => boolean;
+    /** DOM id элемента — цель `aria-activedescendant`. */
+    idOf: (item: TItem, index: number) => string;
+    /**
+     * Стартовый индекс для `init()` (обычно выбранное значение). Не задан или
+     * вне диапазона — первый элемент, при пустом списке — `-1`.
+     */
+    initialIndex?: () => number;
+    /**
+     * Донести активный элемент до экрана. Виртуализация и `scrollIntoView` —
+     * забота компонента: только он знает свой контейнер и смещения окна.
+     */
+    scrollTo?: (item: TItem, index: number) => void | Promise<void>;
+}
+export interface UseComboboxNavigationReturn<TItem> {
+    activeIndex: Ref<number>;
+    activeItem: ComputedRef<TItem | undefined>;
+    activeDescendantId: ComputedRef<string | undefined>;
+    /** Циклический кламп + прокрутка к элементу. */
+    setActive: (index: number) => void;
+    /** Активировать стартовый элемент (вызывается при открытии). */
+    init: () => void;
+    /** Сброс активного (вызывается при закрытии; палитра сбрасывает в `0`). */
+    reset: (index?: number) => void;
+    /**
+     * Механические клавиши: `ArrowDown`/`ArrowUp`/`Home`/`End`. Возвращает
+     * `true`, если клавиша обработана (с `preventDefault`), — остальное
+     * компонент разбирает сам.
+     */
+    handleNavigationKeys: (event: KeyboardEvent) => boolean;
+}
+export declare function useComboboxNavigation<TItem>(options: UseComboboxNavigationOptions<TItem>): UseComboboxNavigationReturn<TItem>;

package/dist/types/src/composables/internal/useControlAddons.d.ts ADDED Viewed

@@ -0,0 +1,61 @@
+import type { ComputedRef, Ref } from 'vue';
+/**
+ * Аддоны контрола: слоты `prefix`/`suffix` и геометрия вокруг них.
+ *
+ * Слот здесь — вершина айсберга. Контракт аддона состоит из шести пропов ширины,
+ * замера фактического размера через `ResizeObserver` и пересчёта внутренних
+ * отступов поля, чтобы текст не заезжал под аддон. Эта математика была написана
+ * дважды — в `GrInput` и `GrNumberInput`, — и раскатать её ещё на четыре
+ * контрола копипастой значило бы завести шесть копий одного расчёта.
+ *
+ * Правило, которое держит композабл: **аддон резервирует место, а не заменяет
+ * отступ**. Поле с аддоном и без него выглядит одинаково отбитым от края —
+ * ширина аддона прибавляется к базовому паддингу ступени, а не вытесняет его.
+ *
+ * Карта ширины по умолчанию остаётся у компонента (`defaultMinWidth`): у
+ * `GrInput` она в `rem`, у `GrNumberInput` — в тех же значениях, но в пикселях,
+ * потому что оттуда же считаются ширины степперов. Сводить их к одной строке
+ * значило бы менять то, что уезжает в `style`, ради косметики.
+ */
+export interface GrControlAddonProps {
+    /** Минимальная ширина префикса. По умолчанию — ширина аддона для ступени размера. */
+    prefixMinWidth?: string;
+    /** Максимальная ширина префикса: содержимое шире — обрезается. */
+    prefixMaxWidth?: string;
+    suffixMinWidth?: string;
+    suffixMaxWidth?: string;
+    /**
+     * Жёсткая ширина префикса (из `prefixMaxWidth` → `prefixMinWidth` → дефолт).
+     * Нужна, когда аддоны соседних полей обязаны совпасть по ширине: без этого
+     * каждое поле меряет свой аддон и колонка «плывёт».
+     */
+    prefixFixed?: boolean;
+    suffixFixed?: boolean;
+}
+export interface UseControlAddonsOptions {
+    /** Ширина аддона по умолчанию для текущей ступени размера. */
+    defaultMinWidth: () => string;
+    /** Базовый горизонтальный отступ поля из size-мапы. */
+    paddingX: () => string;
+    /** Место, занятое собственными элементами контрола слева (степперы `GrNumberInput`). */
+    leadingReserve?: () => string;
+    /** То же справа: кнопки очистки и показа пароля, спиннер, степперы. */
+    trailingReserve?: () => string;
+    /** Прижать суффикс к правому краю — там, где аддон позиционируется абсолютно. */
+    anchorSuffixRight?: boolean;
+}
+export interface ControlAddons {
+    hasPrefix: ComputedRef<boolean>;
+    hasSuffix: ComputedRef<boolean>;
+    /** Вешаются на DOM-элементы аддонов: по ним идёт замер. */
+    prefixEl: Ref<HTMLElement | null>;
+    suffixEl: Ref<HTMLElement | null>;
+    /** Занятое аддоном место (`0px`, если слота нет) — контролу нужно для своих кнопок. */
+    prefixLen: ComputedRef<string>;
+    suffixLen: ComputedRef<string>;
+    prefixStyle: ComputedRef<Record<string, string | undefined>>;
+    suffixStyle: ComputedRef<Record<string, string | undefined>>;
+    /** `paddingLeft`/`paddingRight` поля с учётом аддонов и собственных кнопок. */
+    fieldPadding: ComputedRef<Record<string, string | undefined>>;
+}
+export declare function useControlAddons(props: () => GrControlAddonProps, options: UseControlAddonsOptions): ControlAddons;

package/dist/types/src/composables/internal/useControlledOpen.d.ts ADDED Viewed

@@ -0,0 +1,14 @@
+import type { ComputedRef } from 'vue';
+/**
+ * Контролируемое состояние открытия оверлея — единый контракт `v-model:open`
+ * панельных компонентов (Popover, Select, TreeSelect, Autocomplete, Dropdown).
+ *
+ * Uncontrolled-состояние; в controlled-режиме перекрывается пропом `open`.
+ * Без пропа `v-model` был бы обязателен, а поповер без модели — самый частый
+ * случай использования. Гарды компонента (disabled/readonly) остаются на его
+ * стороне — примитив ведёт только состояние и эмит.
+ */
+export declare function useControlledOpen(controlled: () => boolean | undefined, onChange: (value: boolean) => void): {
+    open: ComputedRef<boolean>;
+    setOpen: (next: boolean) => void;
+};

package/dist/types/src/composables/internal/useFilePreviews.d.ts ADDED Viewed

@@ -0,0 +1,26 @@
+export interface UseFilePreviewsOptions {
+    /** Включены ли миниатюры. Геттер — проп реактивен. */
+    enabled: () => boolean;
+}
+export interface UseFilePreviewsReturn {
+    /** Стабильный ключ файла для `v-for`. */
+    fileKey: (file: File) => string;
+    /** `object URL` миниатюры или `undefined`, если файл не картинка. */
+    previewUrl: (file: File) => string | undefined;
+    revokePreview: (file: File) => void;
+    revokeAllPreviews: () => void;
+}
+/**
+ * Ключи списка и миниатюры превью. Общий на файловые компоненты пакета:
+ * `GrFileUpload` (отправка) и `GrFormFile` (поле формы) показывают один и тот
+ * же набор одинаково, и правила «что считать картинкой» у них обязаны совпадать.
+ *
+ * Ключ считается от самого файла, а не от имени: два одноимённых файла из
+ * разных папок делили бы один `<li>`, и кнопка удаления в строке снимала бы
+ * не тот файл.
+ *
+ * `object URL` живёт ровно столько, сколько файл в наборе: без отзыва blob
+ * висит в памяти вкладки до перезагрузки — утечка тем заметнее, чем чаще
+ * пользователь перевыбирает файлы.
+ */
+export declare function useFilePreviews(options: UseFilePreviewsOptions): UseFilePreviewsReturn;

package/dist/types/src/composables/internal/useFocusWithin.d.ts ADDED Viewed

@@ -0,0 +1,32 @@
+import type { Ref } from 'vue';
+export interface UseFocusWithinOptions {
+    /** Фокус пришёл снаружи внутрь. */
+    enter?: (event: FocusEvent) => void;
+    /** Фокус ушёл изнутри наружу. */
+    leave?: (event: FocusEvent) => void;
+    /**
+     * Узлы, которые считаются частью контрола, хотя лежат вне корня. Нужны там,
+     * где панель телепортирована в `body`, а фокус в неё уходит по-настоящему:
+     * без них переход в поле фильтра открытой панели выглядел бы уходом наружу.
+     */
+    containers?: () => (HTMLElement | null | undefined)[];
+}
+export interface UseFocusWithinHandlers {
+    onFocusIn: (event: FocusEvent) => void;
+    onFocusOut: (event: FocusEvent) => void;
+}
+/**
+ * Граница фокуса составного контрола.
+ *
+ * Нативные `focus`/`blur` не всплывают, поэтому у группы (радиогруппа,
+ * сегменты, набор чекбоксов) их не поймать на корне вовсе — всплывают только
+ * `focusin`/`focusout`. Но всплывают они и когда фокус переезжает **внутри**
+ * группы: между её пунктами, с поля на его же кнопку очистки. Для потребителя
+ * это не уход и не приход — контрол всё это время в фокусе, — а необработанный
+ * переход дал бы `blur` + `focus` на каждую стрелку клавиатуры.
+ *
+ * Поэтому событие считается состоявшимся, только если `relatedTarget` лежит вне
+ * корня. `relatedTarget: null` (клик по body, уход из окна, программный фокус)
+ * — тоже пересечение границы.
+ */
+export declare function useFocusWithin(root: Ref<HTMLElement | null>, options: UseFocusWithinOptions): UseFocusWithinHandlers;

package/dist/types/src/composables/internal/useInertOthers.d.ts ADDED Viewed

@@ -0,0 +1,9 @@
+import type { Ref } from 'vue';
+/**
+ * Пока слой активен, всё вне его ветки помечено `inert`: от корня оверлея вверх
+ * до `<body>`, на каждом уровне — соседи.
+ *
+ * Это вторая половина модальности: `z-index` перекрывает страницу глазами,
+ * `inert` — клавиатурой и скринридером.
+ */
+export declare function useInertOthers(root: Ref<HTMLElement | null>, active: () => boolean): void;

package/dist/types/src/composables/internal/useModalOverlay.d.ts ADDED Viewed

@@ -0,0 +1,95 @@
+import type { ComputedRef, Ref } from 'vue';
+/**
+ * Модальный слой целиком: одна сборка на весь пакет.
+ *
+ * Модальность собиралась вручную в трёх компонентах (`GrModal`, `GrDrawer`,
+ * `GrImageViewer`) из шести примитивов, и сборка повторялась дословно. Дело не
+ * в объёме: в этой проводке сидят инварианты, каждый из которых при пропуске
+ * даёт тихий баг доступности, а не заметную поломку. Здесь они собраны в одном
+ * месте — забыть часть модального слоя больше нельзя.
+ *
+ * Что именно неочевидно:
+ *
+ *  - **`restoreFocus: false` у ловушки.** Возврат фокуса принадлежит стеку
+ *    слоёв: у него правило строже — вернуть, только если на момент закрытия
+ *    фокус ещё был внутри слоя. Две системы возврата подрались бы за фокус.
+ *  - **`containers: layer.rootsAbove`.** Панель селекта, открытого ВНУТРИ окна,
+ *    телепортирована в `body` и лежит вне поддерева панели. Без этого списка
+ *    ловушка считала бы её «снаружи» и отбирала фокус.
+ *  - **Ловушка и `inert` работают, только пока слой верхний.** Иначе нижнее
+ *    окно ворует фокус у открытого поверх него, а `inert` гасит собственную
+ *    панель вместе со страницей.
+ *  - **Клик по подложке считается только тот, что на ней и начался.** Иначе
+ *    выделение текста мышью или перетаскивание, отпущенное за пределами панели,
+ *    закрывает слой.
+ *
+ * Чего композабл НЕ делает: не рисует разметку. Корневой `div`, подложка и
+ * панель у трёх компонентов различаются по существу (обёртки скролла у окна,
+ * сквозные клики у немодальной панели, слои хрома у просмотрщика), а классами
+ * общий модуль владеть не вправе — пресет гранулярности подмешивает safelist
+ * только по директориям выбранных компонентов.
+ */
+export interface UseModalOverlayOptions {
+    /**
+     * Модальный ли слой: блокирует страницу, держит фокус, гасит нижние окна.
+     * Геттером — там, где модальность включается пропом (`GrDrawer`).
+     */
+    modal?: boolean | (() => boolean);
+    /** Закрывать ли по Esc. Геттер — проп компонента реактивен. */
+    closeOnEscape?: () => boolean;
+    /** Закрывать ли по клику в подложку; читается обработчиками `backdrop`. */
+    closeOnBackdrop?: () => boolean;
+    /** Панель слоя: контейнер ловушки фокуса и её запасной приёмник. */
+    panel: Ref<HTMLElement | null>;
+    /**
+     * Свой корень слоя. У якорного оверлея (`GrPopover`) корень и панель — один
+     * элемент: в портал уезжает сама панель, отдельной обёртки нет. Не задан —
+     * композабл заводит корень сам, как у центрированных окон.
+     */
+    root?: Ref<HTMLElement | null>;
+    /**
+     * Точечное переопределение точки монтирования (проп `teleportTo`). По
+     * умолчанию — общий портал оверлеев.
+     */
+    teleportTo?: () => string | HTMLElement | undefined;
+    /**
+     * Кому отдать фокус при открытии. Не задан — первому фокусируемому внутри
+     * панели (правило `useFocusTrap`): просмотрщику нужна именно кнопка тулбара,
+     * а окну — сама панель, и оно передаёт её явно.
+     */
+    initialFocus?: () => HTMLElement | null | undefined;
+    /**
+     * Блокировать ли скролл страницы. По умолчанию — пока слой открыт и модален:
+     * немодальная панель существует ровно ради работы со страницей под ней.
+     */
+    lockScroll?: () => boolean;
+}
+export interface ModalOverlay {
+    /** Корень слоя: цель `ref` в шаблоне, хозяин `inert` и корень для стека слоёв. */
+    rootEl: Ref<HTMLElement | null>;
+    /** Смонтировано ли поддерево: держится до конца leave-анимации панели. */
+    isMounted: Ref<boolean>;
+    /** Показан ли слой: этим переключаются `<Transition>` внутри. */
+    isVisible: Ref<boolean>;
+    /** Верхний ли это слой сейчас. */
+    isTopmost: Ref<boolean>;
+    /** Значение атрибута `inert` для корня: слой перестал быть верхним. */
+    inertAttr: ComputedRef<true | undefined>;
+    portalTarget: ComputedRef<string | HTMLElement>;
+    teleportEnabled: ComputedRef<boolean>;
+    /** `data-theme` на телепортированный корень: в DOM он вне обёртки провайдера. */
+    themeAttrs: ComputedRef<{
+        'data-theme'?: string;
+    }>;
+    /** Для `@after-leave` панели. Компонент оборачивает, если ему нужен эмит `closed`. */
+    onPanelAfterLeave: () => void;
+    /**
+     * Обработчики подложки вместе с guard'ом «клик начался на ней». Имена — под
+     * `v-on="backdrop"`: объектный синтаксис ждёт имена событий, а не пропов.
+     */
+    backdrop: {
+        mousedown: (event: MouseEvent) => void;
+        click: (event: MouseEvent) => void;
+    };
+}
+export declare function useModalOverlay(open: Ref<boolean>, onDismiss: () => void, options: UseModalOverlayOptions): ModalOverlay;

package/dist/types/src/composables/internal/useOverlayPresence.d.ts ADDED Viewed

@@ -0,0 +1,24 @@
+import type { Ref } from 'vue';
+export interface OverlayPresence {
+    /** Смонтировано ли поддерево слоя: держится до конца leave-анимации. */
+    mounted: Ref<boolean>;
+    /** Показан ли слой: этим переключаются `<Transition>` внутри. */
+    visible: Ref<boolean>;
+    /** Вызывается из `@after-leave` панели. */
+    onPanelAfterLeave: () => void;
+}
+/**
+ * Присутствие оверлея в DOM отдельно от его видимости.
+ *
+ * Штатный `<Transition>` анимирует свой элемент, но не координирует соседей:
+ * убери обёртку по `v-if` — и подложка с панелью исчезнут мгновенно, без
+ * leave-анимации. Поэтому присутствие поддерева и видимость слоя — два разных
+ * флага: первый снимается только по концу leave-анимации панели.
+ *
+ * Видимость включается **в том же такте**, что и монтирование: содержимое окна
+ * обязано появляться в DOM сразу после открытия — на этом стоит и код
+ * потребителя, и внутренние компоненты, которые ищут в панели свои элементы.
+ * Enter-анимацию это не отменяет: `<Transition appear>` проигрывает её и на
+ * первом рендере ребёнка.
+ */
+export declare function useOverlayPresence(open: Ref<boolean>): OverlayPresence;

package/dist/types/src/composables/internal/useScrollLock.d.ts CHANGED Viewed

@@ -2,14 +2,19 @@
  * useScrollLock — общий **reference-counted** lock скролла `<body>` для оверлеев
  * (GrModal, GrDrawer, GrImageViewer).
  *
- * Зачем счётчик: раньше каждый оверлей хранил `savedBodyOverflow` per-instance и
- * восстанавливал `overflow` при СВОЁМ закрытии. Если открыты A, затем B, и первым
- * закрывают A — body получал `overflow: ''` при ещё открытой B (баг LIFO).
- * Здесь состояние `<body>` сохраняется один раз (при переходе счётчика 0→1) и
- * восстанавливается только когда закрыт последний оверлей (счётчик 1→0).
+ * Зачем счётчик: состояние `<body>` принадлежит не оверлею, а их совокупности.
+ * Держи каждый свой `savedBodyOverflow`, и закрытие A при ещё открытой B вернуло
+ * бы странице прокрутку под открытым окном — закрывают не всегда в порядке
+ * открытия. Поэтому состояние сохраняется один раз (переход счётчика 0→1) и
+ * восстанавливается только когда закрыт последний оверлей (1→0).
  *
  * Плюс компенсация ширины скроллбара: при `overflow: hidden` скроллбар исчезает и
  * контент дёргается вправо — добавляем `padding-right` на его ширину.
+ *
+ * Отдельная ветка — iOS Safari: там `overflow: hidden` фон не держит, страница
+ * продолжает «резинить» под открытым окном. Лечится тем же, чем лечил
+ * HeadlessUI (`handleIOSLocking`): гасим `touchmove` вне скроллящихся областей
+ * оверлея и возвращаем позицию прокрутки после снятия лока.
  */
 /**
  * Возвращает пару `lock`/`unlock`, идемпотентную **в пределах одного инстанса**

package/dist/types/src/composables/internal/useTeleportEnabled.d.ts ADDED Viewed

@@ -0,0 +1,35 @@
+import { type Ref } from 'vue';
+/**
+ * Можно ли телепортировать содержимое прямо сейчас.
+ *
+ * Возвращает `false` на сервере И на первом клиентском рендере, `true` — сразу
+ * после монтирования. Использовать так:
+ *
+ * ```vue
+ * <teleport to="body" :disabled="!teleportEnabled">…</teleport>
+ * ```
+ *
+ * ## Зачем, если есть `typeof window !== 'undefined'`
+ *
+ * Проверка окружения выглядит достаточной, но именно она и ломала гидрацию.
+ * `isClient` вычисляется в `setup`, поэтому получалось так:
+ *
+ * - сервер: `window` нет → телепорт выключен → содержимое остаётся НА МЕСТЕ
+ *   (`:disabled` означает «рендерить на месте», а не «не рендерить»);
+ * - клиент, первый рендер: `window` есть → телепорт включён → содержимое сразу
+ *   уезжает в `body`.
+ *
+ * Структуры не совпадают, Vue сообщает `Hydration node mismatch`. В лучшем
+ * случае это лишний варнинг и осиротевшая копия панели в DOM; в худшем —
+ * панель «прилипает» к контейнеру приложения и пишет в него свои стили
+ * (`position: fixed` + `display: none` у закрытой панели), после чего страница
+ * исчезает целиком.
+ *
+ * Флаг, поднимаемый в `onMounted`, снимает проблему по построению: **первый**
+ * клиентский рендер повторяет серверный, а телепорт включается уже после
+ * гидрации. Для компонентов без SSR это ничего не меняет: панели закрыты
+ * (`v-show`/`v-if`), а `onMounted` срабатывает в том же тике.
+ *
+ * Стенд, на котором это воспроизводится и проверяется, — `apps/playground-ssr`.
+ */
+export declare function useTeleportEnabled(): Readonly<Ref<boolean>>;

package/dist/types/src/composables/useAnnouncer.d.ts ADDED Viewed

@@ -0,0 +1,44 @@
+/**
+ * Общий живой регион пакета: один канал `aria-live` на документ.
+ *
+ * До него каждый компонент строил свой `role="status"`, а сообщить что-то
+ * скринридеру из кода приложения («скопировано», «строка удалена», «найдено N»)
+ * было нечем вовсе. Регион виджета остаётся правильным решением, когда он
+ * рендерит **состояние** этого виджета (счётчик символов, «загружается»,
+ * «ничего не найдено»); объявитель — для **события**, которое произошло и
+ * прошло, и своего места в разметке не имеет.
+ *
+ * ```ts
+ * const { announce } = useAnnouncer()
+ * announce('Ссылка скопирована')
+ * announce('Не удалось сохранить', { politeness: 'assertive' })
+ * ```
+ *
+ * Композабл не требует setup-контекста: его можно звать из обычного `.ts` —
+ * из стора, обработчика, перехватчика запросов.
+ */
+export type GrAnnouncerPoliteness = 'polite' | 'assertive';
+export interface GrAnnounceOptions {
+    /**
+     * `assertive` перебивает текущую речь и уместен только для того, что нельзя
+     * пропустить (отказ операции, потеря соединения). По умолчанию `polite` —
+     * диктор дочитает начатое.
+     */
+    politeness?: GrAnnouncerPoliteness;
+    /**
+     * Через сколько мс стереть текст. `0` — не стирать.
+     *
+     * Регион остаётся в DOM, и пользователь виртуального курсора наткнётся на
+     * его содержимое при обходе страницы — через минуту после события это уже
+     * дезинформация. По умолчанию `7000`.
+     */
+    clearAfterMs?: number;
+}
+export interface GrAnnouncer {
+    announce: (message: string, options?: GrAnnounceOptions) => void;
+    /** Стирает текст региона. Без аргумента — обоих. */
+    clear: (politeness?: GrAnnouncerPoliteness) => void;
+}
+export declare function useAnnouncer(): GrAnnouncer;
+/** Тестовая/служебная очистка: снимает хост и все отложенные записи. */
+export declare function resetAnnouncer(): void;

package/dist/types/src/composables/useDismissible.d.ts ADDED Viewed

@@ -0,0 +1,32 @@
+import type { Ref } from 'vue';
+export interface UseDismissibleOptions {
+    /**
+     * Закрывать ли слой по Esc. Геттер, а не значение, — чтобы читать реактивный
+     * проп (`closeOnEsc`). По умолчанию закрывается всегда.
+     *
+     * Если геттер вернёт `false`, нажатие всё равно не пройдёт на слой ниже:
+     * пользователь видит верхний слой, и Esc адресован ему.
+     */
+    closeOnEscape?: () => boolean;
+}
+/**
+ * Регистрирует оверлей в общем стеке dismissible-слоёв, пока `open` истинно.
+ *
+ * Контракт один на все оверлеи пакета: **Esc закрывает верхний слой** — тот,
+ * что открыт последним, — и ниже не проваливается. Поэтому панель, открытая
+ * внутри модалки, по Esc закрывает себя, а не модалку; следующий Esc закроет
+ * уже модалку.
+ *
+ * Композабл нужен и потребителю: свой поповер, меню или подсказка, построенные
+ * поверх `useFloating()`, обязаны участвовать в том же стеке — иначе они снова
+ * разъедутся с оверлеями библиотеки.
+ *
+ * ```ts
+ * const open = ref(false)
+ * useDismissible(open, () => { open.value = false })
+ * ```
+ *
+ * Закрытие по клику вне слоя — отдельная задача, для неё есть директива
+ * `vClickOutside`: у Esc есть порядок слоёв, у клика — точка попадания.
+ */
+export declare function useDismissible(open: Ref<boolean>, onDismiss: () => void, options?: UseDismissibleOptions): void;