@dynamicforms/vue-forms 0.5.0 → 0.6.0

package/dist/index.d.cts

@@ -0,0 +1,603 @@
+import { ComponentOptionsMixin } from 'vue';
+import { ComponentProvideOptions } from 'vue';
+import { DefineComponent } from 'vue';
+import { PublicProps } from 'vue';
+import { Ref } from 'vue';
+
+export declare class AbortEventHandlingException extends Error {
+}
+
+export declare class Action<T extends ActionValue = ActionValue> extends Field<T> {
+    protected init(params?: Partial<IFieldConstructorParams<T>>): void;
+    get icon(): string | undefined;
+    set icon(newValue: string | undefined);
+    get label(): string | undefined;
+    set label(newValue: string | undefined);
+    execute(params: any): void;
+}
+
+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: (abstract new (...args: any[]) => T) & {
+        classIdentifier: symbol;
+    }, field: FieldBase, ...params: any[]): any;
+    triggerEager(field: FieldBase, ...params: any[]): any;
+    clone(): ActionsMap;
+    cloneWithoutValidators(): ActionsMap;
+}
+
+export declare interface ActionValue {
+    label?: string;
+    icon?: string;
+}
+
+/**
+ * Depending on the useMarkdownInValidators setting, return either markdown or a plain string error message
+ * @param mdErrorString markdown source to optionally be stripped
+ * @return MdString or string
+ */
+export declare function buildErrorMessage(mdErrorString: string): string | MdString;
+
+export declare type ClassType = string | string[] | Record<string, boolean>;
+
+export declare type ClassTypes = ClassType | ClassType[];
+
+declare class CompareTo<T = any> extends Validator {
+    private otherField;
+    private isValidComparison;
+    private unregistered;
+    constructor(otherField: FieldBase, isValidComparison: (myValue: T, otherValue: T) => boolean, message: RenderContentRef);
+    unregister(): void;
+}
+
+export declare class ConditionalEnabledAction extends ConditionalStatementAction {
+    constructor(statement: Statement);
+}
+
+declare type ConditionalExecutorFn = (field: FieldBase, currentResult: boolean, previousResult: boolean | undefined) => 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: FieldBase): void;
+}
+
+export declare class ConditionalValueAction<T> extends ConditionalStatementAction {
+    constructor(statement: Statement, trueValue: T);
+}
+
+export declare class ConditionalVisibilityAction extends ConditionalStatementAction {
+    constructor(statement: Statement);
+}
+
+/**
+ * DisplayMode enum provides an enumeration for supported ways of rendering a particular object in the DOM
+ */
+export declare enum DisplayMode {
+    SUPPRESS = 1,// Field will be entirely suppressed. it will not render (not even to JSON) and will not parse for PUT
+    HIDDEN = 5,// Field will render as <input type="hidden"> or <tr data-field_name>
+    INVISIBLE = 8,// Field will render completely, but with display: none. Equal to setting its style = {display: none}
+    FULL = 10
+}
+
+export declare namespace DisplayMode {
+    export function fromString(mode: string): DisplayMode;
+    export function fromAny(mode: any): DisplayMode;
+    export function isDefined(mode: number | string): boolean;
+}
+
+export declare const EmptyField: Field<string>;
+
+export declare class EnabledChangedAction extends FieldActionBase {
+    constructor(executorFn: (field: FieldBase, supr: FieldActionExecute, newValue: boolean, oldValue: boolean) => void);
+    static get classIdentifier(): symbol;
+    execute(field: FieldBase, supr: FieldActionExecute, newValue: boolean, oldValue: boolean): void;
+}
+
+export declare class EnabledChangingAction extends FieldActionBase {
+    constructor(executorFn: (field: FieldBase, supr: FieldActionExecute, newValue: boolean, oldValue: boolean) => boolean);
+    static get classIdentifier(): symbol;
+    execute(field: FieldBase, supr: FieldActionExecute, newValue: boolean, oldValue: boolean): boolean;
+}
+
+export declare class ExecuteAction extends FieldActionBase {
+    constructor(executorFn: (field: FieldBase, supr: FieldActionExecute, params: any) => any);
+    static get classIdentifier(): symbol;
+    execute(field: FieldBase, supr: FieldActionExecute, params: any): any;
+}
+
+export declare class Field<T = any> extends FieldBase<T> {
+    protected _value: T;
+    protected _touched: boolean;
+    constructor(params?: Partial<IFieldConstructorParams<T>>);
+    /**
+     * 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.
+     */
+    protected init(params?: Partial<IFieldConstructorParams<T>>): void;
+    get value(): T;
+    set value(newValue: T);
+    get touched(): boolean;
+    set touched(touched: boolean);
+    clone(overrides?: Partial<IFieldConstructorParams<T>>): this;
+}
+
+export declare abstract class FieldActionBase {
+    static get classIdentifier(): symbol;
+    get classIdentifier(): symbol;
+    private readonly executorFn;
+    constructor(executorFn: ActionExecutor);
+    execute(field: FieldBase, supr: FieldActionExecute, ...params: any[]): any;
+    get eager(): boolean;
+    boundToField(field: FieldBase): void;
+    unregister(): void;
+}
+
+export declare type FieldActionExecute<T = any> = (field: FieldBase<T>, ...params: any[]) => any;
+
+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);
+    abstract clone(overrides?: Partial<IFieldConstructorParams<T>>): FieldBase<T>;
+    originalValue: T;
+    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;
+    fieldName?: string;
+    protected actions: ActionsMap;
+    private _visibility;
+    get visibility(): DisplayMode;
+    set visibility(newValue: DisplayMode);
+    private _enabled;
+    get enabled(): boolean;
+    set enabled(newValue: boolean);
+    validate(revalidate?: boolean): void;
+    get valid(): boolean;
+    get fullValue(): any;
+    get isChanged(): boolean;
+    registerAction(action: FieldActionBase): this;
+    triggerAction<T2 extends FieldActionBase>(actionClass: (abstract new (...args: any[]) => T2) & {
+        classIdentifier: symbol;
+    }, ...params: any[]): any;
+    clearValidators(): void;
+}
+
+export declare type FieldsToValues<T extends GenericFieldsInterface> = {
+    [K in keyof T]: T[K]['value'];
+};
+
+declare namespace Form {
+    export {
+        DisplayMode,
+        FieldActionBase,
+        ActionsMap,
+        EnabledChangedAction,
+        EnabledChangingAction,
+        ExecuteAction,
+        VisibilityChangedAction,
+        VisibilityChangingAction,
+        ValidChangedAction,
+        ValueChangedAction,
+        ListItemAddedAction,
+        ListItemRemovedAction,
+        Operator,
+        ConditionalStatementAction,
+        ConditionalVisibilityAction,
+        ConditionalEnabledAction,
+        ConditionalValueAction,
+        OperandType,
+        Statement,
+        ActionValue,
+        Action,
+        NullableAction,
+        MessagesWidget,
+        Field,
+        NullableField,
+        EmptyField,
+        IFieldConstructorActionsList,
+        IFieldConstructorParams,
+        AbortEventHandlingException,
+        FieldActionExecute,
+        FieldBase,
+        GenericFieldsInterface,
+        FieldsToValues,
+        GroupValue,
+        GroupValueInput,
+        Group,
+        NullableGroup,
+        ListValue,
+        List,
+        NullableList,
+        Validators,
+        buildErrorMessage,
+        isSimpleComponentDef,
+        isCallableFunction,
+        MdString,
+        SimpleComponentDef,
+        ClassType,
+        ClassTypes,
+        RenderContentNonCallable,
+        RenderContentCallable,
+        RenderContent,
+        RenderContentRef,
+        ValidationError,
+        ValidationErrorText,
+        ValidationErrorRenderContent,
+        RenderableValue,
+        ValidationFunctionResult,
+        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, FieldBase>;
+
+export declare class Group<T extends GenericFieldsInterface = GenericFieldsInterface> extends FieldBase<GroupValue<T>> {
+    private readonly _fields;
+    private _value;
+    private suppressNotifyValueChanged;
+    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(): 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<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[];
+}
+
+/**
+ * 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;
+    originalValue: T;
+    enabled: boolean;
+    visibility: DisplayMode;
+    touched: boolean;
+    errors: ValidationError[];
+} & IFieldConstructorActionsList;
+
+declare class InAllowedValues<T = any> extends Validator {
+    constructor(allowedValues: T[], message?: RenderContentRef);
+}
+
+export declare function isCallableFunction(msg?: RenderContentRef): msg is RenderContentCallable;
+
+/**
+ * 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 isSimpleComponentDef(msg?: RenderContentRef): msg is SimpleComponentDef;
+
+declare class LengthInRange<T = any> extends Validator {
+    constructor(minLength: number, maxLength: number, message?: RenderContentRef);
+}
+
+export declare class List<T extends GenericFieldsInterface = GenericFieldsInterface> extends FieldBase<ListValue> {
+    private _value;
+    private _itemTemplate?;
+    private _previousValue;
+    constructor(itemTemplate?: Group<T>, params?: Partial<IFieldConstructorParams<ListValue>>);
+    private processSetValueItem;
+    private setValueInternal;
+    get value(): ListValue;
+    set value(newValue: Record<string, any>[]);
+    get touched(): boolean;
+    set touched(touched: boolean);
+    clone(overrides?: Partial<IFieldConstructorParams<ListValue>>): List<T>;
+    notifyValueChanged(): void;
+    get valid(): boolean;
+    validate(revalidate?: boolean): void;
+    get(index: number): Group<T> | undefined;
+    push(item: any): number;
+    pop(): Group<T> | undefined;
+    remove(index: number): Group<T> | undefined;
+    insert(item: any, index: number): number;
+    clear(): void;
+}
+
+export declare class ListItemAddedAction extends FieldActionBase {
+    constructor(executorFn: (field: FieldBase, supr: FieldActionExecute, item: any, index: number) => void);
+    static get classIdentifier(): symbol;
+    execute(field: FieldBase, supr: FieldActionExecute, item: any, index: number): void;
+}
+
+export declare class ListItemRemovedAction extends FieldActionBase {
+    constructor(executorFn: (field: FieldBase, supr: FieldActionExecute, item: any, index: number) => void);
+    static get classIdentifier(): symbol;
+    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);
+}
+
+declare class MaxValue<T = any> extends Validator {
+    constructor(maxValue: T, message?: RenderContentRef);
+}
+
+/**
+ * Marks content for markdown rendering
+ */
+export declare class MdString extends String {
+    plugins?: any[];
+    options?: any;
+    constructor(value: string, options?: any, plugins?: any[]);
+}
+
+export declare const MessagesWidget: DefineComponent<Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+
+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;
+
+export declare type NullableGroup = Group | null;
+
+export declare type NullableList = List | null;
+
+export declare type OperandType = any | Statement | FieldBase;
+
+/**
+ * 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);
+}
+
+declare interface Props {
+    message: string | ValidationError[];
+    classes?: ClassTypes;
+}
+
+/**
+ * A value, renderable three different ways (plain text, markdown, component) - alias for ValidationErrorRenderContent
+ */
+export declare class RenderableValue extends ValidationErrorRenderContent {
+}
+
+/**
+ * Type for different renderable content formats: plain string, markdown, or custom component
+ */
+export declare type RenderContent = RenderContentNonCallable | RenderContentCallable;
+
+export declare type RenderContentCallable = () => RenderContentNonCallable;
+
+export declare type RenderContentNonCallable = string | MdString | SimpleComponentDef;
+
+/**
+ * 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);
+}
+
+/**
+ * Interface for custom component content definition
+ */
+export declare interface SimpleComponentDef {
+    componentName: string;
+    componentProps?: Record<any, any>;
+    componentVHtml?: string;
+}
+
+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<FieldBase>;
+}
+
+/**
+ * Base validation error class with component rendering capabilities
+ */
+export declare class ValidationError {
+    get componentName(): string;
+    get componentBindings(): {};
+    get componentBody(): string;
+    get extraClasses(): ClassTypes;
+}
+
+/**
+ * Validation error that supports multiple content types (plain text, markdown, component)
+ */
+export declare class ValidationErrorRenderContent extends ValidationError {
+    classes: ClassTypes;
+    private text;
+    private textType;
+    constructor(text: RenderContentRef, classes?: ClassTypes);
+    get resolvedText(): RenderContentNonCallable;
+    get getTextType(): "string" | "md" | "component";
+    get componentName(): string;
+    get componentBindings(): Record<any, any>;
+    get componentBody(): string;
+    get extraClasses(): ClassTypes;
+}
+
+/**
+ * Simple text-only ValidationError
+ */
+export declare class ValidationErrorText extends ValidationError {
+    text: string;
+    classes: ClassTypes;
+    constructor(text: string, classes?: ClassTypes);
+    get componentName(): string;
+    get componentBody(): string;
+    get extraClasses(): ClassTypes;
+}
+
+export declare type ValidationFunction<T = any> = (newValue: T, oldValue: T, field: FieldBase<T>) => ValidationFunctionResult | Promise<ValidationFunctionResult>;
+
+export declare type ValidationFunctionResult = 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 replacePlaceholdersFunction(text: RenderContentRef, replace: Record<string, any>): RenderContentRef;
+    protected replacePlaceholders(text: RenderContentRef, replace: Record<string, any>): RenderContentRef;
+}
+
+export declare namespace Validators {
+    export {
+        CompareTo,
+        InAllowedValues,
+        Required_2 as Required,
+        Pattern,
+        ValidationFunctionResult,
+        ValidationFunction,
+        Validator,
+        MinValue,
+        MaxValue,
+        ValueInRange,
+        MinLength,
+        MaxLength,
+        LengthInRange
+    }
+}
+
+export declare class ValidChangedAction extends FieldActionBase {
+    constructor(executorFn: (field: FieldBase, supr: FieldActionExecute, newValue: boolean, oldValue: boolean) => void);
+    static get classIdentifier(): symbol;
+    execute(field: FieldBase, supr: FieldActionExecute, newValue: boolean, oldValue: boolean): void;
+}
+
+export declare class ValueChangedAction<T = any> extends FieldActionBase {
+    constructor(executorFn: (field: FieldBase<T>, supr: FieldActionExecute<T>, newValue: T, oldValue: T) => void);
+    static get classIdentifier(): symbol;
+    execute(field: FieldBase<T>, supr: FieldActionExecute<T>, newValue: T, oldValue: T): void;
+}
+
+declare class ValueInRange<T = any> extends Validator {
+    constructor(minValue: T, maxValue: T, message?: RenderContentRef);
+}
+
+export declare class VisibilityChangedAction extends FieldActionBase {
+    constructor(executorFn: (field: FieldBase, supr: FieldActionExecute, newValue: DisplayMode, oldValue: DisplayMode) => void);
+    static get classIdentifier(): symbol;
+    execute(field: FieldBase, supr: FieldActionExecute, newValue: DisplayMode, oldValue: DisplayMode): void;
+}
+
+export declare class VisibilityChangingAction extends FieldActionBase {
+    constructor(executorFn: (field: FieldBase, supr: FieldActionExecute, newValue: DisplayMode, oldValue: DisplayMode) => DisplayMode);
+    static get classIdentifier(): symbol;
+    execute(field: FieldBase, supr: FieldActionExecute, newValue: DisplayMode, oldValue: DisplayMode): DisplayMode;
+}
+
+export { }