@feugene/granularity 0.46.0 → 0.48.0

package/dist/types/components/GrAutocomplete/composables/useAutocompletePanel.d.ts

@@ -0,0 +1,36 @@
+import type { ComputedRef, Ref } from 'vue';
+import type { GrAutocompleteOption, GrAutocompleteValue } from '../GrAutocomplete.vue';
+/**
+ * Состав панели `GrAutocomplete`: что показывать под запросом.
+ *
+ * Три решения, которые легко перепутать между собой. При `fetchOptions`
+ * локальный матчер выключается — он отсеял бы то, что сервер уже прислал в
+ * ответ на этот же запрос. Ниже `minQueryLength` список пуст, а не «прошлый»:
+ * показывать старый набор под подсказкой «введите ещё N» значит
+ * дезинформировать. А «Add …» не предлагается, если такое значение или подпись
+ * уже есть среди опций.
+ */
+export interface UseAutocompletePanelOptions<TValue extends GrAutocompleteValue> {
+    optionsResolved: ComputedRef<GrAutocompleteOption<TValue>[]>;
+    /** Введённый текст без нормализации: тримит уже сам модуль. */
+    query: Ref<string>;
+    /** Пользователь начал ввод — до этого single-режим показывает весь список. */
+    dirty: Ref<boolean>;
+    filterable: () => boolean;
+    filter: () => ((option: GrAutocompleteOption<TValue>, query: string) => boolean) | undefined;
+    fetchOptions: () => unknown;
+    multiple: () => boolean;
+    minQueryLength: () => number;
+    allowCustomValue: () => boolean;
+    selectedValues: ComputedRef<TValue[]>;
+    modelSingle: ComputedRef<TValue | ''>;
+    isLoading: ComputedRef<boolean>;
+}
+export interface AutocompletePanel<TValue extends GrAutocompleteValue> {
+    searchQuery: ComputedRef<string>;
+    belowMinQuery: ComputedRef<boolean>;
+    effectiveOptions: ComputedRef<GrAutocompleteOption<TValue>[]>;
+    canAddCustom: ComputedRef<boolean>;
+    showEmpty: ComputedRef<boolean>;
+}
+export declare function useAutocompletePanel<TValue extends GrAutocompleteValue>(options: UseAutocompletePanelOptions<TValue>): AutocompletePanel<TValue>;

package/dist/types/components/GrAutocomplete/composables/useAutocompleteValues.d.ts

@@ -0,0 +1,28 @@
+import type { ComputedRef, Ref, ShallowRef } from 'vue';
+import type { GrAutocompleteModelValue, GrAutocompleteOption, GrAutocompleteValue } from '../GrAutocomplete.vue';
+/**
+ * Значение и опции `GrAutocomplete`: что выбрано и как это назвать.
+ *
+ * Ничего про панель, клавиатуру и вид. Состав списка зависит от того, отвечал
+ * ли уже сервер: до первого ответа источник — проп `options`, иначе последний
+ * ответ `fetchOptions`.
+ */
+export interface UseAutocompleteValuesOptions<TValue extends GrAutocompleteValue> {
+    modelValue: () => GrAutocompleteModelValue<TValue>;
+    options: () => GrAutocompleteOption<TValue>[] | undefined;
+    multiple: () => boolean;
+    fetchOptions: () => unknown;
+    remoteOptions: ShallowRef<GrAutocompleteOption<TValue>[]>;
+    remoteAnswered: Ref<boolean>;
+}
+export interface AutocompleteValues<TValue extends GrAutocompleteValue> {
+    optionsResolved: ComputedRef<GrAutocompleteOption<TValue>[]>;
+    isEmptyValue: (value: unknown) => boolean;
+    modelSingle: ComputedRef<TValue | ''>;
+    selectedValues: ComputedRef<TValue[]>;
+    hasSelection: ComputedRef<boolean>;
+    labelFor: (value: GrAutocompleteValue) => string;
+    selectedOptions: ComputedRef<GrAutocompleteOption<TValue>[]>;
+    singleSelectedLabel: ComputedRef<string>;
+}
+export declare function useAutocompleteValues<TValue extends GrAutocompleteValue>(options: UseAutocompleteValuesOptions<TValue>): AutocompleteValues<TValue>;

package/dist/types/components/GrAutocomplete/composables/useAutocompleteVirtual.d.ts

