form-father 0.2.10 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## 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,23 @@ 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, {
+	type FormOptions,
+	type ValidationSchema,
+	type ResponseBody,
+	type ValidationError,
+	type SubmitResult,
+	type FormResetOptions,
+} from 'form-father';
 ```
 
 ## Формат ответов сервера
@@ -75,19 +88,31 @@ 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-кнопками.
 
 ## Отправка формы
 
 - 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 +121,16 @@ import Form, { type FormOptions, type ValidationSchema, type ResponseBody } from
 
 ## Методы
 
+- **Form.initAll(selector, options)**: Инициализирует все формы по селектору и переиспользует уже созданные инстансы.
+- **updateOptions(options)**: Обновляет настройки конкретной формы и перепривязывает live-валидацию.
+- **validate()**: Проверяет всю форму.
+- **validateField(field)**: Проверяет одно поле по имени или DOM-элементу.
+- **showFieldError(field, message, source)**: Показывает ошибку поля вручную.
+- **getErrors()**: Возвращает текущие ошибки в формате `{ field, rule, message, source }`.
+- **getValues()**: Возвращает значения формы обычным объектом.
+- **setValues(values)**: Заполняет поля по `name` и диспатчит `input`/`change`.
+- **clearErrors()**: Очищает ошибки, не меняя значения полей.
+- **reset(options)**: Вызывает native `form.reset()` и по умолчанию очищает ошибки.
 - **clearInputs()**: Очищает все поля ввода формы.
 - **setDefaultParams(params)**: Метод setDefaultParams используется для установки значений по умолчанию для всех
   экземпляров формы. Эти параметры можно переопределить при инициализации конкретной формы.
@@ -188,6 +223,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 +315,31 @@ validationSchema: {
 ### Итоговый порядок проверки
 
 ```
-required  →  schema.rules  →  data-custom-validate
+required  →  schema.rules  →  data-validate  →  data-custom-validate
 ```
 
 - Для каждого поля отображается **только первое** найденное сообщение об ошибке.
 - Неизвестные правила логируются и пропускаются до начала проверки, поэтому не влияют на результат валидации.
 
+## Адаптеры схем
+
+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,141 @@
+<!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>
+
+					<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,92 @@
+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',
+	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();
+		}
+	},
+});

package/demos/styles.css

@@ -0,0 +1,221 @@
+:root {
+	color-scheme: light;
+	--bg: #f5f7fb;
+	--panel: #ffffff;
+	--text: #172033;
+	--muted: #637083;
+	--line: #d9e0ea;
+	--accent: #176b87;
+	--accent-strong: #0f5268;
+	--danger: #b3261e;
+	--success: #176b3a;
+}
+
+* {
+	box-sizing: border-box;
+}
+
+body {
+	margin: 0;
+	background: var(--bg);
+	color: var(--text);
+	font: 16px/1.5 system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+
+.demo-header {
+	display: flex;
+	align-items: flex-end;
+	justify-content: space-between;
+	gap: 24px;
+	padding: 40px min(6vw, 72px) 24px;
+	border-bottom: 1px solid var(--line);
+	background: #ffffff;
+}
+
+.demo-header h1,
+.panel-title h2 {
+	margin: 0;
+	letter-spacing: 0;
+}
+
+.demo-header h1 {
+	max-width: 760px;
+	font-size: clamp(32px, 4vw, 54px);
+	line-height: 1.05;
+}
+
+.eyebrow {
+	margin: 0 0 8px;
+	color: var(--accent);
+	font-size: 13px;
+	font-weight: 700;
+	letter-spacing: 0;
+	text-transform: uppercase;
+}
+
+.github-link,
+button {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	min-height: 42px;
+	padding: 0 16px;
+	border: 1px solid var(--accent);
+	border-radius: 6px;
+	background: var(--accent);
+	color: #ffffff;
+	font: inherit;
+	font-weight: 700;
+	text-decoration: none;
+	cursor: pointer;
+}
+
+.github-link {
+	background: #ffffff;
+	color: var(--accent);
+}
+
+button:hover,
+button:focus-visible {
+	background: var(--accent-strong);
+	border-color: var(--accent-strong);
+}
+
+.github-link:hover,
+.github-link:focus-visible {
+	border-color: var(--accent-strong);
+	color: var(--accent-strong);
+}
+
+.demo-grid {
+	display: grid;
+	grid-template-columns: repeat(2, minmax(0, 1fr));
+	gap: 18px;
+	padding: 24px min(6vw, 72px);
+}
+
+.demo-panel,
+.demo-output {
+	border: 1px solid var(--line);
+	border-radius: 8px;
+	background: var(--panel);
+	padding: 22px;
+}
+
+.panel-title {
+	margin-bottom: 18px;
+}
+
+.panel-title h2 {
+	font-size: 22px;
+	line-height: 1.2;
+}
+
+form {
+	display: grid;
+	gap: 14px;
+}
+
+.field {
+	display: grid;
+	gap: 6px;
+}
+
+.field span {
+	color: var(--muted);
+	font-size: 14px;
+	font-weight: 700;
+}
+
+.input {
+	width: 100%;
+	min-height: 42px;
+	padding: 8px 10px;
+	border: 1px solid var(--line);
+	border-radius: 6px;
+	background: #ffffff;
+	color: var(--text);
+	font: inherit;
+}
+
+.input:focus {
+	border-color: var(--accent);
+	outline: 3px solid rgba(23, 107, 135, 0.16);
+}
+
+.input[aria-invalid="true"] {
+	border-color: var(--danger);
+}
+
+.input[aria-busy="true"] {
+	opacity: 0.72;
+}
+
+.input[data-form-father-state="valid"] {
+	border-color: var(--success);
+}
+
+.input[data-form-father-state="invalid"] {
+	border-color: var(--danger);
+}
+
+[data-form-father-error],
+.field-error {
+	color: var(--danger);
+	font-size: 13px;
+}
+
+.input__wrapper--error .input {
+	border-color: var(--danger);
+}
+
+.button--loading {
+	opacity: 0.74;
+	pointer-events: none;
+}
+
+.button__loader {
+	display: inline-flex;
+	width: 18px;
+	height: 18px;
+	margin-right: 8px;
+}
+
+.button__loader svg {
+	width: 18px;
+	height: 18px;
+}
+
+.error-block-under-input__wrapper {
+	color: var(--danger);
+	font-size: 14px;
+}
+
+.demo-output {
+	margin: 0 min(6vw, 72px) 40px;
+}
+
+pre {
+	min-height: 130px;
+	margin: 0;
+	overflow: auto;
+	padding: 16px;
+	border: 1px solid var(--line);
+	border-radius: 8px;
+	background: #101820;
+	color: #d8f3dc;
+	font-size: 13px;
+	white-space: pre-wrap;
+}
+
+@media (max-width: 760px) {
+	.demo-header {
+		display: grid;
+		align-items: start;
+		padding-top: 28px;
+	}
+
+	.demo-grid {
+		grid-template-columns: 1fr;
+	}
+}