@dynamicforms/vue-forms 0.6.1 → 0.11.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dynamicforms/vue-forms",
   "private": false,
-  "version": "0.6.1",
+  "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",

package/readme.md

@@ -16,17 +16,19 @@ 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**: `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**: `vue` (^3.4) is the only peer dependency; the runtime dependencies are `lodash` and `lodash-es`,
   one for each of the two builds
@@ -65,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:
 
@@ -105,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:
@@ -141,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:
@@ -377,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:
@@ -405,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