@bgroup/wise-form 1.0.1

package/src/models/base.ts

@@ -0,0 +1,164 @@
+import { ReactiveModel } from '@beyond-js/reactive/model';
+import type { WrappedFormModel } from './wrapper';
+import type { FormField } from './field';
+import { PendingPromise } from '../utils/pending-promise';
+import { FieldOrAlias } from './types/callbacks';
+import { IFormModelProps } from './types/model';
+import { IBaseWiseModel } from './types/base-wise-model';
+
+export class BaseWiseModel extends ReactiveModel<IBaseWiseModel> {
+	#settings;
+	get settings() {
+		return this.#settings;
+	}
+
+	set settings(value) {
+		this.#settings = value;
+	}
+
+	#callbacks: Record<string, (...args) => void> = {};
+	get callbacks() {
+		return this.#callbacks;
+	}
+
+	set callbacks(value) {
+		this.#callbacks = value;
+	}
+
+	#initialValues: Record<string, string> = {};
+	get originalValues() {
+		return this.#initialValues;
+	}
+
+	get name() {
+		return this.#settings.name;
+	}
+	get template() {
+		return this.#settings.template;
+	}
+
+	#wrappers: Map<string, WrappedFormModel> = new Map();
+	get wrappers() {
+		return this.#wrappers;
+	}
+
+	set wrappers(value) {
+		this.#wrappers = value;
+	}
+
+	#fields: Map<string, FormField | WrappedFormModel> = new Map();
+	get fields() {
+		return this.#fields;
+	}
+	get values() {
+		const data: Record<string, any> = {};
+		this.#fields.forEach((field, key) => {
+			// FormField has value, WrappedFormModel doesn't
+			if ('value' in field) {
+				data[key] = (field as FormField).value;
+			}
+		});
+		return data;
+	}
+
+	#specs;
+	get specs() {
+		return this.#specs;
+	}
+	set specs(value) {
+		this.#specs = value;
+	}
+
+	#params = {};
+
+	protected loadedPromise: PendingPromise<boolean> = new PendingPromise();
+	protected childWrappersReady: number = 0;
+
+	constructor(settings: IFormModelProps, reactiveProps?) {
+		super(settings);
+
+		this.#params = settings.params ?? {};
+		this.#settings = settings;
+		this.#callbacks = settings.callbacks ?? {};
+	}
+
+	/**
+	 * Sets the value of a specified field within the wrapper. If the field exists, its value is updated.
+	 * @param {string} name - The name of the field to update.
+	 * @param {any} value - The new value for the field.
+	 */
+	setField(name: string, value) {
+		if (!this.getField(name)) {
+			console.error('Field not found', name, this.settings.name, this.fields.keys());
+			return;
+		}
+
+		const field = this.getField(this.getFieldName(name));
+		field.setValue(value);
+	}
+
+	/**
+	 * Retrieves a field or nested wrapper by name. Supports dot notation for accessing deeply nested fields.
+	 * @param {string} name - The name of the field or nested wrapper to retrieve.
+	 * @returns {FormField | WrappedFormModel | undefined} The requested instance, or undefined if not found.
+	 */
+	getField(name: string) {
+		if (!name) return console.warn('You need to provide a name to get a field in form ', this.#settings.name);
+
+		if (!name.includes('.')) {
+			let field = this.#fields.get(name);
+
+			if (!field) {
+				this.#wrappers.forEach(item => {
+					const foundField = item.getField(name);
+					if (foundField) field = foundField;
+				});
+			}
+			return field;
+		}
+
+		const [wrapperName, ...others] = name.split('.');
+		const currentWrapper = this.#wrappers.get(wrapperName);
+
+		const otherWrapper = others.join('.');
+		return currentWrapper.getField(otherWrapper);
+	}
+
+	/**
+	 * Extracts the field name from a FieldOrAlias type. The input can either be a string directly representing
+	 * the field name or an object where the key is the field name and the value is an alias.
+	 * This function returns the field name if it is a string, or the first key (field name) if it is an object,
+	 * assuming the object contains exactly one key-value pair.
+	 *
+	 * @param {FieldOrAlias} field - The field identifier which could be a string or an object with one key-value pair.
+	 * @returns {string} - The field name extracted from the input.
+	 * @throws {Error} - Throws an error if the input is an object that does not contain exactly one key.
+	 */
+	getFieldName(field: FieldOrAlias): string {
+		if (typeof field === 'object' && Object.keys(field).length !== 1) {
+			throw new Error('Field object must contain exactly one key.');
+		}
+
+		if (typeof field === 'string') {
+			return field;
+		}
+
+		return Object.keys(field)[0];
+	}
+
+	/**
+	 * Clears all fields within the wrapper, resetting their values to their initial state.
+	 */
+	clear = () => {
+		this.fields.forEach(field => field.clear());
+		this.triggerEvent();
+		this.triggerEvent('clear');
+	};
+
+	getParams(param) {
+		return this.#params[param];
+	}
+
+
+}
+

