form-father 0.2.11 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,98 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## 0.4.0 - 2026-04-27
+
+### Added
+
+- Added form-level and cross-field validation via `formValidators`.
+- Added `setErrors()` for backend maps, `ErrorResponse[]`, global form errors, and custom validation issue objects.
+- Added `FORM_ERROR_FIELD` constant for form-level errors in `getErrors()`.
+- Added public TypeScript types for form validation contexts and issues.
+
+### Changed
+
+- `validate()` now runs field-level rules first, then form-level validators over `getValues()`.
+- Cross-field and backend errors share the same rendering path as field validation errors.
+
+### Tests
+
+- Test suite expanded to 113 tests.
+- Coverage baseline: 98.31% statements, 87.05% branches, 96.34% functions, 100% lines.
+
+## 0.3.0 - 2026-04-25
+
+### Added
+
+- Added convenience API: `Form.initAll()`, `updateOptions()`, public `submit()`, `validateField()`, `showFieldError()`,
+  `getErrors()`, `getValues()`, `setValues()`, `clearErrors()`, and `reset()`.
+- Added client validation hooks: `onValidationError`, `onBeforeSubmit`, and `onSubmitError`.
+- Added live validation options: `validateOn`, `revalidateOn`, `validationDebounce`, and `focusFirstErroredInput`.
+- Added `data-validate`, `data-error-*`, and `data-error-container` support while keeping `data-custom-validate`.
+- Added optional mutation observing for dynamic fields and submit buttons.
+- Added race-safe async field validation state with `aria-busy` and configurable field state attributes.
+- Added dependency-free schema adapters: `createSchemaValidator()`, `registerSchemaValidator()`, and
+  `createFieldValidator()`.
+- Added static demos for login, callback/server errors, GET search, and multipart upload.
+- Added recipes documentation for common API, data-attribute, adapter, and server-error flows.
+
+### Changed
+
+- Validation now merges every matching schema rule for a field before applying data-attribute rules.
+- Server-side field errors now populate the public `getErrors()` list.
+- Package contents now include docs, demos, and the changelog.
+
+### Tests
+
+- Test suite expanded to 109 tests.
+- Coverage baseline: 98.10% statements, 86.15% branches, 95.69% functions, 100% lines.
+
+## 0.2.11 - 2026-04-25
+
+### Added
+
+- Added release checklist, package smoke checks, CI workflow, and release gate scripts.
+- Added npm pack dry-run script with a temporary npm cache for local cache permission issues.
+
+### Changed
+
+- Updated package metadata and release workflow after `0.2.10` had already been published.
+
+## 0.2.10 - 2026-04-25
+
+### Added
+
+- Exported public helper APIs from the package entrypoint: `serializeToFormData`, validators, URL/email/phone helpers, scroll helpers, and response helpers.
+- Exported TypeScript types for public consumers: `FormOptions`, `ValidationRule`, `ValidationSchema`, `ErrorResponse`, and `ResponseBody`.
+- Added package smoke checks for built files and public exports.
+- Added CI workflow for tests, build, smoke checks, and npm pack dry-run.
+- Added coverage thresholds to keep the stabilization baseline from regressing.
+
+### Changed
+
+- `new Form(formEl)` now works without an options object.
+- Submit detection now supports implicit submit buttons (`<button>`) and `input[type="image"]`.
+- `GET` and `HEAD` forms now append form data to the action query string and do not send a request body.
+- `wrapData` now applies consistently across supported encodings: `application/x-www-form-urlencoded`, `multipart/form-data`, `text/plain`, and `application/json`.
+- Non-200 HTTP responses, `success !== true`, and invalid JSON responses now flow through `onResponseUnsuccess`.
+- Server-side field errors can be applied to `input`, `textarea`, and `select`.
+- `serializeToFormData` now skips disabled controls, controls marked with `data-no-serialize`, and button controls.
+- Built-in validators are registered idempotently across repeated module imports.
+
+### Fixed
+
+- Loader and `waitResponse` cleanup now runs when `fetch` or response parsing fails.
+- Required radio groups now produce one validation error per group.
+- Field error rendering no longer requires a wrapper-level `showError()` method.
+- Release script now exits with `0` on success and handles missing temporary files during cleanup.
+- Rollup IIFE build no longer warns about mixed default and named exports.
+
+### Tests
+
+- Test coverage baseline: 98.32% statements, 86.34% branches, 93.18% functions, 100% lines.
+- Test suite baseline: 93 tests passing.
+
+## 0.2.9
+
+- Previous published patch release.

