@dynamicforms/vue-forms 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 import { ComponentOptionsMixin } from 'vue';
 import { ComponentProvideOptions } from 'vue';
-import { ComputedRef } from 'vue';
 import { DefineComponent } from 'vue';
 import { PublicProps } from 'vue';
 import { Ref } from 'vue';
@@ -9,9 +8,7 @@ export declare class AbortEventHandlingException extends Error {
 }
 
 export declare class Action<T extends ActionValue = ActionValue> extends Field<T> {
-    constructor(guard?: symbol);
     protected init(params?: Partial<IFieldConstructorParams<T>>): void;
-    static create<T extends ActionValue = ActionValue>(params?: Partial<IFieldConstructorParams<T>>): Action<T>;
     get icon(): string | undefined;
     set icon(newValue: string | undefined);
     get label(): string | undefined;
@@ -19,17 +16,16 @@ export declare class Action<T extends ActionValue = ActionValue> extends Field<T
     execute(params: any): void;
 }
 
-declare type ActionExecutor = (field: IField, supr: FieldActionExecute, ...params: any[]) => any;
+declare type ActionExecutor = (field: FieldBase, supr: FieldActionExecute, ...params: any[]) => any;
 
 export declare class ActionsMap extends Map<symbol, FieldActionExecute> {
     private readonly eagerActions;
     private readonly registeredActions;
     register(action: FieldActionBase): void;
-    trigger<T extends FieldActionBase>(ActionClass: {
-        new (...args: any[]): T;
+    trigger<T extends FieldActionBase>(ActionClass: (abstract new (...args: any[]) => T) & {
         classIdentifier: symbol;
-    }, field: IField, ...params: any[]): any;
-    triggerEager(field: IField, ...params: any[]): any;
+    }, field: FieldBase, ...params: any[]): any;
+    triggerEager(field: FieldBase, ...params: any[]): any;
     clone(): ActionsMap;
     cloneWithoutValidators(): ActionsMap;
 }
@@ -54,7 +50,7 @@ declare class CompareTo<T = any> extends Validator {
     private otherField;
     private isValidComparison;
     private unregistered;
-    constructor(otherField: IField, isValidComparison: (myValue: T, otherValue: T) => boolean, message: RenderContentRef);
+    constructor(otherField: FieldBase, isValidComparison: (myValue: T, otherValue: T) => boolean, message: RenderContentRef);
     unregister(): void;
 }
 
@@ -62,7 +58,7 @@ export declare class ConditionalEnabledAction extends ConditionalStatementAction
     constructor(statement: Statement);
 }
 
