GrForm

const grFormConfig: import("@feugene/granum/contract").GranumComponentDescriptor<"GrForm">;

interface GrFormContext {
    /** Реактивная карта ошибок по имени поля. */
    errors: Ref<Record<string, string | undefined>>;
    /** Имена полей, у которых в правилах есть `required` (для маркера `*`). */
    requiredFields: ComputedRef<Set<string>>;
    /**
     * Поля, у которых прямо сейчас идёт асинхронная проверка. Необязательны:
     * тип публичный, и контекст строят руками (в тестах и в своих обёртках) —
     * старая форма контекста продолжает работать.
     */
    validatingFields?: ComputedRef<Set<string>>;
    /** Форма выключена целиком: значение видно, но ничего не редактируется. */
    disabled?: ComputedRef<boolean>;
    /** Поля держат место под строку сообщения, пока ошибки нет (`reserveMessage`). */
    reserveMessage?: ComputedRef<boolean>;
    /** Есть ли для поля правила (тогда `GrFormField` берёт ошибку из формы). */
    hasField: (name: string) => boolean;

function useGrFormContext(): GrFormContext | null;

interface GrFormFileRule {
    /** W3C `accept`: `'image/*,.pdf'`. */
    accept?: string;
    /** Белый список расширений (с точкой или без). */
    extensions?: string[];
    /** Белый список MIME-типов. */
    mimeTypes?: string[];
    /** Предел размера одного файла в мегабайтах. */
    maxSizeMb?: number;
    /** Предел размера одного файла в байтах. Задан вместе с `maxSizeMb` — берётся меньший. */
    maxSizeBytes?: number;
    /** Максимум файлов в наборе. */
    maxCount?: number;
    /** Суммарный размер набора в мегабайтах. */
    maxTotalSizeMb?: number;
    /** Свои валидаторы — тот же тип, что у `GrFormFile` и `v-dropzone`. Идут после встроенных. */
    validators?: FileValidator[];
}

interface GrFormProps<TModel extends object = Record<string, unknown>> {
    /**
     * Реактивный объект данных формы. Поля адресуются по `name` (`GrFormField`),
     * в т.ч. dot-path.
     *
     * Тип дженерик, а не `Record<string, unknown>`: моделью бывает объект чужой
     * библиотеки (`useForm` Inertia, стор), у которого рядом с полями лежат
     * собственные методы. Под словарь он не подходит, и потребителю пришлось бы
     * приводить его через `as unknown as` в каждой форме.
     */
    model: TModel;
    /** Правила валидации по имени поля: `{ email: [{ required: true, type: 'email' }] }`. */
    rules?: GrFormRules;
    /** Валидировать поле при потере фокуса. */
    validateOnBlur?: boolean;
    /** Валидировать поле при каждом изменении значения. */
    validateOnChange?: boolean;
    /** Скроллить к первому невалидному полю после `validate()`. */
    scrollToError?: boolean;
    /** Как прокручивать к полю — к первой ошибке и в `scrollToField`. По умолчанию `smooth`. */
    scrollBehavior?: ScrollBehavior;
    /**
     * Выключить форму целиком — типично на время отправки. Доезжает до контролов
     * через контекст поля, поэтому обходить их по одному не нужно.
     */
    disabled?: boolean;
    /**
     * Все поля формы держат место под строку сообщения: ошибки по submit не
     * сдвигают форму, диалог и панель фиксированной высоты. Поле со своим
     * `reserveMessage` решает за себя.
     */
    reserveMessage?: boolean;
}

interface GrFormEmits<TModel extends object = Record<string, unknown>> {
    /** Форма прошла валидацию по submit. Отдаёт `model`. */
    (e: 'submit', model: TModel): void;
    /** Результат валидации одного поля. */
    (e: 'validate', name: string, valid: boolean, message: string | undefined): void;
    /**
     * Submit не прошёл валидацию. Без этого события «форма невалидна» и «ничего
     * не произошло» выглядят для потребителя одинаково.
     */
    (e: 'invalid', errors: Record<string, string>): void;
}

type GrFormTrigger = 'blur' | 'change' | 'submit';

type GrFormValidatorResult = boolean | string | void;

interface GrFormRule {
    /** Значение обязательно (не пустое). */
    required?: boolean;
    /** Готовый текст ошибки — перекрывает дефолтное сообщение любой проверки этого правила. */
    message?: string;
    /** Минимум: длина для строки/массива, значение для числа. */
    min?: number;
    /** Максимум: длина для строки/массива, значение для числа. */
    max?: number;
    /** Точная длина/значение. */
    len?: number;
    /** Регулярное выражение (проверяется по `String(value)`). */
    pattern?: RegExp;
    /** Встроенный тип-валидатор. */
    type?: 'email' | 'url';
    /** Ограничения для значения `File | File[]`: тип, размер, количество. */
    file?: GrFormFileRule;
    /** Кастомный (в т.ч. async) валидатор. Второй аргумент — весь `model`. */
    validator?: (value: unknown, model: Record<string, unknown>) => GrFormValidatorResult | Promise<GrFormValidatorResult>;

type GrFormRules = Record<string, GrFormRule | GrFormRule[]>;

type GrFormRuleFailure = 'required' | 'min' | 'max' | 'len' | 'pattern' | 'email' | 'url' | 'file' | 'invalid';

type GrFormMessageResolver = (kind: GrFormRuleFailure, rule: GrFormRule, params: Record<string, unknown>) => string;
/** Подпись `t()` из `useGranularityTranslations()`: ключ, фолбэк, параметры. */
export type GrFormMessageTranslate = (key: string, fallback: string, params?: Record<string, unknown>) => string;
/**
 * Дефолтный резолвер сообщений: `rule.message` сильнее всего, иначе ключ
 * `gr.form.<kind>` из локали, иначе английский фолбэк.
 *
 * Вынесен из `GrForm.vue` и экспортируется наружу не «на всякий случай»:
 * `runFieldRules` публичен, но без резолвера бесполезен — любой, кто хочет
 * прогнать те же правила вне формы, обязан был написать свой.
 */
export declare function createGrFormMessageResolver(t: GrFormMessageTranslate, locale?: () => string | undefined): GrFormMessageResolver;
/** Пустое значение: `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>;

type GrFormMessageTranslate = (key: string, fallback: string, params?: Record<string, unknown>) => string;
/**
 * Дефолтный резолвер сообщений: `rule.message` сильнее всего, иначе ключ
 * `gr.form.<kind>` из локали, иначе английский фолбэк.
 *
 * Вынесен из `GrForm.vue` и экспортируется наружу не «на всякий случай»:
 * `runFieldRules` публичен, но без резолвера бесполезен — любой, кто хочет
 * прогнать те же правила вне формы, обязан был написать свой.
 */
export declare function createGrFormMessageResolver(t: GrFormMessageTranslate, locale?: () => string | undefined): GrFormMessageResolver;
/** Пустое значение: `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>;

function createGrFormMessageResolver(t: GrFormMessageTranslate, locale?: () => string | undefined): GrFormMessageResolver;
/** Пустое значение: `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>;

function isEmpty(value: unknown): boolean;

function getByPath(obj: Record<string, unknown>, path: string): unknown;

function setByPath(obj: Record<string, unknown>, path: string, value: unknown): void;

function runFieldRules(value: unknown, rules: GrFormRule[], model: Record<string, unknown>, resolveMessage: GrFormMessageResolver): Promise<string | undefined>;

type GrFormInstance = ComponentExposed<typeof GrFormComponent>;