package/src/models/callback-manager.ts

@@ -0,0 +1,102 @@
+import type { FormField } from './field';
+import type { FormModel } from './model';
+import { CallbackFunction, ICallbackProps } from './types/callbacks';
+
+export class CallbackManager {
+    #field: FormField;
+    #model: FormModel;
+    #callbacks: CallbackFunction[] = [];
+    #listeners = [];
+    constructor(model, field) {
+        this.#field = field;
+        this.#model = model;
+        this.#callbacks = model.callbacks;
+        this.initialize();
+    }
+
+    initialize() {
+        const instance = this.#field;
+        const checkField = async (settings) => {
+            const dependency = this.#model.getField(
+                this.#model.getFieldName(settings.field)
+            );
+            await dependency.isReady;
+            const required = ['field', 'callback'];
+            required.forEach((prop) => {
+                if (!settings[prop])
+                    throw new Error(`${settings?.field} is missing ${prop}`);
+            });
+
+            if (!dependency)
+                throw new Error(`${settings?.field} is not a registered field`);
+
+            if (!this.#callbacks[settings.callback]) {
+                throw new Error(
+                    `${settings.callback} is not  a registered callback ${settings.name}`
+                );
+            }
+
+            // saved in listener array to be able to remove the listener if is required.
+            const event = settings.event || 'value.change';
+            const caller = () => this.executeCallback(settings);
+            this.#listeners.push(caller);
+            dependency.on(event, caller);
+
+            //callback({ dependency, settings, field: instance, form: this });
+        };
+
+        instance?.specs?.dependentOn.forEach(checkField);
+    }
+
+    executeCallback = async (settings) => {
+        const params: ICallbackProps = {
+            ...settings,
+            form: this.#model,
+            field: this.#field,
+           
+            settings,
+        };
+        if (!settings) {
+            console.warn('the field does not have dependentOn settings');
+        }
+        const callback: CallbackFunction = this.#callbacks[settings.callback];
+
+        const dependency = this.#model.getField(
+            this.#model.getFieldName(settings.field)
+        );
+        await dependency.isReady;
+        const fields = { [dependency.name]: dependency };
+        if (settings.hasOwnProperty('fields')) {
+            for (const field of settings.fields) {
+                const instance = this.#model.getField(
+                    this.#model.getFieldName(field)
+                );
+                if (instance) await instance.isReady;
+                const propName =
+                    typeof field === 'string' ? field : field.alias;
+                fields[propName] = instance;
+            }
+
+            params.fields = fields;
+        }
+        params.dependency = dependency;
+
+        //global wiseForm params
+        if (settings.hasOwnProperty('params')) {
+            const specs = {};
+            settings.params.forEach((param) => {
+                if (!this.#model?.getParams(param)) {
+                    console.warn(
+                        `param ${param} is not registered in the form`
+                    );
+                    return;
+                }
+
+                specs[param] = this.#model.getParams(param);
+            });
+            params.specs = specs;
+        }
+        callback(params);
+    };
+}
+

package/src/models/field.ts

