@dynamicforms/vue-forms 0.12.0 → 0.16.0

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@dynamicforms/vue-forms",
   "private": false,
-  "version": "0.12.0",
+  "version": "0.16.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",
+  "author": "Jure Erzno\u017enik",
   "files": [
     "dist/*"
   ],
@@ -61,23 +61,35 @@
     "vue": "^3.5.2"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/lodash-es": "^4.17.12",
     "@types/markdown-it-attrs": "^4.1.3",
-    "@types/node": "^24.5.2",
+    "@types/node": "^26.2.0",
+    "@typescript-eslint/eslint-plugin": "^8.67.0",
+    "@typescript-eslint/parser": "^8.67.0",
     "@vitejs/plugin-vue": "^6",
     "@vitest/coverage-v8": "^3",
     "@vue/test-utils": "^2.2.4",
     "@vue/tsconfig": "^0.7.0",
     "baseline-browser-mapping": "^2.8.31",
-    "eslint-config-velis": "^2.0.11",
+    "eslint": "^10.4.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-config-velis": "^3.0.0",
+    "eslint-import-resolver-typescript": "^4.4.5",
+    "eslint-plugin-import-x": "^4.17.1",
+    "eslint-plugin-prettier": "^5.5.6",
+    "eslint-plugin-unicorn": "^73.0.0",
+    "eslint-plugin-vue": "^10.10.0",
     "jsdom": "^26.0.0",
     "markdown-it-attrs": "^4.3.1",
+    "prettier": "^3.9.6",
     "rollup-plugin-visualizer": "^5.14.0",
     "typescript": "^5",
     "vite": "^7",
     "vite-plugin-dts": "^4",
     "vite-plugin-eslint": "^1.8.1",
     "vitest": "^3",
+    "vue-eslint-parser": "^10.4.1",
     "vue-markdown-render": "^2.3.0",
     "vue-tsc": "^2"
   }

package/readme.md

@@ -22,19 +22,27 @@ mechanism applies at every level of a nested form.
 
 ## Features
 
-- **UI-agnostic**: Works with any Vue UI components or your custom ones
+- **UI-agnostic**: a logic layer for form state, validation and dynamic behaviour. Any Vue components render it,
+  your own included
+- **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
+  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
-- **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
+- **Nested structures**: fields, groups and lists compose recursively, at every level
+- **Event system**: every change travels through an action pipeline; a handler may pass it on, reshape it or stop it
+- **Validation**: built-in validators, custom synchronous and asynchronous rules, cross-field comparisons, and
+  errors that carry a `code` and render as text, markdown or a component of your own
+- **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)
+- **TypeScript support**: full type definitions, and a group's value type inferred from the fields it holds
 - **Lightweight**: `vue` (^3.5.2) is the only peer dependency and `lodash-es` the only runtime one
-- **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
-- **Display modes**: Control field visibility with different display modes (Full, Hidden, Invisible, Suppress)
 
 ## Installation
 
@@ -63,6 +71,10 @@ The import must be a named one — the default export is a namespace of the libr
 (`MdString`). Rendering those requires a globally registered `vue-markdown` component; set the option to `false` if you
 want plain text instead.
 
+The configuration is module-global rather than per app, and `getConfig()`, `setConfig()` and the `FormsConfig` type
+are exported beside the plugin, so the options can be read and written where there is no app to install a plugin
+on.
+
 ## Basic Usage Example
 
 Every form element is created with the constructor: `new Field({ ... })`, `new Action({ ... })`,
@@ -211,13 +223,22 @@ 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.
+invalid immediately. Use `field.touched` to decide when to show the errors in the UI. `Required` trims a string
+before it measures it, so a value of spaces alone is no value; `new Validators.Required({ trim: false })` keeps the
+spaces where they are part of what the field holds.
+
+Every error a built-in validator produces carries a `code` — `required`, `pattern`, `min-length`, … — so a program
+reacting to one particular failure need not match message text that is translated and configurable.
+
+A validation function may return a `Promise`. `field.validating` is `true` while such a run is pending — on the
+field and on every container above it, so a form answers for the whole tree — 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. The
+function receives an `AbortSignal` as its fourth argument, which aborts the moment the run's verdict stops
+counting, so the request behind it can be called off. `form.busy` is the same question with the `Action.execute()`
+runs below it included — what a submit button binds to. 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
 
@@ -326,7 +347,8 @@ const contactsList = new List(contactTemplate);
 contactsList.push({ name: 'John Doe', email: 'john@example.com', phone: '123-456-7890' });
 contactsList.push({ name: 'Jane Doe', email: 'jane@example.com', phone: '987-654-3210' });
 
-// Access list items: get() returns undefined for an invalid index
+// Access list items: items hands out the rows, get() answers undefined for an invalid index
+console.log(contactsList.length);            // 2
 const firstContact = contactsList.get(0)!;
 console.log(firstContact.fields.name.value); // 'John Doe'
 
@@ -337,8 +359,9 @@ firstContact.fields.email.value = 'john.doe@example.com';
 contactsList.remove(1);
 ```
 
-Every list mutation is tracked, so a `v-for` over `contactsList.value` re-renders on `push()`, `insert()`,
-`remove()`, `pop()` and `clear()` without any extra wiring.
+Every list mutation is tracked, so a `v-for` over `contactsList.items` re-renders on `push()`, `insert()`,
+`remove()`, `pop()` and `clear()` without any extra wiring. `items` hands out a frozen array of the live rows,
+rebuilt once per change of the set.
 
 ## TypeScript Support
 
@@ -388,10 +411,11 @@ 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
+// 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 = values.email;
-const prefs: { darkMode: boolean; notifications: boolean } | null = values.preferences;
+const emailFromValue: string | undefined = values.email;
+const prefs: { darkMode?: boolean; notifications?: boolean } | null | undefined = values.preferences;
 
 // Type safety prevents errors
 // userForm.fields.age.value = 'not a number'; // Error: Type 'string' is not assignable to type 'number'
@@ -443,8 +467,8 @@ For more detailed documentation and examples, check out the [documentation](http
 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.
+[migration guide](https://docs.velis.si/dynamicforms/vue-forms/guide/migration) walks the journey from 0.6.1
+onwards, silent breaks first, and keeps a section per release for a project crossing one.
 
 ## Conclusion