adaptform 2.0.5 → 2.2.0

package/README.md

@@ -1,420 +1,422 @@
 # AdaptForm
 
+[English](README.md) · [Русский](README.ru.md)
+
 [![npm version](https://img.shields.io/npm/v/adaptform.svg)](https://www.npmjs.com/package/adaptform)
 [![npm downloads](https://img.shields.io/npm/dm/adaptform.svg)](https://www.npmjs.com/package/adaptform)
-[![bundle size](https://img.shields.io/bundlephobia/minzip/adaptform)](https://bundlephobia.com/package/adaptform)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 
-AdaptForm is a TypeScript-first form modeling framework inspired by Django Forms and Pydantic.
-
-Instead of describing validation schemas, you describe forms as classes with typed fields. Each field is responsible for
-its own state lifecycle, validation, transformation pipeline, and serialization logic.
+**[Open the interactive demo](https://arhimen.github.io/AdaptForm/)** · **[Read the changelog](https://github.com/ArhiMEN/AdaptForm/blob/master/CHANGELOG.md)** · **[Browse the demo source](https://github.com/ArhiMEN/AdaptForm/tree/master/demo)**
 
-## AdaptForm provides:
+Maintainers: [automatic npm publication setup](docs/NPM_PUBLISH.md).
 
-- Typed form models
-- Field-level validation
-- Cross-field validation
-- Input transformation plugins
-- Nested forms and arrays
-- Automatic TypeScript inference
-- Framework-agnostic integration
+AdaptForm is a TypeScript-first, framework-independent, class-based headless form engine inspired by Django Forms and Pydantic. Forms and fields manage values, casting, validation, errors, baselines, subscriptions and observable state without requiring UI framework components.
 
 ## Features
 
-- Form-as-a-domain-model architecture
-- Field-level state + validation ownership
-- Cross-field validation support
-- Plugin-based transformation pipeline
-- Strong TypeScript inference
-- Nested forms & collections
-- Built-in serialization (JSON / FormData)
-- Optional date engine (Luxon)
-- Framework-agnostic design
-- Zero-core-dependencies
-
-## Philosophy
-
-Most form libraries treat forms as validation schemas:
-
-```TypeScript
-const schema = z.object({
-  login: z.string(),
-  password: z.string(),
-})
-````
+- Class-based form models with inferred TypeScript value types.
+- Field-level and cross-field validation.
+- Conditional required rules and custom synchronous validators.
+- String, number, decimal, boolean, and JavaScript Date field types.
+- Dynamic arrays of fields and arrays of nested forms.
+- Input transformation plugins, including `MaskPlugin`.
+- Server-error mapping with `ErrorsSchema`.
+- JSON and `FormData` serialization.
+- Optional Luxon integration through the `adaptform/luxon` entry point.
+- Framework-agnostic core with no required runtime dependencies.
+- Clean-value baselines with `isDirty` and `commitBaseline()` on fields, forms and collections.
+- Stable immutable `getSnapshot()` data, `subscribe()` and unsubscribe for reactive UIs.
+- Synchronous nested `Form.batch()` and propagation of nested form/collection updates.
 
-AdaptForm treats forms as stateful domain models:
+## Installation
 
-```TypeScript
-class LoginForm extends Form {
-  login = new Field(StringType)
-  password = new Field(StringType)
-}
-```
+Install the published npm package:
 
-field is not just a validator — it is a state container that owns:
+```bash
+npm install adaptform
+```
 
-- value
-- validation
-- errors
-- transformation
-- plugins
-- type casting
+Luxon integration is optional:
 
-The form itself becomes a single source of truth.
+```bash
+npm install luxon
+```
 
-Simple Vue:
+The [interactive demo](https://arhimen.github.io/AdaptForm/) runs from repository source, with automatic deployment from `v2.1.0` and `master`. **Headless APIs in the 2.2.0 source candidate are not yet published to npm.** Check the [npm package](https://www.npmjs.com/package/adaptform) for available published versions.
 
-## Without AdaptForm
+The demo supports English and Russian with a persistent language selector: [English](https://arhimen.github.io/AdaptForm/?lang=en) · [Русский](https://arhimen.github.io/AdaptForm/?lang=ru). Switching languages preserves form data and validation state.
 
-A typical Vue form consists of multiple disconnected parts:
+## Quick start
 
-- reactive state
-- validation schema
-- error store
-- input masks
-- submission mapping
+```typescript
+import { BooleanType, Field, Form, StringType } from 'adaptform'
 
-## With AdaptForm
+class RegistrationForm extends Form {
+  name = new Field(StringType, null, {
+    isRequired: true,
+    minLength: 2,
+    maxLength: 50,
+  })
 
-Everything is unified into a single form model:
+  email = new Field(StringType, null, {
+    isRequired: true,
+    pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+  })
 
-```TypeScript
-class RegistrationForm extends Form {
-  phone = new Field(StringType)
+  acceptedTerms = new Field(BooleanType, false, {
+    mustBeTrue: true,
+  })
 }
-````
 
-## Installation
+const form = new RegistrationForm()
+form.fields = {
+  name: 'Alex Morgan',
+  email: 'alex@example.com',
+  acceptedTerms: true,
+}
 
-```bash
-npm install adaptform
+if (form.isValid) {
+  console.log(form.fieldsValue)
+  console.log(form.toJSON())
+} else {
+  console.log(form.allErrors)
+}
 ```
 
-## Optional: Luxon integration
+`form.fields` assigns the supplied values and validates the completed form. Values for fields omitted from the assignment are left unchanged.
 
-```Bash
-npm install luxon
-```
+## Field types and options
 
-## Quick Start
+All field types are constructed using `new Field(TypeConstructor, defaultValue?, options?)`.
 
-```TypeScript
-import {Form, Field, StringType, NumberType} from 'adaptform';
+### StringType
 
-class LoginForm extends Form {
-  login = new Field(StringType, null, {maxLength: 50});
-  password = new Field(StringType, null, {minLength: 8});
-  remember = new Field(BooleanType, false);
-}
+```typescript
+const username = new Field(StringType, null, {
+  isRequired: true,
+  minLength: 3,
+  maxLength: 32,
+  pattern: /^[a-z0-9_]+$/i,
+  messages: {
+    isRequired: 'Enter a username.',
+    minLength: 'Use at least 3 characters.',
+    pattern: 'Use only letters, numbers, and underscores.',
+  },
+})
+```
 
-const form = new LoginForm();
+Supported constraints: `isRequired`, `minLength`, `maxLength`, and `pattern`.
 
-form.fields = {
-  login: 'john_doe',
-  password: 'securepass123'
-};
+### NumberType
 
-console.log(form.isValid); // true
-console.log(form.fieldsValue); // { login: 'john_doe', password: 'securepass123', remember: false }
+```typescript
+const age = new Field(NumberType, null, {
+  isRequired: true,
+  ge: 18,
+  le: 120,
+})
 ```
 
-## Usage Examples
+Supported constraints: `gt`, `ge`, `lt`, and `le`. Values must be finite integers; blank strings and non-finite numbers are rejected.
 
-## Field Types
+### DecimalType
 
-```TypeScript
-import {Field, StringType, NumberType, BooleanType, DecimalType, DateType} from 'adaptform';
+```typescript
+const price = new Field(DecimalType, null, {
+  decimalPlaces: 2,
+  maxDigits: 8,
+  ge: 0,
+})
+```
 
-// String with validation
-const name = new Field(StringType, null, {
-  minLength: 2,
-  maxLength: 50,
-  pattern: /^[a-zA-Z]+$/
-});
+Supports `gt`, `ge`, `lt`, `le`, `decimalPlaces`, and `maxDigits`. Numeric inputs with excess precision are rejected rather than silently rounded. String inputs may use a comma or a period as the decimal separator. Incomplete values such as `"123."` retain their editable text but fail explicit validation; call `Form.checkValid()` before submitting. `toJSON()` does not validate automatically.
 
-// Number with range
-const age = new Field(NumberType, null, {
-  gt: 0,    // greater than
-  lt: 120   // less than
-});
+### BooleanType
 
-// Boolean with requirement
-const agreed = new Field(BooleanType, false, {
+```typescript
+const accepted = new Field(BooleanType, false, {
   mustBeTrue: true,
-  messages: {
-    mustBeTrue: 'You must agree to the terms'
-  }
-});
-```
-
-## Custom Validation
-
-```TypeScript
-const email = new Field(StringType, null, {
-  validate: (value) => {
-    return value.includes('@') || 'Invalid email format';
-  }
-});
-
-// Async validation with form context
-const passwordConfirmation = new Field(StringType, null, {
-  validate: (value, form) => {
-    return value === form?.password?.valueClear || 'Passwords do not match';
-  }
-});
+})
 ```
 
-## Conditional Required Fields
+Supports `mustBeTrue` and `mustBeFalse`.
 
-```TypeScript
-class SignUpForm extends Form {
-  country = new Field(StringType, null);
+### DateType
 
-  state = new Field(StringType, null, {
-    isRequired: (form) => form?.country?.valueClear === 'USA',
-    messages: {
-      isRequired: 'State is required for USA residents'
-    }
-  });
-}
+```typescript
+const birthday = new Field(DateType, null, {
+  isDatetime: false,
+  minDate: new Date('1900-01-01T00:00:00.000Z'),
+  maxDate: new Date(),
+})
 ```
 
-## Input Masks
+Supports `minDate`, `maxDate`, and `isDatetime`. When `isDatetime` is false, comparisons use calendar dates; when true, timestamps are compared. Invalid dates are rejected.
 
-```TypeScript
-import {Field, StringType, MaskPlugin} from 'adaptform';
+### Custom validation and messages
 
-const phone = new Field(StringType, null, {
-  plugins: [
-    new MaskPlugin({
-      maskFormat: '+7 (___) ___-__-__',
-      maskPlaceholder: '_',
-      digitPattern: /\d/
-    })
-  ]
-});
+Field options support `isRequired`, `messages`, and a synchronous `validate(value, form)` callback. A custom validator returns `true` for success, `false` for the configured validation message, or a string for a specific error.
+
+```typescript
+class PasswordForm extends Form {
+  password = new Field(StringType, null, { minLength: 8 })
 
-phone.rawValue = '9991234567';
-console.log(phone.valueClear); // '+7 (999) 123-45-67'
+  confirmation = new Field(StringType, null, {
+    isRequired: true,
+    validate: (value, form) =>
+      value === form?.password.valueClear || 'Passwords do not match.',
+  })
+}
 ```
 
-## Nested Forms
+Validators are synchronous; returning a Promise is not supported. For asynchronous checks such as server-side uniqueness, call the service separately and apply the response through the form's error API.
 
-```TypeScript
-import {ArrayField, Field, NumberType} from 'adaptform';
+## Validation lifecycle and state
 
-const gameIds = new ArrayField(
-  (value?: number) => new Field(NumberType, value, {gt: 0}),
-  {minItems: 1}
-);
+- Constructor defaults begin untouched.
+- Empty strings and whitespace-only strings count as empty values.
+- Global and sticky regular-expression flags do not make repeated string validation stateful.
+- `form.checkValid()` validates every field and returns `false` when a field is invalid or global server errors remain.
+- Reading `isValid` does not run validators. Fields without a non-null default start with `isValid === null`; non-null constructor defaults pass through casting and validation but still start untouched. After `reset()`, field validity is unset until validation runs again.
+- Bulk assignment validates after direct field values have been assigned, so conditional-required rules can inspect the complete form state.
+- If you change dependent fields one at a time, call `form.checkValid()` after the changes to recompute cross-field rules.
+- `field.setRawValue(value, false)` and `form.setFields(data, false)` allow advanced callers to defer validation. Call `checkValid()` before relying on the validity state.
+- `reset()` restores defaults, clears errors, and leaves validity unset until the next validation. Collection validity is false after reset until the collection is checked again.
+- Adding, removing, or clearing collection items refreshes collection validation outside `Form.batch()`; inside a batch automatic validation is deferred. Invalid removal indices are ignored.
 
-gameIds.itemsValue = [1, 2, 3];
-gameIds.add(4);
-console.log(gameIds.itemsValue); // [1, 2, 3, 4]
-```
+## Dynamic collections
 
-## Luxon Date Integration
+### ArrayField
 
-```Bash
-npm install luxon
-```
+Use `ArrayField` for a dynamic list of similarly typed fields.
 
-```TypeScript
-import {DateLuxonType} from 'adaptform/luxon';
-import {DateTime} from 'luxon';
+```typescript
+import { ArrayField, Field, StringType } from 'adaptform'
 
-const birthdate = new Field(DateLuxonType, null, {
-  isDatetime: false,
-  minDate: DateTime.fromISO('1900-01-01'),
-  maxDate: DateTime.now(),
-  inputFormat: 'dd.MM.yyyy',
-  messages: {
-    minDate: 'Date must be after 1900',
-    maxDate: 'Date cannot be in the future'
-  }
-});
+const tags = new ArrayField(
+  (value?: string) => new Field(StringType, value, {
+    isRequired: true,
+    minLength: 2,
+  }),
+  { minItems: 1, maxItems: 5 },
+)
 
-birthdate.rawValue = '15.06.1990';
-console.log(birthdate.valueClear); // Luxon DateTime object
+tags.add('typescript')
+tags.add('forms')
+console.log(tags.itemsValue)
+console.log(tags.isValid)
 ```
 
-## Form Submission
+Options include `isRequired`, `minItems`, `maxItems`, `messages`, and a synchronous `validate(values, form)` callback. `itemsValue` returns an array whose entries may be `null`.
 
-```TypeScript
-class ContactForm extends Form {
-  name = new Field(StringType, null, {maxLength: 100});
-  email = new Field(StringType, null, {
-    pattern: /^[^@]+@[^@.]+\.[^@.]+$/
-  });
-  message = new Field(StringType, null, {maxLength: 1000});
-}
+### ArrayFormField
 
-const form = new ContactForm();
-form.fields = {
-  name: 'John',
-  email: 'john@example.com',
-  message: 'Hello!'
-};
-
-if (form.checkValid()) {
-  // Submit form
-  const formData = form.toFormData();
-  const json = form.toJSON();
-
-  await fetch('/api/contact', {
-    method: 'POST',
-    body: formData
-  });
-} else {
-  console.log(form.allErrors);
-  // {
-  //   name: [],
-  //   email: [],
-  //   message: []
-  // }
-}
-```
+Use `ArrayFormField` for a list of nested form instances.
 
-## Global Errors
+```typescript
+import { ArrayFormField, Field, Form, StringType } from 'adaptform'
 
-```TypeScript
-class LoginForm extends Form {
-  login = new Field(StringType, null);
-  password = new Field(StringType, null);
+class AddressForm extends Form {
+  city = new Field(StringType, null, { isRequired: true })
+  postalCode = new Field(StringType, null, { isRequired: true })
 }
 
-const form = new LoginForm();
-
-// Add server-side errors
-form.errors = {
-  login: 'Account not found',
-  password: 'Invalid password'
-};
+const addresses = new ArrayFormField(AddressForm, {
+  minForms: 1,
+  maxForms: 3,
+})
 
-// Or set global error
-form.setGlobalError('auth', 'Authentication failed');
+addresses.add({ city: 'Berlin', postalCode: '10115' })
+console.log(addresses.formsFieldsValue)
 ```
 
-## Plugin System
+Options include `isRequired`, `minForms`, `maxForms`, `messages`, and a synchronous `validate(forms, form)` callback.
 
-### Built-in Plugins
+## Input masks
 
-* **MaskPlugin** - Input masking (phone, date, credit card)
+Plugins transform input before it is cast and validated. The built-in `MaskPlugin` supports fixed mask characters and digit or custom pattern placeholders.
 
-* **FieldPlugin** - Base plugin for custom extensions
+```typescript
+import { Field, MaskPlugin, StringType } from 'adaptform'
 
-### Creating Custom Plugins
+const phone = new Field(StringType, null, {
+  plugins: [
+    new MaskPlugin({
+      maskFormat: '+1 (___) ___-____',
+      maskPlaceholder: '_',
+      digitPattern: /\d/,
+    }),
+  ],
+})
 
-```TypeScript
-import {BasePlugin} from 'adaptform';
-import type {FieldPlugin} from 'adaptform';
+phone.rawValue = '4155550134'
+console.log(phone.rawValue)
+console.log(phone.valueClear)
+```
 
-class UppercasePlugin extends BasePlugin implements FieldPlugin<string> {
-  toRawValue(value: string): string {
-    return value?.toUpperCase() || '';
-  }
+## Server-side errors with ErrorsSchema
 
-  toValueClear(value: string): string {
-    return value?.toLowerCase() || '';
-  }
-}
+`ErrorsSchema` maps error keys returned by a backend to form fields. By default, unmatched keys fall back to their original names.
 
-const field = new Field(StringType, null, {
-  plugins: [new UppercasePlugin()]
-});
-```
+```typescript
+import { ErrorsSchema, Form, Field, StringType } from 'adaptform'
 
-## API Reference
+class AccountForm extends Form {
+  email = new Field(StringType)
+  username = new Field(StringType)
+}
 
-### Form
+const form = new AccountForm()
+form.errorsShema = new ErrorsSchema()
+  .staticKey('email_address', 'email')
+  .staticKey('user_name', 'username')
+  .fallback(key => key)
 
-* `checkValid(form?)` - Validate all fields
+form.errors = {
+  email_address: 'This email is already registered.',
+  user_name: 'This username is unavailable.',
+  request_id: 'The request could not be completed.',
+}
 
-* `fieldsValue` - Get all field values
+console.log(form.allErrors)
+```
 
-* `allErrors` - Get all validation errors
+Available schema methods:
 
-* `globalErrors` - Get global errors
+- `staticKey(errorKey, fieldName)` maps an exact key.
+- `dynamicKey(pattern, mapping, options?)` maps keys using a regular expression and optional priority.
+- `fallback(handler)` handles keys that do not match configured rules.
+- `transformValue(transformer)` normalizes server error values before mapping.
+- `nest(prefix)` creates a schema for nested field paths.
+- `clone()` and `merge(other)` compose schemas.
+- `ErrorsSchema.fromObject(mapping)` creates a schema from a key-to-field map.
+- `ErrorsSchema.forArray(itemSchema, arrayFieldName, indexExtractor?)` maps array-item errors, including bracket and dotted index notation.
 
-* `toFormData()` - Convert to FormData
+Assigning a new `form.errors` object clears previously applied errors before applying the new payload. Unknown field keys become global errors.
 
-* `toJSON()` - Convert to JSON
+## Serialization
 
-* `reset()` - Reset all fields
+### JSON
 
-### Field
+`toJSON()` returns a JSON-compatible object. JavaScript `Date` instances are recursively converted to ISO 8601 strings, including dates nested in arrays and plain objects.
 
-* `rawValue` - Set raw input value
+```typescript
+const payload = form.toJSON()
+await fetch('/api/profile', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify(payload),
+})
+```
 
-* `valueClear` - Get cleaned/validated value
+### FormData
 
-* `isValid` - Check if field is valid
+`toFormData()` omits `null` and `undefined` values, appends scalar values as strings, serializes dates as ISO 8601 strings, preserves `Blob` and `File` values, and JSON-encodes arrays and nested objects.
 
-* `error` - Get first error message
+```typescript
+const body = form.toFormData()
+await fetch('/api/profile', {
+  method: 'POST',
+  body,
+})
+```
 
-* `errors` - Get all error messages
+Do not set the multipart `Content-Type` header manually; the browser supplies the boundary.
 
-* `isTouched` - Check if field was modified
+## Optional Luxon integration
 
-* `isEmpty` - Check if field is empty
+Install Luxon separately, then import the additional date type from the dedicated subpath:
 
-* `reset()` - Reset to default value
+```bash
+npm install luxon
+```
 
-### ArrayField
+```typescript
+import { Field } from 'adaptform'
+import { DateLuxonType } from 'adaptform/luxon'
+import { DateTime } from 'luxon'
 
-* `add(value?)` - Add new field
+const date = new Field(DateLuxonType, null, {
+  isDatetime: false,
+  minDate: DateTime.fromISO('1900-01-01'),
+  maxDate: DateTime.now(),
+  inputFormat: 'dd.MM.yyyy',
+})
+```
 
-* `remove(index)` - Remove field at index
+## API overview
 
-* `clear()` - Remove all fields
+| Class | Main API |
+| --- | --- |
+| `Form` | `fields`, `setFields()`, `fieldsValue`, `checkValid()`, `isValid`, `isDirty`, `commitBaseline()`, `subscribe()`, `getSnapshot()`, `batch()`, `allErrors`, `globalErrors`, `errors`, `setGlobalError()`, `clearGlobalErrors()`, `reset()`, `toJSON()`, `toFormData()` |
+| `Field` | `rawValue`, `setRawValue()`, `valueClear`, `errors`, `error`, `isValid`, `isTouched`, `isDirty`, `commitBaseline()`, `subscribe()`, `getSnapshot()`, `isEmpty`, `checkValid()`, `reset()` |
+| `ArrayField` | `items`, `itemsValue`, `add()`, `remove()`, `clear()`, `isDirty`, `commitBaseline()`, `subscribe()`, `getSnapshot()`, `checkValid()`, `reset()` |
+| `ArrayFormField` | `forms`, `formsFieldsValue`, `add()`, `remove()`, `clear()`, `isDirty`, `commitBaseline()`, `subscribe()`, `getSnapshot()`, `checkValid()`, `reset()` |
+| `ErrorsSchema` | `staticKey()`, `dynamicKey()`, `fallback()`, `transformValue()`, `parseErrors()`, `parseErrorsDetailed()`, `nest()`, `clone()`, `merge()`, `forArray()`, `fromObject()` |
 
-* `itemsValue` - Get array of values
+## Development
 
-* `items` - Get array of Field instances
+Requirements: Node.js 22 (used by CI) and npm.
 
-### ArrayFormField
+```bash
+npm ci
+npm run lint
+npm test
+npm run build
+npx tsc --noEmit -p tsconfig.json
+npm run check:demo
+npm run build:demo
+```
 
-* `add(data?)` - Add new form
+To run the interactive demo locally:
 
-* `remove(index)` - Remove form at index
+```bash
+npm run dev -- --config demo/vite.config.ts
+```
 
-* `clear()` - Remove all forms
+The demo is built by GitHub Actions from `v2.1.0` and `master`. GitHub Pages is configured to allow both branches to publish to the same demo URL; see [Demo and GitHub Pages notes](https://github.com/ArhiMEN/AdaptForm/blob/master/docs/DEMO.md).
 
-* `forms` - Get array of Form instances
+## Links
 
-* `formsFieldsValue` - Get array of form values
+- **[Interactive demo](https://arhimen.github.io/AdaptForm/)**
+- [GitHub repository](https://github.com/ArhiMEN/AdaptForm)
+- [npm package](https://www.npmjs.com/package/adaptform)
+- [Issue tracker](https://github.com/ArhiMEN/AdaptForm/issues)
+- [Changelog](https://github.com/ArhiMEN/AdaptForm/blob/master/CHANGELOG.md)
+- [License](https://github.com/ArhiMEN/AdaptForm/blob/master/LICENSE.md)
 
-## TypeScript Support
+## License
 
-```TypeScript
-import {Form, Field, StringType, NumberType} from 'adaptform';
+MIT © Stanislav Orlov
 
-class UserForm extends Form {
-  name = new Field(StringType, null);
-  age = new Field(NumberType, null);
-}
+## Headless form state (2.2.0 source candidate)
 
-const form = new UserForm();
+HF-005–HF-010 were merged after independent review. The **source candidate is 2.2.0**, but npm publication is separate, so these APIs may not yet be available from `npm install adaptform`.
 
-// Full type inference
-type UserData = typeof form.fieldsValue;
-// { name: string | null; age: number | null; }
-```
+```typescript
+import {Field, Form, NumberType, StringType} from 'adaptform'
 
-## License
+class SettingsForm extends Form {
+  displayName = new Field(StringType, 'Alex')
+  notifications = new Field(NumberType, 1)
+}
 
-MIT © [Stanislav Orlov](https://github.com/ArhiMEN)
+const form = new SettingsForm()
+const unsubscribe = form.subscribe(() => {
+  const snapshot = form.getSnapshot()
+  console.log(snapshot.isDirty, snapshot.isValid, snapshot.fieldsValue)
+})
 
-## Links
+form.batch(() => {
+  form.displayName.rawValue = 'Alexandra'
+  form.notifications.rawValue = 2
+}) // One coherent notification after final automatic validation
 
-* [GitHub Repository](https://github.com/ArhiMEN/adaptform)
-* [npm Package](https://www.npmjs.com/package/adaptform)
-* [Bug Reports](https://github.com/ArhiMEN/adaptform/issues)
-* [Changelog](https://github.com/ArhiMEN/adaptform/blob/master/CHANGELOG.md)
+form.commitBaseline() // Accept current cleaned values; isDirty becomes false
+unsubscribe()        // Release the listener
+```
 
-## Support
+`isTouched` keeps its former semantics. `commitBaseline()` changes the dirty-comparison baseline, **not** the constructor defaults restored by `reset()`; a reset may leave `isDirty=true`. Snapshots are detached read-only descriptions, not mutable source objects; `toJSON()` still does not validate.
 
-If you find this project useful, please give it a star on GitHub!
+Automatic validation inside `Form.batch()` is deferred, whereas explicit `checkValid()` is immediate. Batch callbacks must be synchronous and do not roll back changes on errors. Direct in-place changes to legacy public arrays or arbitrary form properties are not automatically observed. See [usage and limitations](docs/ai/HEADLESS_STATE_USAGE.md) and the [2.1.1 compatibility table](docs/ai/HEADLESS_STATE_CONTRACT.md#compatibility-with-211).