-declare type ConditionalExecutorFn = (field: IField, currentResult: boolean, previousResult: boolean | undefined) => void;
+declare type ConditionalExecutorFn = (field: FieldBase, currentResult: boolean, previousResult: boolean | undefined) => void;
 
 export declare class ConditionalStatementAction extends ValueChangedAction {
     private lastResult;
@@ -70,7 +66,7 @@ export declare class ConditionalStatementAction extends ValueChangedAction {
     constructor(statement: Statement, executorFn: ConditionalExecutorFn);
     static get classIdentifier(): symbol;
     get eager(): boolean;
-    boundToField(field: IField): void;
+    boundToField(field: FieldBase): void;
 }
 
 export declare class ConditionalValueAction<T> extends ConditionalStatementAction {
@@ -97,67 +93,80 @@ export declare namespace DisplayMode {
     export function isDefined(mode: number | string): boolean;
 }
 
-export declare const EmptyField: Field<unknown>;
+export declare const EmptyField: Field<string>;
 
 export declare class EnabledChangedAction extends FieldActionBase {
-    constructor(executorFn: (field: IField, supr: FieldActionExecute, newValue: boolean, oldValue: boolean) => void);
+    constructor(executorFn: (field: FieldBase, supr: FieldActionExecute, newValue: boolean, oldValue: boolean) => void);
     static get classIdentifier(): symbol;
-    execute(field: IField, supr: FieldActionExecute, newValue: boolean, oldValue: boolean): void;
+    execute(field: FieldBase, supr: FieldActionExecute, newValue: boolean, oldValue: boolean): void;
 }
 
 export declare class EnabledChangingAction extends FieldActionBase {
-    constructor(executorFn: (field: IField, supr: FieldActionExecute, newValue: boolean, oldValue: boolean) => boolean);
+    constructor(executorFn: (field: FieldBase, supr: FieldActionExecute, newValue: boolean, oldValue: boolean) => boolean);
     static get classIdentifier(): symbol;
-    execute(field: IField, supr: FieldActionExecute, newValue: boolean, oldValue: boolean): boolean;
+    execute(field: FieldBase, supr: FieldActionExecute, newValue: boolean, oldValue: boolean): boolean;
 }
 
 export declare class ExecuteAction extends FieldActionBase {
-    constructor(executorFn: (field: IField, supr: FieldActionExecute, params: any) => any);
+    constructor(executorFn: (field: FieldBase, supr: FieldActionExecute, params: any) => any);
     static get classIdentifier(): symbol;
-    execute(field: IField, supr: FieldActionExecute, params: any): any;
+    execute(field: FieldBase, supr: FieldActionExecute, params: any): any;
 }
 
-export declare class Field<T = any> extends FieldBase {
+export declare class Field<T = any> extends FieldBase<T> {
     protected _value: T;
     protected _touched: boolean;
-    constructor(guard?: symbol);
-    protected init(params?: Partial<IFieldConstructorParams<T>>): void;
+    constructor(params?: Partial<IFieldConstructorParams<T>>);
     /**
-     * Creates a new reactive Field instance.
-     * @param params Initial field parameters
-     * @returns Reactive Field instance
+     * Applies the constructor parameters. It is a hook so that a subclass needing different parameter handling
+     * overrides one method instead of redeclaring the constructor - Action does exactly that.
+     *
+     * It is called from this constructor, so it runs before a subclass's own class field initializers, which
+     * only run once super() returns. An override must therefore work off its parameters alone: members the
+     * subclass initializes read as undefined inside it, and anything it writes to such a member is overwritten
+     * the moment the initializer runs.
      */
-    static create<T = any>(this: new (guard?: symbol) => Field<T>, params?: Partial<IFieldConstructorParams<T>>): InstanceType<typeof this>;
+    protected init(params?: Partial<IFieldConstructorParams<T>>): void;
     get value(): T;
     set value(newValue: T);
     get touched(): boolean;
     set touched(touched: boolean);
-    clone(overrides?: Partial<IField<T>>): this;
+    clone(overrides?: Partial<IFieldConstructorParams<T>>): this;
 }
 
-export declare abstract class FieldActionBase implements IFieldAction {
+export declare abstract class FieldActionBase {
     static get classIdentifier(): symbol;
     get classIdentifier(): symbol;
     private readonly executorFn;
     constructor(executorFn: ActionExecutor);
-    execute(field: IField, supr: IFieldAction['execute'], ...params: any[]): any;
+    execute(field: FieldBase, supr: FieldActionExecute, ...params: any[]): any;
     get eager(): boolean;
-    boundToField(field: IField): void;
+    boundToField(field: FieldBase): void;
     unregister(): void;
 }
 
-export declare type FieldActionExecute<T = any> = (field: IField<T>, ...params: any[]) => any;
+export declare type FieldActionExecute<T = any> = (field: FieldBase<T>, ...params: any[]) => any;
 
-export declare abstract class FieldBase<T = any> implements IField<T> {
+export declare abstract class FieldBase<T = any> {
+    /**
+     * A field is a Vue reactive proxy from construction onwards: the base constructor returns the proxy, and a
+     * derived class's `this` is whatever super() returned, so every subclass constructor, field initializer and
+     * method sees the proxy. Consequence: plain `field.property = value` is tracked, with no wrapper in between.
+     */
+    constructor();
     abstract get value(): T;
     abstract set value(newValue: T);
     abstract get touched(): boolean;
     abstract set touched(touched: boolean);
-    readonly reactiveValue: ComputedRef<T>;
-    abstract clone(overrides?: Partial<IField<T>>): IField<T>;
+    abstract clone(overrides?: Partial<IFieldConstructorParams<T>>): FieldBase<T>;
     originalValue: T;
-    protected validatingCount: number;
-    readonly validating = false;
+    private validatingCount;
+    /** true while at least one asynchronous validator is still running for this field */
+    get validating(): boolean;
+    /** announces the start of one asynchronous validation run; validators pair it with endValidating */
+    beginValidating(): void;
+    /** announces the end of one asynchronous validation run */
+    endValidating(): void;
     protected _valid: boolean;
     errors: ValidationError[];
     parent?: Group;
@@ -173,13 +182,15 @@ export declare abstract class FieldBase<T = any> implements IField<T> {
     get valid(): boolean;
     get fullValue(): any;
     get isChanged(): boolean;
-    registerAction(action: IFieldAction<T>): this;
-    triggerAction<T2 extends IFieldAction<T>>(actionClass: new (...args: any[]) => T2, ...params: any[]): any;
+    registerAction(action: FieldActionBase): this;
+    triggerAction<T2 extends FieldActionBase>(actionClass: (abstract new (...args: any[]) => T2) & {
+        classIdentifier: symbol;
+    }, ...params: any[]): any;
     clearValidators(): void;
 }
 
-declare type FieldsToValues<T extends GenericFieldsInterface> = {
-    [K in keyof T]: T[K] extends IField<infer U> ? U : T[K] extends Group<infer G> ? FieldsToValues<G> : any;
+export declare type FieldsToValues<T extends GenericFieldsInterface> = {
+    [K in keyof T]: T[K]['value'];
 };
 
 declare namespace Form {
@@ -210,16 +221,18 @@ declare namespace Form {
         Field,
         NullableField,
         EmptyField,
-        IField,
         IFieldConstructorActionsList,
         IFieldConstructorParams,
         AbortEventHandlingException,
         FieldActionExecute,
-        IFieldAction,
         FieldBase,
         GenericFieldsInterface,
+        FieldsToValues,
+        GroupValue,
+        GroupValueInput,
         Group,
         NullableGroup,
+        ListValue,
         List,
         NullableList,
         Validators,
@@ -253,61 +266,55 @@ declare interface FormsConfig {
     useMarkdownInValidators: boolean;
 }
 
-export declare type GenericFieldsInterface = Record<string, IField>;
+export declare type GenericFieldsInterface = Record<string, FieldBase>;
 
-export declare class Group<T extends GenericFieldsInterface = GenericFieldsInterface> extends FieldBase {
+export declare class Group<T extends GenericFieldsInterface = GenericFieldsInterface> extends FieldBase<GroupValue<T>> {
     private readonly _fields;
     private _value;
-    readonly reactiveValue: ComputedRef<FieldsToValues<T> | null>;
     private suppressNotifyValueChanged;
-    constructor(fields: T, params?: Partial<IFieldConstructorParams>);
+    constructor(fields: T, params?: Partial<IFieldConstructorParams<GroupValueInput<T>>>);
     private addField;
     private static isValidFields;
     static createFromFormData(data: Record<string, any> | null): Group;
     field<K extends keyof T>(fieldName: K): T[K] | null;
     get fields(): T;
-    get value(): FieldsToValues<T> | null;
-    set value(newValue: FieldsToValues<T> | null);
+    get value(): GroupValue<T>;
+    set value(newValue: GroupValueInput<T>);
     get touched(): boolean;
     set touched(touched: boolean);
     get fullValue(): Record<string, any>;
     notifyValueChanged(): void;
     get valid(): boolean;
     validate(revalidate?: boolean): void;
-    clone(overrides?: Partial<IField>): Group<T>;
+    clone(overrides?: Partial<IFieldConstructorParams<GroupValueInput<T>>>): Group<T>;
+}
+
+/** what Group.value reads back: the full field map, or null when no field serializes */
+export declare type GroupValue<T extends GenericFieldsInterface> = FieldsToValues<T> | null;
+
+/** what Group.value and the Group constructor accept: keys left out are simply not assigned */
+export declare type GroupValueInput<T extends GenericFieldsInterface> = Partial<FieldsToValues<T>> | null;
+
+export declare interface IFieldConstructorActionsList {
+    actions?: FieldActionBase[];
+    validators?: FieldActionBase[];
 }
 
-export declare interface IField<T = any> {
+/**
+ * Parameters accepted by field constructors and by clone overrides.
+ *
+ * Only writable members are listed. valid, validating, fullValue and isChanged are getter-only, so assigning
+ * them throws a TypeError. parent and fieldName are set by the container: until a Group or List installs them
+ * as non-configurable accessors, assigning them is silently accepted, which is why the type rejects them.
+ */
+export declare type IFieldConstructorParams<T = any> = {
     value: T;
-    reactiveValue: ComputedRef<T>;
-    fullValue: T;
     originalValue: T;
-    valid: boolean;
-    validating: boolean;
-    errors: ValidationError[];
     enabled: boolean;
     visibility: DisplayMode;
     touched: boolean;
-    parent?: any;
-    fieldName?: string;
-    clone(overrides?: Partial<IField<T>>): IField<T>;
-    registerAction(action: IFieldAction<T>): this;
-    triggerAction<T2 extends IFieldAction<T>>(actionClass: abstract new (...args: any[]) => T2, ...params: any[]): any;
-    validate(revalidate?: boolean): void;
-    clearValidators(): void;
-    isChanged: boolean;
-}
-
-export declare interface IFieldAction<T = any> {
-    execute(field: IField<T>, supr: FieldActionExecute<T>, ...params: any[]): any;
-}
-
-export declare interface IFieldConstructorActionsList<T = any> {
-    actions?: IFieldAction<T>[];
-    validators?: IFieldAction<T>[];
-}
-
-export declare type IFieldConstructorParams<T = any> = IField<T> & IFieldConstructorActionsList<T>;
+    errors: ValidationError[];
+} & IFieldConstructorActionsList;
 
 declare class InAllowedValues<T = any> extends Validator {
     constructor(allowedValues: T[], message?: RenderContentRef);
@@ -326,18 +333,18 @@ declare class LengthInRange<T = any> extends Validator {
     constructor(minLength: number, maxLength: number, message?: RenderContentRef);
 }
 
-export declare class List<T extends GenericFieldsInterface = GenericFieldsInterface> extends FieldBase {
+export declare class List<T extends GenericFieldsInterface = GenericFieldsInterface> extends FieldBase<ListValue> {
     private _value;
     private _itemTemplate?;
     private _previousValue;
-    constructor(itemTemplate?: Group<T>, params?: Partial<IFieldConstructorParams>);
+    constructor(itemTemplate?: Group<T>, params?: Partial<IFieldConstructorParams<ListValue>>);
     private processSetValueItem;
     private setValueInternal;
-    get value(): Record<string, any>[] | null;
+    get value(): ListValue;
     set value(newValue: Record<string, any>[]);
     get touched(): boolean;
     set touched(touched: boolean);
-    clone(overrides?: Partial<IField>): List<T>;
+    clone(overrides?: Partial<IFieldConstructorParams<ListValue>>): List<T>;
     notifyValueChanged(): void;
     get valid(): boolean;
     validate(revalidate?: boolean): void;
@@ -350,17 +357,20 @@ export declare class List<T extends GenericFieldsInterface = GenericFieldsInterf
 }
 
 export declare class ListItemAddedAction extends FieldActionBase {
-    constructor(executorFn: (field: IField, supr: FieldActionExecute, item: any, index: number) => void);
+    constructor(executorFn: (field: FieldBase, supr: FieldActionExecute, item: any, index: number) => void);
     static get classIdentifier(): symbol;
-    execute(field: IField, supr: FieldActionExecute, item: any, index: number): void;
+    execute(field: FieldBase, supr: FieldActionExecute, item: any, index: number): void;
 }
 
 export declare class ListItemRemovedAction extends FieldActionBase {
-    constructor(executorFn: (field: IField, supr: FieldActionExecute, item: any, index: number) => void);
+    constructor(executorFn: (field: FieldBase, supr: FieldActionExecute, item: any, index: number) => void);
     static get classIdentifier(): symbol;
-    execute(field: IField, supr: FieldActionExecute, item: any, index: number): void;
+    execute(field: FieldBase, supr: FieldActionExecute, item: any, index: number): void;
 }
 
+/** what List.value reads back: one plain object per item, or null when the list is empty */
+export declare type ListValue = Record<string, any>[] | null;
+
 declare class MaxLength<T = any> extends Validator {
     constructor(maxLength: number, message?: RenderContentRef);
 }
@@ -396,7 +406,7 @@ export declare type NullableGroup = Group | null;
 
 export declare type NullableList = List | null;
 
-export declare type OperandType = any | Statement | IField;
+export declare type OperandType = any | Statement | FieldBase;
 
 /**
  * Operators provides us a functionality for backend to send us complex condition upon which we send
@@ -482,7 +492,7 @@ export declare class Statement {
      * Recursively collects all fields used in this statement and its nested statements
      * @returns A set of all fields used in this statement
      */
-    collectFields(): Set<IField>;
+    collectFields(): Set<FieldBase>;
 }
 
 /**
@@ -523,7 +533,7 @@ export declare class ValidationErrorText extends ValidationError {
     get extraClasses(): ClassTypes;
 }
 
-export declare type ValidationFunction<T = any> = (newValue: T, oldValue: T, field: IField<T>) => ValidationFunctionResult | Promise<ValidationFunctionResult>;
+export declare type ValidationFunction<T = any> = (newValue: T, oldValue: T, field: FieldBase<T>) => ValidationFunctionResult | Promise<ValidationFunctionResult>;
 
 export declare type ValidationFunctionResult = ValidationError[] | null;
 
@@ -563,15 +573,15 @@ export declare namespace Validators {
 }
 
 export declare class ValidChangedAction extends FieldActionBase {
-    constructor(executorFn: (field: IField, supr: FieldActionExecute, newValue: boolean, oldValue: boolean) => void);
+    constructor(executorFn: (field: FieldBase, supr: FieldActionExecute, newValue: boolean, oldValue: boolean) => void);
     static get classIdentifier(): symbol;
-    execute(field: IField, supr: FieldActionExecute, newValue: boolean, oldValue: boolean): void;
+    execute(field: FieldBase, supr: FieldActionExecute, newValue: boolean, oldValue: boolean): void;
 }
 
 export declare class ValueChangedAction<T = any> extends FieldActionBase {
-    constructor(executorFn: (field: IField<T>, supr: FieldActionExecute<T>, newValue: T, oldValue: T) => void);
+    constructor(executorFn: (field: FieldBase<T>, supr: FieldActionExecute<T>, newValue: T, oldValue: T) => void);
     static get classIdentifier(): symbol;
-    execute(field: IField<T>, supr: FieldActionExecute<T>, newValue: T, oldValue: T): void;
+    execute(field: FieldBase<T>, supr: FieldActionExecute<T>, newValue: T, oldValue: T): void;
 }
 
 declare class ValueInRange<T = any> extends Validator {
@@ -579,15 +589,15 @@ declare class ValueInRange<T = any> extends Validator {
 }
 
 export declare class VisibilityChangedAction extends FieldActionBase {
-    constructor(executorFn: (field: IField, supr: FieldActionExecute, newValue: DisplayMode, oldValue: DisplayMode) => void);
+    constructor(executorFn: (field: FieldBase, supr: FieldActionExecute, newValue: DisplayMode, oldValue: DisplayMode) => void);
     static get classIdentifier(): symbol;
-    execute(field: IField, supr: FieldActionExecute, newValue: DisplayMode, oldValue: DisplayMode): void;
+    execute(field: FieldBase, supr: FieldActionExecute, newValue: DisplayMode, oldValue: DisplayMode): void;
 }
 
 export declare class VisibilityChangingAction extends FieldActionBase {
-    constructor(executorFn: (field: IField, supr: FieldActionExecute, newValue: DisplayMode, oldValue: DisplayMode) => DisplayMode);
+    constructor(executorFn: (field: FieldBase, supr: FieldActionExecute, newValue: DisplayMode, oldValue: DisplayMode) => DisplayMode);
     static get classIdentifier(): symbol;
-    execute(field: IField, supr: FieldActionExecute, newValue: DisplayMode, oldValue: DisplayMode): DisplayMode;
+    execute(field: FieldBase, supr: FieldActionExecute, newValue: DisplayMode, oldValue: DisplayMode): DisplayMode;
 }
 
 export { }

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@dynamicforms/vue-forms",
   "private": false,
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
-  "description": "Data entry forms for vue - logic (no controls here)",
+  "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",
   "files": [
     "dist/*"
@@ -12,34 +12,51 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "require": "./dist/dynamicforms-vue-forms.umd.cjs",
-      "import": "./dist/dynamicforms-vue-forms.js"
-    }
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/dynamicforms-vue-forms.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/dynamicforms-vue-forms.umd.cjs"
+      }
+    },
+    "./style.css": "./dist/dynamicforms-vue-forms.css",
+    "./package.json": "./package.json"
   },
   "workspaces": [
     "docs"
   ],
   "scripts": {
-    "build": "vite build",
+    "build": "vite build && node -e \"require('fs').copyFileSync('dist/index.d.ts', 'dist/index.d.cts')\"",
     "test": "vitest run --coverage",
     "lint": "eslint src --fix && vue-tsc --noEmit",
+    "lint:ci": "eslint src && vue-tsc --noEmit",
     "docs:dev": "npm run docs:dev -w docs",
     "docs:build": "npm run docs:build -w docs",
     "docs:preview": "npm run docs:preview -w docs"
   },
   "keywords": [
     "vue",
+    "vue3",
     "dynamicforms",
-    "velis",
     "forms",
+    "form-state",
+    "form-management",
+    "validation",
+    "reactive",
+    "typescript",
     "data entry"
   ],
   "license": "MIT",
+  "homepage": "https://docs.velis.si/dynamicforms/vue-forms",
   "repository": {
     "type": "git",
-    "url": "git@github.com:dynamicforms/vue-forms.git"
+    "url": "git+https://github.com/velis74/dynamicforms-vue-forms.git"
+  },
+  "bugs": {
+    "url": "https://github.com/velis74/dynamicforms-vue-forms/issues"
   },
-  "issues": "https://github.com/dynamicforms/vue-forms/issues",
   "peerDependencies": {
     "lodash-es": "^4.17.12",
     "vue": "^3.4"