form-father 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to this project are documented here.
 
+## 0.7.0 - 2026-04-27
+
+### Added
+
+- Added `docs/api/README.md` with a compact public API, options, methods, validators, adapters, and helpers reference.
+- Added `docs/demo/README.md` with manual demo scenarios and demo coverage notes.
+- Added a Public API demo panel covering `setValues()`, `validateField()`, `setErrors()`, `getValues()`, and
+  `clearErrors()`.
+- Added `npm run docs:check` to verify documentation files, version references, package README sync, and demo coverage.
+
+### Changed
+
+- `npm run release:check` now includes documentation checks before build and package smoke checks.
+- Package smoke checks now verify the broader public export surface and package documentation files.
+
+### Tests
+
+- Release gate remains at 122 tests plus docs/package smoke checks.
+
 ## 0.6.0 - 2026-04-27
 
 ### Added

package/README.md

@@ -410,9 +410,12 @@ registerSchemaValidator('company-email', z.string().email(), 'Введите к
 
 ## Демо и рецепты
 
-- `demos/index.html` — статическое демо login/callback/search/upload после `npm run build`.
+- `demos/index.html` — статическое демо login/callback/search/upload/public API после `npm run build`.
 - `npm run demos` — сборка и запуск Vite-сервера для демо.
+- `docs/api/README.md` — компактный справочник публичного API, опций, методов и экспортов.
+- `docs/demo/README.md` — сценарии ручной проверки демо и описание demo forms.
 - `docs/recipes/README.md` — короткие рецепты по API, data-атрибутам, adapters и server errors.
+- `CHANGELOG.md` — история релизов и baseline покрытия.
 
 ## Сборка и разработка
 
@@ -420,6 +423,7 @@ registerSchemaValidator('company-email', z.string().email(), 'Введите к
 
 - **npm run build**: Сборка проекта.
 - **npm run watch**: Сборка в режиме наблюдения.
+- **npm run docs:check**: Проверка версии, ссылок документации, demo-файлов и package README.
 - **npm run demos**: Запуск демо-версии с использованием Vite.
 
 ## Вклад

package/demos/index.html

@@ -145,6 +145,43 @@
 					<button type="submit">Отправить</button>
 				</form>
 			</section>
+
+			<section class="demo-panel demo-panel--wide">
+				<div class="panel-title">
+					<p class="eyebrow">Public API</p>
+					<h2>Programmatic control</h2>
+				</div>
+				<form data-form-father action="/demo/api" method="post" data-demo="api" novalidate>
+					<div data-form-father-summary hidden></div>
+
+					<label class="field">
+						<span>Имя</span>
+						<input class="input" name="name" data-validate="required" data-error-required="Укажите имя" />
+					</label>
+
+					<label class="field">
+						<span>Email</span>
+						<input class="input" name="email" type="email" data-validate="required|email" />
+					</label>
+
+					<label class="field">
+						<span>Тариф</span>
+						<select class="input" name="plan">
+							<option value="starter">Starter</option>
+							<option value="team">Team</option>
+							<option value="enterprise">Enterprise</option>
+						</select>
+					</label>
+
+					<div class="demo-actions" aria-label="Public API actions">
+						<button type="button" data-api-action="fill">setValues()</button>
+						<button type="button" data-api-action="validate-email">validateField()</button>
+						<button type="button" data-api-action="server-errors">setErrors()</button>
+						<button type="button" data-api-action="values">getValues()</button>
+						<button type="button" data-api-action="clear">clearErrors()</button>
+					</div>
+				</form>
+			</section>
 		</main>
 
 		<section class="demo-output">

package/demos/main.js

@@ -1,6 +1,6 @@
 const api = window.FormFather || {};
 const Form = api.default || api.Form || api;
-const { createLengthValidator, registerValidator, sameAsField } = api;
+const { FORM_ERROR_FIELD, createLengthValidator, registerValidator, sameAsField } = api;
 const output = document.querySelector('#demo-output');
 
 function writeOutput(title, payload) {
@@ -54,6 +54,14 @@ window.fetch = async (url, options = {}) => {
 		});
 	}
 
+	if (requestUrl.startsWith('/demo/api')) {
+		return json({
+			success: true,
+			message: 'Programmatic API form accepted',
+			method,
+		});
+	}
+
 	return json({ success: false, error: true, 'error-msg': `No demo route for ${requestUrl}` }, 404);
 };
 
@@ -68,7 +76,7 @@ registerValidator(
 	{ override: true },
 );
 
