native-document 1.0.164 → 1.0.166

package/src/components/form/FormControl.js

@@ -1,10 +1,30 @@
-import {debounce} from "../../core/utils/helpers";
-import HasEventEmitter from "../../core/utils/HasEventEmitter";
-import { $ } from "../../core/data/Observable";
-import Validator from "../../core/utils/validator";
-import NativeDocumentError from "../../../src/core/errors/NativeDocumentError";
-import BaseComponent from "../BaseComponent";
-
+import {debounce} from '../../core/utils/helpers';
+import HasEventEmitter from '../../core/utils/HasEventEmitter';
+import { $ } from '../../core/data/Observable';
+import Validator from '../../core/utils/validator';
+import NativeDocumentError from '../../../src/core/errors/NativeDocumentError';
+import BaseComponent from '../BaseComponent';
+
+/**
+ * Top-level form controller. Manages field registration, layout, validation, submission, error display, and reactive value tracking.
+ *
+ *
+ * @example
+ * const form = new FormControl()
+ *     .fields((form) => {
+ *         new StringField('email').label('Email').required().email();
+ *         new PasswordField('password').label('Password').required().strong();
+ *     })
+ *     .layout((fields) => VStack(fields.email, fields.password))
+ *     .onSubmit(async (values, form) => {
+ *         await api.login(values);
+ *     })
+ *     .onError((errors) => console.log(errors))
+ *     .errorsMode('inline');
+ *
+ * @constructor
+ * @param {GlobalAttributes} [props]
+ */
 export default function FormControl(props) {
     if(!(this instanceof FormControl)) {
         return new FormControl(props);
@@ -25,16 +45,37 @@ export default function FormControl(props) {
         errors:          $(null),
         isDirty:         $(false),
         isValid:         $(false),
-        props
+        props,
     };
 }
 
 FormControl.defaultTemplate = null;
 
+/**
+ * Registers the render template for FormControl.
+ * @param {(description: {
+ *     data: *|null,
+ *     fieldBuilder: ((form: FormControl) => void)|null,
+ *     layout: ((fields: Record<string, Field>) => NdChild)|null,
+ *     errorsMode: 'dispatch'|'inline'|'summary'|'none',
+ *     errorsPosition: 'top'|'bottom',
+ *     errorsMapper: Record<string, string>|null,
+ *     renderErrors: ((errors: Record<string, string[]>) => NdChild)|null,
+ *     submitting: Observable<boolean>,
+ *     errors: Observable<Record<string, string[]>|null>,
+ *     isDirty: Observable<boolean>,
+ *     isValid: Observable<boolean>,
+ *     props: GlobalAttributes,
+ * }, instance: FormControl) => NdChild} template
+ */
 FormControl.use = function(template) {
     FormControl.defaultTemplate = template;
 };
 
+/**
+ * @param {GlobalAttributes} [props]
+ * @returns {FormControl}
+ */
 FormControl.create = function(props) {
     return new FormControl(props);
 };
@@ -43,17 +84,21 @@ BaseComponent.extends(FormControl);
 BaseComponent.use(FormControl, HasEventEmitter);
 
 Object.defineProperty(FormControl.prototype, 'isDirty', {
-    get() { return this.$description.isDirty; }
+    get() { return this.$description.isDirty; },
 });
 
 Object.defineProperty(FormControl.prototype, 'isValid', {
-    get() { return this.$description.isValid; }
+    get() { return this.$description.isValid; },
 });
 
 Object.defineProperty(FormControl.prototype, 'submitting', {
-    get() { return this.$description.submitting; }
+    get() { return this.$description.submitting; },
 });
 
+/**
+ * @param {(form: FormControl) => void} fieldBuilder
+ * @returns {this}
+ */
 FormControl.prototype.fields = function(fieldBuilder) {
     if(typeof fieldBuilder !== 'function') {
         throw new NativeDocumentError('FormControl.fields() expects a function');
@@ -92,6 +137,10 @@ FormControl.prototype.$registerField = function(name, field) {
     field.value(dataSource);
 };
 
+/**
+ * @param {string} fieldName
+ * @returns {Field|null}
+ */
 FormControl.prototype.get = function(fieldName) {
     const field = this.$fields[fieldName];
     if(!field) {
@@ -100,6 +149,10 @@ FormControl.prototype.get = function(fieldName) {
     return field;
 };
 
+/**
+ * @param {(fields: Record<string, Field>) => NdChild} layoutCallback
+ * @returns {this}
+ */
 FormControl.prototype.layout = function(layoutCallback) {
     if(typeof layoutCallback !== 'function') {
         throw new NativeDocumentError('FormControl.layout() expects a function');
@@ -108,43 +161,72 @@ FormControl.prototype.layout = function(layoutCallback) {
     return this;
 };
 
+/**
+ * @param {'inline'|'summary'|'none'} mode
+ * @returns {this}
+ */
 FormControl.prototype.errorsMode = function(mode) {
     this.$description.errorsMode = mode;
     return this;
 };
 
+/**
+ * @param {Record<string, string>|null} [mapper=null]
+ * @returns {this}
+ */
 FormControl.prototype.dispatchErrors = function(mapper = null) {
     this.$description.errorsMode   = this.$description.errorsMode === 'summary' ? 'both' : 'dispatch';
     this.$description.errorsMapper = mapper;
     return this;
 };
 
+/**
+ * @returns {Record<string, string[]>}
+ */
 FormControl.prototype.summarizeErrors = function() {
     this.$description.errorsMode = this.$description.errorsMode === 'dispatch' ? 'both' : 'summary';
     return this;
 };
 
+/**
+ * @param {Record<string, string>|null} [mapper=null]
+ * @returns {this}
+ */
 FormControl.prototype.dispatchAndSummarize = function(mapper = null) {
     this.$description.errorsMode   = 'both';
     this.$description.errorsMapper = mapper;
     return this;
 };
 
+/**
+ * @param {'top'|'bottom'} position
+ * @returns {this}
+ */
 FormControl.prototype.errorsPosition = function(position) {
     this.$description.errorsPosition = position;
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 FormControl.prototype.errorsAtTop = function() {
     this.$description.errorsPosition = 'top';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 FormControl.prototype.errorsAtBottom = function() {
     this.$description.errorsPosition = 'bottom';
     return this;
 };
 
+/**
+ * @param {(errors: Record<string, string[]>) => NdChild} renderFn
+ * @returns {this}
+ */
 FormControl.prototype.renderErrors = function(renderFn) {
     this.$description.renderErrors = renderFn;
     return this;
@@ -169,6 +251,9 @@ FormControl.prototype.$dispatchServerErrors = function(error) {
     }
 };
 
+/**
+ * @returns {this}
+ */
 FormControl.prototype.reset = function() {
     this.$description.isDirty.set(false);
     this.$description.isValid.set(false);
@@ -184,19 +269,31 @@ FormControl.prototype.reset = function() {
     return this;
 };
 
+/**
+ * @param {string} name
+ * @returns {this}
+ */
 FormControl.prototype.resetField = function(name) {
     const field = this.$fields[name];
     if(!field) {
         return this;
     }
-    field.reset()
+    field.reset();
     return this;
 };
 
+/**
+ * @param {string} event
+ * @returns {this}
+ */
 FormControl.prototype.submit = function(event) {
     return this.$handleSubmit(event);
 };
 
+/**
+ * @param {...string} fieldNames
+ * @returns {this}
+ */
 FormControl.prototype.trigger = function(...fieldNames) {
     const values = this.values();
     fieldNames.forEach(name => {
@@ -205,6 +302,10 @@ FormControl.prototype.trigger = function(...fieldNames) {
     return this;
 };
 
+/**
+ * @param {string|null} [fieldName=null]
+ * @returns {this}
+ */
 FormControl.prototype.disable = function(fieldName = null) {
     if(fieldName) {
         this.$fields[fieldName]?.disabled?.(true);
@@ -217,6 +318,10 @@ FormControl.prototype.disable = function(fieldName = null) {
     return this;
 };
 
+/**
+ * @param {string|null} [fieldName=null]
+ * @returns {this}
+ */
 FormControl.prototype.enable = function(fieldName = null) {
     if(fieldName) {
         this.$fields[fieldName]?.disabled?.(false);
@@ -229,6 +334,9 @@ FormControl.prototype.enable = function(fieldName = null) {
     return this;
 };
 
+/**
+ * @returns {Record<string, *>}
+ */
 FormControl.prototype.values = function() {
     const values = {};
     for(const [name, field] of Object.entries(this.$fields)) {
@@ -237,6 +345,11 @@ FormControl.prototype.values = function() {
     return values;
 };
 
+/**
+ * @param {string} fieldName
+ * @param {(value: *, field: Field) => void} handler
+ * @returns {this}
+ */
 FormControl.prototype.watch = function(fieldName, handler) {
     const field = this.$fields[fieldName];
     if(!field) {
@@ -300,11 +413,19 @@ FormControl.prototype.$handleSubmit = async function(event) {
     }
 };
 
+/**
+ * @param {(values: Record<string, *>, form: FormControl) => void|Promise<void>} callback
+ * @returns {this}
+ */
 FormControl.prototype.onSubmit = function(callback) {
     this.on('submit', callback);
     return this;
 };
 
+/**
+ * @param {Function} callback
+ * @returns {this}
+ */
 FormControl.prototype.onPreventSubmit = function(callback) {
     this.on('submit', function(event) {
         event.preventDefault();
@@ -313,25 +434,47 @@ FormControl.prototype.onPreventSubmit = function(callback) {
     return this;
 };
 
-FormControl.prototype.onDebouncedSubmit = function(callback, delay = 300) {
+/**
+ * @param {(values: Record<string, *>) => void} callback
+ * @param {number} [delay=300]
+ * @returns {this}
+ */
+FormControl.prototype.onDebouncedSubmit = function(callback, delay = 300){
     return this.onSubmit(debounce(callback.bind(this), delay));
 };
 
+/**
+ * @param {(values: Record<string, *>) => void} callback
+ * @returns {this}
+ */
 FormControl.prototype.onSuccess = function(callback) {
     this.on('success', callback);
     return this;
 };
 
+/**
+ * @param {(errors: Record<string, string[]>) => void} callback
+ * @returns {this}
+ */
 FormControl.prototype.onError = function(callback) {
     this.on('error', callback);
     return this;
 };
 
+
+/**
+ * @param {Function} callback
+ * @returns {this}
+ */
 FormControl.prototype.onChange = function(callback) {
     this.on('change', callback);
     return this;
 };
 
+/**
+ * @param {Function} callback
+ * @returns {this}
+ */
 FormControl.prototype.onReset = function(callback) {
     this.on('reset', callback);
     return this;

package/src/components/form/field/Field.js

@@ -1,9 +1,27 @@
-import { $ } from "../../../core/data/Observable";
-import Validator from "../../../core/utils/validator";
-import BaseComponent from "../../BaseComponent";
-import HasEventEmitter from "../../../core/utils/HasEventEmitter";
-import HasValidation from "../../$traits/has-validation/HasValidation";
-
+import { $ } from '../../../core/data/Observable';
+import Validator from '../../../core/utils/validator';
+import BaseComponent from '../../BaseComponent';
+import HasEventEmitter from '../../../core/utils/HasEventEmitter';
+import HasValidation from '../../$traits/has-validation/HasValidation';
+
+/**
+ * Base form field with label, hint, placeholder, validation rules, clearable state, and reactive value binding. Extended by all typed field variants.
+ *
+ *
+ * @example
+ * const field = new Field('username', 'text')
+ *     .label(Span('Username'))
+ *     .placeholder('Enter your username')
+ *     .required('Username is required')
+ *     .minLength(3)
+ *     .model(usernameObs)
+ *     .clearable(true);
+ *
+ * @constructor
+ * @param {string} name
+ * @param {string} [type]
+ * @param {GlobalAttributes} [props]
+ */
 export default function Field(name, type, props) {
     if(!(this instanceof Field)) {
         return new Field(name, type, props);
@@ -36,7 +54,7 @@ export default function Field(name, type, props) {
             label:   null,
             input:   null,
             error:   null,
-            hint:    null
+            hint:    null,
         },
         render:          null,
         clearButtonIcon: null,
@@ -44,7 +62,7 @@ export default function Field(name, type, props) {
         isDirty:  $(false),
         isTouched:  $(false),
         slots: {},
-        props
+        props,
     };
 
     this.$description.errors.intercept((nextValue) => nextValue === null ? [] : nextValue);
@@ -55,6 +73,32 @@ BaseComponent.extends(Field);
 BaseComponent.use(Field, HasEventEmitter);
 BaseComponent.use(Field, HasValidation);
 
+/**
+ * Registers the render template for Field.
+ * @param {(description: {
+ *     name: string,
+ *     type: string,
+ *     key: string,
+ *     label: NdChild|null,
+ *     placeholder: NdChild|null,
+ *     help: NdChild|null,
+ *     defaultValue: *,
+ *     disabled: boolean|Observable<boolean>,
+ *     readonly: boolean|Observable<boolean>,
+ *     rules: Array<{ fn: Function, params: *, message: string }>,
+ *     clearErrorOn: string,
+ *     validateOn: string,
+ *     value: Observable<*>|null,
+ *     clearable: boolean|Observable<boolean>|null,
+ *     hasErrors: Observable<boolean>,
+ *     errors: Observable<string[]>,
+ *     showErrors: Observable<boolean>,
+ *     render: ((desc: *, instance: Field) => NdChild)|null,
+ *     clearButtonIcon: NdChild|null,
+ *     focus: Observable<boolean>,
+ *     isDirty: Observable<boolean>,
+ * }, instance: Field) => NdChild} template
+ */
 Field.use = function(template) {
     Field.defaultTemplate = template;
 };
@@ -67,20 +111,35 @@ Field.prototype.$model = function() {
     return this.$description.value || this.$description.checked;
 };
 
+/**
+ * @param {*} forceValue
+ * @returns {void}
+ */
 Field.prototype.forceShowErrors = function(forceValue) {
     this.$description.showErrors.intercept(() => forceValue);
-}
+};
 
+/**
+ * @param {string} key
+ * @returns {this}
+ */
 Field.prototype.key = function(key) {
     this.$description.key = key;
     return this;
 };
 
+/**
+ * @param {string} suffix
+ * @returns {this}
+ */
 Field.prototype.suffix = function(suffix) {
     this.$description.suffix = suffix;
     return this;
 };
 
+/**
+ * @returns {HTMLElement|DocumentFragment}
+ */
 Field.prototype.field = function() {
     if(!this.$element) {
         this.$element = this.toNdElement();
@@ -89,6 +148,10 @@ Field.prototype.field = function() {
 };
 Field.prototype.node = Field.prototype.field;
 
+/**
+ * @param {Function} callback
+ * @returns {this}
+ */
 Field.prototype.input = function(callback) {
     if(!this.$input) {
         this.field();
@@ -97,6 +160,10 @@ Field.prototype.input = function(callback) {
     return this;
 };
 
+/**
+ * @param {Observable<*>} observable
+ * @returns {this}
+ */
 Field.prototype.model = function(observable) {
     this.$description.value        = observable;
     this.$description.initialValue = Validator.isObservable(observable)
@@ -107,6 +174,10 @@ Field.prototype.model = function(observable) {
 
 Field.prototype.bind = Field.prototype.model;
 
+/**
+ * @param {Observable<string[]>} errors
+ * @returns {this}
+ */
 Field.prototype.errors = function(errors) {
     if(!Validator.isObservable(errors)) {
         throw new Error('Errors must be an observable');
@@ -115,51 +186,90 @@ Field.prototype.errors = function(errors) {
     return this;
 };
 
+/**
+ * @param {string} type
+ * @returns {this}
+ */
 Field.prototype.type = function(type) {
     this.$description.type = type;
     return this;
 };
 
+/**
+ * @param {*} defaultValue
+ * @returns {this}
+ */
 Field.prototype.default = function(defaultValue) {
     this.$description.defaultValue = defaultValue;
     return this;
 };
 
+/**
+ * @param {NdChild} text
+ * @returns {this}
+ */
 Field.prototype.label = function(text) {
     this.$description.label = text;
     return this;
 };
 
+/**
+ * @param {NdChild} text
+ * @returns {this}
+ */
 Field.prototype.help = function(text) {
     this.$description.help = text;
     return this;
 };
 
+/**
+ * @param {NdChild} text
+ * @returns {this}
+ */
 Field.prototype.hint = function(text) {
     this.$description.help = text;
     return this;
 };
 
+/**
+ * @param {NdChild} text
+ * @returns {this}
+ */
 Field.prototype.placeholder = function(text) {
     this.$description.placeholder = text;
     return this;
 };
 
+/**
+ * @param {boolean|Observable<boolean>} [disabled]
+ * @returns {this}
+ */
 Field.prototype.disabled = function(disabled) {
     this.$description.disabled = BaseComponent.obs(disabled);
     return this;
 };
 
+/**
+ * @param {boolean|Observable<boolean>} [readonly]
+ * @returns {this}
+ */
 Field.prototype.readonly = function(readonly) {
     this.$description.readonly = BaseComponent.obs(readonly);
     return this;
 };
 
+/**
+ * @returns {*}
+ */
 Field.prototype.value = function() {
     const value = this.$model();
     return Validator.isObservable(value) ? value.val() : value;
 };
 
+/**
+ * @param {*} newValue
+ * @returns {this}
+ */
 Field.prototype.setValue = function(newValue) {
     const value = this.$model();
     if(Validator.isObservable(value)) {
@@ -170,66 +280,115 @@ Field.prototype.setValue = function(newValue) {
     return this;
 };
 
+/**
+ * @param {*} wrapperProps
+ * @returns {this}
+ */
 Field.prototype.wrapperProps = function(wrapperProps) {
     this.$description.elementsProps.wrapper = wrapperProps;
     return this;
 };
 
+/**
+ * @param {*} inputProps
+ * @returns {this}
+ */
 Field.prototype.inputProps = function(inputProps) {
     this.$description.elementsProps.input = inputProps;
     return this;
 };
 
+/**
+ * @param {*} labelProps
+ * @returns {this}
+ */
 Field.prototype.labelProps = function(labelProps) {
     this.$description.elementsProps.label = labelProps;
     return this;
 };
 
+/**
+ * @param {*} errorProps
+ * @returns {this}
+ */
 Field.prototype.errorProps = function(errorProps) {
     this.$description.elementsProps.error = errorProps;
     return this;
 };
 
+/**
+ * @param {*} hintProps
+ * @returns {this}
+ */
 Field.prototype.hintProps = function(hintProps) {
     this.$description.elementsProps.hint = hintProps;
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Field.prototype.focus = function() {
     this.$description.focus.set(true);
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Field.prototype.blur = function() {
     this.$description.focus.set(false);
     return this;
 };
 
+/**
+ * @param {NdChild} content
+ * @returns {this}
+ */
 Field.prototype.leading = function(content) {
     this.$description.slots.leading = content;
     return this;
 };
 
+/**
+ * @param {NdChild} content
+ * @returns {this}
+ */
 Field.prototype.trailing = function(content) {
     this.$description.slots.trailing = content;
     return this;
 };
 
+/**
+ * @param {NdChild} content
+ * @returns {this}
+ */
 Field.prototype.bottom = function(content) {
     this.$description.slots.bottom = content;
     return this;
 };
 
+/**
+ * @param {*} [mode]
+ * @returns {this}
+ */
 Field.prototype.clearable = function(mode = true) {
     this.$description.clearable = BaseComponent.obs(mode);
     return this;
 };
 
+/**
+ * @param {*} clearButtonIcon
+ * @returns {this}
+ */
 Field.prototype.clearButtonIcon = function(clearButtonIcon) {
     this.$description.slots.clearButtonIcon = clearButtonIcon;
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Field.prototype.reset = function() {
     const value = this.$model();
     if(Validator.isObservable(value)) {
@@ -248,6 +407,10 @@ Field.prototype.reset = function() {
     return this;
 };
 
+/**
+ *
+ * @param {string|string[]} error
+ */
 Field.prototype.setError =  function(error) {
     const errs = Array.isArray(error) ? error : [error];
     this.$description.errors.set(errs);