@feugene/granularity 0.11.0 → 0.13.0

package/dist/types/src/components/GrConfigProvider/context.d.ts

@@ -0,0 +1,131 @@
+import { type ComputedRef, type InjectionKey } from 'vue';
+/**
+ * Контекст `GrConfigProvider` — глобальные дефолты для вложенных GR-компонентов:
+ * размер контролов и per-component дефолтные пропсы.
+ *
+ * Компоненты читают его через {@link useGrConfig} (или хелперы ниже) и используют
+ * как fallback, когда соответствующий проп не задан на самом компоненте. Провайдер
+ * можно вкладывать — дочерний мержится поверх родительского.
+ */
+/**
+ * Размеры, которыми оперирует провайдер. Это «размеры контролов» — общий
+ * знаменатель формных компонентов, а не объединение всех size-шкал пакета
+ * (у оверлеев есть свои `xl`/`full`, у слайдера нет `xs`).
+ */
+export declare const GR_COMPONENT_SIZES: readonly ["xs", "sm", "md", "lg"];
+export type GrComponentSize = typeof GR_COMPONENT_SIZES[number];
+/**
+ * Открытый реестр компонентов, у которых есть настраиваемые через конфиг пропы.
+ *
+ * Пустой по умолчанию: каждый компонент дополняет его **из своей папки** через
+ * declaration merging (`GrButton/defaults.ts` и т. п.). Так провайдер не знает
+ * ни имён, ни типов конкретных компонентов — контракт объявляет тот, кто им
+ * владеет, а не общий модуль.
+ *
+ * Практическое следствие: реестр состоит ровно из тех компонентов, которые
+ * попали в граф типов потребителя. Импортировали только `GrButton` — в
+ * `componentDefaults` типизирована только кнопка, типы `GrBadge` в проект не
+ * приезжают.
+ *
+ * ```ts
+ * // GrButton/defaults.ts
+ * declare module '../GrConfigProvider/context' {
+ *   interface GrComponentDefaultsRegistry {
+ *     GrButton: GrButtonConfigurableProps
+ *   }
+ * }
+ * ```
+ */
+export interface GrComponentDefaultsRegistry {
+}
+/** Имя компонента, у которого есть настраиваемые через конфиг пропы. */
+export type GrConfigurableComponent = keyof GrComponentDefaultsRegistry;
+/**
+ * Дефолтные пропсы по имени компонента: `{ GrButton: { variant: 'secondary' } }`.
+ *
+ * Набор ключей закрыт реестром, а не `Record<string, unknown>`: через конфиг
+ * должны настраиваться только «оформительские» пропы. Пустить туда что угодно —
+ * значит разрешить задать глобальный `modelValue` или обработчик и получить баг,
+ * который ищется часами.
+ */
+export type GrComponentDefaults = {
+    [TComponent in GrConfigurableComponent]?: Partial<GrComponentDefaultsRegistry[TComponent]>;
+};
+type GrDefaultsOf<TComponent extends GrConfigurableComponent> = Partial<GrComponentDefaultsRegistry[TComponent]>;
+export interface GrConfigContext {
+    /** Дефолтный размер контролов (если проп `size` не задан на компоненте). */
+    size: ComputedRef<GrComponentSize | undefined>;
+    /** Дефолтные пропсы по компонентам. */
+    componentDefaults: ComputedRef<GrComponentDefaults>;
+}
+export declare const GR_CONFIG_KEY: InjectionKey<GrConfigContext>;
+/** Возвращает ближайший `GrConfigProvider` или пустой конфиг, если провайдера нет. */
+export declare function useGrConfig(): GrConfigContext;
+/**
+ * Источник конфига для {@link resolveGrConfig}: сам контекст, `AppContext` или
+ * инстанс компонента — у двух последних читается `provides`.
+ */
+export type GrConfigSource = GrConfigContext | {
+    provides?: Record<symbol | string, unknown>;
+};
+/**
+ * Конфиг там, где `inject` недоступен — вне `setup`: в директивах, императивных
+ * сервисах, утилитах. Порядок: явный контекст → `provides` источника → `inject`
+ * (если есть активный инстанс) → пустой конфиг.
+ *
+ * Важно понимать границу: `provides` у `AppContext` содержит только то, что
+ * роздано через `app.provide()`. Значения от `<GrConfigProvider>` живут в дереве
+ * компонентов, и достать их можно лишь оттуда, где это дерево ещё есть — то есть
+ * захватом в `setup`. Просто передать `appContext` в отрыве от дерева
+ * недостаточно; см. `SPEC-GrConfig-resolver.md`.
+ */
+export declare function resolveGrConfig(source?: GrConfigSource | null): GrConfigContext;
+export type UseGrComponentSizeOptions<TSize extends string> = {
+    /**
+     * Имя компонента, чтобы учесть точечный `componentDefaults[Component].size`.
+     * Без него читается только глобальный `size` провайдера.
+     */
+    component?: GrConfigurableComponent;
+    /** Размер, когда ни проп, ни конфиг ничего не дали. По умолчанию `md`. */
+    fallback?: TSize;
+    /**
+     * Размеры, которые компонент реально умеет. Значение из конфига вне этого
+     * списка игнорируется в пользу `fallback`.
+     *
+     * Обязателен для компонентов, у которых size-шкала уже общей (`GrSlider`,
+     * `GrRating`, `GrSwitch`, `GrLink`, `GrStatistic` не знают про `xs`): без него
+     * `<GrConfigProvider size="xs">` дал бы `sizeMap['xs'] === undefined`, то есть
+     * компонент без размерных классов — молча, без ошибки сборки.
+     */
+    supported?: readonly TSize[];
+};
+/** Сброс дедупликации предупреждений. Внутреннее API — нужно тестам. */
+export declare function resetUnsupportedSizeWarnings(): void;
+/**
+ * Эффективный размер компонента. Приоритет:
+ * локальный проп → `componentDefaults[Component].size` → глобальный `size`
+ * провайдера → `fallback`. Точечная настройка компонента должна побеждать
+ * общую — иначе `componentDefaults` нельзя было бы использовать как исключение
+ * из глобального правила.
+ *
+ * Передавайте `size` геттером, чтобы сохранить реактивность.
+ *
+ * Локальный проп не проверяется по `supported`: он уже сужен типом пропа самого
+ * компонента, и передать туда лишнее — явная ошибка вызывающего кода. Проверка
+ * нужна конфигу: это глобальный канал, который не знает, кто его читает.
+ */
+export declare function useGrComponentSize<TSize extends string = GrComponentSize>(localSize: () => TSize | undefined, options?: UseGrComponentSizeOptions<TSize>): ComputedRef<TSize>;
+/** Дефолтные пропсы конкретного компонента из ближайшего провайдера. */
+export declare function useGrComponentDefaults<TComponent extends GrConfigurableComponent>(name: TComponent): ComputedRef<GrDefaultsOf<TComponent>>;
+/**
+ * Эффективное значение «оформительского» пропа: локальный проп →
+ * `componentDefaults[Component][prop]` → собственный дефолт компонента.
+ *
+ * Обязательное условие на стороне компонента: у такого пропа в `withDefaults`
+ * должен стоять `undefined`, а «настоящий» дефолт — переехать сюда, в `fallback`.
+ * Иначе конфиг не сработает никогда: Vue отдаёт `props.x` уже с подставленным
+ * дефолтом, и отличить «пользователь передал значение» от «сработал дефолт»
+ * изнутри компонента невозможно.
+ */
+export declare function useGrComponentProp<TComponent extends GrConfigurableComponent, TProp extends keyof GrDefaultsOf<TComponent>>(component: TComponent, prop: TProp, localValue: () => GrDefaultsOf<TComponent>[TProp], fallback: NonNullable<GrDefaultsOf<TComponent>[TProp]>): ComputedRef<NonNullable<GrDefaultsOf<TComponent>[TProp]>>;
+export {};

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

