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

@feugene/granularity 0.13.0 → 0.18.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 (1266) hide show

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

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

@@ -0,0 +1,63 @@
+import type { Ref } from 'vue';
+/**
+ * Скелет указательного жеста: нажал, повёл, отпустил.
+ *
+ * Механика написана в пакете дважды дословно (`GrSlider`, `GrSplitter`) и
+ * ещё раз иначе (`GrImageViewer`), а следующие потребители известны заранее —
+ * swipe у `GrToaster`, перенос узла в `GrTree`, ресайз колонок `GrDataTable`.
+ * Дублируется при этом не разметка, а **правило**: оборванный жест не
+ * коммитит. Живя в двух копиях, оно разъезжается молча.
+ *
+ * Слушатели вешаются на `window`, а не на элемент: указатель уходит за
+ * границы дорожки и разделителя постоянно, и жест обязан это переживать.
+ * Захват (`setPointerCapture`) дал бы то же самое, но привязал бы жест к
+ * живому DOM-узлу — а он в середине жеста может перерисоваться.
+ *
+ * У жеста **два разных исхода**, и это главное, ради чего примитив заведён:
+ * `pointerup` — завершение (значение коммитится), `pointercancel` — обрыв
+ * (браузер забрал указатель: системный жест, скролл, потеря окна), и тогда
+ * состояние возвращается к тому, что было до нажатия.
+ *
+ * Осознанно **не** делает:
+ * - не вызывает `preventDefault` — в слайдере и сплиттере это гашение
+ *   выделения текста, а в панорамировании картинки помешало бы; строка
+ *   дешевле опции, меняющей поведение невидимо;
+ * - не считает координаты и дельты — это доменная арифметика компонента;
+ * - не знает про порог начала жеста: он нужен сортировке, где нажатие ещё не
+ *   означает перенос, и появится вместе с ней.
+ *
+ * ```ts
+ * const drag = useDragGesture({
+ *   disabled: () => isDisabled.value,
+ *   onStart: (event) => { activeThumb.value = nearestThumb(event) },
+ *   onMove: (event) => setValue(valueFromPointer(event), false),
+ *   onEnd: () => commit(),
+ *   onCancel: () => rollback(),
+ * })
+ *
+ * <div @pointerdown="drag.start" />
+ * ```
+ */
+export interface UseDragGestureOptions {
+    /** Жест не начинается: `disabled` / `readonly`. */
+    disabled?: () => boolean;
+    /**
+     * Нажатие прошло проверки. Вернуть `false` — жест не начинать: так
+     * отсеивается попадание мимо цели, когда `disabled` тут ни при чём.
+     */
+    onStart?: (event: PointerEvent) => boolean | void;
+    onMove: (event: PointerEvent) => void;
+    /** Жест завершён отпусканием: значение коммитится. */
+    onEnd?: (event?: PointerEvent) => void;
+    /** Жест оборван: откат к состоянию до нажатия. */
+    onCancel?: () => void;
+}
+export interface UseDragGestureReturn {
+    /** Идёт ли жест. Менять снаружи не нужно — состоянием владеет примитив. */
+    isDragging: Ref<boolean>;
+    /** Вешается на `@pointerdown` цели. */
+    start: (event: PointerEvent) => void;
+    /** Принудительное завершение. По умолчанию — как обрыв, без коммита. */
+    stop: (commit?: boolean) => void;
+}
+export declare function useDragGesture(options: UseDragGestureOptions): UseDragGestureReturn;

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

@@ -0,0 +1,80 @@
+import type { Ref } from 'vue';
+/**
+ * Модель перестановки: перенос элемента указателем и с клавиатуры.
+ *
+ * Композабл владеет **механикой** — сессией жеста поверх `useDragGesture`,
+ * порогом начала, попаданием в элемент, автопрокруткой у краёв и состоянием
+ * переноса. **Смысл** остаётся у компонента: что считать целью (индекс вставки
+ * у списка, «до / внутрь / после» у дерева), какими клавишами это делается и
+ * что сказать в живой регион.
+ *
+ * Граница проведена так не из вкуса: у списка цель переноса — число, у дерева —
+ * пара «узел и зона», а `Space` в дереве уже занят чекбоксом. Общая у них
+ * механика, а не семантика; обобщать семантику значило бы завести опцию на
+ * каждое расхождение.
+ *
+ * Данные композабл не меняет: он сообщает «источник и цель», перестановку
+ * делает потребитель (`moveItem` из `internal/dragSortGeometry` — если она
+ * обычная).
+ *
+ * ```ts
+ * const sort = useDragSort<string, number>({
+ *   items: () => keys.value,
+ *   elementFor: key => rowEls.get(key),
+ *   scroller: () => scrollerEl.value,
+ *   resolveTarget: (hit, source) => insertionIndex(hit, indexOf(source), keys.value.length),
+ *   onDrop: (source, to) => emit('move', indexOf(source), to),
+ * })
+ * ```
+ */
+export type DragSortOrientation = 'vertical' | 'horizontal';
+/** Чем ведётся перенос: указателем или с клавиатуры. */
+export type DragSortMode = 'pointer' | 'keyboard';
+export interface DragSortHit<TKey> {
+    key: TKey;
+    index: number;
+    /** Доля вдоль элемента: 0 — начало, 1 — конец. Зоны нарезает компонент. */
+    fraction: number;
+}
+export interface UseDragSortOptions<TKey, TTarget> {
+    items: () => readonly TKey[];
+    elementFor: (key: TKey) => HTMLElement | null | undefined;
+    /** По умолчанию `vertical`. */
+    orientation?: () => DragSortOrientation;
+    /** Скроллер для автопрокрутки у краёв. Не задан — автопрокрутки нет. */
+    scroller?: () => HTMLElement | null | undefined;
+    disabled?: () => boolean;
+    canDrag?: (key: TKey) => boolean;
+    /** Сдвиг, после которого нажатие становится переносом. По умолчанию 4px. */
+    threshold?: () => number;
+    /**
+     * Попадание указателя → цель переноса. `null` — сюда положить нельзя.
+     *
+     * Третьим аргументом приходит прежняя цель: цели сравниваются по ссылке, и
+     * объектной цели (как «узел плюс зона» у дерева) стоит вернуть **ту же**
+     * ссылку, пока смысл не изменился, — иначе подсветка и объявления будут
+     * дёргаться на каждом движении указателя.
+     */
+    resolveTarget: (hit: DragSortHit<TKey>, source: TKey, previous: TTarget | null) => TTarget | null;
+    /** Перенос состоялся. */
+    onDrop: (source: TKey, target: TTarget) => void;
+    /** Состояние изменилось: подсветка строк и объявления — на этом. */
+    onUpdate?: (source: TKey | null, target: TTarget | null, mode: DragSortMode | null) => void;
+}
+export interface UseDragSortReturn<TKey, TTarget> {
+    source: Ref<TKey | null>;
+    target: Ref<TTarget | null>;
+    mode: Ref<DragSortMode | null>;
+    isActive: Ref<boolean>;
+    /** Вешается на `@pointerdown` ручки или строки. */
+    startFrom: (key: TKey) => (event: PointerEvent) => void;
+    /** Клавиатурный перенос: взять элемент. */
+    grab: (key: TKey) => void;
+    /** Клавиатурный перенос: назначить цель (двигать ведёт компонент). */
+    setTarget: (target: TTarget | null) => void;
+    /** Положить: если цель есть — состоится `onDrop`. */
+    drop: () => void;
+    /** Отменить: ничего не переносится. */
+    cancel: () => void;
+}
+export declare function useDragSort<TKey, TTarget>(options: UseDragSortOptions<TKey, TTarget>): UseDragSortReturn<TKey, TTarget>;

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

