@dynamicforms/vue-forms 0.6.0 → 0.11.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dynamicforms/vue-forms",
   "private": false,
-  "version": "0.6.0",
+  "version": "0.11.0",
   "type": "module",
   "description": "A lightweight Vue.js library for form state management with built-in validation, conditional logic, nested structures, and a rich event system. UI-agnostic and TypeScript-first.",
   "author": "Jure Erznožnik",
@@ -29,6 +29,7 @@
   ],
   "scripts": {
     "build": "vite build && node -e \"require('fs').copyFileSync('dist/index.d.ts', 'dist/index.d.cts')\"",
+    "prepack": "npm run build",
     "test": "vitest run --coverage",
     "lint": "eslint src --fix && vue-tsc --noEmit",
     "lint:ci": "eslint src && vue-tsc --noEmit",
@@ -52,13 +53,19 @@
   "homepage": "https://docs.velis.si/dynamicforms/vue-forms",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/velis74/dynamicforms-vue-forms.git"
+    "url": "git+https://github.com/dynamicforms/vue-forms.git"
   },
   "bugs": {
-    "url": "https://github.com/velis74/dynamicforms-vue-forms/issues"
+    "url": "https://github.com/dynamicforms/vue-forms/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "lodash": "^4.17.21",
+    "lodash-es": "^4.17.21"
   },
   "peerDependencies": {
-    "lodash-es": "^4.17.12",
     "vue": "^3.4"
   },
   "devDependencies": {

package/readme.md

@@ -16,19 +16,22 @@ mechanism applies at every level of a nested form.
 
 - **UI-Agnostic**: A logic layer for form state, validation and dynamic behaviour. Works with any Vue components, including your own.
 - **Fields that react to each other**: Conditional visibility, enablement and values are declared as statements over other fields, and an action pipeline lets a handler intercept, transform or abort an event.
-- **Reactive & Type-Safe**: Fields, groups and lists are Vue reactive objects, and a group's value type is inferred from the fields it holds, nested structures included.
+- **Reactive & Type-Safe**: Every member of a field, group or list is a tracked read, and a group's value type is inferred from the fields it holds, nested structures included.
 - **Structural serialization**: A group's value is the shape of its fields, and `Group.createFromFormData()` turns a plain object back into a form.
-- **Lightweight**: Depends on Vue and lodash-es, and nothing else.
+- **Lightweight**: `vue` (^3.4) is the only peer dependency, and `lodash` and `lodash-es` — one per build — the only runtime ones.
 
 ## Features
 
 - **UI-agnostic**: Works with any Vue UI components or your custom ones
-- **Reactive**: Fields, groups and lists are Vue reactive objects — read and assign their properties directly, with
-  no `ref` to unwrap and no computed mirror to keep in sync
+- **Reactive**: every member of a field, group or list is a tracked read — assign a property directly, with no
+  `ref` to unwrap and no computed mirror to keep in sync
 - **Nested structures**: Support for complex data with nested fields and groups
 - **Event system**: Rich event handling for field changes, validation, and more
+- **Transactional**: every mutating operation is atomic — events are announced once, over the net change, and a
+  handler that throws leaves the form exactly as it was
 - **TypeScript support**: Full type definitions for excellent developer experience
-- **Lightweight**: depends only on `vue` (^3.4) and `lodash-es` (^4.17)
+- **Lightweight**: `vue` (^3.4) is the only peer dependency; the runtime dependencies are `lodash` and `lodash-es`,
+  one for each of the two builds
 - **Field types**: Core field types (Field, Action, Group, List) to represent any data structure
 - **Validation**: Comprehensive validation system with built-in validators and extensible error handling
 - **Conditional logic**: Dynamic form behavior based on field values and conditions
@@ -40,6 +43,11 @@ mechanism applies at every level of a nested form.
 npm install @dynamicforms/vue-forms
 ```
 
+The package ships two builds of the same source: an ESM build that imports `lodash-es` and a CJS/UMD build that
+requires `lodash`. Both lodash packages are declared as dependencies and install with the package, so an `import` and
+a `require()` both resolve without further setup. Node 18 or newer is required, and `vue` (^3.4) is the only peer
+dependency. Type definitions ship for both entry points; the stylesheet is `@dynamicforms/vue-forms/style.css`.
+
 ## Setup
 
 The library ships a Vue plugin for its global options:
@@ -59,9 +67,10 @@ want plain text instead.
 ## Basic Usage Example
 
 Every form element is created with the constructor: `new Field({ ... })`, `new Action({ ... })`,
-`new Group({ ... })`, `new List(template)`. The instance is a Vue reactive object from that moment on, so reading
+`new Group({ ... })`, `new List(template)`. Every read through it is tracked from that moment on, so reading
 `field.value` in a template tracks it and `field.value = x` re-renders — there is no `ref` to unwrap and no
-computed mirror to maintain.
+computed mirror to maintain. The element itself is not a Vue proxy, so watch what you read:
+`watch(() => field.value, cb)`.
 
 Here's a simple example of how to create and use a form with fields and groups:
 
@@ -99,9 +108,14 @@ const saveAction = new Action({
   actions: [new ExecuteAction((field, supr, params) => { console.log('saving', params); })]
 });
 
-saveAction.execute({ form: personForm });  // 'saving { form: ... }'
+await saveAction.execute({ form: personForm });  // 'saving { form: ... }'; saveAction.busy until it settles
 ```
 
+`Action` is the one deliberate exception to "UI-agnostic": it names a label and an icon because it exists as the
+element a form's submit and cancel hang on, and that minimal pair is what makes the concept legible. The shape is
+minimal because a UI library is expected to extend it — [`@dynamicforms/vuetify-inputs`](https://docs.velis.si/dynamicforms/vuetify-inputs/examples/df-actions.html)
+widens the value with render options and per-breakpoint variants on top of it.
+
 ## Events Example
 
 The library provides a powerful event system for field changes and other actions:
@@ -135,6 +149,21 @@ const form = new Group({
 Assigning `field.errors` directly replaces the whole array, including errors owned by validators — prefer a
 `Validator` (see below) when all you want is to add a validation rule.
 
+Events are announced when the operation carrying them finishes, over the net change. Wrap several writes in a
+`transaction()` and they announce as one:
+
+```typescript
+import { transaction } from '@dynamicforms/vue-forms';
+
+// one ValueChangedAction on the form, not two
+transaction(() => {
+  form.fields.email.value = 'janez@example.com';
+  form.fields.username.value = 'janez';
+});
+```
+
+A throw out of the callback rolls the whole transaction back and rethrows, so a form is never left half-applied.
+
 ## Built-in Validators
 
 The library provides several built-in validators for common validation scenarios:
@@ -185,6 +214,12 @@ const validatedForm = new Group({
 Validators run eagerly — a field is validated the moment it is created, so a form built from empty required fields is
 invalid immediately. Use `field.touched` to decide when to show the errors in the UI.
 
+A validation function may return a `Promise`. `field.validating` is `true` while such a run is pending, and the
+verdict applied to the field is always the one belonging to the newest run, so a slow check cannot overwrite a faster
+one started after it. A validator message given as a `Ref` or `computed` is resolved when the message is rendered, so
+a translated message follows a locale switch without revalidating. `field.clearValidators()` drops the validators,
+empties the errors and cancels whatever validation is still in flight.
+
 ## Messages Widget Component
 
 The library includes a `messages-widget` Vue component for displaying validation errors and messages:
@@ -365,18 +400,30 @@ const prefs: { darkMode: boolean; notifications: boolean } | null = values.prefe
 
 The value shape is derived from the fields map by the exported `FieldsToValues<T>`, with `GroupValue<T>` and
 `GroupValueInput<T>` as the group's read and write types, and `ListValue` for lists. Constructor parameters have
-their own exported type, `IFieldConstructorParams<T>`, shared by all four element classes and by `clone()`:
+their own exported type, `IFieldParams<T, X>`, shared by all four element classes:
 
 ```typescript
-import { Field, IFieldConstructorParams } from '@dynamicforms/vue-forms';
+import { Field, IFieldParams } from '@dynamicforms/vue-forms';
 
-const defaults: Partial<IFieldConstructorParams<string>> = { value: '', enabled: false };
+const defaults: IFieldParams<string> = { value: '', enabled: false };
 const field = new Field(defaults);
 ```
 
 It admits only the writable members — `value`, `originalValue`, `enabled`, `visibility`, `touched`, `errors`,
-`validators` and `actions`. Derived members such as `valid` and `isChanged` are getters, and passing one is a
-compile error.
+`validators` and `actions`, listed by `IFieldConstructorParams<T>`. Derived members such as `valid` and
+`isChanged` are getters, and passing one is a compile error.
+
+`X` is what an element carries beyond those: declare it, and the parameter object takes those properties too,
+`extra` reads them back and `setExtendedValues()` writes them. It is how a form built from a server's description
+carries the label, hint or css class a UI layer binds to its inputs:
+
+```typescript
+interface Presentation { label: string; hint?: string }
+
+const name = new Field<string, Presentation>({ value: 'John', label: 'First name' });
+name.extra.label; // 'First name', and a template reading it re-renders when it is written
+name.setExtendedValues({ hint: 'as in your passport' });
+```
 
 `FieldBase<T>` is the abstract base of `Field`, `Action`, `Group` and `List`, and the type to use in your own
 signatures whenever you accept any form element:
@@ -393,9 +440,12 @@ function isDirty(field: FieldBase): boolean {
 
 For more detailed documentation and examples, check out the [documentation](https://docs.velis.si/dynamicforms/vue-forms).
 
-Upgrading from 0.5.x? The
-[migration guide](https://docs.velis.si/dynamicforms/vue-forms/guide/migration) lists every breaking change with
-before/after code.
+[The model](https://docs.velis.si/dynamicforms/vue-forms/guide/model) is the whole library in one page: elements,
+declarations, transactions, where validity comes from and how a `List` builds its rows.
+
+Upgrading an existing project? The
+[migration guide](https://docs.velis.si/dynamicforms/vue-forms/guide/migration) walks the journey from 0.6.1 to
+0.10.x, silent breaks first, and keeps a section per release for a project crossing one.
 
 ## Conclusion