form-father 0.2.11 → 0.4.0

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/types/adapters.d.ts

@@ -0,0 +1,28 @@
+import { type ValidatorFieldElement, type ValidatorResult } from './validators';
+type MaybePromise<T> = T | Promise<T>;
+export type SchemaParseResult = {
+    success: true;
+    data?: unknown;
+} | {
+    success: false;
+    error?: unknown;
+    issues?: Array<{
+        message?: string;
+    }>;
+};
+export type SchemaLike = {
+    safeParse?: (value: unknown) => MaybePromise<SchemaParseResult>;
+    parse?: (value: unknown) => MaybePromise<unknown>;
+} | ((value: unknown) => MaybePromise<boolean | ValidatorResult | void>);
+export type AdapterValidator = (value: string, $input: ValidatorFieldElement, $form: HTMLElement, params?: any) => MaybePromise<boolean | ValidatorResult>;
+export interface SchemaValidatorOptions {
+    message?: string | ((error: unknown) => string);
+    mapValue?: (value: string, $input: ValidatorFieldElement, $form: HTMLElement, params?: any) => unknown;
+}
+export interface RegisterSchemaValidatorOptions extends SchemaValidatorOptions {
+    override?: boolean;
+}
+export declare function createSchemaValidator(schema: SchemaLike, options?: SchemaValidatorOptions): AdapterValidator;
+export declare function registerSchemaValidator(name: string, schema: SchemaLike, defaultMessage: string, options?: RegisterSchemaValidatorOptions): void;
+export declare function createFieldValidator(predicate: (value: string, $input: ValidatorFieldElement, $form: HTMLElement, params?: any) => MaybePromise<boolean>, message?: string): AdapterValidator;
+export {};

package/dist/types/index.d.ts

@@ -1,14 +1,50 @@
 export * from './validators';
+export * from './adapters';
 export { serializeToFormData, isEmailValid, isUrlValid, parseCommonResponseProperties, closest, isPhoneValid, blockScrollBody, unblockScrollBody, serializeFormToJSON, } from './helpers';
 export type ValidationRule = string | {
     rule: string;
     params?: any;
 };
+export type ValidationTrigger = 'submit' | 'input' | 'blur' | 'change';
+export type ValidationErrorSource = 'client' | 'server' | 'manual';
+export type FieldReference = string | FormFieldElement;
+export declare const FORM_ERROR_FIELD = "_form";
+export interface ValidationError {
+    field: string;
+    rule: string;
+    message: string;
+    source: ValidationErrorSource;
+}
+export interface SubmitResult {
+    success: boolean;
+    response?: Response;
+    responseBody?: ResponseBody;
+    error?: unknown;
+}
+export interface FormResetOptions {
+    clearErrors?: boolean;
+}
+export interface ValidationIssue {
+    field?: string;
+    rule?: string;
+    message: string;
+    source?: ValidationErrorSource;
+}
+export type ValidationIssueInput = string | ValidationIssue | ErrorResponse | Record<string, string> | Array<string | ValidationIssue | ErrorResponse>;
+export interface FormValidatorContext {
+    form: Form;
+    formElement: HTMLFormElement;
+    values: Record<string, any>;
+    errors: ValidationError[];
+}
+export type FormValidatorResult = boolean | string | void | ValidationIssue | Array<string | ValidationIssue>;
+export type FormValidator = (context: FormValidatorContext) => FormValidatorResult | Promise<FormValidatorResult>;
 export type ValidationSchema = Record<string, {
     rules: ValidationRule[];
     selector?: string;
     messages?: Record<string, string>;
 }>;
