@dynamicforms/vue-forms 1.1.0 → 2.0.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dynamicforms/vue-forms",
   "private": false,
-  "version": "1.1.0",
+  "version": "2.0.3",
   "type": "module",
   "description": "A 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",
@@ -55,10 +55,10 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@dynamicforms/translatable": "^0.1.0",
     "lodash-es": "^4.17.21"
   },
   "peerDependencies": {
+    "@dynamicforms/translatable": "^0.1.0",
     "vue": "^3.5.2"
   },
   "devDependencies": {

package/readme.md

@@ -14,7 +14,7 @@ mechanism applies at every level of a nested form.
 
 ### Design Goals
 
-- **UI-Agnostic**: A logic layer for form state, validation and dynamic behaviour. Works with any Vue components, including your own.
+- **UI-Agnostic**: A logic layer for form state, validation and dynamic behaviour. Works with any Vue components, including your own. The few members that speak about the interface — `visibility`, `enabled`, `touched`, error render content and `Action` — are there because nearly every form needs them; [Rationale](https://docs.velis.si/dynamicforms/vue-forms/guide/rationale#what-the-library-carries-for-the-interface) lists them with the reason for each.
 - **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**: 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.
@@ -22,13 +22,13 @@ mechanism applies at every level of a nested form.
 ## Features
 
 - **UI-agnostic**: a logic layer for form state, validation and dynamic behaviour. Any Vue components render it,
-  your own included
+  your own included; the few members that speak about the interface are [listed with their reasons](https://docs.velis.si/dynamicforms/vue-forms/guide/rationale#what-the-library-carries-for-the-interface)
 - **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. `transaction()` makes several writes one operation, and
   `tx.rollback()` withdraws one without an error
 - **Lists that scale**: a `List` is meant to hold thousands of rows. Writing one field of one row costs that row
   and the depth it sits at, a `push()` costs one row, and reading `value` or `valid` again costs nothing
-- **Declared once, bound per record**: the `Group` handed to `new List(template)` is the declaration every row is
+- **Declared once, bound per record**: the element handed to `new List(template)` is the declaration every row is
   built from. One validator instance and one conditional rule serve every row, and each row answers for itself
 - **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
@@ -39,7 +39,13 @@ mechanism applies at every level of a nested form.
 - **Conditional logic**: visibility, enablement and values declared as statements over other fields
 - **Extended properties**: a field carries whatever your UI renders it with — a label, a hint, a width — declared
   as a second type argument, checked by the compiler and read through `extra`
-- **Display modes**: control field visibility with different display modes (Full, Hidden, Invisible, Suppress)
+- **Application state, not only forms**: the same elements hold state no screen shows — a cart, the filters of a list view, editor
+  settings — with the reactivity, transactions and validation a form has
+- **Plain-data views**: `view(group)` reads an element as plain properties — `form.address.city`,
+  `v-model="form.name"` — with the element itself as `form.$`
+- **Access**: `'editable'`, `'readonly'`, `'disabled'` and `'disabled-null'` decide whether an element accepts input
+  and what it contributes to the value its form sends — its own value, `null`, or nothing — and validation follows
+  what is sent; `visibility` states how it is drawn
 - **TypeScript support**: full type definitions, and a group's value type inferred from the fields it holds
 
 ## Installation
@@ -48,9 +54,8 @@ mechanism applies at every level of a nested form.
 npm install @dynamicforms/vue-forms
 ```
 
-The package is ESM-only: it ships one build, which imports `lodash-es`, its only runtime dependency. Node 22 or newer
-is required, and `vue` (^3.5.2) is the only peer dependency. A CommonJS consumer reaches it through `require()` of an
-ES module, which Node supports. Type definitions ship with the build; the stylesheet is
+The package is ESM-only and requires Node 22 or newer. A CommonJS consumer reaches it through `require()` of an ES
+module, which Node supports. Type definitions ship with the build; the stylesheet is
 `@dynamicforms/vue-forms/style.css`.
 
 ## Setup
@@ -101,9 +106,9 @@ console.log(personForm.value);  // { firstName: 'John', lastName: 'Doe', age: 30
 personForm.fields.firstName.value = 'Jane';
 
 // Disable a field
-personForm.fields.age.enabled = false;
+personForm.fields.age.access = 'disabled';
 
-// Form serializes only enabled fields
+// The form leaves a disabled field out of what it sends
 console.log(personForm.value);  // { firstName: 'Jane', lastName: 'Doe', active: true }
 ```
 
@@ -120,8 +125,10 @@ const saveAction = new Action({
 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
+`Action` is one of the few members that speak about the interface, listed with their reasons in
+[Rationale](https://docs.velis.si/dynamicforms/vue-forms/guide/rationale#what-the-library-carries-for-the-interface):
+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.
 
@@ -298,7 +305,7 @@ Create dynamic forms with conditional logic using Statements and Operators:
 ```typescript
 import { 
   Field, Group, Statement, Operator,
-  ConditionalVisibilityAction, ConditionalEnabledAction 
+  ConditionalVisibilityAction, ConditionalAccessAction
 } from '@dynamicforms/vue-forms';
 
 const form = new Group({
@@ -308,20 +315,17 @@ const form = new Group({
   lastName: new Field()
 });
 
-// Show company name field only when isCompany is true
-const showCompanyNameStatement = new Statement(form.fields.isCompany, Operator.EQUALS, true);
-form.fields.companyName.registerAction(
-  new ConditionalVisibilityAction(showCompanyNameStatement)
-);
-
-// Show personal name fields only when isCompany is false
-const showPersonalFieldsStatement = new Statement(form.fields.isCompany, Operator.EQUALS, false);
-form.fields.firstName.registerAction(
-  new ConditionalVisibilityAction(showPersonalFieldsStatement)
-);
-form.fields.lastName.registerAction(
-  new ConditionalVisibilityAction(showPersonalFieldsStatement)
-);
+// Show and send the company name only when isCompany is true
+const isCompany = new Statement(form.fields.isCompany, Operator.EQUALS, true);
+form.fields.companyName.registerAction(new ConditionalVisibilityAction(isCompany));
+form.fields.companyName.registerAction(new ConditionalAccessAction(isCompany));
+
+// Show and send the personal name fields only when isCompany is false
+const isPerson = new Statement(form.fields.isCompany, Operator.EQUALS, false);
+[form.fields.firstName, form.fields.lastName].forEach((field) => {
+  field.registerAction(new ConditionalVisibilityAction(isPerson));
+  field.registerAction(new ConditionalAccessAction(isPerson));
+});
 ```
 
 ## Advanced Data Structures (Lists)
@@ -409,28 +413,28 @@ const email: string = userForm.fields.email.value;
 const age: number = userForm.fields.age.value;
 const darkMode: boolean = userForm.fields.preferences.fields.darkMode.value;
 
-// The serialized value is typed too, member by member. Every member is optional, because a disabled field is
-// left out of the object the group builds
-const values = userForm.value!;
-const emailFromValue: string | undefined = values.email;
-const prefs: { darkMode?: boolean; notifications?: boolean } | null | undefined = values.preferences;
+// The serialized value is typed too, member by member. Every member is optional, because a 'disabled' member is
+// left out of the object the group builds, and nullable, because a 'disabled-null' one is sent as null
+const values = userForm.value;
+const emailFromValue: string | null | undefined = values.email;
+const prefs: { darkMode?: boolean | null; notifications?: boolean | null } | null | undefined = values.preferences;
 
 // Type safety prevents errors
 // userForm.fields.age.value = 'not a number'; // Error: Type 'string' is not assignable to type 'number'
 ```
 
 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
+`GroupValueInput<T>` as the group's read and write types, and `ListValue<R>` for lists. Constructor parameters have
 their own exported type, `IFieldParams<T, X>`, shared by all four element classes:
 
 ```typescript
 import { Field, IFieldParams } from '@dynamicforms/vue-forms';
 
-const defaults: IFieldParams<string> = { value: '', enabled: false };
+const defaults: IFieldParams<string> = { value: '', access: 'readonly' };
 const field = new Field(defaults);
 ```
 
-It admits only the writable members — `value`, `originalValue`, `enabled`, `visibility`, `touched`, `errors`,
+It admits only the writable members — `value`, `originalValue`, `access`, `visibility`, `touched`, `errors`,
 `validators` and `actions`, listed by `IFieldConstructorParams<T>`. Derived members such as `valid` and
 `isChanged` are getters, and passing one is a compile error.