@@ -0,0 +1,57 @@
+import type { CSSProperties, Ref } from 'vue';
+import type { Placement } from '@floating-ui/dom';
+export type UseFloatingPlacement = Placement;
+export interface UseFloatingOptions {
+    /**
+     * Предпочитаемое место панели относительно триггера. По умолчанию `bottom-start`.
+     * Можно передать функцию-геттер, если место зависит от реактивного пропа
+     * (например, `align`) — она вызывается заново при каждом пересчёте позиции.
+     */
+    placement?: UseFloatingPlacement | (() => UseFloatingPlacement);
+    /** Зазор между триггером и панелью, px. По умолчанию `8`. */
+    offsetPx?: number;
+    /** Минимальный отступ от края viewport при flip/shift, px. По умолчанию `8`. */
+    boundaryPadding?: number;
+    /**
+     * Согласовать ширину панели с шириной триггера (актуально для Select/TreeSelect).
+     * Не годится для Dropdown/Tooltip, где ширина панели определяется контентом.
+     * - `true` — точная ширина (`width = ширина триггера`);
+     * - `'min'` — панель растёт по контенту (`width: max-content`), но не уже триггера
+     *   (`min-width = ширина триггера`) — режим `GrSelect view="link"`;
+     * - функция-геттер — как и `placement`, для реактивной зависимости от пропа.
+     */
+    matchWidth?: boolean | 'min' | (() => boolean | 'min');
+    /**
+     * CSS-переменная шкалы слоёв (см. `styles/tokens.css`). По умолчанию
+     * `--gr-z-dropdown`. Действует, пока панель открыта вне модального окна: над
+     * окном высоту задаёт стек слоёв (см. {@link floatingZIndex}).
+     */
+    zIndexVar?: string;
+}
+export interface UseFloatingReturn {
+    /** Готовый объект для `:style` на плавающем элементе. */
+    floatingStyle: Ref<CSSProperties>;
+    /**
+     * Итоговое место панели ПОСЛЕ применения `flip` — может отличаться от запрошенного
+     * `placement`, если места не хватило и панель перевернуло на противоположную сторону.
+     * Полезно для выбора `transform-origin`/направления transition в потребителе.
+     */
+    resolvedPlacement: Ref<Placement>;
+    /** Принудительный пересчёт позиции (например, после изменения контента панели). */
+    update: () => void;
+}
+/**
+ * Единый движок позиционирования floating-панелей (Dropdown/Select/TreeSelect/Tooltip)
+ * поверх `@floating-ui/dom`: flip (переворот при нехватке места), shift (клэмп к границам
+ * viewport), опциональный `size`-мидлвар для растягивания по ширине триггера.
+ *
+ * Пересчёт положения при скролле/ресайзе делает `autoUpdate` из `@floating-ui/dom` —
+ * он сам использует `ResizeObserver`/`IntersectionObserver` и пассивные слушатели вместо
+ * наивного враппера на каждый `scroll`/`resize`, поэтому отдельный rAF-throttling здесь
+ * не нужен (в отличие от прежней ручной реализации в `GrSelect`/`GrDropdown`).
+ *
+ * Требует, чтобы `floatingEl` был примонтирован в DOM на момент открытия (обычно —
+ * `<teleport to="body">` + `v-show`, а не `v-if`): позиционирование не может измерить
+ * элемент, которого нет в дереве.
+ */
+export declare function useFloating(referenceEl: Ref<HTMLElement | null>, floatingEl: Ref<HTMLElement | null>, open: Ref<boolean>, options?: UseFloatingOptions): UseFloatingReturn;

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

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