@@ -0,0 +1,5 @@
+export { default } from './GrConfigProvider.vue';
+export { default as GrConfigProvider } from './GrConfigProvider.vue';
+export type { GrComponentDefaults, GrComponentSize } from './GrConfigProvider.vue';
+export { GR_COMPONENT_SIZES, GR_CONFIG_KEY, type GrComponentDefaultsRegistry, type GrConfigContext, type GrConfigSource, type GrConfigurableComponent, resolveGrConfig, useGrComponentDefaults, useGrComponentProp, useGrComponentSize, type UseGrComponentSizeOptions, useGrConfig, } from './context';
+export { grConfigProviderConfig } from './config';

package/dist/types/src/components/GrConfirmDialog/GrConfirmDialog.vue.d.ts

@@ -94,12 +94,12 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     confirmDisabled: boolean;
     closeOnConfirm: boolean;
 }>>> & Readonly<{
-    "onUpdate:modelValue"?: ((value: boolean) => any) | undefined;
     onCancel?: (() => any) | undefined;
+    "onUpdate:modelValue"?: ((value: boolean) => any) | undefined;
     onConfirm?: (() => any) | undefined;
 }>, {
-    title: string;
     size: GrDialogSize;
+    title: string;
     error: ResponseErrorInfo | null;
     closeOnBackdrop: boolean;
     closeOnEsc: boolean;

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

@@ -11,18 +11,54 @@ export interface GrDataTableProps<TRow extends Record<string, unknown> = Record<
     columns: GrDataColumn[];
     /** Ключ строки или функция-резолвер. По умолчанию — поле `'id'`. */
     rowKey?: GrDataTableRowKey<TRow>;
-    /** Ключ колонки для начальной сортировки. */
+    /** Ключ колонки для начальной сортировки (uncontrolled-режим). */
     initialSortKey?: string;
-    /** Направление начальной сортировки. */
+    /** Направление начальной сортировки (uncontrolled-режим). */
     initialSortDir?: 'asc' | 'desc';
+    /** Контролируемый ключ сортировки: `v-model:sortKey`. Задаёт controlled-режим. */
+    sortKey?: string;
+    /** Контролируемое направление сортировки: `v-model:sortDir`. */
+    sortDir?: 'asc' | 'desc';
+    /**
+     * Внешняя сортировка (например серверная): компонент НЕ сортирует `rows`
+     * сам, а только сообщает о смене через `update:sortKey`/`update:sortDir`/
+     * `sort-change`. `rows` при этом должны приходить уже отсортированными.
+     */
+    externalSort?: boolean;
+    /**
+     * Выбор строк: добавляет ведущую колонку с чекбоксами (+ «выбрать все» в шапке).
+     * Выбранные ключи строк — через `v-model:selected`.
+     */
+    selectable?: boolean;
+    /** Контролируемый список выбранных ключей строк: `v-model:selected`. */
+    selected?: Array<string | number>;
+    /**
+     * Состояние загрузки: тело таблицы заменяется строкой-индикатором.
+     * `empty`-состояние при этом не показывается.
+     */
+    loading?: boolean;
+    /** Текст индикатора загрузки. i18n: fallback `gr.dataTable.loading`. */
+    loadingText?: string;
     density?: GrTableDensity;
     caption?: string;
     ariaLabel?: string;
     ariaLabelledby?: string;
     regionLabel?: string;
+    /** Прилипающий заголовок при вертикальном скролле (нужен `maxHeight`). */
+    stickyHeader?: boolean;
+    /** Максимальная высота таблицы (вертикальный скролл). Число — в пикселях. */
+    maxHeight?: string | number;
 }
 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>> & (typeof globalThis extends {
+    props: import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps & __VLS_PrettifyLocal<GrDataTableProps<TRow> & {
+        "onUpdate:sortKey"?: ((value: string) => any) | undefined;
+        "onUpdate:sortDir"?: ((value: "desc" | "asc") => any) | undefined;
+        "onSort-change"?: ((value: {
+            key: string;
+            dir: "asc" | "desc";
+        }) => any) | undefined;
+        "onUpdate:selected"?: ((value: (string | number)[]) => any) | undefined;
+    }> & (typeof globalThis extends {
         __VLS_PROPS_FALLBACK: infer P;
     } ? P : {});
     expose: (exposed: {}) => void;
@@ -38,7 +74,15 @@ declare const __VLS_export: <TRow extends Record<string, unknown> = Record<strin
     } & {
         foot?: (props: {}) => any;
     };
-    emit: {};
+    emit: {
+        (e: "update:sortKey", value: string): void;
+        (e: "update:sortDir", value: "asc" | "desc"): void;
+        (e: "sort-change", value: {
+            key: string;
+            dir: "asc" | "desc";
+        }): void;
+        (e: "update:selected", value: Array<string | number>): void;
+    };
 }>) => import("vue").VNode & {
     __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
 };

