@dynamicforms/vue-forms 3.0.0-alpha.2 → 3.0.0-alpha.4

package/dist/index.d.ts

@@ -551,6 +551,14 @@ export declare interface DevtoolsOptions {
 /** Which elements the devtools list: every root element except the hidden ones, or only the described ones. */
 export declare type DevtoolsRegistration = 'opt-out' | 'opt-in';
 
+/**
+ * Returns the element at `path` below `root`, or `undefined` if the path does not exist. A string path is split on
+ * `.`; `''` and `[]` return `root`. A step below a `Group` is a member name, below a `List` a non-negative integer
+ * (a number, or digits without leading zeros). A path that continues below an element that is neither a `Group` nor
+ * a `List` does not exist.
+ */
+export declare function elementAt(root: FieldBase, path: string | readonly (string | number)[]): FieldBase | undefined;
+
 /**
  * The mutable state of one element, held in a separate object, not in the element's own properties.
  *
@@ -655,15 +663,24 @@ export declare class EnabledChangingAction extends FieldActionBase {
     execute(field: FieldBase, supr: FieldActionExecute, newValue: boolean, oldValue: boolean): boolean;
 }
 
+/**
+ * The namespace of the error codes this library declares. A code the library raises is `${ERROR_NAMESPACE}.<code>`,
+ * such as `vue-forms.required`.
+ */
+export declare const ERROR_NAMESPACE = "vue-forms";
+
 /**
  * The content of an error: what failed, the values it failed with, an English sentence describing it, and its
  * origin. An error the application builds from a server's response has the same content, so a renderer converts
  * validator and server errors to text with one function.
  */
 export declare interface ErrorDescription {
-    /** Machine-readable identifier of what failed, in snake_case. */
+    /**
+     * Machine-readable identifier of what failed: `<namespace>.<code>`, such as `vue-forms.min_value`. The namespace
+     * names the package that declared the code.
+     */
     readonly code: string;
-    /** The values of the failure, such as `minValue` for `min_value`. */
+    /** The values of the failure, such as `minValue` for `vue-forms.min_value`. */
     readonly params: Readonly<Record<string, unknown>>;
     /** The failure in English, plain text, with `params` substituted. */
     readonly detail: string;
@@ -1473,6 +1490,7 @@ declare namespace Form {
         visibilityValues,
         defaultVisibility,
         isVisibility,
+        elementAt,
         configureDevtools,
         describeState,
         DevtoolsOptions,
@@ -1543,6 +1561,7 @@ declare namespace Form {
         ListItemInput,
         List,
         NullableList,
+        ERROR_NAMESPACE,
         ErrorPolicies,
         ErrorPolicy,
         ErrorPolicyRule,
@@ -2396,8 +2415,8 @@ export declare class ValidationError implements ErrorDescription {
     readonly detail: string;
     private readonly statedOrigin?;
     /**
-     * @param code Machine-readable identifier of what failed, in snake_case.
-     * @param params The values of the failure, such as `minValue` for `min_value`.
+     * @param code Machine-readable identifier of what failed, `<namespace>.<code>`. Stored as given.
+     * @param params The values of the failure, such as `minValue` for `vue-forms.min_value`.
      * @param detail The failure in English, plain text. Stored as given.
      * @param statedOrigin The origin of the error, if its author sets it; see `origin`.
      */
@@ -2421,11 +2440,14 @@ export declare class ValidationError implements ErrorDescription {
  * renderer has a text for that code.
  */
 declare type ValidationErrorOptions = {
-    /** The error's `code`. Defaults to the validator's own, such as `required`. */
+    /**
+     * The error's `code`, used as given. Defaults to the validator's own, such as `vue-forms.required`. The
+     * application prefixes its own codes with a namespace of its own.
+     */
     code?: string;
     detail?: never;
 } | {
-    /** The error's `code`. */
+    /** The error's `code`, used as given. */
     code: string;
     /** The error's English `detail`, plain text. `{name}` placeholders are replaced with the error's `params`. */
     detail?: string;
@@ -2492,7 +2514,8 @@ declare class Validator<T = any> extends ValueChangedAction {
     protected newBindingState(): ValidatorBindingState;
     /**
      * Returns the error a built-in validator reports: `code` and `detail` from `options` if set, the validator's own
-     * otherwise, with `params` substituted into the detail.
+     * otherwise, with `params` substituted into the detail. Both codes are used as given: a built-in validator passes
+     * its own code as `vue-forms.<code>`, and a subclass of the application passes a code in a namespace of its own.
      */
     protected errorFor(options: ValidationErrorOptions | undefined, code: string, detail: string, params: Record<string, unknown>): ValidationError;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dynamicforms/vue-forms",
   "private": false,
-  "version": "3.0.0-alpha.2",
+  "version": "3.0.0-alpha.4",
   "type": "module",
   "sideEffects": false,
   "description": "Reactive forms and application state for Vue.js: validation, rules between fields, transactions and lists. UI-agnostic and TypeScript-first.",
@@ -28,8 +28,7 @@
     "build": "vite build",
     "prepack": "npm run build",
     "test": "vitest run --coverage",
-    "lint": "eslint src --fix && vue-tsc --noEmit",
-    "lint:ci": "eslint src && vue-tsc --noEmit",
+    "lint": "node scripts/lint.mjs",
     "docs:dev": "npm run docs:dev -w docs",
     "docs:build": "npm run docs:build -w docs",
     "docs:preview": "npm run docs:preview -w docs"
@@ -87,6 +86,7 @@
     "eslint-plugin-unicorn": "^73.0.0",
     "eslint-plugin-vue": "^10.10.0",
     "jsdom": "^26.0.0",
+    "markdownlint-cli2": "^0.18.1",
     "prettier": "^3.9.6",
     "rollup-plugin-visualizer": "^5.14.0",
     "typescript": "^5",

package/readme.md

@@ -60,7 +60,8 @@ npm install @dynamicforms/vue-forms
 ```
 
 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 without a flag from 22.12; on 22.0–22.11 it needs `--experimental-require-module`. Type definitions ship with the build. The package ships no components and no styles.
+module, which Node supports without a flag from 22.12; on 22.0–22.11 it needs `--experimental-require-module`. Type
+definitions ship with the build. The package ships no components and no styles.
 
 ## Basic Usage Example
 
@@ -185,7 +186,7 @@ import { Field, Group, Validators } from '@dynamicforms/vue-forms';
 const validatedForm = new Group({
   // Required field
   username: new Field({ 
-    validators: [new Validators.Required({ code: 'username_required', detail: 'Username is required' })] 
+    validators: [new Validators.Required({ code: 'app.username_required', detail: 'Username is required' })] 
   }),
   
   // Email validation with pattern
@@ -193,7 +194,7 @@ const validatedForm = new Group({
     validators: [
       new Validators.Pattern(
         /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/,
-        { code: 'invalid_email', detail: 'Please enter a valid email address' }
+        { code: 'app.invalid_email', detail: 'Please enter a valid email address' }
       )
     ] 
   }),
@@ -202,7 +203,7 @@ const validatedForm = new Group({
   age: new Field({ 
     value: 25, 
     validators: [
-      new Validators.ValueInRange(18, 100, { code: 'age_range', detail: 'Age must be between {minValue} and {maxValue}' })
+      new Validators.ValueInRange(18, 100, { code: 'app.age_range', detail: 'Age must be between {minValue} and {maxValue}' })
     ] 
   }),
   
@@ -216,7 +217,7 @@ const validatedForm = new Group({
   // Text length validation
   bio: new Field({
     validators: [
-      new Validators.LengthInRange(10, 200, { code: 'bio_length', detail: 'Bio must be between 10 and 200 characters' })
+      new Validators.LengthInRange(10, 200, { code: 'app.bio_length', detail: 'Bio must be between 10 and 200 characters' })
     ]
   })
 });
@@ -227,10 +228,12 @@ invalid immediately. `field.touched` determines when the UI shows the errors. `R
 measuring it, so a value of only spaces counts as empty; `new Validators.Required({ trim: false })` keeps spaces as
 part of the value.
 
-An error is data: a `code` (`required`, `pattern`, `min_length`, …), the `params` it failed with, and an English
-`detail`. The library does not render it. The application, or a UI library such as `@dynamicforms/vuetify-inputs`,
-converts it into text, translated by its code. A validator's last argument, `{ code, detail }`, replaces the
-validator's default code and English detail.
+An error is data: a `code` (`vue-forms.required`, `vue-forms.pattern`, `vue-forms.min_length`, …), the `params` it
+failed with, and an English `detail`. A code is `<namespace>.<code>`; the library's namespace is `vue-forms`,
+exported as `ERROR_NAMESPACE`. The library does not render an error. The application, or a UI library such as
+`@dynamicforms/vuetify-inputs`, converts it into text, translated by its code. A validator's last argument,
+`{ code, detail }`, replaces the validator's default code and English detail; the library uses that code as given,
+and the application prefixes its own codes with a namespace of its own.
 
 A validation function may return a `Promise`; `field.validating` is `true` while it runs, and only the newest run
 determines the result. [Asynchronous validation](https://docs.velis.si/dynamicforms/vue-forms/api/validators#asynchronous-validation)