+export type FormFieldElement = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
 /** Параметры формы. */
 export interface FormOptions {
     /**
@@ -24,6 +60,20 @@ export interface FormOptions {
      * @param formInstance - Инстанс формы.
      */
     onAfterValidate?: (isValid: boolean, formInstance: Form) => void;
+    /**
+     * Функция обратного вызова. Запускается после неуспешной клиентской валидации.
+     *
+     * @param errors - Список ошибок валидации.
+     * @param formInstance - Инстанс формы.
+     */
+    onValidationError?: (errors: ValidationError[], formInstance: Form) => void;
+    /**
+     * Функция обратного вызова. Запускается перед отправкой уже валидной формы. Если вернуть `false`, отправка будет
+     * отменена.
+     *
+     * @param formInstance - Инстанс формы.
+     */
+    onBeforeSubmit?: (formInstance: Form) => void | boolean | Promise<void | boolean>;
     /**
      * Функция обратного вызова. Запускается, когда форма отправляется.
      *
@@ -51,10 +101,19 @@ export interface FormOptions {
      * @param formInstance - Инстанс формы.
      */
     onResponseUnsuccess?: (responseBody: ResponseBody, formInstance: Form) => void;
+    /**
+     * Функция обратного вызова. Запускается при исключении во время отправки формы.
+     *
+     * @param error - Ошибка отправки.
+     * @param formInstance - Инстанс формы.
+     */
+    onSubmitError?: (error: unknown, formInstance: Form) => void;
     /** Нужно ли показывать loader в кнопке. По умолчанию `true`. */
     showLoaderButton?: boolean;
     /** Нужно ли проскроливать до первого по порядку элемента с ошибкой. По умолчанию `true`. */
     scrollToFirstErroredInput?: boolean;
+    /** Нужно ли переводить фокус в первое ошибочное поле. По умолчанию `false`. */
+    focusFirstErroredInput?: boolean;
     /** Кастомный тип ошибки. */
     customTypeError?: any;
     /** Цвет лоадера. */
@@ -68,10 +127,27 @@ export interface FormOptions {
      * `.input-primary`.
      */
     inputWrapperSelector?: string;
+    /**
+     * События, на которых нужно запускать валидацию поля. `submit` всегда обрабатывается отдельно. По умолчанию
+     * `submit`.
+     */
+    validateOn?: ValidationTrigger | ValidationTrigger[];
+    /** События, на которых нужно повторно проверять уже ошибочные поля. По умолчанию `input` и `change`. */
+    revalidateOn?: ValidationTrigger | ValidationTrigger[];
+    /** Задержка live-валидации в миллисекундах. По умолчанию `0`. */
+    validationDebounce?: number;
+    /** Атрибут с CSS-селектором контейнера для ошибки поля. По умолчанию `data-error-container`. */
+    errorContainerAttribute?: string;
+    /** Атрибут, куда пишется состояние поля: `validating`, `valid` или `invalid`. */
+    validationStateAttribute?: string;
+    /** Следить за динамически добавленными/удалёнными полями и submit-кнопками. По умолчанию `false`. */
+    observeMutations?: boolean;
     /** Функция для обёртки отправляемых данных. */
     wrapData?: (data: Record<string, any>) => Record<string, any>;
     /** Схема валидации: поле → массив правил + override-сообщения */
     validationSchema?: ValidationSchema;
+    /** Валидаторы всей формы: cross-field, conditional required, date ranges и другие проверки над `getValues()`. */
+    formValidators?: FormValidator | FormValidator[];
 }
 export interface ErrorResponse {
     name: string;
@@ -98,6 +174,12 @@ export default class Form {
     private inputs;
     private _onSubmitHandler?;
     private _onSubmitClickHandler?;
+    private fieldEventHandlers;
+    private liveValidationTimers;
+    private fieldValidationTokens;
+    private fieldValidationTokenCounter;
+    private mutationObserver?;
+    private errors;
     private static get defaultParams();
     private static set defaultParams(value);
     static get defaultValidationSchema(): ValidationSchema;
@@ -110,6 +192,32 @@ export default class Form {
      */
     constructor($el: HTMLElement, options?: FormOptions);
     getOptions(): FormOptions;
+    /**
+     * Инициализирует сразу несколько форм по CSS-селектору. Если форма уже инициализирована, её настройки обновятся.
+     *
+     * @param selector - CSS-селектор форм. По умолчанию `form[data-form-father]`.
+     * @param options - Общие параметры для найденных форм.
+     */
+    static initAll(selector?: string, options?: FormOptions): Form[];
+    /** Обновляет настройки конкретного инстанса формы без пересоздания обработчиков вручную. */
+    updateOptions(options: Partial<FormOptions>): this;
+    /** Возвращает текущий список ошибок формы. */
+    getErrors(): ValidationError[];
+    /** Возвращает значения формы обычным объектом. */
+    getValues(): Record<string, any>;
+    private normalizeValueList;
+    /** Проставляет значения полей по `name` и уведомляет UI через `input`/`change` события. */
+    setValues(values: Record<string, any>): this;
+    /** Снимает все клиентские и серверные ошибки с формы, не меняя значения полей. */
+    clearErrors(): this;
+    private isErrorResponse;
+    private normalizeValidationIssues;
+    private applyValidationIssue;
+    /** Показывает несколько ошибок формы или полей: из backend map/array, `ErrorResponse[]` или form validators. */
+    setErrors(issues: ValidationIssueInput, source?: ValidationErrorSource): this;
+    private validateFormValidators;
+    /** Сбрасывает форму через native `reset()` и опционально очищает ошибки. */
+    reset(options?: FormResetOptions): this;
     /**
      * Обновляет параметры по умолчанию для настроек формы. Метод объединяет переданные параметры с уже существующими
      * параметрами по умолчанию.
@@ -118,8 +226,17 @@ export default class Form {
      *   свойства, которые необходимо обновить; остальные сохранятся без изменений.
      */
     static setDefaultParams(params: Partial<FormOptions>): void;
+    private refreshControls;
     private findSubmitElements;
+    private bindSubmitHandlers;
     private initialization;
+    private handleSubmitEvent;
+    private normalizeTriggers;
+    private clearFieldValidationEvents;
+    private bindFieldValidationEvents;
+    private scheduleFieldValidation;
+    private setupMutationObserver;
+    private getErrorContainer;
     /**
      * Показывает ошибку для поля ввода.
      *
@@ -143,17 +260,49 @@ export default class Form {
      * @param {HTMLElement[]} inputsList - Массив элементов с ошибкой.
      */
     private scrollToFirstErroredInput;
+    private focusFirstErroredInput;
+    private getValidationSchema;
+    private getAllFields;
+    private getFieldKey;
+    private hasFieldError;
+    private clearFieldErrorRecord;
+    private setErrorRecord;
+    private getValidationStateAttribute;
+    private setFieldValidationState;
+    private startFieldValidation;
+    private isLatestFieldValidation;
+    private finishFieldValidation;
+    private clearFieldValidationState;
+    private setValidationError;
+    private resolveField;
+    private parseRuleString;
+    private parseValidationAttribute;
+    private getRuleName;
+    private getRuleIdentity;
+    private collectRules;
+    private getRuleMessage;
+    private fieldMatchesSchemaDefinition;
+    private getFieldValidationConfig;
+    private getValidationFields;
+    private validateInput;
+    private runFieldValidation;
+    private getRadioGroup;
+    /** Показывает ошибку конкретного поля по имени или DOM-элементу. */
+    showFieldError(field: FieldReference, message: string, source?: ValidationErrorSource, rule?: string): boolean;
+    /** Проверяет одно поле по имени или DOM-элементу. */
+    validateField(field: FieldReference): Promise<boolean>;
     /**
      * Проверяет все поля ввода.
      *
-     * Порядок для КАЖДОГО `<input>`:
+     * Порядок для каждого поля:
      *
      * 1. `required` — если атрибут `required`
      * 2. правила из `validationSchema`
-     * 3. правила из `data-custom-validate`
+     * 3. правила из `data-validate`
+     * 4. правила из `data-custom-validate`
      *
      * Для одного поля показывается только первая ошибка. Неизвестные правила фиксируются `console.warn` и исключаются ДО
-     * валидации, поэтому валидационный цикл больше не проверяет их наличие.
+     * валидации.
      */
     validate($block?: HTMLElement): Promise<boolean>;
     /** Блокирует кнопку отправки данных. */
@@ -197,5 +346,5 @@ export default class Form {
     private parseResponseBody;
     private handleUnsuccessfulResponse;
     private sendData;
-    private submit;
+    submit(): Promise<SubmitResult | undefined>;
 }

package/dist/types/validators.d.ts

@@ -1,9 +1,10 @@
 export type ValidatorEffectCtx = {
     value: string;
-    $input: HTMLInputElement | HTMLTextAreaElement;
+    $input: ValidatorFieldElement;
     $form: HTMLElement;
     params?: any;
 };
+export type ValidatorFieldElement = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
 export type ValidatorResult = {
     valid: boolean;
     /** Сообщение об ошибке, если нужно переопределить дефолт */
@@ -13,7 +14,7 @@ export type ValidatorResult = {
     /** Остановить дальнейшие правила для поля (даже если valid=true). Полезно, если валидатор полностью «ведёт» поле. */
     stopOthers?: boolean;
 };
-type ValidatorFn = (value: string, $input: HTMLInputElement | HTMLTextAreaElement, $form: HTMLElement, params?: any) => boolean | Promise<boolean> | ValidatorResult | Promise<ValidatorResult>;
+export type ValidatorFn = (value: string, $input: ValidatorFieldElement, $form: HTMLElement, params?: any) => boolean | ValidatorResult | Promise<boolean | ValidatorResult>;
 interface Validator {
     fn: ValidatorFn;
     defaultMessage: string;

package/docs/en/README.md

@@ -0,0 +1,225 @@
+# Form Father
+
+[![npm version](https://img.shields.io/npm/v/form-father)](https://www.npmjs.com/package/form-father)
+[![npm downloads](https://img.shields.io/npm/dm/form-father)](https://www.npmjs.com/package/form-father)
+
+[🇷🇺 Документация на русском](https://github.com/Poliklot/form-father/blob/master/README.md)
+
+**Form Father** is a library for handling forms in pure JavaScript, providing convenient validation and form submission
+with TypeScript support.
+
+## Installation
+
+Install the library via npm:
+
+```bash
+npm install form-father
+```
+
+## Usage
+
+```javascript
+import Form, { isUrlValid, serializeToFormData } from 'form-father';
+
+Form.setDefaultParams({
+  showLoaderButton: false,
+  scrollToFirstErroredInput: false,
+  logging: true,
+});
+
+const formElement = document.querySelector('#myForm');
+const options = {
+	onSubmit: formInstance => {
+		// Actions on form submission
+	},
+	onResponse: (responseBody, formInstance) => {
+		// Actions on receiving server response
+	},
+	// Other options...
+};
+
+const form = new Form(formElement, options);
+const simpleForm = new Form(document.querySelector('#simpleForm')); // options are optional
+
+const forms = Form.initAll('form[data-form-father]', {
+	inputWrapperSelector: '.field',
+	validateOn: ['blur', 'change'],
+	revalidateOn: ['input', 'change'],
+});
+```
+
+```ts
+import Form, {
+	FORM_ERROR_FIELD,
+	type FormOptions,
+	type ValidationSchema,
+	type ResponseBody,
+	type ValidationError,
+	type SubmitResult,
+	type FormResetOptions,
+	type FormValidator,
+	type ValidationIssue,
+} from 'form-father';
+```
+
+## Options
+
+- **onSubmit**: Callback function executed on form submission.
+- **onBeforeSubmit**: Runs before sending an already valid form; returning `false` cancels the request.
+- **onSubmitError**: Runs when form submission throws.
+- **onResponse**: Callback function executed when a server response is received.
+- **onResponseSuccess**: Callback function executed for a successful HTTP response with `success: true`.
+- **onResponseUnsuccess**: Callback function executed for unsuccessful HTTP responses, `success !== true`, or invalid JSON.
+- **onValidationError**: Runs when client-side validation fails.
+- **showLoaderButton**: Whether to display a loader in the submit button. Defaults to `true`.
+- **scrollToFirstErroredInput**: Whether to scroll to the first input with an error. Defaults to `true`.
+- **focusFirstErroredInput**: Whether to focus the first invalid field. Defaults to `false`.
+- **customTypeError**: Custom error type.
+- **loaderColor**: Color of the loader in the submit button.
+- **logging**: Specifies whether to log data to the console. Defaults to false.
+- **validateOn**: Field live-validation events: `submit`, `input`, `blur`, `change`.
+- **revalidateOn**: Events used to re-check already invalid fields. Defaults to `input` and `change`.
+- **validationDebounce**: Live-validation delay in milliseconds.
+- **errorContainerAttribute**: Attribute containing the CSS selector for a custom error container. Defaults to
+  `data-error-container`.
+- **validationStateAttribute**: Field state attribute: `validating`, `valid`, or `invalid`. Defaults to
+  `data-form-father-state`.
+- **observeMutations**: Watches dynamically added fields and submit buttons.
+- **formValidators**: A form validator or array of validators for cross-field rules.
+
+## Form Submission
+
+- Submit elements are `button[type="submit"]`, `button` without `type`, `input[type="submit"]`, and
+  `input[type="image"]`.
+- `submit()` is public and returns `Promise<SubmitResult | undefined>`.
+- For `method="GET"` and `method="HEAD"`, data is appended to the `action` query string and no request body is sent.
+- `wrapData` applies to every supported `enctype`: `application/x-www-form-urlencoded`, `multipart/form-data`,
+  `text/plain`, and `application/json`.
+- `onResponseSuccess` runs only for a successful HTTP response with `success: true`.
+- `onResponseUnsuccess` runs for unsuccessful HTTP responses, `success !== true`, or invalid JSON responses.
+
+## Methods
+
+- **Form.initAll(selector, options)**: Initializes all forms matching a selector and reuses existing instances.
+- **updateOptions(options)**: Updates one form instance and rebinds live validation.
+- **validate()**: Validates the whole form.
+- **validateField(field)**: Validates one field by name or DOM element.
+- **showFieldError(field, message, source)**: Shows a field error manually.
+- **setErrors(errors, source)**: Applies backend/form-level errors from an object, array, or `ErrorResponse[]`.
+- **getErrors()**: Returns current errors as `{ field, rule, message, source }`.
+- **getValues()**: Returns form values as a plain object.
+- **setValues(values)**: Fills fields by `name` and dispatches `input`/`change`.
+- **clearErrors()**: Clears errors without changing field values.
+- **reset(options)**: Calls native `form.reset()` and clears errors by default.
+- **clearInputs()**: Clears all input fields in the form.
+- **setDefaultParams(params):** The setDefaultParams method is used to set default values for all instances of the form. These parameters can be overridden when initializing a specific form.
+- **destroy()**: Removes event listeners and runtime artifacts.
+
+## Validation
+
+```html
+<input
+	name="email"
+	type="email"
+	data-validate="required|email"
+	data-error-required="Email is required"
+	data-error-email="Enter a valid email"
+	data-error-container="#email-error"
+/>
+<small id="email-error" hidden></small>
+```
+
+- `data-validate` accepts rules separated by `|`, spaces, or commas.
+- `data-error-rule-name` overrides a message for one rule.
+- `data-error-container` points to a custom error container without requiring wrapper markup.
+- During async validation, fields receive `aria-busy="true"` and a `validating` state attribute; stale validator
+  responses are ignored.
+- `data-custom-validate` is still supported for backward compatibility.
+
+Final rule order:
+
+```text
+required  →  schema.rules  →  data-validate  →  data-custom-validate
+```
+
+### Cross-field and form-level validation
+
+```ts
+const form = new Form($form, {
+	formValidators: [
+		({ values }) =>
+			values.password === values.passwordConfirm
+				? true
+				: {
+						field: 'passwordConfirm',
+						rule: 'same-as-password',
+						message: 'Passwords do not match',
+					},
+		({ values }) => (values.start <= values.end ? true : { field: 'end', message: 'End date must be after start' }),
+	],
+});
+```
+
+Return a string or an issue without `field` to show a form-level error. In `getErrors()`, it uses
+`FORM_ERROR_FIELD` (`"_form"`).
+
+```ts
+form.setErrors({
+	email: 'Email is already used',
+	[FORM_ERROR_FIELD]: 'Please check the form',
+});
+```
+
+## Schema Adapters
+
+Form Father has no schema-library runtime dependency, but can wrap Zod/Valibot/Yup-like schemas with `safeParse()` or
+`parse()`.
+
+```ts
+import { registerSchemaValidator } from 'form-father';
+
+registerSchemaValidator('company-email', z.string().email(), 'Use a company email');
+```
+
+For simple checks, use `createFieldValidator(predicate, message)`.
+
+## Demos and Recipes
+
+- `demos/index.html` is a static login/callback/search/upload demo after `npm run build`.
+- `npm run demos` builds the package and starts the Vite demo server.
+- `docs/recipes/README.md` contains short API, data-attribute, adapter, and server-error recipes.
+
+## Helpers
+
+The library provides a number of utility functions:
+
+- **serializeToFormData($element)**: Serializes form data into a `FormData` object.
+- **isEmailValid(value)**: Checks if a string is a valid email address.
+- **isUrlValid(value)**: Checks an `http(s)` URL, domain, IP, or `localhost`; the scheme may be omitted.
+- **isPhoneValid(value)**: Checks if a string is a valid phone number.
+- **closest($el, selector)**: Finds the closest parent element matching the given selector.
+- **blockScrollBody()**: Blocks page scrolling.
+- **unblockScrollBody()**: Unblocks page scrolling.
+- **parseCommonResponseProperties(responseBody)**: Processes common properties from the server response.
+- **serializeFormToJSON(form)**: Serializes form data into a plain object.
+
+## Build and Development
+
+**Rollup** is used for building the project. Main commands:
+
+- **npm run build**: Builds the project.
+- **npm run watch**: Builds the project in watch mode.
+- **npm run demos**: Runs a demo version using Vite.
+
+## Contributing
+
+We welcome your suggestions and improvements! Please create [issues](https://github.com/poliklot/form-father/issues) and
+submit [pull requests](https://github.com/poliklot/form-father/pulls).
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+© 2024 Poliklot

package/docs/recipes/README.md

@@ -0,0 +1,115 @@
+# Form Father Recipes
+
+## Init several forms
+
+```ts
+import Form from 'form-father';
+
+const forms = Form.initAll('form[data-form-father]', {
+	inputWrapperSelector: '.field',
+	validateOn: ['blur', 'change'],
+	revalidateOn: ['input', 'change'],
+});
+```
+
+## HTML-only rules
+
+```html
+<input
+	name="email"
+	type="email"
+	data-validate="required|email"
+	data-error-required="Email is required"
+	data-error-email="Enter a valid email"
+	data-error-container="#email-error"
+/>
+<small id="email-error" hidden></small>
+```
+
+## Programmatic field API
+
+```ts
+const form = new Form(document.querySelector('form')!);
+
+await form.validateField('email');
+form.showFieldError('email', 'This email is already used', 'server');
+console.log(form.getErrors());
+```
+
+## State helpers
+
+```ts
+form.setValues({
+	email: 'user@example.com',
+	interests: ['docs', 'api'],
+});
+
+console.log(form.getValues());
+form.clearErrors();
+form.reset();
+```
+
+## Cross-field validation
+
+```ts
+const form = new Form(document.querySelector('form')!, {
+	formValidators: ({ values }) =>
+		values.password === values.passwordConfirm
+			? true
+			: {
+					field: 'passwordConfirm',
+					rule: 'same-as-password',
+					message: 'Passwords do not match',
+				},
+});
+```
+
+## Applying backend errors
+
+```ts
+import { FORM_ERROR_FIELD } from 'form-father';
+
+form.setErrors({
+	email: 'Email is already registered',
+	[FORM_ERROR_FIELD]: 'Please check the form',
+});
+```
+
+## Async validation state
+
+```css
+[data-form-father-state="validating"] {
+	opacity: 0.7;
+}
+
+[data-form-father-state="invalid"] {
+	border-color: #b3261e;
+}
+```
+
+Async validators are race-safe: if an older validation finishes after a newer one started, Form Father ignores the stale
+result and keeps the latest field state.
+
+## Zod-like schema adapter
+
+```ts
+import { registerSchemaValidator } from 'form-father';
+
+registerSchemaValidator('email-domain', z.string().email().endsWith('@company.com'), 'Use a company email');
+```
+
+The adapter only expects a `safeParse(value)` or `parse(value)` method, so it can be used with Zod-like libraries without
+adding runtime dependencies to Form Father.
+
+## Server response errors
+
+```json
+{
+	"success": false,
+	"error": true,
+	"error-msg": "Please check the form",
+	"errors": [{ "name": "email", "error-msg": "Email is already registered" }]
+}
+```
+
+Field errors are shown through the same rendering path as client-side validation errors.

package/package.json

@@ -1,9 +1,9 @@
 {
 	"name": "form-father",
-	"version": "0.2.11",
+	"version": "0.4.0",
 	"description": "Form Father: Библиотека для обработки форм",
 	"type": "module",
-	"files": ["dist", "README.md", "LICENSE", "RESPONSE_API.md"],
+	"files": ["dist", "README.md", "LICENSE", "RESPONSE_API.md", "CHANGELOG.md", "docs", "demos"],
 	"exports": {
 		".": {
 			"import": "./dist/index.js",