package/dist/types/src/components/GrDialog/GrDialog.vue.d.ts

@@ -47,8 +47,8 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
 }>>> & Readonly<{
     "onUpdate:modelValue"?: ((value: boolean) => any) | undefined;
 }>, {
-    title: string;
     size: GrDialogSize;
+    title: string;
     closeOnBackdrop: boolean;
     closeOnEsc: boolean;
     showCloseButton: boolean;

package/dist/types/src/components/GrDialogService/store.d.ts

@@ -1,3 +1,6 @@
+import type { Raw } from 'vue';
+import type { GrConfigContext } from '../GrConfigProvider/context';
+import type { GranularityI18nLike } from '../../internal/granularityI18n';
 import type { DialogBaseOptions, DialogKind, DialogOnConfirm, DialogResult } from './types';
 /**
  * Внутреннее описание одного запроса диалога в очереди. Создаётся методами
@@ -12,6 +15,21 @@ export interface DialogRequest {
     onConfirm?: DialogOnConfirm<any>;
     /** Резолвит промис вызова детальным результатом `{ action, value }`. */
     resolve: (result: DialogResult<any>) => void;
+    /**
+     * Конфиг и i18n, захваченные в месте вызова сервиса (в `setup`, где вызывающий
+     * компонент ещё находится внутри дерева провайдера). Хост монтируется в
+     * `document.body` вне дерева, поэтому сам их не увидит — см.
+     * `SPEC-GrConfig-resolver.md`.
+     *
+     * Лежат в запросе, а не в модульной переменной: два поддерева с разными
+     * провайдерами должны получать каждое свой конфиг.
+     *
+     * `Raw<…>` обязателен: очередь — `reactive`, а он разворачивает вложенные рефы.
+     * Без `markRaw` контекст превратился бы в объект значений, `size.value` стало
+     * бы `undefined`, и мост молча перестал бы работать.
+     */
+    config?: Raw<GrConfigContext> | null;
+    i18n?: Raw<GranularityI18nLike> | null;
 }
 /**
  * Модульный синглтон очереди диалогов: единый источник правды для всех

package/dist/types/src/components/GrDivider/GrDivider.vue.d.ts

@@ -0,0 +1,58 @@
+/**
+ * GrDivider — разделитель контента.
+ *
+ * - `orientation="horizontal"` (по умолчанию) — линия на всю ширину; с `label`
+ *   или default-слотом рисует текст по центру/краю между отрезками линии.
+ * - `orientation="vertical"` — тонкая вертикальная линия (для inline-разделения,
+ *   например в тулбарах).
+ */
+export type GrDividerOrientation = 'horizontal' | 'vertical';
+export type GrDividerAlign = 'start' | 'center' | 'end';
+type __VLS_Props = {
+    orientation?: GrDividerOrientation;
+    label?: string;
+    align?: GrDividerAlign;
+};
+declare var __VLS_1: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToOption<__VLS_Props>, {
+    orientation: string;
+    label: undefined;
+    align: string;
+}>>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToOption<__VLS_Props>, {
+    orientation: string;
+    label: undefined;
+    align: string;
+}>>> & Readonly<{}>, {
+    label: string;
+    align: GrDividerAlign;
+    orientation: GrDividerOrientation;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_TypePropsToOption<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? {
+        type: import('vue').PropType<Required<T>[K]>;
+    } : {
+        type: import('vue').PropType<T[K]>;
+        required: true;
+    };
+};
+type __VLS_WithDefaults<P, D> = {
+    [K in keyof Pick<P, keyof P>]: K extends keyof D ? __VLS_PrettifyLocal<P[K] & {
+        default: D[K];
+    }> : P[K];
+};
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};
+type __VLS_PrettifyLocal<T> = (T extends any ? {
+    [K in keyof T]: T[K];
+} : {
+    [K in keyof T as K]: T[K];
+}) & {};

