@dynamicforms/vue-forms 0.1.5 → 0.2.0

package/dist/index.d.ts

@@ -1,14 +1,16 @@
 import { ComputedRef } from 'vue';
+import { Ref } from 'vue';
 
 export declare class AbortEventHandlingException extends Error {
 }
 
 export declare class Action extends FieldBase {
     private readonly _value;
-    protected constructor(params?: Partial<IField<ActionValue>>);
+    protected constructor(params?: Partial<IFieldConstructorParams<ActionValue>>);
     static create(params?: Partial<IField<ActionValue>>): Action;
     get value(): ActionValue;
     set value(newValue: ActionValue);
+    setValue(newValue: ActionValue): Promise<void>;
     get icon(): string | undefined;
     set icon(newValue: string | undefined);
     get label(): string | undefined;
@@ -20,8 +22,13 @@ export declare class Action extends FieldBase {
 declare type ActionExecutor = (field: IField, supr: FieldActionExecute, ...params: any[]) => Promise<any>;
 
 export declare class ActionsMap extends Map<symbol, FieldActionExecute> {
+    private readonly eagerActions;
     register(action: FieldActionBase): void;
-    trigger<T extends FieldActionBase>(ActionClass: new (...args: any[]) => T, field: IField, ...params: any[]): any;
+    trigger<T extends FieldActionBase>(ActionClass: {
+        new (...args: any[]): T;
+        classIdentifier: symbol;
+    }, field: IField, ...params: any[]): Promise<any>;
+    triggerEager(field: IField, ...params: any[]): Promise<any>;
 }
 
 export declare interface ActionValue {
@@ -29,6 +36,39 @@ export declare interface ActionValue {
     icon?: string;
 }
 
+export declare function buildErrorMessage(mdErrorString: string): string | MdString;
+
+export declare class ConditionalEnabledAction extends ConditionalStatementAction {
+    constructor(statement: Statement);
+}
+
+declare type ConditionalExecutorFn = (field: IField, currentResult: boolean, previousResult: boolean | undefined) => Promise<void>;
+
+export declare class ConditionalStatementAction extends ValueChangedAction {
+    private lastResult;
+    private readonly boundFields;
+    constructor(statement: Statement, executorFn: ConditionalExecutorFn);
+    static get classIdentifier(): symbol;
+    get eager(): boolean;
+    boundToField(field: IField): void;
+}
+
+export declare class ConditionalValueAction<T> extends ConditionalStatementAction {
+    constructor(statement: Statement, trueValue: T);
+}
+
+export declare class ConditionalVisibilityAction extends ConditionalStatementAction {
+    constructor(statement: Statement);
+}
+
+/**
+ * Interface for custom component content definition
+ */
+export declare interface CustomModalContentComponentDef {
+    componentName: string;
+    componentProps: Record<any, any>;
+}
+
 /**
  * DisplayMode enum provides an enumeration for supported ways of rendering a particular object in the DOM
  */
@@ -49,36 +89,45 @@ export declare const EmptyField: Field<string>;
 
 export declare class EnabledChangedAction extends FieldActionBase {
     constructor(executorFn: (field: IField, supr: FieldActionExecute, newValue: boolean, oldValue: boolean) => Promise<void>);
-    get classIdentifier(): symbol;
+    static get classIdentifier(): symbol;
     execute(field: IField, supr: FieldActionExecute, newValue: boolean, oldValue: boolean): Promise<void>;
 }
 
 export declare class EnabledChangingAction extends FieldActionBase {
     constructor(executorFn: (field: IField, supr: FieldActionExecute, newValue: boolean, oldValue: boolean) => Promise<boolean>);
-    get classIdentifier(): symbol;
+    static get classIdentifier(): symbol;
     execute(field: IField, supr: FieldActionExecute, newValue: boolean, oldValue: boolean): Promise<boolean>;
 }
 
 export declare class ExecuteAction extends FieldActionBase {
     constructor(executorFn: (field: IField, supr: FieldActionExecute, params: any) => Promise<any>);
-    get classIdentifier(): symbol;
+    static get classIdentifier(): symbol;
     execute(field: IField, supr: FieldActionExecute, params: any): Promise<any>;
 }
 
 export declare class Field<T = any> extends FieldBase {
     private _value;
-    protected constructor(params?: Partial<IField<T>>);
-    static create<T = any>(params?: Partial<IField<T>>): Field<T>;
+    protected constructor(params?: Partial<IFieldConstructorParams<T>>);
+    /**
+     * Creates a new reactive Field instance.
+     * @param params Initial field parameters
+     * @returns Reactive Field instance
+     */
+    static create<T = any>(params?: Partial<IFieldConstructorParams<T>>): Field<T>;
     get value(): T;
     set value(newValue: T);
+    setValue(newValue: T): Promise<void>;
     clone(overrides?: Partial<IField<T>>): Field<T>;
 }
 
 export declare abstract class FieldActionBase implements IFieldAction {
-    abstract get classIdentifier(): symbol;
+    static get classIdentifier(): symbol;
+    get classIdentifier(): symbol;
     private readonly executorFn;
     constructor(executorFn: ActionExecutor);
     execute(field: IField, supr: IFieldAction['execute'], ...params: any[]): Promise<any>;
+    get eager(): boolean;
+    boundToField(field: IField): void;
 }
 
 export declare type FieldActionExecute<T = any> = (field: IField<T>, ...params: any[]) => Promise<any>;
@@ -86,6 +135,7 @@ export declare type FieldActionExecute<T = any> = (field: IField<T>, ...params:
 export declare abstract class FieldBase<T = any> implements IField<T> {
     abstract get value(): T;
     abstract set value(newValue: T);
+    abstract setValue(newValue: T): Promise<void>;
     readonly reactiveValue: ComputedRef<T>;
     abstract clone(overrides?: Partial<IField<T>>): IField<T>;
     originalValue: T;
@@ -112,8 +162,6 @@ export declare abstract class FieldBase<T = any> implements IField<T> {
 declare namespace Form {
     export {
         DisplayMode,
-        ValidationError,
-        ValidationErrorText,
         FieldActionBase,
         ActionsMap,
         EnabledChangedAction,
@@ -125,6 +173,13 @@ declare namespace Form {
         ValueChangedAction,
         ListItemAddedAction,
         ListItemRemovedAction,
+        Operator,
+        ConditionalStatementAction,
+        ConditionalVisibilityAction,
+        ConditionalEnabledAction,
+        ConditionalValueAction,
+        OperandType,
+        Statement,
         ActionValue,
         Action,
         NullableAction,
@@ -132,6 +187,8 @@ declare namespace Form {
         NullableField,
         EmptyField,
         IField,
+        IFieldConstructorActionsList,
+        IFieldConstructorParams,
         AbortEventHandlingException,
         FieldActionExecute,
         IFieldAction,
@@ -140,26 +197,47 @@ declare namespace Form {
         Group,
         NullableGroup,
         List,
-        NullableList
+        NullableList,
+        Validators,
+        buildErrorMessage,
+        isCustomModalContentComponentDef,
+        MdString,
+        CustomModalContentComponentDef,
+        RenderContent,
+        RenderContentRef,
+        ValidationError,
+        ValidationErrorText,
+        ValidationErrorRenderContent,
+        ValidationFunction,
+        Validator
     }
 }
 export default Form;
 
+export declare const forms: {
+    install(app: any, options?: Partial<FormsConfig>): void;
+};
+
+declare interface FormsConfig {
+    useMarkdownInValidators: boolean;
+}
+
 export declare type GenericFieldsInterface = Record<string, IField>;
 
 export declare class Group<T extends GenericFieldsInterface = GenericFieldsInterface> extends FieldBase {
     private readonly _fields;
     private _value;
     private suppressNotifyValueChanged;
-    constructor(fields: T, params?: Partial<IField>);
+    constructor(fields: T, params?: Partial<IFieldConstructorParams>);
     private static isValidFields;
     static createFromFormData(data: Record<string, any> | null): Group;
-    field(fieldName: string): IField | null;
+    field<K extends keyof T>(fieldName: K): T[K] | null;
     get fields(): T;
     get value(): Record<string, any> | null;
     set value(newValue: Record<string, any> | null);
+    setValue(newValue: Record<string, any> | null): Promise<void>;
     get fullValue(): Record<string, any>;
-    notifyValueChanged(): void;
+    notifyValueChanged(): Promise<void>;
     clone(overrides?: Partial<IField>): Group<T>;
 }
 
@@ -175,6 +253,9 @@ export declare interface IField<T = any> {
     parent?: any;
     fieldName?: string;
     clone(overrides?: Partial<IField<T>>): IField<T>;
+    setVisibility(newValue: DisplayMode): Promise<void>;
+    setEnabled(newValue: boolean): Promise<void>;
+    setValue(newValue: T): Promise<void>;
     registerAction(action: IFieldAction<T>): this;
     triggerAction<T2 extends IFieldAction<T>>(actionClass: abstract new (...args: any[]) => T2, ...params: any[]): any;
     validate(): void;
@@ -185,15 +266,38 @@ 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>;
+
+declare class InAllowedValues<T = any> extends Validator {
+    constructor(allowedValues: T[], message?: RenderContentRef);
+}
+
+/**
+ * Type guard to check if content is a custom component definition
+ * @param msg - Content to check
+ * @returns True if content is a custom component definition
+ */
+export declare function isCustomModalContentComponentDef(msg?: RenderContentRef): msg is CustomModalContentComponentDef;
+
+declare class LengthInRange<T = any> extends Validator {
+    constructor(minLength: number, maxLength: number, message?: RenderContentRef);
+}
+
 export declare class List<T extends GenericFieldsInterface = GenericFieldsInterface> extends FieldBase {
     private _value;
     private _itemTemplate?;
     private _previousValue;
-    constructor(itemTemplate?: Group<T>, params?: Partial<IField>);
+    constructor(itemTemplate?: Group<T>, params?: Partial<IFieldConstructorParams>);
     private processSetValueItem;
-    private setValue;
+    private setValueInternal;
     get value(): Record<string, any>[] | null;
     set value(newValue: Record<string, any>[]);
+    setValue(newValue: Record<string, any>[]): Promise<void>;
     clone(overrides?: Partial<IField>): List<T>;
     notifyValueChanged(): void;
     get(index: number): Group<T> | undefined;
@@ -206,16 +310,38 @@ export declare class List<T extends GenericFieldsInterface = GenericFieldsInterf
 
 export declare class ListItemAddedAction extends FieldActionBase {
     constructor(executorFn: (field: IField, supr: FieldActionExecute, item: any, index: number) => Promise<void>);
-    get classIdentifier(): symbol;
+    static get classIdentifier(): symbol;
     execute(field: IField, supr: FieldActionExecute, item: any, index: number): Promise<void>;
 }
 
 export declare class ListItemRemovedAction extends FieldActionBase {
     constructor(executorFn: (field: IField, supr: FieldActionExecute, item: any, index: number) => Promise<void>);
-    get classIdentifier(): symbol;
+    static get classIdentifier(): symbol;
     execute(field: IField, supr: FieldActionExecute, item: any, index: number): Promise<void>;
 }
 
+declare class MaxLength<T = any> extends Validator {
+    constructor(maxLength: number, message?: RenderContentRef);
+}
+
+declare class MaxValue<T = any> extends Validator {
+    constructor(maxValue: T, message?: RenderContentRef);
+}
+
+/**
+ * Marks content for markdown rendering
+ */
+export declare class MdString extends String {
+}
+
+declare class MinLength<T = any> extends Validator {
+    constructor(minLength: number, message?: RenderContentRef);
+}
+
+declare class MinValue<T = any> extends Validator {
+    constructor(minValue: T, message?: RenderContentRef);
+}
+
 export declare type NullableAction = Action | null;
 
 export declare type NullableField<T = any> = Field<T> | null;
@@ -224,41 +350,160 @@ export declare type NullableGroup = Group | null;
 
 export declare type NullableList = List | null;
 
+export declare type OperandType = any | Statement | IField;
+
+/**
+ * Operators provides us a functionality for backend to send us complex condition upon which we send
+ * dynamic visibility prop for form input fields
+ */
+export declare enum Operator {
+    NOT = 0,
+    OR = 1,
+    AND = 2,
+    XOR = 3,
+    NAND = 4,
+    NOR = 5,
+    EQUALS = -1,
+    NOT_EQUALS = -2,
+    GT = -3,
+    LT = -4,
+    GE = -5,
+    LE = -6,
+    IN = -7,
+    NOT_IN = -8,
+    INCLUDES = -9,
+    NOT_INCLUDES = -10
+}
+
+export declare namespace Operator {
+    export function fromString(operator: string): Operator;
+    export function fromAny(mode: any): Operator;
+    export function isDefined(operator: number | string): boolean;
+    export function isLogicOperator(operator: Operator): boolean;
+}
+
+declare class Pattern<T = any> extends Validator {
+    constructor(pattern: RegExp, message?: RenderContentRef);
+}
+
+/**
+ * Type for different renderable content formats: plain string, markdown, or custom component
+ */
+export declare type RenderContent = string | MdString | CustomModalContentComponentDef;
+
+/**
+ * Type for different renderable content formats (supporting references): plain string, markdown, or custom component
+ */
+export declare type RenderContentRef = RenderContent | Ref<RenderContent>;
+
+declare class Required_2<T = any> extends Validator {
+    constructor(message?: RenderContentRef);
+}
+
+export declare class Statement {
+    private readonly operand1;
+    private readonly operator;
+    private readonly operand2;
+    constructor(operand1: OperandType, operator: Operator, operand2: OperandType);
+    get operand1Value(): any;
+    get operand2Value(): any;
+    evaluate(): boolean;
+    /**
+     * 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>;
+}
+
+/**
+ * Base validation error class with component rendering capabilities
+ */
 export declare class ValidationError {
     get componentName(): string;
     get componentBindings(): {};
+    get componentBody(): string;
+}
+
+/**
+ * Validation error that supports multiple content types (plain text, markdown, component)
+ */
+export declare class ValidationErrorRenderContent extends ValidationError {
+    text: Ref<RenderContent>;
+    textType: ComputedRef<'string' | 'md' | 'component'>;
+    constructor(text: RenderContentRef);
+    get getTextType(): "string" | "md" | "component";
+    get componentName(): string;
+    get componentBindings(): Record<any, any>;
+    get componentBody(): string;
 }
 
+/**
+ * Simple text-only ValidationError
+ */
 export declare class ValidationErrorText extends ValidationError {
     text: string;
     constructor(text: string);
     get componentName(): string;
-    get componentBindings(): {
-        class: string;
-    };
+    get componentBody(): string;
+}
+
+export declare type ValidationFunction<T = any> = (newValue: T, oldValue: T, field: IField<T>) => ValidationError[] | null;
+
+/**
+ * Validator is a specialized action that performs validation when a field's value changes.
+ * It automatically adds/removes validation errors from the field's errors array.
+ */
+export declare class Validator<T = any> extends ValueChangedAction {
+    private readonly source;
+    /**
+     * Creates a new validator
+     * @param validationFn Function that validates the field value and returns errors or null
+     */
+    constructor(validationFn: ValidationFunction<T>);
+    static get classIdentifier(): symbol;
+    get eager(): boolean;
+    protected replacePlaceholders(text: RenderContentRef, replace: Record<string, any>): string | MdString | CustomModalContentComponentDef;
+}
+
+export declare namespace Validators {
+    export {
+        InAllowedValues,
+        Required_2 as Required,
+        Pattern,
+        MinValue,
+        MaxValue,
+        ValueInRange,
+        MinLength,
+        MaxLength,
+        LengthInRange
+    }
 }
 
 export declare class ValidChangedAction extends FieldActionBase {
     constructor(executorFn: (field: IField, supr: FieldActionExecute, newValue: boolean, oldValue: boolean) => Promise<void>);
-    get classIdentifier(): symbol;
+    static get classIdentifier(): symbol;
     execute(field: IField, supr: FieldActionExecute, newValue: boolean, oldValue: boolean): Promise<void>;
 }
 
 export declare class ValueChangedAction<T = any> extends FieldActionBase {
     constructor(executorFn: (field: IField<T>, supr: FieldActionExecute<T>, newValue: T, oldValue: T) => Promise<void>);
-    get classIdentifier(): symbol;
+    static get classIdentifier(): symbol;
     execute(field: IField<T>, supr: FieldActionExecute<T>, newValue: T, oldValue: T): Promise<void>;
 }
 
+declare class ValueInRange<T = any> extends Validator {
+    constructor(minValue: T, maxValue: T, message?: RenderContentRef);
+}
+
 export declare class VisibilityChangedAction extends FieldActionBase {
     constructor(executorFn: (field: IField, supr: FieldActionExecute, newValue: DisplayMode, oldValue: DisplayMode) => Promise<void>);
-    get classIdentifier(): symbol;
+    static get classIdentifier(): symbol;
     execute(field: IField, supr: FieldActionExecute, newValue: DisplayMode, oldValue: DisplayMode): Promise<void>;
 }
 
 export declare class VisibilityChangingAction extends FieldActionBase {
     constructor(executorFn: (field: IField, supr: FieldActionExecute, newValue: DisplayMode, oldValue: DisplayMode) => Promise<DisplayMode>);
-    get classIdentifier(): symbol;
+    static get classIdentifier(): symbol;
     execute(field: IField, supr: FieldActionExecute, newValue: DisplayMode, oldValue: DisplayMode): Promise<DisplayMode>;
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dynamicforms/vue-forms",
   "private": false,
-  "version": "0.1.5",
+  "version": "0.2.0",
   "type": "module",
   "description": "Data entry forms for vue - logic (no controls here)",
   "author": "Jure Erznožnik",

package/readme.md

@@ -21,7 +21,9 @@ separates these concerns, allowing you to build forms that match your design sys
 - **TypeScript support**: Full type definitions for excellent developer experience
 - **Lightweight**: No dependencies besides Vue and lodash
 - **Field types**: Core field types (Field, Action, Group, List) to represent any data structure
-- **Validation**: Simple validation system with extensible error handling
+- **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
 
@@ -88,6 +90,118 @@ const form = new Group({
 }));
 ```
 
+## Built-in Validators
+
+The library provides several built-in validators for common validation scenarios:
+
+```typescript
+import { Field, Group, Validators } from '@dynamicforms/vue-forms';
+
+const validatedForm = new Group({
+  // Required field
+  username: Field.create({ 
+    validators: [new Validators.Required('Username is required')] 
+  }),
+  
+  // Email validation with pattern
+  email: Field.create({ 
+    validators: [
+      new Validators.Pattern(
+        /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/,
+        'Please enter a valid email address'
+      )
+    ] 
+  }),
+  
+  // Numeric range validation
+  age: Field.create({ 
+    value: 25, 
+    validators: [
+      new Validators.ValueInRange(18, 100, 'Age must be between 18 and 100')
+    ] 
+  }),
+  
+  // Allowed values validation
+  role: Field.create({ 
+    validators: [
+      new Validators.InAllowedValues(['admin', 'user', 'guest'])
+    ] 
+  }),
+  
+  // Text length validation
+  bio: Field.create({
+    validators: [
+      new Validators.LengthInRange(10, 200, 'Bio must be between 10 and 200 characters')
+    ]
+  })
+});
+```
+
+## Conditional Form Behavior
+
+Create dynamic forms with conditional logic using Statements and Operators:
+
+```typescript
+import { 
+  Field, Group, Statement, Operator,
+  ConditionalVisibilityAction, ConditionalEnabledAction 
+} from '@dynamicforms/vue-forms';
+
+const form = new Group({
+  isCompany: Field.create({ value: false }),
+  companyName: Field.create(),
+  firstName: Field.create(),
+  lastName: Field.create()
+});
+
+// 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)
+);
+```
+
+## Advanced Data Structures (Lists)
+
+Work with array data using the List component:
+
+```typescript
+import { Field, Group, List } from '@dynamicforms/vue-forms';
+
+// Define a template for list items
+const contactTemplate = new Group({
+  name: Field.create(),
+  email: Field.create(),
+  phone: Field.create()
+});
+
+// Create a list with the template
+const contactsList = new List(contactTemplate);
+
+// Add items to the list
+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
+const firstContact = contactsList.get(0);
+console.log(firstContact.fields.name.value); // 'John Doe'
+
+// Modify items
+firstContact.fields.email.value = 'john.doe@example.com';
+
+// Remove items
+contactsList.remove(1);
+```
+
 ## TypeScript Support
 
 The library is written in TypeScript and provides full type definitions:
@@ -95,39 +209,61 @@ The library is written in TypeScript and provides full type definitions:
 ```typescript
 import { Field, Group, IField } from '@dynamicforms/vue-forms';
 
+// Define field types explicitly
+const usernameField = Field.create<string>({ value: '' });
+const emailField = Field.create<string>({ value: '' });
+const ageField = Field.create<number>({ value: 25 });
+const isActiveField = Field.create<boolean>({ value: true });
+
+// Type inference also works with initial values
+const implicitTypedField = Field.create({ value: 'string' }); // Type is inferred as string
+
 // Define your form structure with types
-interface UserFormData {
-  username: Field;
-  email: Field;
+interface UserFormData extends GenericFieldsInterface {
+  username: Field<string>;
+  email: Field<string>;
+  age: Field<number>;
+  isActive: Field<boolean>;
   preferences: Group<{
-    darkMode: Field;
-    notifications: Field;
+    darkMode: Field<boolean>;
+    notifications: Field<boolean>;
   }>;
 }
 
 // Create the form with type checking
 const userForm = new Group<UserFormData>({
-  username: Field.create({ value: '' }),
-  email: Field.create({ value: '' }),
-  preferences: new Group({
-    darkMode: Field.create({ value: true }),
-    notifications: Field.create({ value: true })
+  username: Field.create<string>({ value: '' }),
+  email: Field.create<string>({ value: '' }),
+  age: Field.create<number>({ value: 25 }),
+  isActive: Field.create<boolean>({ value: true }),
+  preferences: new Group<{
+    darkMode: Field<boolean>;
+    notifications: Field<boolean>;
+  }>({
+    darkMode: Field.create<boolean>({ value: true }),
+    notifications: Field.create<boolean>({ value: true })
   })
 });
 
-// TypeScript knows the structure
+// TypeScript knows the structure and types
+const email: string = userForm.fields.email.value;
+const age: number = userForm.fields.age.value;
 const darkMode: boolean = userForm.fields.preferences.fields.darkMode.value;
+
+// Type safety prevents errors
+// userForm.fields.age.value = 'not a number'; // Error: Type 'string' is not assignable to type 'number'
 ```
 
+## Documentation
+
+For more detailed documentation and examples, check out the documentation (currently only locally runnable).
+
 ## Conclusion
 
 `@dynamicforms/vue-forms` provides a clean, flexible approach to form management in Vue applications. By focusing on 
 data structures and state management rather than UI components, it offers unparalleled flexibility while maintaining 
 a simple, intuitive API.
 
-For more detailed documentation and examples, check out the [source code](https://github.com/velis74/dynamicforms-vue-forms) or reach out to the author 
-for assistance.
-
 ## License
 
 MIT