@@ -0,0 +1,426 @@
+import { ReactiveModel } from '@beyond-js/reactive/model';
+import type { WrappedFormModel } from './wrapper';
+import { FormModel } from './model';
+import { IFormField, IFormFieldProps } from './types/form-field';
+import { IDisabled } from './types/disabled';
+
+/**
+ * Represents a single form field within a `FormModel` or `WrappedFormModel`, providing mechanisms for data binding, validation, and interaction.
+ * This class extends `ReactiveModel` to enable reactive updates and interactions within the form's lifecycle.
+ *
+ * @extends ReactiveModel<IFormField>
+ */
+export class FormField extends ReactiveModel<IFormField> {
+    // The parent model, either FormModel or WrappedFormModel, containing this field.
+    #parent: WrappedFormModel | FormModel;
+    get parent() {
+        return this.#parent;
+    }
+
+    #NATIVE_ACTIONS = ['hide', 'disable', 'enable', 'show', 'reset'];
+    #EVENTS = ['onClick', 'onChange', 'onKeyup'];
+    setEvents(events: string[]) {
+        this.#EVENTS.concat(events);
+    }
+    #isReady: boolean = false;
+    // Can be a boolean or an object specifying dynamic disablingvas logic based on other fields' values.
+    #disabled: boolean | IDisabled = false;
+
+    /**
+     * Evaluates and returns the disabled state of the field. If `#disabled` is an object, it checks the specified fields' values to determine the disabled state dynamically.
+     * @returns {boolean} The disabled state of the field.
+     */
+    get disabled() {
+        if (typeof this.#disabled !== 'object' || !this.#disabled?.fields)
+            return this.#disabled;
+
+        const validate = (field) => {
+            if (typeof field !== 'object')
+                return !this.#parent.form.getField(field).value;
+            const { name, value } = field;
+            const fieldInstance = this.#parent.getField(name);
+            if (!fieldInstance) return false;
+            if (field.hasOwnProperty('condition')) {
+                const compare = this.evaluations[field.condition](
+                    fieldInstance.value,
+                    field.value
+                );
+                return compare;
+            }
+            const { value: fieldValue } = fieldInstance;
+            return value !== fieldValue;
+        };
+
+        return this.#disabled.fields.some(validate);
+    }
+
+    set disabled(value) {
+        if (value === this.#disabled) return;
+        this.#disabled = value;
+        this.triggerEvent();
+    }
+
+    // Field specifications including its type, validation rules, and other metadata.
+    #specs: Record<string, any>;
+    get specs() {
+        return this.#specs;
+    }
+
+    get attributes() {
+        const props = this.getProperties();
+        return {
+            ...props,
+            disabled: this.#disabled,
+        };
+    }
+
+    #value: string;
+    get value() {
+        return this.#value;
+    }
+
+    set value(value) {
+        this.setValue(value);
+    }
+
+    // Tracks other fields this field listens to for changes, enabling reactive behavior and allowing the cleanup of event listeners.
+    #listeningItems = new Map();
+
+    /**
+     * Constructs a FormField instance with specified properties and parent form model.
+     * @param {Object} params - Construction parameters including the parent form model and field specifications.
+     */
+    constructor({ parent, specs }: { parent; specs: IFormFieldProps }) {
+        let { properties, disabled, ...props } = specs;
+        super({
+            ...props,
+            properties: [
+                'name',
+                'type',
+                'placeholder',
+                'required',
+                'label',
+                'variant',
+                'options',
+                'className',
+                'checked',
+                'id',
+                'icon',
+                'hidden',
+
+                ...properties,
+            ],
+        });
+
+        (this as any).__instanceID = `${specs.name}.${this.generateRandomNumber()}`;
+
+        this.#specs = specs;
+        this.#parent = parent;
+        (this as any).__instance = Math.random();
+
+        const toSet: Record<string, any> = {};
+        /**
+         * @todo:  review this code
+         */
+        Object.keys(props).forEach((key) => {
+            if (key === 'properties') return;
+
+            if (
+                typeof props[key] === 'string' &&
+                props[key]?.includes('state:')
+            ) {
+                const state = props[key].split('state:')[1];
+                if (state === 'create' && !this.#parent.form.update) {
+                    props[key] = true;
+                }
+            }
+            toSet[key] = props[key];
+        });
+        // this.#disabled = disabled;
+        // this.set(toSet);
+
+        this.set(specs);
+    }
+
+    getProperties() {
+        const properties = super.getProperties();
+        return { ...properties, value: this.#value };
+    }
+
+    /**
+     *  This method is used to set the value property of the field and fire the value.change event
+     *
+     * @param value
+     * @returns
+     */
+    setValue(value: string) {
+        if (value === this.value) return;
+        this.#value = value;
+        this.trigger('change');
+        this.trigger('value.change', this);
+    }
+
+    generateRandomNumber = () => {
+        return Math.floor(Math.random() * (1000000 - 10000 + 1)) + 10000;
+    };
+
+    /**
+     * Performs initial setup based on the field's specifications, setting up validation, default values, and any specified dynamic behavior.
+     */
+    initialize = () => {
+        this.checkSettings(this.#specs);
+        this.on('change', this.listenerEvents);
+        // this.on('value.change', this.listenerEvents);
+    };
+
+    /**
+     * Resets the field to its initial value and state, including resetting the disabled state if it's statically defined.
+     */
+    clear = () => {
+        // Get initial values from specs or use empty object
+        const initValues = this.#specs || {};
+        this.set(initValues);
+        if (initValues.hasOwnProperty('disabled'))
+            this.disabled = initValues.disabled;
+        this.triggerEvent('clear');
+    };
+
+    /**
+     * Listens to changes in sibling fields (specified in dynamic disabling logic) and updates its state accordingly.
+     */
+    #listenSiblings = () => {
+        this.triggerEvent('change');
+        this.triggerEvent();
+        this.triggerEvent('value.change');
+    };
+
+    /**
+     * Checks and applies the field's settings, particularly for dynamic disabling, establishing listeners on related fields as necessary.
+     * @param {Object} props - The field's properties and settings to check and apply.
+     */
+    checkSettings(props) {
+        if (props.hasOwnProperty('disabled')) {
+            if (typeof props.disabled === 'boolean') {
+                this.#disabled = props.disabled;
+                return;
+            }
+
+            if (typeof props.disabled !== 'object') {
+                throw new Error(
+                    `The disabled property of the field ${props.name} must be a boolean or an object`
+                );
+            }
+            if (!props.disabled.fields && !props.disabled.mode) {
+                throw new Error(
+                    `The disabled property of the field ${props.name} must have a fields property or a mode defined`
+                );
+            }
+
+            if (props.disabled.mode) {
+                // posible modes : create, update;
+                this.#disabled = this.#parent.form.mode === props.disabled.mode;
+                return;
+            }
+
+            let allValid;
+            props.disabled.fields.forEach((item) => {
+                const name = typeof item === 'string' ? item : item.name;
+
+                const instance = this.#parent.form.getField(name);
+                allValid = instance;
+                if (!allValid) return;
+                instance.on('change', this.#listenSiblings);
+                instance.on('value.change', this.#listenSiblings);
+                this.#listeningItems.set(name, {
+                    item: instance,
+                    listener: this.#listenSiblings,
+                });
+            });
+
+            if (!allValid) {
+                const fieldName = this.getProperties().name || 'unknown';
+                throw new Error(
+                    `the field ${allValid} does not exist in the form ${
+                        (this.#parent as any).name
+                    }, field passed in invalid settings of field "${fieldName}"`
+                );
+            }
+            this.#disabled = props.disabled;
+        }
+    }
+
+    /**
+     * En este metodo se recorre el objeto asociado al evento y ejecuta cada una de las acciones asociadas
+     * como las acciones nativas del FormModel (HIDE, SHOW, DISABLE, ENABLE), hace el seteo de propiedades
+     * en caso de recibir field y ejecuta las callbacks asociadas
+     * @param actions objeto  con las acciones que se van a realizar al ejecutarse el evento asociado
+     * @returns
+     */
+    async #executeEvent(actions) {
+        if (typeof actions !== 'object' || Array.isArray(actions)) return;
+
+        const formModel = this.#parent.form;
+
+        const sortedKeys = Object.keys(actions).sort(
+            (a, b) => actions[a]?.__order - actions[b]?.__order
+        );
+
+        for (let action of sortedKeys) {
+            if (action === 'fields') {
+                for (let fieldName in actions[action]) {
+                    const field = this.#parent.form.getField(fieldName);
+
+                    if (!field) continue;
+                    await field.isReady;
+                    field.set(actions[action][fieldName]);
+                }
+                continue;
+            }
+            if (formModel.callbacks.hasOwnProperty(action)) {
+                formModel.callbacks[action]({
+                    ...actions[action],
+                    form: formModel,
+                });
+                continue;
+            }
+
+            if (
+                this.#NATIVE_ACTIONS.includes(action) &&
+                formModel.hasOwnProperty(action)
+            ) {
+                formModel[action](actions[action].target);
+            }
+        }
+    }
+
+    /**
+     * Busca el evento configurado en el field
+     * @param item objeto que tiene el evento
+     * @returns
+     */
+    #getEvent(item) {
+        let event: string;
+        const keys = Object.keys(item);
+        keys.forEach((key) => {
+            if (event) return;
+            if (this.#EVENTS.includes(key)) event = key;
+        });
+        return event;
+    }
+
+    /**
+     * Metodo para identificar si es field con multiples eventos configurados o solo es un evento configurado
+     * hace la busqueda del evento lanzado al haber multiples
+     * @returns
+     */
+    listenerEvents = (event2) => {
+        if (!this.#isReady) {
+            this.#isReady = true;
+            return;
+        }
+
+        if (!this.specs?.events) {
+            const event = this.#getEvent(this.specs);
+            if (!event) return;
+            this.#executeEvent(this.specs[event]);
+            return;
+        }
+
+        const event = this.#getEvent(this.specs.events);
+        if (!event) return;
+        const item = this.specs.events[event].hasOwnProperty(this.value)
+            ? this.specs.events[event][this.value]
+            : null;
+        if (!item) return;
+        this.#executeEvent(item);
+    };
+
+    /**
+     * Cleans up any established listeners and internal state when the field is removed or the form is reset, ensuring no memory leaks or stale data.
+     */
+    cleanUp() {
+        this.#listeningItems.forEach(({ item, listener }) =>
+            item.off('change', listener)
+        );
+        // todo: remove all events
+    }
+
+    /**
+     * The `set` method sets one or more properties on the model.
+     *
+     *
+     * This method overwrites the original reactiveModel set to pass the object as param
+     * when the change event is fired.
+     * Eventually this method will be removed and the original set method will be used, but
+     * it requires an upgrade in the reactive model package.
+     * @param {keyof ReactiveModelPublic<T>} property - The name of the property to set.
+     * @param {*} value - The value to set the property to.
+     * @returns {void}
+     */
+    set(properties: Partial<IFormField>): any {
+        let updated = false;
+        try {
+            Object.keys(properties).forEach((prop) => {
+                const currentProperties = Object.keys(this.getProperties());
+                if (!currentProperties || !currentProperties.includes(prop))
+                    return;
+
+                const sameObject =
+                    typeof properties[prop] === 'object' &&
+                    JSON.stringify(properties[prop]) ===
+                        JSON.stringify(this[prop]);
+
+                if (this[prop] === properties[prop] || sameObject) return;
+                const descriptor = Object.getOwnPropertyDescriptor(this, prop);
+
+                if (descriptor?.set) return;
+                this[prop] = properties[prop];
+                updated = true;
+            });
+        } catch (e) {
+            console.error(`Error setting properties:`, e);
+            throw new Error(`Error setting properties: ${e}`);
+        } finally {
+            if (updated) this.trigger('change', this);
+        }
+    }
+
+    hide = () => {
+        const className = this.getProperties().className || '';
+        const isHidden = className.includes('hidden');
+        const cls = isHidden ? className : `${className} hidden`;
+        if (cls !== className) this.set({ className: cls });
+    };
+
+    show = () => {
+        const className = this.getProperties().className || '';
+        const isHidden = className.includes('hidden');
+        const cls = isHidden
+            ? className.replace(/\bhidden\b/g, '').trim()
+            : className;
+        if (cls !== className) this.set({ className: cls });
+    };
+
+    private evaluations: Record<
+        string,
+        (value: any, comparisonValue?: any) => boolean
+    > = {
+        equal: (value, comparisonValue) => value == comparisonValue,
+        lower: (value, comparisonValue) =>
+            Number(value) < Number(comparisonValue),
+        upper: (value, comparisonValue) =>
+            Number(value) > Number(comparisonValue),
+        between: (value, [min, max]) => {
+            const numValue = Number(value);
+            return numValue >= Number(min) && numValue <= Number(max);
+        },
+        different: (value, comparisonValue) => value != comparisonValue,
+        hasValue: (value) => ![undefined, null, '', false].includes(value),
+        empty: (value) => [undefined, null, ''].includes(value),
+        lessOrEqual: (value, comparisonValue) =>
+            Number(value) <= Number(comparisonValue),
+        greaterOrEqual: (value, comparisonValue) =>
+            Number(value) >= Number(comparisonValue),
+    };
+}
+

package/src/models/index.ts

@@ -0,0 +1,14 @@
+export { FormModel } from './model';
+export { FormField } from './field';
+export { WrappedFormModel } from './wrapper';
+export { BaseWiseModel } from './base';
+export { CallbackManager } from './callback-manager';
+export { PluginsManager } from './plugins';
+
+export type { IFormField, IFormFieldProps } from './types/form-field';
+export type { IFormModelProps } from './types/model';
+export type { IWrapperFormModelProps } from './types/wrapped-form-model-props';
+export type { IDisabled, TDisabledSettings } from './types/disabled';
+export type { ICallbackProps, CallbackFunction, FieldOrAlias } from './types/callbacks';
+export type { IPluginForm, IPluginFormSpecs } from './types/plugins';
+