-Form.initAll('form[data-form-father]', {
+const forms = Form.initAll('form[data-form-father]', {
 	inputSelector: '.input',
 	inputWrapperSelector: '.field',
 	validateOn: ['blur', 'change'],
@@ -93,3 +101,49 @@ Form.initAll('form[data-form-father]', {
 		}
 	},
 });
+
+const formByDemo = new Map(forms.map(form => [form.$el.dataset.demo, form]));
+const apiForm = formByDemo.get('api');
+
+document.querySelectorAll('[data-api-action]').forEach(button => {
+	button.addEventListener('click', async () => {
+		if (!apiForm) return;
+
+		switch (button.dataset.apiAction) {
+			case 'fill':
+				apiForm.setValues({
+					name: 'Ada Lovelace',
+					email: 'ada@example.com',
+					plan: 'team',
+				});
+				writeOutput('setValues()', apiForm.getValues());
+				break;
+
+			case 'validate-email': {
+				const valid = await apiForm.validateField('email');
+				writeOutput('validateField("email")', {
+					valid,
+					errors: apiForm.getErrors(),
+				});
+				break;
+			}
+
+			case 'server-errors':
+				apiForm.setErrors({
+					email: 'Этот email уже зарегистрирован',
+					[FORM_ERROR_FIELD]: 'Сервер попросил проверить форму',
+				});
+				writeOutput('setErrors()', apiForm.getErrors());
+				break;
+
+			case 'values':
+				writeOutput('getValues()', apiForm.getValues());
+				break;
+
+			case 'clear':
+				apiForm.clearErrors();
+				writeOutput('clearErrors()', apiForm.getErrors());
+				break;
+		}
+	});
+});

package/demos/styles.css

@@ -102,6 +102,10 @@ button:focus-visible {
 	padding: 22px;
 }
 
+.demo-panel--wide {
+	grid-column: 1 / -1;
+}
+
 .panel-title {
 	margin-bottom: 18px;
 }
@@ -156,6 +160,17 @@ form {
 	color: var(--accent-strong);
 }
 
+.demo-actions {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 8px;
+}
+
+.demo-actions button {
+	min-height: 38px;
+	padding-inline: 12px;
+}
+
 .field {
 	display: grid;
 	gap: 6px;

package/docs/api/README.md

@@ -0,0 +1,153 @@
+# Form Father API Reference
+
+This page is a compact reference for the public API exported by `form-father`.
+
+## Main Import
+
+```ts
+import Form from 'form-father';
+```
+
+`Form` is the default export and is constructed with a native `<form>` element.
+
+```ts
+const form = new Form(document.querySelector('form')!, {
+	inputWrapperSelector: '.field',
+	validateOn: ['blur', 'change'],
+	revalidateOn: ['input', 'change'],
+	errorSummary: true,
+});
+```
+
+## Form Options
+
+| Option | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `inputSelector` | `string` | `.input` | Selector used by legacy input collection helpers. |
+| `inputWrapperSelector` | `string` | `.input-primary` | Field wrapper selector used for inline error rendering. |
+| `showLoaderButton` | `boolean` | `true` | Adds a loader to submit buttons while a request is pending. |
+| `loaderColor` | `string` | `#fff` | Loader SVG color. |
+| `scrollToFirstErroredInput` | `boolean` | `true` | Scrolls to the first invalid field. |
+| `focusFirstErroredInput` | `boolean` | `false` | Focuses the first invalid field after validation. |
+| `validateOn` | `ValidationTrigger | ValidationTrigger[]` | `submit` | Live validation triggers: `submit`, `input`, `blur`, `change`. |
+| `revalidateOn` | `ValidationTrigger | ValidationTrigger[]` | `input`, `change` | Rechecks fields that are already invalid. |
+| `validationDebounce` | `number` | `0` | Delay for live validation. |
+| `validationSchema` | `ValidationSchema` | built in defaults | Field rules matched by selectors or `data-validate`. |
+| `formValidators` | `FormValidator | FormValidator[]` | none | Cross-field and form-level validation. |
+| `errorContainerAttribute` | `string` | `data-error-container` | Attribute containing a selector for a custom error container. |
+| `validationStateAttribute` | `string` | `data-form-father-state` | Field state attribute: `validating`, `valid`, `invalid`. |
+| `ariaDescribeErrors` | `boolean` | `true` | Links inline errors to fields with `aria-describedby`. |
+| `errorIdPrefix` | `string` | `form-father-error` | Prefix for generated error element ids. |
+| `errorSummary` | `boolean | ErrorSummaryOptions` | `false` | Enables an accessible form error summary. |
+| `observeMutations` | `boolean` | `false` | Rebinds controls when fields/buttons are added dynamically. |
+| `wrapData` | `(data) => data` | none | Transforms form values before request body creation. |
+| `logging` | `boolean` | `false` | Logs submitted `FormData` values. |
+
+## Lifecycle Callbacks
+
+| Callback | When it runs |
+| --- | --- |
+| `onBeforeValidate(form)` | Before submit-time validation. |
+| `onAfterValidate(isValid, form)` | After validation and before submit. |
+| `onValidationError(errors, form)` | When client-side validation fails. |
+| `onBeforeSubmit(form)` | Before a valid form is sent. Return `false` to cancel. |
+| `onSubmit(form)` | When request sending starts. |
+| `onResponse(body, form)` | After a response body is parsed. |
+| `onResponseSuccess(body, form)` | For successful HTTP responses with `success: true`. |
+| `onResponseUnsuccess(body, form)` | For non-OK responses, `success !== true`, or invalid JSON. |
+| `onSubmitError(error, form)` | When sending or response parsing throws. |
+
+## Instance Methods
+
+| Method | Returns | Purpose |
+| --- | --- | --- |
+| `validate()` | `Promise<boolean>` | Validates the whole form. |
+| `validateField(field)` | `Promise<boolean>` | Validates one field by `name` or element. |
+| `submit()` | `Promise<SubmitResult | undefined>` | Sends the form programmatically. |
+| `showFieldError(field, message, source?)` | `boolean` | Shows a field error manually. |
+| `setErrors(errors, source?)` | `this` | Applies backend, form-level, or manual errors. |
+| `getErrors()` | `ValidationError[]` | Returns current error records. |
+| `getValues()` | `Record<string, any>` | Serializes the form into a plain object. |
+| `setValues(values)` | `this` | Sets field values by `name` and dispatches `input`/`change`. |
+| `clearErrors()` | `this` | Clears field and form errors. |
+| `reset(options?)` | `this` | Calls native `form.reset()` and clears errors by default. |
+| `clearInputs()` | `void` | Clears input values without resetting native defaults. |
+| `updateOptions(options)` | `this` | Updates options and rebinds listeners. |
+| `destroy()` | `void` | Removes listeners, loaders, error nodes, and runtime state. |
+
+## Static Methods and Constants
+
+```ts
+Form.initAll('form[data-form-father]', options);
+Form.setDefaultParams({ inputWrapperSelector: '.field' });
+Form.defaultValidationSchema = {};
+```
+
+| Export | Purpose |
+| --- | --- |
+| `FORM_ERROR_FIELD` | Constant for form-level errors in `getErrors()` and `setErrors()`. |
+| `Form.initAll(selector, options)` | Initializes matching forms and reuses existing instances. |
+| `Form.setDefaultParams(params)` | Merges global default options for future instances. |
+| `Form.defaultValidationSchema` | Global default validation schema. |
+
+## Validators
+
+```ts
+import {
+	createLengthValidator,
+	createPatternValidator,
+	registerFieldValidator,
+	registerValidator,
+} from 'form-father';
+```
+
+| Export | Purpose |
+| --- | --- |
+| `registerValidator(name, fn, message, options?)` | Registers a full validator. |
+| `registerFieldValidator(name, predicate, message, options?)` | Registers a predicate-only field validator. |
+| `getValidator(name)` | Reads one validator definition. |
+| `getAllValidators()` | Reads the validator registry. |
+| `createPatternValidator(pattern)` | Builds a regex validator. |
+| `createLengthValidator(options)` | Builds min/max length validation. |
+
+## Form Validators
+
+```ts
+import { dateOrder, requiredIf, sameAsField } from 'form-father';
+```
+
+| Export | Purpose |
+| --- | --- |
+| `createFormValidator(predicate, issue)` | Builds a reusable cross-field validator. |
+| `sameAsField(field, otherField, message?, rule?)` | Checks that two values match. |
+| `requiredIf(field, condition, message?, rule?)` | Makes a field required when a predicate is true. |
+| `dateOrder(startField, endField, message?, rule?)` | Checks chronological field order. |
+
+## Schema Adapters
+
+```ts
+import { createSchemaValidator, registerSchemaValidator } from 'form-father';
+```
+
+Adapters expect a schema-like object with either `safeParse(value)` or `parse(value)`.
+
+| Export | Purpose |
+| --- | --- |
+| `createSchemaValidator(schema, message?)` | Converts a schema into a field validator function. |
+| `registerSchemaValidator(name, schema, message?, options?)` | Registers a schema-backed rule. |
+| `createFieldValidator(predicate, message)` | Creates a simple predicate validator. |
+
+## Helpers
+
+| Export | Purpose |
+| --- | --- |
+| `serializeToFormData(element)` | Serializes a form-like element into `FormData`. |
+| `serializeFormToJSON(form)` | Serializes a form into a plain object. |
+| `isEmailValid(value)` | Checks email format. |
+| `isUrlValid(value)` | Checks URLs, domains, IPs, and `localhost`. |
+| `isPhoneValid(value)` | Checks Russian `+7XXXXXXXXXX` phone numbers. |
+| `closest(element, selector)` | Finds a closest matching ancestor. |
+| `parseCommonResponseProperties(body)` | Normalizes common response flags. |
+| `blockScrollBody()` | Locks body scrolling. |
+| `unblockScrollBody()` | Restores body scrolling. |
+

package/docs/demo/README.md

@@ -0,0 +1,37 @@
+# Demo Guide
+
+The demo is a static, dependency-light page that exercises common Form Father flows after a package build.
+
+```bash
+npm run build
+npm run demos
+```
+
+Open the Vite URL printed by the command. The page loads `dist/FormFather.min.js` and `demos/main.js`, so it reflects the
+actual browser bundle.
+
+## Demo Forms
+
+| Form | What it demonstrates |
+| --- | --- |
+| Login | Live validation, async validator state, password confirmation, and custom error containers. |
+| Callback | Server-side field errors and form-level API errors. |
+| Search | `GET` forms and query-string body handling. |
+| Multipart | Browser-managed `FormData` upload flow. |
+| Public API | `setValues()`, `validateField()`, `setErrors()`, `getValues()`, and `clearErrors()`. |
+
+## Useful Manual Checks
+
+- Enter `taken@example.com` in the Login email field to see async validation fail.
+- Submit Callback with a valid phone to see backend field errors applied after the mocked response.
+- Clear the Search query and submit to inspect the accessible error summary.
+- Use Public API buttons to inspect programmatic state changes in the Output panel.
+
+## Files
+
+| File | Purpose |
+| --- | --- |
+| `demos/index.html` | Demo markup and forms. |
+| `demos/main.js` | Mock API, validator registration, `Form.initAll()`, and public API playground actions. |
+| `demos/styles.css` | Minimal UI styling for fields, summaries, output, and loading states. |
+

package/docs/en/README.md

@@ -226,9 +226,12 @@ 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`.
+- `demos/index.html` is a static login/callback/search/upload/public API demo after `npm run build`.
 - `npm run demos` builds the package and starts the Vite demo server.
+- `docs/api/README.md` is a compact reference for public API, options, methods, and exports.
+- `docs/demo/README.md` explains manual demo checks and demo form coverage.
 - `docs/recipes/README.md` contains short API, data-attribute, adapter, and server-error recipes.
+- `CHANGELOG.md` tracks releases and coverage baselines.
 
 ## Helpers
 
@@ -250,6 +253,7 @@ The library provides a number of utility functions:
 
 - **npm run build**: Builds the project.
 - **npm run watch**: Builds the project in watch mode.
+- **npm run docs:check**: Checks docs links, version references, demo files, and package README sync.
 - **npm run demos**: Runs a demo version using Vite.
 
 ## Contributing

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "form-father",
-	"version": "0.6.0",
+	"version": "0.7.0",
 	"description": "Form Father: Библиотека для обработки форм",
 	"type": "module",
 	"files": ["dist", "README.md", "LICENSE", "RESPONSE_API.md", "CHANGELOG.md", "docs", "demos"],
@@ -14,7 +14,8 @@
 		"build": "rollup -c",
 		"watch": "rollup -c -w",
 		"release": "node scripts/release.js",
-		"release:check": "npm test -- --runInBand --watchman=false && npm run build && npm run smoke:package && npm run pack:dry-run",
+		"release:check": "npm test -- --runInBand --watchman=false && npm run docs:check && npm run build && npm run smoke:package && npm run pack:dry-run",
+		"docs:check": "node scripts/check-docs.mjs",
 		"test": "jest --coverage",
 		"prepublishOnly": "npm test -- --runInBand --watchman=false && npm run build",
 		"pack:dry-run": "npm_config_cache=/tmp/form-father-npm-cache npm pack --dry-run",