@@ -0,0 +1,33 @@
+import type { ComputedRef, Ref } from 'vue';
+import { useVirtualList } from '../../../composables/useVirtualList';
+import type { GrAutocompleteOption, GrAutocompleteValue } from '../GrAutocomplete.vue';
+/**
+ * Виртуализация панели `GrAutocomplete`.
+ *
+ * Набор — `[«Add …»?] + effectiveOptions`, тот же, по которому ходит клавиатура.
+ * Иначе верхняя распорка вытолкнула бы строку «Add …» вниз: она отрисована
+ * внутри listbox'а первой и является полноценной опцией. Отсюда `addOffset`,
+ * который сдвигает окно виртуализатора относительно индексов в списке опций.
+ */
+export interface UseAutocompleteVirtualOptions<TValue extends GrAutocompleteValue> {
+    /** Контейнер списка: по нему считается окно и замеряются строки. */
+    listboxEl: Ref<HTMLElement | null>;
+    effectiveOptions: ComputedRef<GrAutocompleteOption<TValue>[]>;
+    canAddCustom: ComputedRef<boolean>;
+    virtual: () => boolean;
+    dropdownMaxHeight: () => number;
+}
+export interface AutocompleteVirtual<TValue extends GrAutocompleteValue> {
+    /** Сдвиг окна из-за строки «Add …»: она идёт нулевым элементом набора. */
+    addOffset: ComputedRef<number>;
+    virtualCount: ComputedRef<number>;
+    virtualizer: ReturnType<typeof useVirtualList>;
+    showAddOption: ComputedRef<boolean>;
+    renderedOptions: ComputedRef<Array<{
+        option: GrAutocompleteOption<TValue>;
+        index: number;
+    }>>;
+    optionSetProps: (virtualIndex: number) => Record<string, number> | undefined;
+    listboxStyle: ComputedRef<Record<string, string>>;
+}
+export declare function useAutocompleteVirtual<TValue extends GrAutocompleteValue>(options: UseAutocompleteVirtualOptions<TValue>): AutocompleteVirtual<TValue>;

package/dist/types/components/GrAutocomplete/composables/useRemoteOptions.d.ts

@@ -0,0 +1,33 @@
+import type { Ref, ShallowRef } from 'vue';
+import type { GrAutocompleteOption, GrAutocompleteValue } from '../GrAutocomplete.vue';
+/**
+ * Дебаунснутая удалённая загрузка опций.
+ *
+ * Три вещи, каждая из которых по отдельности выглядит необязательной, а вместе
+ * составляют весь смысл модуля: запрос откладывается на `debounce`, летящий
+ * отменяется новым, а ответ, стартовавший раньше и пришедший позже, обязан
+ * проиграть последнему — иначе список показывает результат старого запроса.
+ *
+ * От DOM не зависит вовсе, поэтому проверяется без монтирования компонента.
+ *
+ * Единственный потребитель сегодня — `GrAutocomplete`. Появится второй
+ * (открытая строка аудита: `GrTransfer` отдаёт `search` наружу, а подгрузку
+ * делает потребитель) — модулю место в `composables/internal/`.
+ */
+export interface UseRemoteOptionsOptions<TValue extends GrAutocompleteValue> {
+    fetchOptions: () => ((query: string, signal: AbortSignal) => Promise<GrAutocompleteOption<TValue>[]>) | undefined;
+    /** Стартовый список: его смена сбрасывает ответ сервера. */
+    options: () => GrAutocompleteOption<TValue>[] | undefined;
+    debounce: () => number;
+    minQueryLength: () => number;
+    onSearch: (query: string) => void;
+    onSearchError: (error: unknown) => void;
+}
+export interface RemoteOptions<TValue extends GrAutocompleteValue> {
+    remoteOptions: ShallowRef<GrAutocompleteOption<TValue>[]>;
+    remoteAnswered: Ref<boolean>;
+    remoteLoading: Ref<boolean>;
+    scheduleSearch: (value: string) => void;
+    cancelSearch: () => void;
+}
+export declare function useRemoteOptions<TValue extends GrAutocompleteValue>(options: UseRemoteOptionsOptions<TValue>): RemoteOptions<TValue>;

package/dist/types/components/GrAvatar/GrAvatar.vue.d.ts

@@ -16,6 +16,14 @@ export interface GrAvatarProps {
     /** Имя участника: даёт инициалы и доступное имя аватара. */
     name?: string;
     shape?: GrAvatarShape;
+    /**
+     * Красить фон по имени: одинаковое имя всегда даёт одинаковый цвет.
+     *
+     * Выключен по умолчанию — серый аватар это осознанный нейтральный дефолт, а
+     * цветной может спорить с оформлением продукта. Палитру задаёт тема
+     * (`--gr-avatar-N-bg`/`-fg`), компонент только выбирает слот.
+     */
+    autoColor?: boolean;
     /** Статус участника. Точка декоративна — рядом идёт скрытая подпись. */
     status?: GrAvatarStatus;
 }
