@feugene/granularity 0.13.0 → 0.18.0

package/dist/types/src/components/GrTreeSelect/grTreeSelectTypes.d.ts

@@ -17,10 +17,36 @@ export interface GrTreeSelectProps<T extends object = any> {
     disabled?: boolean;
     placeholder?: string;
     size?: GrInputSize;
+    /**
+     * Данные ещё едут. Панель показывает индикатор вместо «Нет данных» — иначе
+     * пустой ответ и незагруженный выглядят одинаково.
+     */
+    loading?: boolean;
     invalid?: boolean;
+    /** Только для чтения: значение видно, но не меняется. */
+    readonly?: boolean;
+    /** Обязательное поле (`aria-required`). */
+    required?: boolean;
+    /** Доступное имя вне `GrFormField`. */
+    ariaLabel?: string;
     state?: GrTreeSelectState;
     multiple?: boolean;
+    /**
+     * Чекбоксы в дереве вместо собственной галочки: отметка родителя каскадом
+     * закрывает поддерево, полувыбранный родитель показывается `mixed`. Работает
+     * только вместе с `multiple`.
+     */
+    showCheckbox?: boolean;
+    /** Отвязать родителей от детей: отметка перестаёт распространяться каскадом. */
+    checkStrictly?: boolean;
     clearable?: boolean;
+    /**
+     * Контролируемое состояние панели (`v-model:open`). Без пропа панель ведёт
+     * себя сама (uncontrolled), с ним — слушайте `update:open` и меняйте проп.
+     */
+    open?: boolean;
+    /** Имя для нативной формы: hidden input на каждый выбранный ключ. */
+    name?: string;
     /** Как отображать выбранное значение в single-режиме. */
     valueDisplay?: GrTreeSelectValueDisplay;
     filterable?: boolean;
@@ -29,5 +55,22 @@ export interface GrTreeSelectProps<T extends object = any> {
     filterNodeMethod?: GrTreeFilterNodeMethod<T>;
     closeOnSelect?: boolean;
     dropdownMaxHeight?: number;
+    /**
+     * Виртуализация дерева в панели: в DOM живёт только окно вокруг вьюпорта.
+     *
+     * Скроллером в этом режиме становится само дерево, а не контейнер панели —
+     * два вложенных скроллера дали бы две полосы прокрутки на одном списке.
+     */
+    virtual?: boolean;
+    /**
+     * Ширины аддонов `prefix`/`suffix` — общий контракт контролов пакета
+     * (`docs/form-controls.md`).
+     */
+    prefixMinWidth?: string;
+    prefixMaxWidth?: string;
+    suffixMinWidth?: string;
+    suffixMaxWidth?: string;
+    prefixFixed?: boolean;
+    suffixFixed?: boolean;
 }
 export {};

package/dist/types/src/components/GrTreeSelect/index.d.ts

@@ -1,5 +1,10 @@
+import type { ComponentExposed } from '../shared/instance';
+import type GrTreeSelectComponent from './GrTreeSelect.vue';
 export { default } from './GrTreeSelect.vue';
 export { default as GrTreeSelect } from './GrTreeSelect.vue';
 export type { GrTreeSelectModelValue, GrTreeSelectProps, GrTreeSelectValueDisplay } from './grTreeSelectTypes';
 export { grTreeSelectConfig } from './config';
+export type { GrTreeSelectConfigurableProps } from './defaults';
 export { grTreeSelectSafelist } from './safelist';
+export type { GrTreeSelectEmits } from './GrTreeSelect.vue';
+export type GrTreeSelectInstance = ComponentExposed<typeof GrTreeSelectComponent>;

package/dist/types/src/components/shared/hotkey.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Разбор, матчинг и человекочитаемое представление сочетаний клавиш.
+ *
+ * Общий модуль, а не часть `GrCommandPalette`: то же нужно `GrKbd`, а импорт из
+ * чужой компонентной директории на сборке дал бы ребро `GrKbd →
+ * GrCommandPalette` (хелпер уехал бы в чанк палитры) — `granular doctor` считает
+ * такое незадекларированной зависимостью.
+ *
+ * Директива `v-hotkey` для палитры не годится: ей нужен смонтированный элемент,
+ * а палитра в закрытом состоянии не рендерит ничего. Поэтому здесь — свой
+ * матчер на `window`, с тем же синтаксисом комбинаций плюс токен `mod`.
+ */
+import { type HotkeyKeyView } from './hotkeyTokens';
+export { isAppleDevice } from '../../internal/keyboard';
+export { findKbdToken, GR_KBD_TOKENS } from './hotkeyTokens';
+export type { GrKbdKeyName, GrKbdTokenGroup, GrKbdTokenSpec, HotkeyKeyView } from './hotkeyTokens';
+export type ParsedCommandHotkey = {
+    key: string;
+    ctrl: boolean;
+    meta: boolean;
+    alt: boolean;
+    shift: boolean;
+    /** `mod` — Cmd на macOS, Ctrl на остальных платформах. */
+    mod: boolean;
+};
+export declare function parseCommandHotkey(combo: string): ParsedCommandHotkey | null;
+export declare function matchesCommandHotkey(event: KeyboardEvent, hotkey: ParsedCommandHotkey, apple?: boolean): boolean;
+/** Человекочитаемые клавиши для подсказки в поле ввода (`⌘` / `Ctrl`). */
+export declare function formatCommandHotkey(hotkey: ParsedCommandHotkey, apple?: boolean): string[];
+/**
+ * Токен → то, что видит пользователь. Каталог общий с витриной и докой
+ * (`hotkeyTokens.ts`): цепочка `if` расходилась бы со списком, который читает
+ * потребитель.
+ */
+export declare function formatHotkeyToken(token: string, apple: boolean): HotkeyKeyView;
+export declare function formatHotkeyTokens(tokens: readonly string[], apple: boolean): HotkeyKeyView[];
+/** Комбинация строкой (`mod+shift+K`) — в набор токенов в порядке показа. */
+export declare function splitHotkeyCombo(combo: string): string[];

package/dist/types/src/components/shared/hotkeyTokens.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Каталог клавиш, которые понимает `keys` у `GrKbd`.
+ *
+ * Таблица, а не цепочка `if`, по двум причинам: во-первых, список — часть
+ * публичного контракта (потребителю нужно знать, что можно написать), и
+ * витрина показывает именно его, а не свою копию; во-вторых, копия в демо или
+ * в доке разошлась бы с форматтером молча.
+ */
+/** Ключи читаемых имён — `gr.kbd.<name>`. */
+export type GrKbdKeyName = 'command' | 'option' | 'shift' | 'control' | 'enter' | 'escape' | 'tab' | 'backspace' | 'delete' | 'pageUp' | 'pageDown' | 'arrowUp' | 'arrowDown' | 'arrowLeft' | 'arrowRight';
+/** Одна клавиша в человекочитаемом виде. */
+export interface HotkeyKeyView {
+    /** Что видно на экране: символ (`⌘`) или слово (`Ctrl`). */
+    label: string;
+    /**
+     * Ключ читаемого имени (`gr.kbd.<name>`) для символьных клавиш. У `K` или
+     * `Ctrl` его нет — они и так читаются вслух.
+     */
+    name?: GrKbdKeyName;
+    /** Символ (`⌘`, `↑`) или слово (`Ctrl`, `Esc`): от этого зависит склейка в одной плашке. */
+    symbol?: boolean;
+}
+/** Смысловая группа — ею витрина и дока раскладывают каталог. */
+export type GrKbdTokenGroup = 'modifier' | 'editing' | 'navigation';
+export interface GrKbdTokenSpec {
+    /** Канонический токен: его пишут в `keys`. */
+    token: string;
+    /** Что ещё принимается — синонимы и сам глиф. */
+    aliases: readonly string[];
+    group: GrKbdTokenGroup;
+    /** Вид на macOS и на остальных платформах. */
+    apple: HotkeyKeyView;
+    other: HotkeyKeyView;
+}
+export declare const GR_KBD_TOKENS: readonly GrKbdTokenSpec[];
+/** Токен или его синоним — в описание клавиши. Регистр не важен, глиф тоже принимается. */
+export declare function findKbdToken(token: string): GrKbdTokenSpec | undefined;

package/dist/types/src/components/shared/instance.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Тип публичного API компонента — то, что он отдал через `defineExpose`.
+ *
+ * Зачем свой, а не `InstanceType<typeof GrX>`: у компонентов с
+ * `<script setup generic>` (`GrSelect`, `GrTree`, `GrDataTable`, …) `InstanceType`
+ * не работает вовсе — такой компонент компилируется не в класс, а в функцию.
+ *
+ * Зачем выводом, а не руками: написанный руками тип — копия `defineExpose`,
+ * которая расходится с оригиналом молча. Здесь разойтись не с чем.
+ *
+ * Определение — из `vue-component-type-helpers` (MIT). Скопировано, а не
+ * подключено зависимостью: пакет публикуемый, и тащить потребителю целый
+ * пакет ради одного условного типа несоразмерно.
+ */
+export type ComponentExposed<T> = T extends new (...args: any) => infer E ? E : T extends (props: any, ctx: any, expose: (exposed: infer E) => any, ...args: any) => any ? NonNullable<E> : Record<string, never>;

package/dist/types/src/components/shared/optionFilter.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Подстрочный поиск по опциям — один на пакет.
+ *
+ * Тот же предикат был написан трижды, и у каждой копии был свой контракт
+ * нормализации: `GrSelect` лоукейсил запрос в вызывающем коде, `GrAutocomplete`
+ * внутри матчера, `GrCommandPalette` — внутри своего. Расхождение такого рода
+ * не видно на глаз и всплывает как «в одном компоненте регистр учитывается, в
+ * другом нет».
+ *
+ * Нормализация здесь ровно одна (`normalizeOptionQuery`), а компонент выбирает,
+ * что ему нужно: готовый плоский список (`filterOptions`) или голый предикат
+ * (`matchesOptionQuery`) — `GrSelect` фильтрует внутри обхода групп и списка не
+ * имеет.
+ */
+/** Запрос в сравнимом виде: без краевых пробелов и в нижнем регистре. */
+export declare function normalizeOptionQuery(raw: string): string;
+/**
+ * Ядро матча: подстрока в любом из полей. `undefined` в наборе пропускается —
+ * у команды палитры может не быть ни описания, ни группы.
+ *
+ * `needle` ожидается уже нормализованным: нормализовать на каждый элемент
+ * списка значило бы делать одну и ту же работу n раз.
+ */
+export declare function matchesQueryParts(parts: readonly (string | undefined)[], needle: string): boolean;
+/** Опция в терминах поиска: метка видна пользователю, значение — то, что он мог запомнить. */
+export interface OptionLike {
+    label: string;
+    value: unknown;
+}
+/** Матчер по умолчанию: метка и значение опции. */
+export declare function matchesOptionQuery(option: OptionLike, needle: string): boolean;
+/**
+ * Плоская фильтрация списка опций.
+ *
+ * Пустой запрос отдаёт **тот же массив** и матчер не зовёт вовсе: свой `filter`
+ * потребителя не должен решать, что показывать «без запроса», а копия на
+ * каждый пересчёт била бы по виртуализированным спискам на тысячи опций.
+ *
+ * Пользовательскому матчеру уходит **сырой** запрос (только `trim`), а не
+ * нормализованный: это публичный контракт пропа `filter` у `GrAutocomplete`,
+ * и чужая реализация вправе смотреть на регистр.
+ */
+export declare function filterOptions<TOption extends OptionLike>(options: TOption[], rawQuery: string, filter?: (option: TOption, query: string) => boolean): TOption[];
+/**
+ * Значения выбора — в опции для чипов.
+ *
+ * Значение, которого нет среди опций, показывается как есть: так выглядит
+ * произвольное значение (`allowCustomValue`) и значение, пришедшее из модели
+ * раньше, чем подгрузились опции. Прятать его нельзя — пользователь видел бы
+ * пустое место вместо своего выбора.
+ *
+ * Сравнение идёт через ключ, а не `===`: объектные значения приходят в модель
+ * отдельной копией, и ссылочное равенство не нашло бы ничего.
+ */
+export declare function resolveSelectedOptions<TValue, TOption extends {
+    label: string;
+    value: TValue;
+}>(values: readonly TValue[], options: readonly TOption[], keyOf?: (value: TValue) => string): (TOption | {
+    value: TValue;
+    label: string;
+})[];

package/dist/types/src/components/shared/sizes.d.ts

@@ -0,0 +1,30 @@
+import type { GrComponentSize } from '../GrConfigProvider/context';
+export type { GrComponentSize } from '../GrConfigProvider/context';
+export { GR_COMPONENT_SIZES } from '../GrConfigProvider/context';
+/**
+ * Каноническая шкала размеров контролов — `GrComponentSize` (`xs|sm|md|lg`).
+ *
+ * До сведе́ния шкал в пакете было пять несовместимых: `xs sm md lg`, `sm md lg`,
+ * `sm md lg xl full`, `sm md lg full`, `md lg xl`, `sm md` и отдельно
+ * `GrAvatar.size: number`. Практическое следствие: `<GrConfigProvider size="xs">`
+ * физически не мог примениться к половине пакета, а `size="xl"` компилировался у
+ * одного компонента и падал у соседнего.
+ */
+/**
+ * Шкала **ширины оверлея** — отдельный тип, а не размер контрола.
+ *
+ * У модалки «размер» означает ширину окна, а не высоту строки и не кегль, и
+ * шкала у неё своя: `full` осмыслен, `xs` — нет. Смешивать их в одном типе
+ * значило бы разрешить `<GrModal size="xs">` и `<GrInput size="full">`.
+ */
+export declare const GR_OVERLAY_SIZES: readonly ["sm", "md", "lg", "xl", "full"];
+export type GrOverlaySize = typeof GR_OVERLAY_SIZES[number];
+/**
+ * Визуальное состояние форм-контрола. Было объявлено четырьмя независимыми
+ * копиями (`GrTextareaState`, `GrInputTagState`, `GrNumberInputState`,
+ * `GrTreeSelectState`) — расхождение обнаружилось бы только рантаймом.
+ */
+export declare const GR_CONTROL_STATES: readonly ["default", "success", "warning", "danger"];
+export type GrControlState = typeof GR_CONTROL_STATES[number];
+/** Размер контрола с escape-hatch в пиксели: только `GrAvatar` и `GrIcon`. */
+export type GrSizeWithPx = GrComponentSize | number;

package/dist/types/src/components/shared/slotNodes.d.ts

@@ -0,0 +1,19 @@
+import { type VNode } from 'vue';
+/**
+ * Разбор содержимого слота.
+ *
+ * Общий модуль, а не приватные функции внутри SFC: то же самое нужно и
+ * `GrFileUpload` («слот с кастомным UI или просто текст»), и `GrList` («в
+ * списке пусто»). Импорт из чужой компонентной директории на сборке дал бы
+ * ребро между компонентами, которого в разметке нет.
+ */
+/** `v-for` и `<template>` приходят фрагментами — разворачиваем до реальных узлов. */
+export declare function flattenSlotNodes(nodes: VNode[]): VNode[];
+export declare function isWhitespaceTextNode(node: VNode): boolean;
+/**
+ * Узлы, которые пользователь действительно видит: без комментариев (их
+ * оставляет после себя каждый `v-if`) и без переносов строк из шаблона.
+ */
+export declare function meaningfulSlotNodes(nodes: VNode[]): VNode[];
+/** Есть ли в слоте хоть что-то, кроме комментариев и пробелов. */
+export declare function hasMeaningfulSlotContent(nodes: VNode[]): boolean;

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

@@ -0,0 +1,59 @@
+/**
+ * Геометрия перестановки: чистая арифметика без DOM и без реактивности.
+ *
+ * Вынесена отдельно, потому что ошибка здесь проявляется не исключением, а
+ * «элемент встал не туда» — поймать это можно только тестом на числах.
+ * Композабл `useDragSort` сводит `DOMRect` к отрезкам вдоль оси и зовёт эти
+ * функции; какой смысл у попадания, решает уже компонент.
+ */
+/** Отрезок, занимаемый элементом вдоль оси переноса. */
+export interface DragSortSpan {
+    start: number;
+    end: number;
+}
+export interface DragSortHitResult {
+    /** Индекс элемента в переданном наборе. */
+    index: number;
+    /** Доля вдоль элемента: 0 — его начало, 1 — конец. */
+    fraction: number;
+}
+/**
+ * Какой элемент под указателем и в каком месте его.
+ *
+ * Промах не отбрасывается: между строками есть зазоры, а курсор уезжает за
+ * край списка — и в обоих случаях перенос обязан продолжать показывать
+ * ближайшую цель, иначе индикатор мигает на каждом пикселе между строками.
+ *
+ * Вырожденный отрезок (нулевая высота строки) даёт `fraction: 0` — цель
+ * остаётся детерминированной, а не зависящей от направления подхода.
+ */
+export declare function hitTest(spans: readonly DragSortSpan[], position: number): DragSortHitResult | null;
+/**
+ * Куда встанет элемент, если отпустить сейчас.
+ *
+ * Верхняя половина строки — «до неё», нижняя — «после». Индекс возвращается
+ * **в терминах итогового массива**, то есть уже с поправкой на то, что
+ * перетаскиваемый элемент из него временно вынут: без поправки перенос вниз
+ * на одну позицию не двигал бы ничего.
+ */
+export declare function insertionIndex(hit: DragSortHitResult, from: number, count: number): number;
+export interface AutoScrollOptions {
+    /** Ширина чувствительной полосы у каждого края, px. По умолчанию 32. */
+    zone?: number;
+    /** Скорость на самом краю, px за кадр. По умолчанию 12. */
+    speed?: number;
+}
+/**
+ * На сколько прокрутить контейнер за кадр: отрицательное — к началу.
+ *
+ * Скорость растёт линейно по мере приближения к краю, а не включается
+ * ступенькой: ступенька на длинном списке ощущается как рывок и промахивается
+ * мимо цели.
+ */
+export declare function autoScrollDelta(viewport: DragSortSpan, position: number, options?: AutoScrollOptions): number;
+/**
+ * Перестановка без мутации входа: массив потребителя остаётся нетронутым,
+ * наружу уходит новый. `v-model` с мутацией исходного набора ломает и
+ * сравнение «было — стало», и историю в сторе потребителя.
+ */
+export declare function moveItem<T>(items: readonly T[], from: number, to: number): T[];

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

@@ -0,0 +1,30 @@
+/**
+ * Что пакет считает фокусируемым.
+ *
+ * Один источник правды на ловушку фокуса, roving-навигацию и «первый элемент
+ * панели». До него каждый компонент собирал свой селектор: у `GrDropdown` в
+ * список не попадали `select` и `textarea`, а фильтр видимости стоял на
+ * `offsetParent !== null` — он врёт на `position: fixed` (у таких элементов
+ * `offsetParent` всегда `null`), то есть на панелях самих оверлеев.
+ */
+export declare function isFocusable(element: HTMLElement): boolean;
+/** Участвует ли элемент в таб-порядке (`tabindex="-1"` — нет). */
+export declare function isTabbable(element: HTMLElement): boolean;
+/**
+ * Фокусируемые внутри корня, в порядке документа.
+ *
+ * `tabbableOnly` (по умолчанию) оставляет только участников таб-порядка — это
+ * то, что нужно циклу Tab. Полный список нужен «первому фокусируемому» при
+ * открытии: панель с `tabindex="-1"` фокусируется программно.
+ */
+export declare function getFocusableElements(root: HTMLElement | null | undefined, options?: {
+    tabbableOnly?: boolean;
+}): HTMLElement[];
+/**
+ * Фокусируемые сразу в нескольких корнях, в порядке документа.
+ *
+ * Нужен ловушке: панель селекта, открытого внутри модалки, телепортирована в
+ * `body` и лежит вне DOM-поддерева окна, но для пользователя это продолжение
+ * того же слоя.
+ */
+export declare function getFocusableElementsIn(roots: (HTMLElement | null | undefined)[]): HTMLElement[];

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

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

@@ -0,0 +1,71 @@
+/**
+ * Единый стек слоёв оверлеев: модалки, drawer'ы, просмотрщик, панели селектов,
+ * дропдауны, подсказки — всё, что открывается поверх страницы.
+ *
+ * Список один, и порядок регистрации совпадает с порядком открытия, но из него
+ * выводятся **две разные вершины**:
+ *
+ *  - **Esc** → последний слой любого рода. Дропдаун, открытый внутри модалки,
+ *    обязан закрыться первым — пользователь видит верхним именно его.
+ *  - **`inert`** → ставится на модальные слои ниже последнего **модального**.
+ *    Немодальный слой сверху модалку не понижает: иначе окно ушло бы в `inert`
+ *    вместе со своим же открытым дропдауном и перестало отвечать.
+ *  - **высота** → `openModalCount()` поднимает floating-панель над окном, из
+ *    которого её открыли: телепортированная панель лежит рядом с корнем окна,
+ *    и статический `z-index` дропдауна оставлял её под ним.
+ *
+ * Вести эти две вершины в двух независимых реестрах нельзя: реестры описывают
+ * один и тот же порядок и расходятся молча — достаточно оверлея, который
+ * зарегистрировался в одном и забыл про другой.
+ *
+ * Ловушку фокуса стек не реализует сам, но питает её (`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;
+/**
+ * Сколько **модальных** слоёв открыто прямо сейчас.
+ *
+ * Читает `useFloating`, когда считает высоту панели: панель телепортирована в
+ * общий портал и лежит рядом с корнем окна, а не внутри него, поэтому свой
+ * стек-контекст её не спасает — высоту приходится брать из порядка слоёв.
+ */
+export declare function openModalCount(): number;
+/** Тестовая/служебная очистка стека. */
+export declare function resetOverlayStack(): void;

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

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

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