package/README.md

@@ -59,10 +59,26 @@ const options = {
 
 const form = new Form(formElement, options);
 const simpleForm = new Form(document.querySelector('#simpleForm')); // options можно не передавать
+
+const forms = Form.initAll('form[data-form-father]', {
+	inputWrapperSelector: '.field',
+	validateOn: ['blur', 'change'],
+	revalidateOn: ['input', 'change'],
+});
 ```
 
 ```ts
-import Form, { type FormOptions, type ValidationSchema, type ResponseBody } from 'form-father';
+import Form, {
+	FORM_ERROR_FIELD,
+	type FormOptions,
+	type ValidationSchema,
+	type ResponseBody,
+	type ValidationError,
+	type SubmitResult,
+	type FormResetOptions,
+	type FormValidator,
+	type ValidationIssue,
+} from 'form-father';
 ```
 
 ## Формат ответов сервера
@@ -75,19 +91,32 @@ import Form, { type FormOptions, type ValidationSchema, type ResponseBody } from
 ## Опции
 
 - **onSubmit**: Функция обратного вызова, вызываемая при отправке формы.
+- **onBeforeSubmit**: Функция вызывается перед отправкой уже валидной формы; `false` отменяет отправку.
+- **onSubmitError**: Функция вызывается при исключении во время отправки.
 - **onResponse**: Функция обратного вызова при получении ответа от сервера.
 - **onResponseSuccess**: Функция вызывается при успешном HTTP-ответе и `success: true`.
 - **onResponseUnsuccess**: Функция вызывается при неуспешном HTTP-ответе, `success !== true` или некорректном JSON.
+- **onValidationError**: Функция вызывается, когда клиентская валидация не прошла.
 - **showLoaderButton**: Показывать ли лоадер в кнопке отправки. По умолчанию `true`.
 - **scrollToFirstErroredInput**: Прокручивать ли к первому полю с ошибкой. По умолчанию `true`.
+- **focusFirstErroredInput**: Переводить ли фокус в первое поле с ошибкой. По умолчанию `false`.
 - **customTypeError**: Кастомный тип ошибки.
 - **loaderColor**: Цвет лоадера в кнопке отправки.
 - **logging**: Нужно ли выводить данные в консоль. По умолчанию `false`.
+- **validateOn**: События live-валидации поля: `submit`, `input`, `blur`, `change`.
+- **revalidateOn**: События повторной проверки уже ошибочных полей. По умолчанию `input` и `change`.
+- **validationDebounce**: Задержка live-валидации в миллисекундах.
+- **errorContainerAttribute**: Атрибут с CSS-селектором контейнера ошибки. По умолчанию `data-error-container`.
+- **validationStateAttribute**: Атрибут состояния поля: `validating`, `valid`, `invalid`. По умолчанию
+  `data-form-father-state`.
+- **observeMutations**: Следить за динамически добавленными полями и submit-кнопками.
+- **formValidators**: Валидатор или массив валидаторов всей формы для cross-field правил.
 
 ## Отправка формы
 
 - Submit-элементами считаются `button[type="submit"]`, `button` без `type`, `input[type="submit"]` и
   `input[type="image"]`.
+- `submit()` доступен публично и возвращает `Promise<SubmitResult | undefined>`.
 - Для `method="GET"` и `method="HEAD"` данные добавляются в query string `action`, тело запроса не отправляется.
 - `wrapData` применяется для всех поддержанных `enctype`: `application/x-www-form-urlencoded`, `multipart/form-data`,
   `text/plain`, `application/json`.
@@ -96,6 +125,17 @@ import Form, { type FormOptions, type ValidationSchema, type ResponseBody } from
 
 ## Методы
 
+- **Form.initAll(selector, options)**: Инициализирует все формы по селектору и переиспользует уже созданные инстансы.
+- **updateOptions(options)**: Обновляет настройки конкретной формы и перепривязывает live-валидацию.
+- **validate()**: Проверяет всю форму.
+- **validateField(field)**: Проверяет одно поле по имени или DOM-элементу.
+- **showFieldError(field, message, source)**: Показывает ошибку поля вручную.
+- **setErrors(errors, source)**: Применяет backend/form-level ошибки из объекта, массива или `ErrorResponse[]`.
+- **getErrors()**: Возвращает текущие ошибки в формате `{ field, rule, message, source }`.
+- **getValues()**: Возвращает значения формы обычным объектом.
+- **setValues(values)**: Заполняет поля по `name` и диспатчит `input`/`change`.
+- **clearErrors()**: Очищает ошибки, не меняя значения полей.
+- **reset(options)**: Вызывает native `form.reset()` и по умолчанию очищает ошибки.
 - **clearInputs()**: Очищает все поля ввода формы.
 - **setDefaultParams(params)**: Метод setDefaultParams используется для установки значений по умолчанию для всех
   экземпляров формы. Эти параметры можно переопределить при инициализации конкретной формы.
@@ -188,6 +228,27 @@ _Порядок применения для одного `<input>`:_
 
 ---
 
+### Правила через data-атрибуты
+
+```html
+<input
+	name="email"
+	type="email"
+	data-validate="required|email"
+	data-error-required="Email обязателен"
+	data-error-email="Введите корректный email"
+	data-error-container="#email-error"
+/>
+<small id="email-error" hidden></small>
+```
+
+- `data-validate` принимает правила через `|`, пробел или запятую.
+- `data-error-rule-name` переопределяет сообщение конкретного правила.
+- `data-error-container` указывает контейнер для ошибки без обязательной wrapper-разметки.
+- Во время async-валидации поле получает `aria-busy="true"` и state-атрибут `validating`; устаревшие ответы
+  валидаторов игнорируются.
+- `data-custom-validate` сохранён для обратной совместимости.
+
 ### Правило через `data-custom-validate`
 
 ```html
@@ -259,12 +320,59 @@ validationSchema: {
 ### Итоговый порядок проверки
 
 ```
-required  →  schema.rules  →  data-custom-validate
+required  →  schema.rules  →  data-validate  →  data-custom-validate
 ```
 
 - Для каждого поля отображается **только первое** найденное сообщение об ошибке.
 - Неизвестные правила логируются и пропускаются до начала проверки, поэтому не влияют на результат валидации.
 
+### Cross-field и form-level validation
+
+```ts
+const form = new Form($form, {
+	formValidators: [
+		({ values }) =>
+			values.password === values.passwordConfirm
+				? true
+				: {
+						field: 'passwordConfirm',
+						rule: 'same-as-password',
+						message: 'Пароли не совпадают',
+					},
+		({ values }) => (values.start <= values.end ? true : { field: 'end', message: 'Дата окончания раньше начала' }),
+	],
+});
+```
+
+Глобальную ошибку формы можно вернуть строкой или issue без `field`. В `getErrors()` она будет иметь поле
+`FORM_ERROR_FIELD` (`"_form"`).
+
+```ts
+form.setErrors({
+	email: 'Email уже занят',
+	[FORM_ERROR_FIELD]: 'Проверьте данные формы',
+});
+```
+
+## Адаптеры схем
+
+Form Father не тянет внешние зависимости, но умеет оборачивать Zod/Valibot/Yup-подобные схемы с `safeParse()` или
+`parse()`.
+
+```ts
+import { registerSchemaValidator } from 'form-father';
+
+registerSchemaValidator('company-email', z.string().email(), 'Введите корпоративный email');
+```
+
+Для простых проверок есть `createFieldValidator(predicate, message)`.
+
+## Демо и рецепты
+
+- `demos/index.html` — статическое демо login/callback/search/upload после `npm run build`.
+- `npm run demos` — сборка и запуск Vite-сервера для демо.
+- `docs/recipes/README.md` — короткие рецепты по API, data-атрибутам, adapters и server errors.
+
 ## Сборка и разработка
 
 Для сборки проекта используется **Rollup**. Основные команды:

package/demos/index.html

@@ -0,0 +1,153 @@
+<!doctype html>
+<html lang="ru">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<title>Form Father demos</title>
+		<link rel="stylesheet" href="./styles.css" />
+	</head>
+	<body>
+		<header class="demo-header">
+			<div>
+				<p class="eyebrow">Form Father</p>
+				<h1>Демо форм, валидации и ответов сервера</h1>
+			</div>
+			<a class="github-link" href="https://github.com/Poliklot/form-father">GitHub</a>
+		</header>
+
+		<main class="demo-grid">
+			<section class="demo-panel">
+				<div class="panel-title">
+					<p class="eyebrow">Login</p>
+					<h2>Live validation</h2>
+				</div>
+				<form data-form-father action="/demo/login" method="post" enctype="application/json" data-demo="login" novalidate>
+					<label class="field">
+						<span>Email</span>
+						<input
+							class="input"
+							name="email"
+							type="email"
+							autocomplete="email"
+							data-validate="required|email|available-email"
+							data-error-required="Email обязателен"
+							data-error-email="Введите корректный email"
+							data-error-available-email="Этот email уже занят"
+							data-error-container="#login-email-error"
+						/>
+						<small id="login-email-error" class="field-error" hidden></small>
+					</label>
+
+					<label class="field">
+						<span>Password</span>
+						<input
+							class="input"
+							name="password"
+							type="password"
+							autocomplete="current-password"
+							data-validate="required|min-length:6"
+							data-error-required="Пароль обязателен"
+							data-error-min-length="Минимум 6 символов"
+						/>
+					</label>
+
+					<label class="field">
+						<span>Repeat password</span>
+						<input
+							class="input"
+							name="passwordConfirm"
+							type="password"
+							autocomplete="current-password"
+							data-validate="required"
+							data-error-required="Повторите пароль"
+						/>
+					</label>
+
+					<button type="submit">Войти</button>
+				</form>
+			</section>
+
+			<section class="demo-panel">
+				<div class="panel-title">
+					<p class="eyebrow">Callback</p>
+					<h2>Server field errors</h2>
+				</div>
+				<form data-form-father action="/demo/callback" method="post" data-demo="callback" novalidate>
+					<label class="field">
+						<span>Имя</span>
+						<input class="input" name="name" data-validate="required" data-error-required="Укажите имя" />
+					</label>
+
+					<label class="field">
+						<span>Телефон</span>
+						<input
+							class="input"
+							name="tel"
+							type="tel"
+							placeholder="+79991234567"
+							data-validate="required|tel"
+							data-error-tel="Телефон в формате +7XXXXXXXXXX"
+						/>
+					</label>
+
+					<button type="submit">Заказать звонок</button>
+				</form>
+			</section>
+
+			<section class="demo-panel">
+				<div class="panel-title">
+					<p class="eyebrow">Search</p>
+					<h2>GET query</h2>
+				</div>
+				<form data-form-father action="/demo/search?source=demos" method="get" data-demo="search" novalidate>
+					<label class="field">
+						<span>Запрос</span>
+						<input class="input" name="q" value="form father" data-validate="required" />
+					</label>
+
+					<label class="field">
+						<span>Раздел</span>
+						<select class="input" name="section">
+							<option value="docs">Docs</option>
+							<option value="api">API</option>
+							<option value="examples">Examples</option>
+						</select>
+					</label>
+
+					<button type="submit">Найти</button>
+				</form>
+			</section>
+
+			<section class="demo-panel">
+				<div class="panel-title">
+					<p class="eyebrow">Multipart</p>
+					<h2>FormData upload</h2>
+				</div>
+				<form data-form-father action="/demo/upload" method="post" enctype="multipart/form-data" data-demo="upload" novalidate>
+					<label class="field">
+						<span>Название</span>
+						<input class="input" name="title" data-validate="required" />
+					</label>
+
+					<label class="field">
+						<span>Файл</span>
+						<input class="input" name="attachment" type="file" />
+					</label>
+
+					<button type="submit">Отправить</button>
+				</form>
+			</section>
+		</main>
+
+		<section class="demo-output">
+			<div class="panel-title">
+				<p class="eyebrow">Output</p>
+				<h2>Последний ответ</h2>
+			</div>
+			<pre id="demo-output">Заполните любую форму.</pre>
+		</section>
+
+		<script src="../dist/FormFather.min.js"></script>
+		<script src="./main.js"></script>
+	</body>
+</html>

package/demos/main.js

@@ -0,0 +1,103 @@
+const api = window.FormFather || {};
+const Form = api.default || api.Form || api;
+const { registerValidator } = api;
+const output = document.querySelector('#demo-output');
+
+function writeOutput(title, payload) {
+	output.textContent = `${title}\n\n${JSON.stringify(payload, null, 2)}`;
+}
+
+function json(body, status = 200) {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { 'Content-Type': 'application/json' },
+	});
+}
+
+window.fetch = async (url, options = {}) => {
+	const requestUrl = String(url);
+	const method = options.method || 'GET';
+
+	if (requestUrl.startsWith('/demo/login')) {
+		return json({
+			success: true,
+			message: 'Logged in',
+			method,
+		});
+	}
+
+	if (requestUrl.startsWith('/demo/callback')) {
+		return json(
+			{
+				success: false,
+				error: true,
+				'error-msg': 'Сервер вернул ошибки по полям.',
+				errors: [{ name: 'tel', 'error-msg': 'Этот номер уже есть в заявках' }],
+			},
+			422,
+		);
+	}
+
+	if (requestUrl.startsWith('/demo/search')) {
+		return json({
+			success: true,
+			query: requestUrl,
+			results: ['Validation API', 'Server response format', 'Demo recipes'],
+		});
+	}
+
+	if (requestUrl.startsWith('/demo/upload')) {
+		return json({
+			success: true,
+			message: 'FormData accepted',
+			contentType: options.headers?.['Content-Type'] || 'browser-managed multipart boundary',
+		});
+	}
+
+	return json({ success: false, error: true, 'error-msg': `No demo route for ${requestUrl}` }, 404);
+};
+
+registerValidator('min-length', (value, _input, _form, min) => value.length >= Number(min), 'Слишком короткое значение', {
+	override: true,
+});
+registerValidator(
+	'available-email',
+	value =>
+		new Promise(resolve => {
+			setTimeout(() => resolve(value.toLowerCase() !== 'taken@example.com'), 350);
+		}),
+	'Email is already used',
+	{ override: true },
+);
+
+Form.initAll('form[data-form-father]', {
+	inputSelector: '.input',
+	inputWrapperSelector: '.field',
+	validateOn: ['blur', 'change'],
+	revalidateOn: ['input', 'change'],
+	validationDebounce: 120,
+	focusFirstErroredInput: true,
+	loaderColor: 'currentColor',
+	formValidators({ values }) {
+		if (values.password && values.passwordConfirm && values.password !== values.passwordConfirm) {
+			return {
+				field: 'passwordConfirm',
+				rule: 'same-as-password',
+				message: 'Пароли не совпадают',
+			};
+		}
+
+		return true;
+	},
+	onValidationError(errors) {
+		writeOutput('Client validation errors', errors);
+	},
+	onResponse(responseBody, form) {
+		writeOutput(`${form.$el.dataset.demo || 'form'} response`, responseBody);
+	},
+	onResponseSuccess(responseBody, form) {
+		if (form.$el.dataset.demo === 'login' || form.$el.dataset.demo === 'upload') {
+			form.clearInputs();
+		}
+	},
+});