@@ -30,6 +38,7 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     alt: undefined;
     name: undefined;
     shape: undefined;
+    autoColor: undefined;
     status: undefined;
 }>>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToOption<GrAvatarProps>, {
     size: undefined;
@@ -38,10 +47,12 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     alt: undefined;
     name: undefined;
     shape: undefined;
+    autoColor: undefined;
     status: undefined;
 }>>> & Readonly<{}>, {
     size: GrSizeWithPx;
     shape: GrAvatarShape;
+    autoColor: boolean;
     status: GrAvatarStatus;
     name: string;
     alt: string;

package/dist/types/components/GrAvatar/defaults.d.ts

@@ -8,6 +8,7 @@ import type { GrAvatarShape } from './grAvatarStyles';
 export interface GrAvatarConfigurableProps {
     size: GrComponentSize;
     shape: GrAvatarShape;
+    autoColor: boolean;
 }
 declare module '../../composables/useGrComponentConfig' {
     interface GrComponentDefaultsRegistry {

package/dist/types/components/GrAvatar/grAvatarStyles.d.ts

@@ -3,7 +3,32 @@ export type GrAvatarShape = 'circle' | 'square';
 export declare const GR_AVATAR_STATUSES: readonly ["online", "offline", "busy", "away"];
 export type GrAvatarStatus = typeof GR_AVATAR_STATUSES[number];
 export declare const shapes: Record<GrAvatarShape, string>;
-export declare const rootBaseClass = "relative inline-flex shrink-0 items-center justify-center overflow-hidden border border-[var(--gr-brd)] bg-[var(--gr-muted)] text-[var(--gr-muted-fg)] font-700";
+export declare const rootBaseClass = "relative inline-flex shrink-0 items-center justify-center overflow-hidden border border-[var(--gr-brd)] font-700";
+/** Цвет по умолчанию. Отделён от базы, иначе он спорил бы с автоцветом порядком правил. */
+export declare const rootNeutralClass = "bg-[var(--gr-muted)] text-[var(--gr-muted-fg)]";
+/**
+ * Палитра автоцвета: подложка и инициалы одним классом на слот.
+ *
+ * Цвета сюда не попадают — только имена слотов. Что стоит за слотом, решает
+ * тема (`--gr-avatar-N-bg`/`-fg` ссылаются на пары `-light`/`-text` тонов), и
+ * приложение вправе переопределить любой, не трогая компонент.
+ *
+ * Классы статические: UnoCSS сканирует литералы, и собранный в рантайме
+ * `bg-[var(--gr-avatar-${n}-bg)]` в CSS не превратился бы.
+ */
+export declare const avatarToneClasses: string[];
+/**
+ * Слот палитры по имени: тот же человек — тот же цвет.
+ *
+ * Стабильность здесь и есть смысл функции: цвет не должен меняться ни между
+ * сессиями, ни между сервером и клиентом, иначе аватар мигает на гидрации, а
+ * узнаваемость — то, ради чего автоцвет и заводят, — теряется. Отсюда обычный
+ * детерминированный перебор кодов, а не хеш из окружения.
+ *
+ * `>>> 0` обязателен: без него сумма уходит в отрицательные на длинных именах,
+ * и остаток от деления даёт отрицательный индекс.
+ */
+export declare function avatarToneIndex(name: string): number;
 /** Индикатор статуса: кольцо цветом фона отделяет точку от самого аватара. */
 export declare const statusDotClass = "absolute bottom-0 right-0 block h-1/4 w-1/4 min-h-2 min-w-2 rounded-[var(--gr-radius-full)] ring-2 ring-[var(--gr-bg)]";
 export declare const statusToneClass: Record<GrAvatarStatus, string>;

package/dist/types/components/GrDataTable/GrDataTable.vue.d.ts

@@ -1,4 +1,4 @@
-import { type GrDataTableSortDir } from './grDataTableSort';
+import type { GrDataTableSortDir } from './grDataTableSort';
 import { type GrDataTableSize } from './grDataTableStyles';
 /**
  * Ключ колонки. Собственные поля строки подсказываются автодополнением, но
@@ -150,6 +150,31 @@ export interface GrDataTableProps<TRow extends Record<string, unknown> = Record<
      * Не заданы — ширины компонент помнит сам.
      */
     columnWidths?: Record<string, number>;
+    /**
+     * Второй ярус строки: колонка с кнопкой раскрытия и блок подробностей под
+     * строкой. Содержимое рисует слот `#detail`.
+     */
+    expandable?: boolean;
+    /** Контролируемый список раскрытых ключей (`v-model:expandedKeys`). */
+    expandedKeys?: Array<string | number>;
+    /** У какой строки есть второй ярус. Остальные кнопки не получают. */
+    expandableRow?: (row: TRow) => boolean;
+    /**
+     * Подгрузка подробностей в момент раскрытия. Без неё содержимое берётся из
+     * самой строки. `signal` обязателен: строку сворачивают чаще, чем ждут.
+     */
+    loadDetail?: (row: TRow, signal: AbortSignal) => Promise<unknown>;
+    /** Раскрыта не больше одной строки. */
+    accordion?: boolean;
+    /**
+     * Рисовать ли служебную колонку с собственной кнопкой раскрытия.
+     *
+     * `false` — колонки нет, и раскрытием управляет разметка потребителя: слоты
+     * ячеек получают `expanded` и `toggleExpand`, чтобы кнопку можно было
+     * поставить в свой столбец действий рядом с остальными. Тогда `aria-expanded`
+     * и доступное имя ложатся на неё же — компоненту их вешать не на что.
+     */
+    expandColumn?: boolean;
 }
 export interface GrDataTableEmits<TRow extends Record<string, unknown> = Record<string, unknown>> {
     (e: 'update:sortKey', value: string): void;
@@ -175,10 +200,32 @@ export interface GrDataTableEmits<TRow extends Record<string, unknown> = Record<
         key: string;
         width: number;
     }): void;
+    (e: 'update:expandedKeys', value: Array<string | number>): void;
+    (e: 'expand', payload: {
+        row: TRow;
+        key: string | number;
+    }): void;
+    (e: 'collapse', payload: {
+        row: TRow;
+        key: string | number;
+    }): void;
+    (e: 'detailLoadError', payload: {
+        row: TRow;
+        key: string | number;
+        error: unknown;
+    }): void;
 }
 declare const __VLS_export: <TRow extends Record<string, unknown> = Record<string, unknown>>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
     props: import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps & __VLS_PrettifyLocal<GrDataTableProps<TRow> & {
+        onCollapse?: ((payload: {
+            row: TRow;
+            key: string | number;
+        }) => any) | undefined;
         "onUpdate:selected"?: ((value: (string | number)[]) => any) | undefined;
+        onExpand?: ((payload: {
+            row: TRow;
+            key: string | number;
+        }) => any) | undefined;
         "onUpdate:sortKey"?: ((value: string) => any) | undefined;
         "onUpdate:sortDir"?: ((value: GrDataTableSortDir) => any) | undefined;
         onSortChange?: ((value: {
@@ -201,6 +248,12 @@ declare const __VLS_export: <TRow extends Record<string, unknown> = Record<strin
             key: string;
             width: number;
         }) => any) | undefined;
+        "onUpdate:expandedKeys"?: ((value: (string | number)[]) => any) | undefined;
+        onDetailLoadError?: ((payload: {
+            row: TRow;
+            key: string | number;
+            error: unknown;
+        }) => any) | undefined;
     }> & (typeof globalThis extends {
         __VLS_PROPS_FALLBACK: infer P;
     } ? P : {});
