adaptform 2.0.4 → 2.1.0

package/CHANGELOG.md

@@ -0,0 +1,152 @@
+# Changelog
+
+[English](CHANGELOG.md) · [Русский](CHANGELOG.ru.md)
+
+All notable changes to AdaptForm are documented here. The `2.1.0` section is prepared for release; it remains unreleased until the maintainer publishes it.
+
+**[Interactive demo](https://arhimen.github.io/AdaptForm/)** · [Demo source](https://github.com/ArhiMEN/AdaptForm/tree/master/demo) · [Documentation](https://github.com/ArhiMEN/AdaptForm/blob/master/README.md)
+
+## [2.1.0] - Unreleased
+
+### Added
+
+- Prepare gated npm publication after successful `master` CI, using the version in `package.json` and either npm Trusted Publisher or a repository-scoped npm secret; activation awaits authentication setup.
+
+- Add English/Russian demo localization with persistent language selection and language-specific documentation links, preserving entered values and validation state.
+- Add complete Russian companion documentation, changelog, release tracking, repository instructions, and license information alongside the English originals.
+
+- Add a browser-based interactive playground covering field validation, conditional requirements, field state, arrays, nested forms, server-error handling, serialization, and input masks.
+- Add a GitHub Actions workflow to build and deploy the playground to GitHub Pages from `v2.1.0` and `master`.
+- Add dedicated demo type-checking and production-build commands, and run both as part of CI.
+- Add automated npm package-content verification to ensure required ESM, CommonJS, and TypeScript declaration files are present while development sources and tests stay out of the published package.
+- Export `ErrorsSchema` from the public package entry point.
+- Infer `Form.fieldsValue` from declared `Field`, `ArrayField`, and `ArrayFormField` properties.
+
+### Changed
+
+- Configure ESLint for TypeScript source, tests, and demo code; run linting and dependency audits in CI on Node.js 22.
+- Upgrade Vitest, Vite, ESLint, and TypeScript lint tooling; pin patched transitive dependency versions and align the lockfile.
+- Replace the machine-specific absolute Vitest alias with a portable project-relative path.
+- Batch direct field values before form-level validation so conditional-required rules can inspect the complete form state without invoking those direct field validators twice.
+- Add `Form.setFields(data, validate?)` and `Field.setRawValue(value, validate?)` for controlled assignment with optional deferred validation.
+- Make reset behavior explicit: field defaults are restored without running custom validators, errors are cleared, and validity remains unset until validation runs again.
+- Clear stale server errors recursively when a new error payload is assigned.
+- Revalidate collections after mutations, avoid hidden repeated validation when reading `ArrayFormField.isValid`, ignore invalid removal indices, and leave collection validity unset after reset until the next check.
+- Improve inferred form-value types, nullable array values, nested form collection types, and JSON serialization return types.
+- Serialize arrays and nested objects as JSON in `FormData`; omit `null`/`undefined`; preserve `Blob`/`File` values; recursively serialize nested JavaScript `Date` values to ISO 8601 strings in JSON output.
+- Rewrite the README to document supported APIs, validation lifecycle, collection options, error mapping, serialization, development commands, and the interactive demo.
+
+### Fixed
+
+- Make string validation deterministic when patterns contain global or sticky regular-expression flags.
+- Reject blank and non-finite values in `NumberType`.
+- Reject numeric decimal values with excess precision instead of silently rounding them; correctly handle `decimalPlaces: 0`.
+- Treat whitespace-only strings as empty and keep constructor defaults untouched.
+- Correct conditional-required validation after bulk form assignment.
+- Refresh array validation after adding items/forms and avoid invalid negative, fractional, or out-of-range removal indices.
+- Fix `ErrorsSchema.forArray()` to honor custom index extractors, apply item-schema mappings and transformers, and support bracket, dotted, and custom index notation.
+- Invoke an `ErrorsSchema` fallback handler only once when it declines an error.
+- Correct regression coverage for a date-time boundary test and add tests for reset state, nested error clearing, assignment batching, nullable arrays, Date serialization, and Blob/File handling.
+
+### Security and maintenance
+
+- Support both array and keyed-object npm pack JSON manifests in the package-content check; require English/Russian package documentation.
+
+- Add `npm audit --audit-level=moderate` to CI and update vulnerable transitive dependency versions using reviewed overrides. The final verified workflow reports zero known vulnerabilities from npm audit; the previous lockfile scan also reported zero.
+- Verify lint, tests, ESM/CJS build, declaration generation, source type-checking, demo type-checking/build, and npm package contents in CI.
+
+### Compatibility notes
+
+- Built-in library validation messages and their language have not been changed in this release candidate. Localization and any structured error-code contract are deferred to a separate coordinated task.
+- PlayLease-specific integration work is explicitly out of scope for this branch.
+- This changelog describes the release candidate in branch `v2.1.0`; npm publication and the GitHub release are still maintainer actions.
+
+## [2.0.5] - 2026-07-22
+
+### Added
+
+- `ErrorsSchema` class for flexible server error parsing and mapping
+- Static error mapping with `staticKey()` for exact key matching
+- Dynamic error mapping with `dynamicKey()` supporting regex patterns and priority
+- `fallback()` handler for unmatched error keys
+- `transformValue()` for normalizing error messages (array to string, removing prefixes, etc.)
+- `parseErrors()` method returning flat `Record<string, string>`
+- `parseErrorsDetailed()` method returning `ParsedError` objects with metadata (sourceKey, matchedBy)
+- `nest()` method for creating prefixed schemas for nested forms
+- `clone()` and `merge()` methods for schema composition and reuse
+- `ErrorsSchema.fromObject()` factory for quick mapping from plain objects
+- `ErrorsSchema.forArray()` factory for array field error patterns
+- Predefined schemas: `DefaultErrorSchema`, `LaravelErrorSchema`, `GraphQLErrorSchema`
+- Priority system for dynamic rules to control matching order
+- Value transformers chain for sequential error message normalization
+- Support for nested error objects with recursive parsing
+- Pydantic-style error format support out of the box
+
+### Changed
+
+- `Form.errors` setter now uses `ErrorsSchema` for intelligent error mapping
+- `Form.errorsShema` property added for per-form error schema configuration
+- `Form.applyErrorToField()` now supports nested field paths (e.g., `accounts.0.email`)
+- `Form.applyNestedError()` handles `ArrayFormField` recursively with proper error context
+- `Form.allErrors` getter now recursively collects errors from nested `ArrayFormField`
+- `Form.reset()` now properly clears all field errors and global errors
+- Error clearing logic improved: setting empty errors object clears all previous errors
+- Global errors are now properly scoped to their target form instance
+- `DefaultErrorsSchema` uses `fallback((key) => key)` for backward compatibility
+
+### Fixed
+
+- Fixed nested error propagation for `ArrayFormField` with out-of-range indices
+- Fixed error context when applying errors to fields inside nested forms
+- Fixed `allErrors` not including errors from nested forms in `ArrayFormField`
+- Fixed global errors not being properly cleared when setting new errors
+- Fixed null/undefined error values causing unexpected behavior
+- Fixed error mapping for array fields (ArrayField) with index-based keys
+
+## [2.0.0 - 2.0.4] - 2026-05-29
+
+### Added
+
+- Complete TypeScript rewrite with full type inference
+- Plugin system with MaskPlugin, FieldPlugin, and DecoratorPlugin
+- ArrayField for dynamic field arrays
+- ArrayFormField for nested form arrays
+- New field types: DecimalType, DateLuxonType, BooleanType
+- Optional Luxon integration via `adaptform/luxon` subpath export
+- Input mask support with flexible configuration
+- Conditional required fields based on form state
+- Custom validation messages for all field types
+- Global error handling for server-side errors
+- Form serialization (`toJSON()`, `toFormData()`)
+- Tree-shakeable exports for smaller bundles
+- ESM and CJS module support
+- Full TypeScript declarations with proper types
+
+### Changed
+
+- **Complete API redesign** - new class-based architecture
+- Field creation now uses `new Field(TypeClass, defaultValue, options)` pattern
+- Form validation now requires explicit field declarations in class body
+- Plugin system replaces old middleware approach
+- Error handling unified across all field types
+- Validation methods now return string arrays instead of boolean
+- Options interface restructured for better type inference
+
+### Breaking Changes
+
+- **Full rewrite from v1.x** - no backward compatibility
+- Form must extend base `Form` class with field declarations
+- Field constructors require TypeClass as first argument
+- `validate()` now returns `string[]` instead of `boolean`
+- Plugin API completely redesigned
+- Import paths changed for tree-shaking support
+- Luxon date type moved to separate entry point `adaptform/luxon`
+
+### Removed
+
+- Legacy function-based API
+- Old validation middleware system
+- Global configuration singleton
+- Automatic Luxon dependency (now optional)
+
+[2.0.4]: https://github.com/ArhiMEN/adaptform/releases/tag/v2.0.4

package/CHANGELOG.ru.md

@@ -0,0 +1,152 @@
+# История изменений
+
+[English](CHANGELOG.md) · [Русский](CHANGELOG.ru.md)
+
+Здесь описаны все значимые изменения AdaptForm. Раздел `2.1.0` подготовлен к выпуску, но остаётся неопубликованным до публикации сопровождающим проекта.
+
+**[Интерактивное демо](https://arhimen.github.io/AdaptForm/?lang=ru)** · [Исходный код демо](https://github.com/ArhiMEN/AdaptForm/tree/master/demo) · [Документация](https://github.com/ArhiMEN/AdaptForm/blob/master/README.ru.md)
+
+## [2.1.0] — Не выпущено
+
+### Добавлено
+
+- Подготовлена управляемая публикация в npm после успешного CI для `master` с версией из `package.json` и авторизацией через Trusted Publisher либо секрет репозитория; включение ожидает настройки авторизации.
+
+- Локализация демо на английский и русский с сохранением выбранного языка и ссылками на документацию соответствующего языка; введённые значения и состояние валидации сохраняются.
+- Полные русские версии документации, истории изменений, плана выпуска, журнала статуса, инструкций репозитория и сведений о лицензии рядом с английскими оригиналами.
+
+- Интерактивное демо в браузере: валидация полей, условная обязательность, состояния полей, массивы, вложенные формы, серверные ошибки, сериализация и маски ввода.
+- Workflow GitHub Actions для сборки и публикации демо в GitHub Pages из `v2.1.0` и `master`.
+- Отдельные команды проверки типов и производственной сборки демо, выполняемые в CI.
+- Автоматическая проверка состава npm-пакета: обязательные ESM, CommonJS и декларации TypeScript включены, исходный код разработки и тесты исключены.
+- Экспорт `ErrorsSchema` из публичной точки входа пакета.
+- Вывод типов `Form.fieldsValue` из объявленных свойств `Field`, `ArrayField` и `ArrayFormField`.
+
+### Изменено
+
+- ESLint настроен для TypeScript-кода библиотеки, тестов и демо; lint и аудит зависимостей выполняются в CI на Node.js 22.
+- Обновлены Vitest, Vite, ESLint и инструменты lint для TypeScript; закреплены исправленные транзитивные зависимости и согласован lockfile.
+- Абсолютный путь в псевдониме Vitest заменён переносимым путём относительно проекта.
+- Значения непосредственных полей присваиваются до проверки формы, чтобы условные правила видели полное состояние без двойного запуска валидаторов этих полей.
+- Добавлены `Form.setFields(data, validate?)` и `Field.setRawValue(value, validate?)` для управляемого присваивания с необязательной отложенной валидацией.
+- Уточнён сброс: значения по умолчанию восстанавливаются без вызова пользовательских валидаторов, ошибки очищаются, корректность не определена до следующей проверки.
+- При назначении нового ответа ошибок предыдущие серверные ошибки очищаются рекурсивно.
+- Коллекции проверяются после изменения, чтение `ArrayFormField.isValid` не вызывает скрытую повторную валидацию, некорректные индексы удаления игнорируются, после сброса корректность ожидает новой проверки.
+- Улучшены выведенные типы значений формы, nullable-значения массивов, типы коллекций вложенных форм и результаты JSON-сериализации.
+- Массивы и вложенные объекты кодируются в JSON в `FormData`; `null`/`undefined` пропускаются; `Blob`/`File` сохраняются; вложенные JavaScript `Date` рекурсивно преобразуются в ISO 8601 в JSON.
+- README переписан для описания API, жизненного цикла валидации, параметров коллекций, сопоставления ошибок, сериализации, команд разработки и интерактивного демо.
+
+### Исправлено
+
+- Проверка строк стала детерминированной для регулярных выражений с глобальным или липким флагом.
+- `NumberType` отклоняет пустые и неконечные значения.
+- Десятичные числа с избыточной точностью отклоняются без скрытого округления; `decimalPlaces: 0` обрабатывается корректно.
+- Строки только из пробелов считаются пустыми; значения по умолчанию конструктора сохраняют состояние «не изменено».
+- Исправлена условная обязательность после массового присваивания полей формы.
+- Валидация массива обновляется после добавления элементов/форм; отрицательные, дробные и выходящие за границы индексы удаления игнорируются.
+- `ErrorsSchema.forArray()` учитывает пользовательский извлекатель индекса, правила и преобразования схемы элемента, поддерживает скобочную, точечную и пользовательскую запись индекса.
+- Обработчик fallback в `ErrorsSchema` вызывается только один раз, если он отклоняет ошибку.
+- Исправлен тест граничного времени; добавлены проверки сброса, очистки вложенных ошибок, группового присваивания, nullable-массивов, сериализации Date и обработки Blob/File.
+
+### Безопасность и сопровождение
+
+- Проверка состава пакета поддерживает JSON-манифесты npm pack в виде массива и объекта с ключами; документация пакета обязательна на английском и русском.
+
+- В CI добавлен `npm audit --audit-level=moderate`; уязвимые транзитивные зависимости обновлены проверенными overrides. Последний проверенный workflow сообщает о нуле известных уязвимостей в npm audit; предыдущая проверка lockfile также сообщила о нуле.
+- В CI проверяются lint, тесты, сборка ESM/CJS, декларации, типы библиотеки, типы и сборка демо, состав npm-пакета.
+
+### Совместимость
+
+- Встроенные сообщения валидации библиотеки и их язык в этом кандидате не изменены. Их локализация и контракт структурированных кодов ошибок отложены до отдельной согласованной задачи.
+- Интеграция с PlayLease явно исключена из области этой ветки.
+- Эта история описывает кандидата в ветке `v2.1.0`; публикация npm-пакета и выпуск на GitHub остаются действиями сопровождающего проекта.
+
+## [2.0.5] — 2026-07-22
+
+### Добавлено
+
+- Класс `ErrorsSchema` для гибкого разбора и сопоставления серверных ошибок
+- Статическое сопоставление точных ключей через `staticKey()`
+- Динамическое сопоставление через `dynamicKey()` с регулярными выражениями и приоритетом
+- Обработчик `fallback()` для ключей без соответствия
+- `transformValue()` для нормализации сообщений (массив в строку, удаление префиксов и т. п.)
+- Метод `parseErrors()`, возвращающий плоский `Record<string, string>`
+- Метод `parseErrorsDetailed()`, возвращающий объекты `ParsedError` с метаданными (sourceKey, matchedBy)
+- Метод `nest()` для схем с префиксами вложенных форм
+- Методы `clone()` и `merge()` для композиции и повторного использования схем
+- Фабрика `ErrorsSchema.fromObject()` для быстрого сопоставления из обычного объекта
+- Фабрика `ErrorsSchema.forArray()` для шаблонов ошибок массивов полей
+- Готовые схемы: `DefaultErrorSchema`, `LaravelErrorSchema`, `GraphQLErrorSchema`
+- Система приоритетов динамических правил для управления порядком сопоставления
+- Цепочка преобразователей значений для последовательной нормализации сообщений
+- Рекурсивный разбор вложенных объектов ошибок
+- Встроенная поддержка ошибок в формате Pydantic
+
+### Изменено
+
+- Сеттер `Form.errors` использует `ErrorsSchema` для сопоставления ошибок
+- Добавлено свойство `Form.errorsShema` для настройки схемы отдельной формы
+- `Form.applyErrorToField()` поддерживает вложенные пути (например, `accounts.0.email`)
+- `Form.applyNestedError()` рекурсивно обрабатывает `ArrayFormField` с правильным контекстом
+- Геттер `Form.allErrors` рекурсивно собирает ошибки вложенных `ArrayFormField`
+- `Form.reset()` очищает ошибки всех полей и общие ошибки
+- Пустой объект ошибок очищает все ранее применённые ошибки
+- Общие ошибки привязаны к соответствующему экземпляру формы
+- `DefaultErrorsSchema` использует `fallback((key) => key)` для обратной совместимости
+
+### Исправлено
+
+- Передача вложенных ошибок `ArrayFormField` при индексах за границами массива
+- Контекст ошибок при назначении полям вложенных форм
+- Отсутствие ошибок вложенных форм `ArrayFormField` в `allErrors`
+- Неполная очистка общих ошибок при назначении новых
+- Неожиданное поведение при значениях ошибок null/undefined
+- Сопоставление ошибок массивов полей (ArrayField) по индексным ключам
+
+## [2.0.0 - 2.0.4] — 2026-05-29
+
+### Добавлено
+
+- Полная переработка на TypeScript с выводом типов
+- Система плагинов MaskPlugin, FieldPlugin и DecoratorPlugin
+- ArrayField для динамических массивов полей
+- ArrayFormField для массивов вложенных форм
+- Новые типы: DecimalType, DateLuxonType, BooleanType
+- Необязательная интеграция Luxon через экспорт `adaptform/luxon`
+- Маски ввода с гибкой настройкой
+- Условная обязательность полей в зависимости от состояния формы
+- Пользовательские сообщения валидации для всех типов полей
+- Общие ошибки для ответов сервера
+- Сериализация форм (`toJSON()`, `toFormData()`)
+- Экспорты с поддержкой tree shaking для уменьшения сборок
+- Поддержка ESM и CJS
+- Полные декларации TypeScript с корректными типами
+
+### Изменено
+
+- **Полная переработка API** — новая архитектура на основе классов
+- Поля создаются через `new Field(TypeClass, defaultValue, options)`
+- Валидация требует явных объявлений полей в теле класса
+- Система плагинов заменяет прежний механизм middleware
+- Обработка ошибок унифицирована для всех типов полей
+- Методы валидации возвращают массивы строк вместо boolean
+- Интерфейс параметров перестроен для улучшения вывода типов
+
+### Несовместимые изменения
+
+- **Полная переработка относительно v1.x** — обратная совместимость отсутствует
+- Форма должна наследовать базовый класс `Form` и объявлять поля
+- Конструктор поля требует TypeClass первым аргументом
+- `validate()` возвращает `string[]` вместо `boolean`
+- API плагинов полностью переработан
+- Пути импорта изменены для поддержки tree shaking
+- Тип даты Luxon вынесен в отдельную точку входа `adaptform/luxon`
+
+### Удалено
+
+- Прежний API на основе функций
+- Старый механизм middleware для валидации
+- Глобальная конфигурация singleton
+- Автоматическая зависимость от Luxon (теперь необязательна)
+
+[2.0.4]: https://github.com/ArhiMEN/adaptform/releases/tag/v2.0.4

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 ArhiMEN (Stanislav Orlov)
+Copyright (c) 2025 Stanislav Orlov (ArhiMEN)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -19,3 +19,5 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+[English](LICENSE.md) · [Русский](LICENSE.ru.md)

package/LICENSE.ru.md

@@ -0,0 +1,25 @@
+# Лицензия MIT
+
+Copyright (c) 2025 Stanislav Orlov (ArhiMEN)
+
+Настоящим бесплатно предоставляется разрешение любому лицу, получившему копию
+данного программного обеспечения и соответствующей документации (далее «ПО»),
+использовать ПО без ограничений, включая права на использование, копирование,
+изменение, объединение, публикацию, распространение, сублицензирование и/или
+продажу копий ПО, а также предоставлять такие права лицам, которым передаётся
+ПО, при соблюдении следующих условий:
+
+Указанное выше уведомление об авторских правах и данное уведомление о разрешении
+должны включаться во все копии или существенные части ПО.
+
+ПО ПРЕДОСТАВЛЯЕТСЯ «КАК ЕСТЬ», БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, ЯВНЫХ ИЛИ
+ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ ГАРАНТИИ ПРИГОДНОСТИ ДЛЯ ПРОДАЖИ, СООТВЕТСТВИЯ
+ОПРЕДЕЛЁННОЙ ЦЕЛИ И НЕНАРУШЕНИЯ ПРАВ. НИ ПРИ КАКИХ ОБСТОЯТЕЛЬСТВАХ АВТОРЫ
+ИЛИ ПРАВООБЛАДАТЕЛИ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ПО ЛЮБЫМ ТРЕБОВАНИЯМ, УЩЕРБУ
+ИЛИ ИНОЙ ОТВЕТСТВЕННОСТИ, ВОЗНИКАЮЩИМ В СИЛУ ДОГОВОРА, ДЕЛИКТА ИЛИ ИНЫМ
+ОБРАЗОМ В СВЯЗИ С ПО, ЕГО ИСПОЛЬЗОВАНИЕМ ИЛИ ИНЫМИ ДЕЙСТВИЯМИ С НИМ.
+
+Это справочный русский перевод. Условия лицензии определяются английским
+оригиналом [LICENSE.md](LICENSE.md).
+
+[English](LICENSE.md) · [Русский](LICENSE.ru.md)