@feugene/granularity 0.12.0 → 0.16.0

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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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;

package/dist/types/src/composables/useFocusTrap.d.ts

@@ -0,0 +1,50 @@
+import type { Ref } from 'vue';
+export interface UseFocusTrapOptions {
+    /**
+     * Работает ли ловушка сейчас. Геттер, а не значение: модальное окно держит
+     * фокус, только пока оно верхнее в стеке слоёв, — иначе нижнее окно отбирало
+     * бы фокус у открытого поверх него.
+     */
+    active?: () => boolean;
+    /** Кому отдать фокус при активации. Не задан или не фокусируем — первый в контейнере. */
+    initialFocus?: () => HTMLElement | null | undefined;
+    /**
+     * Запасной приёмник фокуса, когда фокусировать внутри нечего: обычно сама
+     * панель с `tabindex="-1"`. Без него фокус остался бы снаружи, и Tab увёл бы
+     * пользователя на страницу под окном.
+     */
+    fallbackFocus?: () => HTMLElement | null | undefined;
+    /**
+     * Дополнительные корни, которые считаются частью слоя. Панель селекта,
+     * открытого внутри окна, телепортирована в `body` и лежит вне поддерева
+     * контейнера — без этого списка ловушка отбирала бы у неё фокус.
+     */
+    containers?: () => (HTMLElement | null | undefined)[];
+    /**
+     * Возвращать фокус туда, где он был до активации. По умолчанию — да.
+     * Оверлеи пакета выключают: возврат делает стек слоёв по более строгому
+     * правилу (только если фокус на момент закрытия ещё внутри слоя).
+     */
+    restoreFocus?: boolean;
+}
+/**
+ * Ловушка фокуса: пока активна, Tab ходит по кругу внутри слоя, а фокус,
+ * утёкший наружу, возвращается обратно.
+ *
+ * Реализована на `keydown` и `focusin`, **без sentinel-узлов**: распространённый
+ * подход с двумя focus-guard кнопками по краям кладёт в разметку интерактивные
+ * элементы, а внутрь контейнера с ARIA-ролью их класть нельзя — роль объявляет
+ * потомков презентационными (axe: `nested-interactive`).
+ *
+ * Слой из ловушки не выводится: порядок окон, Esc и `inert` — забота
+ * `useOverlayLayer`. Композиция такая:
+ *
+ * ```ts
+ * const layer = useOverlayLayer(open, close, { modal: true, root: panelRef })
+ * useFocusTrap(panelRef, {
+ *   active: () => open.value && isTopmost.value,
+ *   containers: layer.rootsAbove,
+ * })
+ * ```
+ */
+export declare function useFocusTrap(container: Ref<HTMLElement | null>, options?: UseFocusTrapOptions): void;

package/dist/types/src/composables/useGrFormControl.d.ts

@@ -0,0 +1,52 @@
+import type { ComputedRef } from 'vue';
+/**
+ * Общий контракт форм-контрола.
+ *
+ * До него каждый контрол решал одно и то же по-своему: `invalid` был то своим
+ * пропом, то только контекстом, то не был реализован вовсе; `readonly` жил у
+ * трёх контролов из пятнадцати, `required` — у двух. Из-за этого «форма только
+ * на чтение» приходилось делать через `disabled`, а это меняет и семантику
+ * (значение не уходит в форму), и контраст.
+ *
+ * Композабл сводит два источника — собственные пропы контрола и контекст
+ * `GrFormField` — в одно состояние. Правило одно: **проп контрола сильнее**,
+ * контекст работает как fallback. Исключение — `invalid`, `required` и
+ * `disabled`: там источники складываются по «или», потому что поле может
+ * объявить ошибку, о которой контрол не знает (правило формы), а форма —
+ * выключить себя целиком на время отправки.
+ */
+export interface GrFormControlProps {
+    /** Контрол недоступен: не фокусируется, значение не отправляется. */
+    disabled?: boolean;
+    /** Значение видно и отправляется, но не редактируется. */
+    readonly?: boolean;
+    /** Визуальное и ARIA-состояние ошибки. */
+    invalid?: boolean;
+    /** Обязательное поле. */
+    required?: boolean;
+    /** Доступное имя вне `GrFormField`. */
+    ariaLabel?: string;
+}
+export interface GrFormControlState {
+    /** Итоговый `disabled`. */
+    disabled: ComputedRef<boolean>;
+    /** Итоговый `readonly`. */
+    readonly: ComputedRef<boolean>;
+    /** Итоговый `invalid`: свой проп ИЛИ ошибка поля. */
+    invalid: ComputedRef<boolean>;
+    /** Итоговый `required`: свой проп ИЛИ обязательность поля. */
+    required: ComputedRef<boolean>;
+    /** Id контрола из поля (для `<label for>`). */
+    id: ComputedRef<string | undefined>;
+    /** Id подписи поля — для виджетов с ARIA-ролью, к которым `<label for>` неприменим. */
+    labelId: ComputedRef<string | undefined>;
+    /** `aria-describedby`: подсказка и/или текст ошибки поля. */
+    describedBy: ComputedRef<string | undefined>;
+    /** `true`, когда контрол не принимает ввод (`disabled` или `readonly`). */
+    locked: ComputedRef<boolean>;
+}
+/**
+ * @param source геттер собственных пропов контрола. Геттер, а не объект, —
+ * чтобы не терять реактивность на `props`.
+ */
+export declare function useGrFormControl(source?: () => GrFormControlProps): GrFormControlState;