@@ -213,6 +266,12 @@ declare const __VLS_export: <TRow extends Record<string, unknown> = Record<strin
         clearSort: () => void;
         /** Отметить/снять все выбираемые строки. */
         toggleAll: () => void;
+        /**
+         * Сбросить загруженные подробности: у одной строки либо у всех.
+         * Нужен, когда запись изменилась на сервере, — само по себе раскрытие
+         * держит загруженное, пока строка жива.
+         */
+        invalidateDetail: (key?: import("./composables/useDataTableExpansion").GrDataTableRowKey) => void;
     }>) => void;
     attrs: any;
     slots: {

package/dist/types/components/GrDataTable/composables/useDataTableColumnOrder.d.ts

@@ -0,0 +1,45 @@
+import type { ComputedRef } from 'vue';
+import { useDragSort } from '../../../composables/useDragSort';
+import { useRovingFocus } from '../../../composables/useRovingFocus';
+import type { GrDataColumn } from '../GrDataTable.vue';
+/**
+ * Порядок колонок `GrDataTable`: перестановка указателем и с клавиатуры.
+ *
+ * Закреплённые колонки стоят своими группами у своих краёв, и перенос через
+ * границу группы запрещён — иначе «закреплена слева» перестало бы означать
+ * «слева». Отсюда `pinGroupOf` и проверка `sameGroup` в каждом пути переноса.
+ *
+ * Карты элементов приходят снаружи: их наполняет шаблон, и они же нужны
+ * модулям ширины и раскладки — владеть ими единолично этот модуль не может.
+ */
+export interface UseDataTableColumnOrderOptions<TRow extends Record<string, unknown>> {
+    columns: () => GrDataColumn<TRow>[];
+    /** Контролируемый порядок. `undefined` — компонент помнит порядок сам. */
+    columnOrder: () => string[] | undefined;
+    reorderableColumns: () => boolean;
+    loading: () => boolean;
+    /** Заголовочные ячейки по ключу колонки — цель перетаскивания. */
+    headerCellEls: Map<string, HTMLElement>;
+    /** Ручки переноса по ключу колонки — кольцо роверного фокуса. */
+    columnHandleEls: Map<string, HTMLElement>;
+    onOrderChange: (order: string[], moved: {
+        key: string;
+        from: number;
+        to: number;
+    }) => void;
+    /** Объявление в живой регион: перенос указателем без него беззвучен. */
+    announceMove: (label: string, position: number, count: number) => void;
+}
+export interface DataTableColumnOrder<TRow extends Record<string, unknown>> {
+    orderedColumns: ComputedRef<GrDataColumn<TRow>[]>;
+    columnKeys: ComputedRef<string[]>;
+    pinGroupOf: (col: GrDataColumn<TRow>) => number;
+    indexOfColumn: (key: string) => number;
+    draggingColumnKey: ComputedRef<string | null>;
+    columnDropClass: (index: number) => string;
+    onColumnHandleKeydown: (event: KeyboardEvent, key: string) => Promise<void>;
+    /** Жест и кольцо фокуса отдаются целиком: шаблон зовёт их собственный API. */
+    columnSort: ReturnType<typeof useDragSort<string, number>>;
+    columnRoving: ReturnType<typeof useRovingFocus<string>>;
+}
+export declare function useDataTableColumnOrder<TRow extends Record<string, unknown>>(options: UseDataTableColumnOrderOptions<TRow>): DataTableColumnOrder<TRow>;

package/dist/types/components/GrDataTable/composables/useDataTableColumnWidths.d.ts

@@ -0,0 +1,38 @@
+import type { ComputedRef, Ref } from 'vue';
+import type { GrDataColumn } from '../GrDataTable.vue';
+/** Уже колонки не бывает: в неё перестаёт помещаться даже стрелка сортировки. */
+export declare const MIN_COLUMN_WIDTH = 48;
+/**
+ * Ширина колонок `GrDataTable`: протяжка ручки, клавиатура и сброс к авторазметке.
+ *
+ * Измеренные ширины сюда **приходят снаружи** (`setMeasuredWidths`): замер —
+ * дело раскладки, которая ходит в DOM после отрисовки, а здесь они только
+ * читаются, чтобы ручка называла значение с первого рендера.
+ */
+export interface UseDataTableColumnWidthsOptions<TRow extends Record<string, unknown>> {
+    /** Колонки в текущем порядке — по ним считается минимальная ширина таблицы. */
+    orderedColumns: () => GrDataColumn<TRow>[];
+    /** Контролируемые ширины. `undefined` — компонент помнит их сам. */
+    columnWidths: () => Record<string, number> | undefined;
+    resizableColumns: () => boolean;
+    loading: () => boolean;
+    /** Заголовочные ячейки: стартовая ширина протяжки берётся замером. */
+    headerCellEls: Map<string, HTMLElement>;
+    onWidthsChange: (widths: Record<string, number>) => void;
+    onColumnResize: (key: string, width: number) => void;
+    announceWidth: (label: string, width: number) => void;
+}
+export interface DataTableColumnWidths<TRow extends Record<string, unknown>> {
+    columnWidths: ComputedRef<Record<string, number>>;
+    measuredColumnWidths: Ref<Record<string, number>>;
+    setMeasuredWidths: (widths: Record<string, number>) => void;
+    widthOf: (col: GrDataColumn<TRow>) => string | number | undefined;
+    tableMinWidth: ComputedRef<number | undefined>;
+    resizingKey: Ref<string | null>;
+    onResizerPointerDown: (event: PointerEvent, key: string) => void;
+    onResizerKeydown: (event: KeyboardEvent, key: string) => void;
+    /** Сброс к авторазметке — двойной клик по ручке в шаблоне. */
+    resetColumnWidth: (key: string) => void;
+    resizerValue: (col: GrDataColumn<TRow>) => number;
+}
+export declare function useDataTableColumnWidths<TRow extends Record<string, unknown>>(options: UseDataTableColumnWidthsOptions<TRow>): DataTableColumnWidths<TRow>;

package/dist/types/components/GrDataTable/composables/useDataTableExpansion.d.ts

@@ -0,0 +1,46 @@
+import type { ComputedRef } from 'vue';
+export type GrDataTableDetailState = 'idle' | 'loading' | 'error' | 'ready';
+export type GrDataTableRowKey = string | number;
+/** Подгрузка подробностей строки. `signal` обязателен: строку сворачивают чаще, чем ждут. */
+export type GrDataTableLoadDetail<TRow> = (row: TRow, signal: AbortSignal) => Promise<unknown>;
+/**
+ * Раскрытие строк `GrDataTable`: состояние второго яруса и его подгрузка.
+ *
+ * Всё хранится **по ключу строки**, а не по индексу: сортировка и смена
+ * страницы переставляют строки, и привязка к позиции показывала бы подробности
+ * соседа.
+ *
+ * Асинхронность здесь по образцу `GrAutocomplete/useRemoteOptions`, а не
+ * `useTree`: у дерева ленивая загрузка живёт колбэком без пути ошибки — не
+ * позвал потребитель `resolve`, и узел грузится вечно. Строка обязана уметь
+ * показать отказ и дать повтор.
+ */
+export interface UseDataTableExpansionOptions<TRow extends Record<string, unknown>> {
+    /** Контролируемый список. `undefined` — состояние помнит компонент. */
+    expandedKeys: () => GrDataTableRowKey[] | undefined;
+    /** Идентичность набора: её смена сбрасывает кэш подробностей. */
+    rows: () => TRow[];
+    expandableRow: () => ((row: TRow) => boolean) | undefined;
+    loadDetail: () => GrDataTableLoadDetail<TRow> | undefined;
+    /** Раскрыта не больше одной строки. */
+    accordion: () => boolean;
+    rowKeyValue: (row: TRow) => GrDataTableRowKey;
+    onExpandedChange: (keys: GrDataTableRowKey[]) => void;
+    onExpand: (row: TRow, key: GrDataTableRowKey) => void;
+    onCollapse: (row: TRow, key: GrDataTableRowKey) => void;
+    onDetailLoadError: (row: TRow, key: GrDataTableRowKey, error: unknown) => void;
+}
+export interface DataTableExpansion<TRow extends Record<string, unknown>> {
+    expandedKeys: ComputedRef<Set<GrDataTableRowKey>>;
+    isRowExpandable: (row: TRow) => boolean;
+    isRowExpanded: (row: TRow) => boolean;
+    toggleRow: (row: TRow) => void;
+    collapseAll: () => void;
+    detailStateOf: (row: TRow) => GrDataTableDetailState;
+    detailDataOf: (row: TRow) => unknown;
+    /** Повтор после отказа — и он же ручной перезапрос. */
+    retryDetail: (row: TRow) => void;
+    /** Сбросить загруженное: у ключа либо целиком. */
+    invalidateDetail: (key?: GrDataTableRowKey) => void;
+}
+export declare function useDataTableExpansion<TRow extends Record<string, unknown>>(options: UseDataTableExpansionOptions<TRow>): DataTableExpansion<TRow>;

package/dist/types/components/GrDataTable/composables/useDataTableLayout.d.ts

@@ -0,0 +1,29 @@
+import type { ComputedRef } from 'vue';
+import type { GrDataColumn } from '../GrDataTable.vue';
+/** Служебная колонка выбора в реестре ячеек: своего ключа у неё нет. */
+export declare const SELECT_COLUMN_KEY = "__select__";
+/**
+ * Раскладка закреплённых колонок: смещения липких ячеек и замер шапки.
+ *
+ * Единственный модуль таблицы, который целиком про DOM. Смещения нельзя
+ * вычислить из пропов: колонка может жить на авторазметке, и её ширина
+ * известна только после отрисовки — отсюда замер, а не `computed`.
+ */
+export interface UseDataTableLayoutOptions<TRow extends Record<string, unknown>> {
+    orderedColumns: () => GrDataColumn<TRow>[];
+    columnKeys: () => string[];
+    selectable: () => boolean;
+    resizableColumns: () => boolean;
+    headerCellEls: Map<string, HTMLElement>;
+    /** Пересчитать раскладку заново при смене этих значений. */
+    watchSources: () => unknown;
+    /** Измеренные ширины уезжают модулю ширин: ручка ресайза называет по ним значение. */
+    onMeasuredWidths: (widths: Record<string, number>) => void;
+}
+export interface DataTableLayout<TRow extends Record<string, unknown>> {
+    hasPinnedLeft: ComputedRef<boolean>;
+    pinnedStyleOf: (col: GrDataColumn<TRow>) => Record<string, string> | undefined;
+    pinnedCellClass: (col: GrDataColumn<TRow>, index: number) => string[];
+    measureLayout: () => void;
+}
+export declare function useDataTableLayout<TRow extends Record<string, unknown>>(options: UseDataTableLayoutOptions<TRow>): DataTableLayout<TRow>;

package/dist/types/components/GrDataTable/composables/useDataTableRowKeys.d.ts

@@ -0,0 +1,16 @@
+import type { GrDataTableRowKey } from '../GrDataTable.vue';
+/**
+ * Ключ строки: значение из данных, а при его отсутствии — синтетический.
+ *
+ * Без синтетического строка получила бы `String(undefined ?? '')` — **один и
+ * тот же** ключ на всю таблицу: Vue переиспользовал бы DOM не по назначению, а
+ * выбор одной строки помечал бы выбранными все. Ключ привязан к идентичности
+ * объекта, поэтому переживает сортировку и не зависит от индекса.
+ */
+export interface UseDataTableRowKeysOptions<TRow extends Record<string, unknown>> {
+    rowKey: () => GrDataTableRowKey<TRow>;
+}
+export interface DataTableRowKeys<TRow extends Record<string, unknown>> {
+    rowKeyValue: (row: TRow) => string | number;
+}
+export declare function useDataTableRowKeys<TRow extends Record<string, unknown>>(options: UseDataTableRowKeysOptions<TRow>): DataTableRowKeys<TRow>;

package/dist/types/components/GrDataTable/composables/useDataTableSelection.d.ts

@@ -0,0 +1,32 @@
+import type { ComputedRef } from 'vue';
+/**
+ * Выбор строк `GrDataTable`.
+ *
+ * Считается по **видимым и выбираемым** строкам: они же дают состояние
+ * галочки в шапке. Ключи строк, которых сейчас в наборе нет (отфильтрованы,
+ * на другой странице), из выбора не выпадают — «снять все» убирает только
+ * видимые.
+ *
+ * Как и сортировка, эмитов не знает: наружу сообщает `onSelectedChange`.
+ */
+export interface UseDataTableSelectionOptions<TRow extends Record<string, unknown>> {
+    /** Строки в текущем порядке — уже отсортированные. */
+    rows: () => TRow[];
+    /** Контролируемый список ключей. `undefined` — компонент помнит выбор сам. */
+    selected: () => Array<string | number> | undefined;
+    selectableRow: () => ((row: TRow) => boolean) | undefined;
+    rowKeyValue: (row: TRow) => string | number;
+    onSelectedChange: (keys: Array<string | number>) => void;
+}
+export interface DataTableSelection<TRow extends Record<string, unknown>> {
+    selectedKeys: ComputedRef<Set<string | number>>;
+    isRowSelectable: (row: TRow) => boolean;
+    isRowSelected: (row: TRow) => boolean;
+    /** Видимые выбираемые строки: по их числу шапка гасит «выбрать все». */
+    selectableRows: ComputedRef<TRow[]>;
+    allSelected: ComputedRef<boolean>;
+    someSelected: ComputedRef<boolean>;
+    toggleRow: (row: TRow) => void;
+    toggleAll: () => void;
+}
+export declare function useDataTableSelection<TRow extends Record<string, unknown>>(options: UseDataTableSelectionOptions<TRow>): DataTableSelection<TRow>;

package/dist/types/components/GrDataTable/composables/useDataTableSort.d.ts

@@ -0,0 +1,37 @@
+import type { ComputedRef } from 'vue';
+import type { GrDataColumn, GrDataTableSortCycle } from '../GrDataTable.vue';
+import type { GrDataTableSortDir } from '../grDataTableSort';
+/**
+ * Сортировка `GrDataTable`: состояние, порядок строк и обход состояний по клику.
+ *
+ * Модель эмитов не знает — о смене сообщает колбэком `onSortChange`, а
+ * `update:sortKey`/`update:sortDir`/`sortChange` остаются заботой компонента.
+ * Так же устроен `GrTree`: модель отдельно, эмиты связывает SFC.
+ *
+ * Сравнение значений, включая пустые и смешанные типы, живёт в
+ * `grDataTableSort.ts` и здесь только вызывается.
+ */
+export interface UseDataTableSortOptions<TRow extends Record<string, unknown>> {
+    rows: () => TRow[];
+    /** Контролируемый ключ. `undefined` — компонент помнит порядок сам. */
+    sortKey: () => string | undefined;
+    /** Контролируемое направление. */
+    sortDir: () => GrDataTableSortDir | undefined;
+    initialSortKey: () => string | undefined;
+    initialSortDir: () => GrDataTableSortDir;
+    /** Внешняя сортировка: `rows` приходят уже отсортированными. */
+    externalSort: () => boolean;
+    sortCycle: () => GrDataTableSortCycle;
+    /** Язык сравнения строк; не задан — сравнение по умолчанию рантайма. */
+    locale: () => string | undefined;
+    onSortChange: (key: string, dir: GrDataTableSortDir) => void;
+}
+export interface DataTableSort<TRow extends Record<string, unknown>> {
+    currentSortKey: ComputedRef<string>;
+    currentSortDir: ComputedRef<GrDataTableSortDir>;
+    sortedRows: ComputedRef<TRow[]>;
+    toggleSort: (col: GrDataColumn<TRow>) => void;
+    clearSort: () => void;
+    ariaSortFor: (col: GrDataColumn<TRow>) => 'ascending' | 'descending' | 'none' | undefined;
+}
+export declare function useDataTableSort<TRow extends Record<string, unknown>>(options: UseDataTableSortOptions<TRow>): DataTableSort<TRow>;

package/dist/types/components/GrDataTable/grDataTableStyles.d.ts

@@ -72,3 +72,26 @@ export declare const headerGaps: Record<GrDataTableSize, string>;
 export declare const spinnerSizes: Record<GrDataTableSize, string>;
 /** Стрелка сортировки берёт размер из шкалы `GrIcon` (`xs…lg` → `14…20px`). */
 export declare const sortIconSizes: Record<GrDataTableSize, GrComponentSize>;
+/**
+ * Второй ярус строки: подробности под ней.
+ *
+ * Фон мягче строки набора, а не ярче: подробности обязаны читаться как
+ * вложенное в строку, а не как следующая строка. Акцентная полоса слева
+ * связывает деталь с её строкой, когда между ними уже прокрутили.
+ */
+export declare const detailRowClass = "bg-[var(--gr-datatable-detail-bg,color-mix(in_srgb,var(--gr-muted)_45%,transparent))]";
+export declare const detailCellClass = "border-t border-[var(--gr-brd)] border-l-2 border-l-[var(--gr-datatable-detail-accent,var(--gr-primary))]";
+/** Содержимое липнет к левому краю: иначе при горизонтальной прокрутке его не видно. */
+export declare const detailContentClass = "sticky left-0";
+export declare const detailPaddings: Record<GrDataTableSize, string>;
+/** Колонка кнопки раскрытия — той же ширины, что колонка выбора: шапка не должна съезжать. */
+export declare const expandColumnWidths: Record<"xs" | "sm" | "md" | "lg", string>;
+export declare const expandButtonClass = "inline-flex items-center justify-center rounded-[var(--gr-radius-sm)] text-[var(--gr-muted-fg)] transition-colors hover:bg-[var(--gr-muted)] hover:text-[var(--gr-fg)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--gr-ring)]";
+/**
+ * Поворот шеврона. Своего `motion-reduce:` здесь нет намеренно: движение пакет
+ * гасит одним глобальным блоком в `base.css`, а под `presetMini` этот вариант
+ * вдобавок не генерирует CSS вовсе (`docs/motion.md`).
+ */
+export declare const expandIconClass = "h-4 w-4 transition-transform duration-[var(--gr-duration-fast)]";
+export declare const expandIconOpenClass = "rotate-90";
+export declare const detailErrorClass = "flex flex-wrap items-center gap-2 text-[var(--gr-invalid-text)]";

package/dist/types/components/GrFormField/GrFormField.vue.d.ts

@@ -17,7 +17,13 @@ export interface GrFormFieldProps {
     error?: string | string[];
     /** Подсказка под лейблом/над контролом (можно также через слот `#hint`). */
     hint?: string;
-    /** Помечает поле обязательным (маркер `*` + `aria-required` у контрола). */
+    /**
+     * Помечает поле обязательным: маркер `*` в подписи и `aria-required` у контрола.
+     *
+     * Маркер помечен `aria-hidden`, поэтому объявляет обязательность именно
+     * контрол — а чем именно, решает его роль. Разбор случая `role="group"`,
+     * который `aria-required` не допускает, — на странице компонента.
+     */
     required?: boolean;
     /** Всё поле только для чтения: контролы внутри перестают редактироваться. */
     readonly?: boolean;