package/dist/types/src/components/GrDivider/config.d.ts

@@ -0,0 +1 @@
+export declare const grDividerConfig: import("@feugene/unocss-preset-granular").GranularComponentDescriptor<"GrDivider">;

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

@@ -0,0 +1,4 @@
+export { default } from './GrDivider.vue';
+export { default as GrDivider } from './GrDivider.vue';
+export type { GrDividerAlign, GrDividerOrientation } from './GrDivider.vue';
+export { grDividerConfig } from './config';

package/dist/types/src/components/GrDrawer/GrDrawer.vue.d.ts

@@ -15,13 +15,13 @@ export interface GrDrawerProps {
     /** i18n-friendly aria-label для кнопки закрытия. */
     closeLabel?: string;
 }
-declare var __VLS_47: {}, __VLS_68: {}, __VLS_70: {};
+declare var __VLS_46: {}, __VLS_67: {}, __VLS_69: {};
 type __VLS_Slots = {} & {
-    title?: (props: typeof __VLS_47) => any;
+    title?: (props: typeof __VLS_46) => any;
 } & {
-    default?: (props: typeof __VLS_68) => any;
+    default?: (props: typeof __VLS_67) => any;
 } & {
-    footer?: (props: typeof __VLS_70) => any;
+    footer?: (props: typeof __VLS_69) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToOption<GrDrawerProps>, {
     title: undefined;
@@ -42,8 +42,8 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
 }>>> & Readonly<{
     "onUpdate:modelValue"?: ((value: boolean) => any) | undefined;
 }>, {
-    title: string;
     size: GrDrawerSize;
+    title: string;
     closeOnBackdrop: boolean;
     closeOnEsc: boolean;
     closeLabel: string;

package/dist/types/src/components/GrDropdown/GrDropdown.vue.d.ts

@@ -11,12 +11,19 @@ export interface GrDropdownProps {
     /** Куда телепортировать панель (`body` по умолчанию). */
     teleportTo?: string | HTMLElement;
 }
+declare function onTriggerKeydown(event: KeyboardEvent): void;
 declare function toggle(): void;
 declare function close(): void;
 declare var __VLS_1: {
     open: boolean;
     toggle: typeof toggle;
     close: typeof close;
+    triggerProps: {
+        'aria-haspopup': "menu";
+        'aria-expanded': boolean;
+        'aria-controls': string | undefined;
+        onKeydown: typeof onTriggerKeydown;
+    };
 }, __VLS_15: {
     close: typeof close;
 };
@@ -38,8 +45,8 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     contentClass: string;
     teleportTo: string;
 }>>> & Readonly<{}>, {
-    width: GrDropdownWidth;
     align: GrDropdownAlign;
+    width: GrDropdownWidth;
     closeOnContentClick: boolean;
     contentClass: string;
     teleportTo: string | HTMLElement;

package/dist/types/src/components/GrDropdownMenu/GrDropdownMenu.vue.d.ts

@@ -22,6 +22,12 @@ declare var __VLS_9: {
     open: boolean;
     toggle: () => void;
     close: () => void;
+    triggerProps: {
+        'aria-haspopup': "menu";
+        'aria-expanded': boolean;
+        'aria-controls': string | undefined;
+        onKeydown: (event: KeyboardEvent) => void;
+    };
 }, __VLS_18: {
     close: () => void;
 };
@@ -49,8 +55,8 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     borderBottom: boolean;
     listClass: string;
 }>>> & Readonly<{}>, {
-    width: GrDropdownMenuWidth;
     align: GrDropdownMenuAlign;
+    width: GrDropdownMenuWidth;
     borderBottom: boolean;
     borderTop: boolean;
     closeOnContentClick: boolean;

package/dist/types/src/components/GrDropdownMenu/GrDropdownMenuItem.vue.d.ts

@@ -23,9 +23,9 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     variant: string;
 }>>> & Readonly<{}>, {
     variant: GrDropdownMenuItemVariant;
+    align: GrDropdownMenuItemAlign;
     disabled: boolean;
     as: string | Component;
-    align: GrDropdownMenuItemAlign;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;

package/dist/types/src/components/GrFileUpload/GrFileUpload.vue.d.ts

@@ -155,11 +155,11 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     onError?: ((error: unknown) => any) | undefined;
     onStateChange?: ((state: GrUploadState) => any) | undefined;
 }>, {
-    disabled: boolean;
     name: string;
-    headers: Record<string, string>;
-    placeholder: string;
     multiple: boolean;
+    disabled: boolean;
+    placeholder: string;
+    headers: Record<string, string>;
     withCredentials: boolean;
     action: string;
     request: GrFileUploadRequest;

package/dist/types/src/components/GrForm/GrForm.vue.d.ts

@@ -0,0 +1,93 @@
+import { type GrFormRules, type GrFormTrigger } from './validation';
+export type { GrFormRule, GrFormRules, GrFormTrigger, GrFormValidatorResult, } from './validation';
+/**
+ * Публичный GR-примитив «Form» — оркестрация валидации над `GrFormField`.
+ *
+ * Модель формы (`v-model`-объект приложения) + декларативные `rules` по имени поля.
+ * Форма прогоняет правила, раскладывает ошибки по контексту, скроллит к первой
+ * ошибке и эмитит `submit` только при валидной форме. Императивный API — через
+ * template ref (`validate` / `validateField` / `clearValidate` / `resetFields` /
+ * `scrollToField`).
+ */
+export interface GrFormProps {
+    /** Реактивный объект данных формы. Поля адресуются по `name` (`GrFormField`), в т.ч. dot-path. */
+    model: Record<string, unknown>;
+    /** Правила валидации по имени поля: `{ email: [{ required: true, type: 'email' }] }`. */
+    rules?: GrFormRules;
+    /** Валидировать поле при потере фокуса. */
+    validateOnBlur?: boolean;
+    /** Валидировать поле при каждом изменении значения. */
+    validateOnChange?: boolean;
+    /** Скроллить к первому невалидному полю после `validate()`. */
+    scrollToError?: boolean;
+    scrollBehavior?: ScrollBehavior;
+}
+declare function validateField(name: string, trigger?: GrFormTrigger): Promise<boolean>;
+declare function validate(): Promise<boolean>;
+declare function clearValidate(names?: string | string[]): void;
+declare function resetFields(): void;
+declare function scrollToField(name: string): void;
+declare var __VLS_1: {
+    validate: typeof validate;
+    errors: Record<string, string | undefined>;
+};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToOption<GrFormProps>, {
+    rules: undefined;
+    validateOnBlur: boolean;
+    validateOnChange: boolean;
+    scrollToError: boolean;
+    scrollBehavior: string;
+}>>, {
+    validate: typeof validate;
+    validateField: typeof validateField;
+    clearValidate: typeof clearValidate;
+    resetFields: typeof resetFields;
+    scrollToField: typeof scrollToField;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    submit: (model: Record<string, unknown>) => void;
+    validate: (name: string, valid: boolean, message: string | undefined) => void;
+}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToOption<GrFormProps>, {
+    rules: undefined;
+    validateOnBlur: boolean;
+    validateOnChange: boolean;
+    scrollToError: boolean;
+    scrollBehavior: string;
+}>>> & Readonly<{
+    onSubmit?: ((model: Record<string, unknown>) => any) | undefined;
+    onValidate?: ((name: string, valid: boolean, message: string | undefined) => any) | undefined;
+}>, {
+    scrollBehavior: ScrollBehavior;
+    rules: GrFormRules;
+    validateOnBlur: boolean;
+    validateOnChange: boolean;
+    scrollToError: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_TypePropsToOption<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? {
+        type: import('vue').PropType<Required<T>[K]>;
+    } : {
+        type: import('vue').PropType<T[K]>;
+        required: true;
+    };
+};
+type __VLS_WithDefaults<P, D> = {
+    [K in keyof Pick<P, keyof P>]: K extends keyof D ? __VLS_PrettifyLocal<P[K] & {
+        default: D[K];
+    }> : P[K];
+};
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};
+type __VLS_PrettifyLocal<T> = (T extends any ? {
+    [K in keyof T]: T[K];
+} : {
+    [K in keyof T as K]: T[K];
+}) & {};

package/dist/types/src/components/GrForm/config.d.ts

@@ -0,0 +1 @@
+export declare const grFormConfig: import("@feugene/unocss-preset-granular").GranularComponentDescriptor<"GrForm">;

package/dist/types/src/components/GrForm/context.d.ts

@@ -0,0 +1,27 @@
+import { type ComputedRef, type InjectionKey, type Ref } from 'vue';
+import type { GrFormTrigger } from './validation';
+/**
+ * Контекст формы, который `GrForm` предоставляет своим `GrFormField`.
+ *
+ * Ключевая идея архитектуры: контролы (`GrInput`/`GrSelect`/`GrAutocomplete`/…) НЕ
+ * знают про форму — они, как и раньше, читают только контекст `GrFormField`
+ * (`id`/`aria-describedby`/`invalid`/`required`). А `GrFormField`, находясь внутри
+ * `GrForm`, подтягивает свою ошибку и признак обязательности из ЭТОГО контекста по
+ * `name` и триггерит валидацию поля. Так оркестрация добавляется сверху, не трогая
+ * ни один контрол.
+ */
+export interface GrFormContext {
+    /** Реактивная карта ошибок по имени поля. */
+    errors: Ref<Record<string, string | undefined>>;
+    /** Имена полей, у которых в правилах есть `required` (для маркера `*`). */
+    requiredFields: ComputedRef<Set<string>>;
+    /** Есть ли для поля правила (тогда `GrFormField` берёт ошибку из формы). */
+    hasField: (name: string) => boolean;
+    /** Регистрирует корневой элемент поля (для scroll-to-error). Возвращает unregister. */
+    registerField: (name: string, getEl: () => HTMLElement | null) => () => void;
+    /** Валидирует одно поле (с учётом триггера и настроек формы). */
+    validateField: (name: string, trigger?: GrFormTrigger) => Promise<boolean>;
+}
+export declare const GR_FORM_KEY: InjectionKey<GrFormContext>;
+/** Возвращает контекст формы или `null`, если поле вне `GrForm`. */
+export declare function useGrFormContext(): GrFormContext | null;

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

@@ -0,0 +1,6 @@
+export { default } from './GrForm.vue';
+export { default as GrForm } from './GrForm.vue';
+export { grFormConfig } from './config';
+export { GR_FORM_KEY, type GrFormContext, useGrFormContext } from './context';
+export type { GrFormProps, GrFormRule, GrFormRules, GrFormTrigger, GrFormValidatorResult, } from './GrForm.vue';
+export { getByPath, type GrFormMessageResolver, type GrFormRuleFailure, isEmpty, runFieldRules, } from './validation';

package/dist/types/src/components/GrForm/validation.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Движок валидации `GrForm` — чистый (без Vue/i18n), тестируется изолированно.
+ *
+ * Правило описывает набор проверок значения поля; `runFieldRules` прогоняет их по
+ * порядку и возвращает первое сообщение об ошибке (или `undefined`, если валидно).
+ * Сообщения резолвит потребитель (компонент) через `resolveMessage` — так i18n и
+ * дефолтные тексты остаются в компоненте, а движок ничего о них не знает.
+ */
+export type GrFormTrigger = 'blur' | 'change' | 'submit';
+/** Результат кастомного валидатора: `true`/void — ок; `false` — ошибка (дефолт-текст); строка — текст ошибки. */
+export type GrFormValidatorResult = boolean | string | void;
+export interface GrFormRule {
+    /** Значение обязательно (не пустое). */
+    required?: boolean;
+    /** Готовый текст ошибки — перекрывает дефолтное сообщение любой проверки этого правила. */
+    message?: string;
+    /** Минимум: длина для строки/массива, значение для числа. */
+    min?: number;
+    /** Максимум: длина для строки/массива, значение для числа. */
+    max?: number;
+    /** Точная длина/значение. */
+    len?: number;
+    /** Регулярное выражение (проверяется по `String(value)`). */
+    pattern?: RegExp;
+    /** Встроенный тип-валидатор. */
+    type?: 'email' | 'url';
+    /** Кастомный (в т.ч. async) валидатор. Второй аргумент — весь `model`. */
+    validator?: (value: unknown, model: Record<string, unknown>) => GrFormValidatorResult | Promise<GrFormValidatorResult>;
+    /** Когда правило срабатывает. По умолчанию — на любом триггере (blur/change/submit). */
+    trigger?: GrFormTrigger | GrFormTrigger[];
+}
+export type GrFormRules = Record<string, GrFormRule | GrFormRule[]>;
+/** Вид сработавшей проверки — ключ для дефолтного i18n-сообщения. */
+export type GrFormRuleFailure = 'required' | 'min' | 'max' | 'len' | 'pattern' | 'email' | 'url' | 'invalid';
+export type GrFormMessageResolver = (kind: GrFormRuleFailure, rule: GrFormRule, params: Record<string, unknown>) => string;
+/** Пустое значение: `null`/`undefined`/пустая (или пробельная) строка/пустой массив. */
+export declare function isEmpty(value: unknown): boolean;
+/** Достаёт значение из объекта по dot-path (`address.city`). */
+export declare function getByPath(obj: Record<string, unknown>, path: string): unknown;
+/** Записывает значение в объект по dot-path (создаёт промежуточные объекты). */
+export declare function setByPath(obj: Record<string, unknown>, path: string, value: unknown): void;
+/** Нормализует правило(а) поля в массив. */
+export declare function toRuleArray(rules: GrFormRule | GrFormRule[] | undefined): GrFormRule[];
+/** Правила поля, применимые для данного триггера (undefined = все). */
+export declare function rulesForTrigger(rules: GrFormRule[], trigger?: GrFormTrigger): GrFormRule[];
+/** Есть ли среди правил `required` (для маркера обязательности в поле). */
+export declare function rulesRequired(rules: GrFormRule[]): boolean;
+/**
+ * Прогоняет правила по порядку, возвращает первое сообщение об ошибке или `undefined`.
+ * Пустое необязательное значение проходит все проверки (кроме `required`).
+ */
+export declare function runFieldRules(value: unknown, rules: GrFormRule[], model: Record<string, unknown>, resolveMessage: GrFormMessageResolver): Promise<string | undefined>;