native-document 1.0.164 → 1.0.166

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

@@ -1,10 +1,27 @@
-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 NativeDocumentError from "../../../core/errors/NativeDocumentError";
+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 NativeDocumentError from '../../../core/errors/NativeDocumentError';
 
+/**
+ * Repeatable field group. Allows adding/removing instances dynamically with validation rules on the collection (min/max count).
+ *
+ *
+ * @example
+ * const phones = new FieldCollection('phones')
+ *     .fields((fields, index) =>
+ *         new Field(\`phones[\${index}]\`, 'tel').label(Span(\`Phone \${index + 1}\`))
+ *     )
+ *     .renderAdd(() => Button(Span('+ Add phone')))
+ *     .min(1, 'At least one phone is required')
+ *     .max(5, 'Maximum 5 phones allowed');
+ *
+ * @constructor
+ * @param {string} [name]
+ * @param {GlobalAttributes} [props={}]
+ */
 export default function FieldCollection(name, props = {}) {
     if(!(this instanceof FieldCollection)) {
         return new FieldCollection(name, props);
@@ -25,11 +42,11 @@ export default function FieldCollection(name, props = {}) {
         renderItem: null,
         renderAdd: null,
         transition: null,
-        props
+        props,
     };
 
     this.$description.value.interceptMutations((items) =>
-        items.map(item => Validator.isObservable(item) ? item : $.object(item))
+        items.map(item => Validator.isObservable(item) ? item : $.object(item)),
     );
 }
 
@@ -39,10 +56,29 @@ BaseComponent.use(FieldCollection, HasValidation);
 
 FieldCollection.defaultTemplate = null;
 
+/**
+ * Registers the render template for FieldCollection.
+ * @param {(description: {
+ *     name: string,
+ *     value: Observable<*[]>,
+ *     hasErrors: Observable<boolean>,
+ *     errors: Observable<string[]>,
+ *     defaultItem: *,
+ *     fieldBuilder: ((fields: FieldCollection, index: number) => NdChild)|null,
+ *     renderItem: ((item: *, index: number) => NdChild)|null,
+ *     renderAdd: (() => NdChild)|null,
+ *     transition: string|null,
+ *     props: GlobalAttributes,
+ * }, instance: FieldCollection) => NdChild} template
+ */
 FieldCollection.use = function(template) {
     FieldCollection.defaultTemplate = template;
 };
 
+/**
+ * @param {(fields: FieldCollection, index: number) => NdChild} fieldBuilder
+ * @returns {this}
+ */
 FieldCollection.prototype.fields = function(fieldBuilder) {
     if(typeof fieldBuilder !== 'function') {
         throw new NativeDocumentError('FieldCollection.fields() expects a function');
@@ -51,6 +87,10 @@ FieldCollection.prototype.fields = function(fieldBuilder) {
     return this;
 };
 
+/**
+ * @param {*} defaultItem
+ * @returns {this}
+ */
 FieldCollection.prototype.data = function(defaultItem) {
     if(typeof defaultItem !== 'function') {
         throw new NativeDocumentError('FieldCollection.data() expects a factory function');
@@ -59,26 +99,42 @@ FieldCollection.prototype.data = function(defaultItem) {
     return this;
 };
 
+/**
+ * @param {(item: *, index: number) => NdChild} fn
+ * @returns {this}
+ */
 FieldCollection.prototype.renderItem = function(fn) {
     this.$description.renderItem = fn;
     return this;
 };
 
+/**
+ * @param {() => NdChild} fn
+ * @returns {this}
+ */
 FieldCollection.prototype.renderAdd = function(fn) {
     this.$description.renderAdd = fn;
     return this;
 };
 
+/**
+ * @param {string} transitionName
+ * @returns {this}
+ */
 FieldCollection.prototype.transition = function(transitionName) {
     this.$description.transition = transitionName;
     return this;
 };
 
+/**
+ * @param {Observable<*[]>} observable
+ * @returns {this}
+ */
 FieldCollection.prototype.model = function(observable) {
     if(Validator.isObservable(observable)) {
         this.$description.value = observable;
         this.$description.value.interceptMutations((items) =>
-            items.map(item => Validator.isObservable(item) ? item : $.object(item))
+            items.map(item => Validator.isObservable(item) ? item : $.object(item)),
         );
         return this;
     }
@@ -86,6 +142,9 @@ FieldCollection.prototype.model = function(observable) {
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 FieldCollection.prototype.add = function() {
     if(!this.$description.fieldBuilder) {
         throw new NativeDocumentError('FieldCollection: fields() must be defined before add()');
@@ -100,51 +159,87 @@ FieldCollection.prototype.add = function() {
     return this;
 };
 
+/**
+ * @param {*} item
+ * @returns {this}
+ */
 FieldCollection.prototype.remove = function(item) {
     this.$description.value.removeItem(item);
     this.emit('remove', item);
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 FieldCollection.prototype.clear = function() {
     this.$description.value.clear();
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 FieldCollection.prototype.reset = function() {
     this.clear();
     return this;
 };
 
+/**
+ * @returns {*[]}
+ */
 FieldCollection.prototype.value = function() {
     return this.$description.value.map(item =>
-        Validator.isObservable(item) ? item.val() : item
+        Validator.isObservable(item) ? item.val() : item,
     );
 };
 
+/**
+ * @returns {number}
+ */
 FieldCollection.prototype.count = function() {
     return this.$description.value.val().length;
 };
 
+/**
+ * @returns {boolean}
+ */
 FieldCollection.prototype.isEmpty = function() {
     return this.$description.value.val().length === 0;
 };
 
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
 FieldCollection.prototype.onChange = function(handler) {
     this.on('change', handler);
     return this;
 };
 
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
 FieldCollection.prototype.onAdd = function(handler) {
     this.on('add', handler);
     return this;
 };
 
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
 FieldCollection.prototype.onRemove = function(handler) {
     this.on('remove', handler);
     return this;
 };
 
+/**
+ * @param {number} minCount
+ * @param {string} [message]
+ * @returns {this}
+ */
 FieldCollection.prototype.min = function(minCount, message) {
     return this.addRule(
         (values) => ({
@@ -152,10 +247,15 @@ FieldCollection.prototype.min = function(minCount, message) {
             message: `Minimum ${minCount} item(s) required`,
         }),
         [],
-        message
+        message,
     );
 };
 
+/**
+ * @param {number} maxCount
+ * @param {string} [message]
+ * @returns {this}
+ */
 FieldCollection.prototype.max = function(maxCount, message) {
     return this.addRule(
         (values) => ({
@@ -163,11 +263,15 @@ FieldCollection.prototype.max = function(maxCount, message) {
             message: `Maximum ${maxCount} item(s) allowed`,
         }),
         [],
-        message
+        message,
     );
 };
 
 // Override validate
+/**
+ * @param {*} [allValues]
+ * @returns {{ key: string, errors: string[] }}
+ */
 FieldCollection.prototype.validate = function(allValues) {
     const errors     = [];
     const rowsValues = this.value();

package/src/components/form/field/types/AutocompleteField.js

@@ -1,5 +1,29 @@
-import StringField from "./StringField";
+import StringField from '../../field/types/StringField';
 
+/**
+ * Text field with asynchronous autocomplete suggestions. Supports static arrays
+ * and async data sources, configurable debounce, min chars, and item rendering.
+ * @example
+ * const field = new AutocompleteField('city')
+ *     .label(Span('City'))
+ *     .source((query) => fetch(\`/api/cities?q=\${query}\`).then(r => r.json()))
+ *     .minChars(2)
+ *     .debounce(300)
+ *     .valueKey('id')
+ *     .labelKey('name')
+ *     .renderItem((item) => Div(Span(item.name), Span({ class: 'hint' }, item.country)))
+ *     .onSelect((item) => console.log('selected', item));
+ *
+ * AutocompleteField.use((description, instance) => {
+ *     // description.source, description.minChars, description.debounce,
+ *     // description.valueKey, description.labelKey, description.renderItem...
+ *     return Input({ type: 'text', placeholder: description.placeholder });
+ * });
+ *
+ * @constructor
+ * @param {string} name
+ * @param {GlobalAttributes} [props]
+ */
 export default function AutocompleteField(name, props) {
     if(!(this instanceof AutocompleteField)) {
         return new AutocompleteField(name, props);
@@ -20,6 +44,29 @@ export default function AutocompleteField(name, props) {
 
 AutocompleteField.defaultTemplate = null;
 
+/**
+ * Registers the render template for AutocompleteField.
+ * @param {(description: {
+ *     name: string,
+ *     type: 'autocomplete',
+ *     label: NdChild|null,
+ *     placeholder: NdChild|null,
+ *     value: Observable<*>|null,
+ *     source: *[]|((query: string) => Promise<*[]>)|null,
+ *     minChars: number,
+ *     debounce: number,
+ *     maxResults: number,
+ *     valueKey: string,
+ *     labelKey: string,
+ *     renderItem: ((item: *) => NdChild)|null,
+ *     disabled: boolean|Observable<boolean>,
+ *     readonly: boolean|Observable<boolean>,
+ *     hasErrors: Observable<boolean>,
+ *     errors: Observable<string[]>,
+ *     showErrors: Observable<boolean>,
+ *     props: GlobalAttributes
+ * }, instance: AutocompleteField) => NdChild} template
+ */
 AutocompleteField.use = function(template) {
     AutocompleteField.defaultTemplate = template;
 };
@@ -28,50 +75,93 @@ AutocompleteField.use = function(template) {
 AutocompleteField.prototype = Object.create(StringField.prototype);
 AutocompleteField.prototype.constructor = AutocompleteField;
 
+/**
+ * @param {*[]|((query: string) => Promise<*[]>)} dataSource
+ * @returns {this}
+ */
 AutocompleteField.prototype.source = function(dataSource) {
     this.$description.source = dataSource;
     return this;
 };
 
+/**
+ * @param {number} min - Minimum characters before triggering the source
+ * @returns {this}
+ */
 AutocompleteField.prototype.minChars = function(min) {
     this.$description.minChars = min;
     return this;
 };
 
+/**
+ * @param {number} ms
+ * @returns {this}
+ */
 AutocompleteField.prototype.debounce = function(ms) {
     this.$description.debounce = ms;
     return this;
 };
 
+/**
+ * @param {number} max
+ * @returns {this}
+ */
 AutocompleteField.prototype.maxResults = function(max) {
     this.$description.maxResults = max;
     return this;
 };
 
+/**
+ * Validates that the entered value exists in the allowed list.
+ * @param {*[]} allowedValues
+ * @param {string} [message]
+ * @returns {this}
+ */
 AutocompleteField.prototype.oneOf = function(allowedValues, message) {
     this.$description.rules.push({
         validate: (value) => {
             if (!value) return true;
             return allowedValues.includes(value);
         },
-        message: message || `Must be one of: ${allowedValues.join(', ')}`
+        message: message || `Must be one of: ${allowedValues.join(', ')}`,
     });
     return this;
 };
 
+/**
+ * Key in the data object used as the field value.
+ * @param {string} key
+ * @returns {this}
+ */
 AutocompleteField.prototype.valueKey = function(key) {
     this.$description.valueKey = key;
     return this;
 };
 
+/**
+ * Key in the data object used as the display label.
+ * @param {string} key
+ * @returns {this}
+ */
 AutocompleteField.prototype.labelKey = function(key) {
     this.$description.labelKey = key;
     return this;
 };
+
+/**
+ * @param {(item: *) => void} handler
+ * @returns {this}
+ */
 AutocompleteField.prototype.onSelect = function(handler) {
     this.on('select', handler);
     return this;
 };
+
+/**
+ * Custom render for each suggestion item in the dropdown.
+ * @param {(item: *) => NdChild} callback
+ * @returns {this}
+ */
 AutocompleteField.prototype.renderItem = function(callback) {
     this.$description.renderItem = callback;
     return this;

package/src/components/form/field/types/CheckboxField.js

@@ -1,6 +1,23 @@
-import Field from "../Field";
-import Validator from "../../../../core/utils/validator";
+import Field from '../../field/Field';
+import Validator from '../../../../core/utils/validator';
 
+/**
+ * Single checkbox field for boolean values. Supports reactive model binding.
+ * @example
+ * const field = new CheckboxField('agree')
+ *     .label(Span('I agree to the terms'))
+ *     .model(agreeObs)
+ *     .required('You must agree');
+ *
+ * CheckboxField.use((description, instance) => {
+ *     // description.checked — Observable<boolean> or boolean
+ *     return Input({ type: 'checkbox', checked: description.checked });
+ * });
+ *
+ * @constructor
+ * @param {string} name
+ * @param {GlobalAttributes} [props]
+ */
 export default function CheckboxField(name, props) {
     if(!(this instanceof CheckboxField)) {
         return new CheckboxField(name, props);
@@ -15,6 +32,21 @@ export default function CheckboxField(name, props) {
 
 CheckboxField.defaultTemplate = null;
 
+/**
+ * Registers the render template for CheckboxField.
+ * @param {(description: {
+ *     name: string,
+ *     type: 'checkbox',
+ *     label: NdChild|null,
+ *     checked: Observable<boolean>|boolean,
+ *     disabled: boolean|Observable<boolean>,
+ *     readonly: boolean|Observable<boolean>,
+ *     hasErrors: Observable<boolean>,
+ *     errors: Observable<string[]>,
+ *     showErrors: Observable<boolean>,
+ *     props: GlobalAttributes
+ * }, instance: CheckboxField) => NdChild} template
+ */
 CheckboxField.use = function(template) {
     CheckboxField.defaultTemplate = template;
 };
@@ -22,11 +54,20 @@ CheckboxField.use = function(template) {
 CheckboxField.prototype = Object.create(Field.prototype);
 CheckboxField.prototype.constructor = CheckboxField;
 
+/**
+ * Binds the checked state to an observable.
+ * @param {Observable<boolean>} observable
+ * @returns {this}
+ */
 CheckboxField.prototype.model = function(observable) {
     this.$description.checked = observable;
     return this;
 };
 
+/**
+ * Returns the current checked value (resolves the observable if needed).
+ * @returns {boolean}
+ */
 CheckboxField.prototype.checked = function() {
     const checked = this.$description.checked;
     if(Validator.isObservable(checked)) {

package/src/components/form/field/types/CheckboxGroupField.js

@@ -1,5 +1,32 @@
-import Field from "../Field";
-
+import Field from '../../field/Field';
+
+/**
+ * Group of checkboxes for multi-value selection. Supports vertical/horizontal/grid layout
+ * and min/max/exact count validation.
+ * @example
+ * const field = new CheckboxGroupField('roles')
+ *     .label(Span('Roles'))
+ *     .option('admin', Span('Administrator'))
+ *     .option('editor', Span('Editor'))
+ *     .option('viewer', Span('Viewer'))
+ *     .horizontal()
+ *     .minChecked(1, 'Select at least one role')
+ *     .maxChecked(2);
+ *
+ * CheckboxGroupField.use((description, instance) => {
+ *     // description.options — Array<{ value, label, props }>
+ *     // description.layout — 'vertical' | 'horizontal' | 'grid'
+ *     return Div({ class: \`checkbox-group checkbox-group--\${description.layout}\` },
+ *         ...description.options.map(opt =>
+ *             Label(Input({ type: 'checkbox', value: opt.value }), opt.label)
+ *         )
+ *     );
+ * });
+ *
+ * @constructor
+ * @param {string} name
+ * @param {GlobalAttributes} [props]
+ */
 export default function CheckboxGroupField(name, props) {
     if(!(this instanceof CheckboxGroupField)) {
         return new CheckboxGroupField(name, props);
@@ -11,12 +38,30 @@ export default function CheckboxGroupField(name, props) {
         options: [],
         layout: 'vertical',
         validateOn: 'change',
-        defaultValue: []
+        defaultValue: [],
     });
 }
 
 CheckboxGroupField.defaultTemplate = null;
 
+/**
+ * Registers the render template for CheckboxGroupField.
+ * @param {(description: {
+ *     name: string,
+ *     type: 'checkbox-group',
+ *     label: NdChild|null,
+ *     options: Array<{ value: *, label: NdChild, props: GlobalAttributes }>,
+ *     layout: 'vertical'|'horizontal'|'grid',
+ *     value: Observable<*[]>|null,
+ *     defaultValue: *[],
+ *     disabled: boolean|Observable<boolean>,
+ *     readonly: boolean|Observable<boolean>,
+ *     hasErrors: Observable<boolean>,
+ *     errors: Observable<string[]>,
+ *     showErrors: Observable<boolean>,
+ *     props: GlobalAttributes
+ * }, instance: CheckboxGroupField) => NdChild} template
+ */
 CheckboxGroupField.use = function(template) {
     CheckboxGroupField.defaultTemplate = template;
 };
@@ -24,16 +69,30 @@ CheckboxGroupField.use = function(template) {
 CheckboxGroupField.prototype = Object.create(Field.prototype);
 CheckboxGroupField.prototype.constructor = CheckboxGroupField;
 
+/**
+ * @param {Array<{ value: *, label: NdChild, props?: GlobalAttributes }>} opts
+ * @returns {this}
+ */
 CheckboxGroupField.prototype.options = function(opts) {
     this.$description.options = opts;
     return this;
 };
 
+/**
+ * @param {*} value
+ * @param {NdChild} label
+ * @param {GlobalAttributes} [props={}]
+ * @returns {this}
+ */
 CheckboxGroupField.prototype.option = function(value, label, props = {}) {
     this.$description.options.push({ value, label, props });
     return this;
 };
 
+/**
+ * @param {'vertical'|'horizontal'|'grid'} value
+ * @returns {this}
+ */
 CheckboxGroupField.prototype.layout = function(value) {
     const allowedLayouts = ['vertical', 'horizontal', 'grid'];
 
@@ -45,50 +104,68 @@ CheckboxGroupField.prototype.layout = function(value) {
     return this;
 };
 
+/** @returns {this} */
 CheckboxGroupField.prototype.horizontal = function() {
     this.$description.layout = 'horizontal';
     return this;
 };
 
+/** @returns {this} */
 CheckboxGroupField.prototype.vertical = function() {
     this.$description.layout = 'vertical';
     return this;
 };
 
+/** @returns {this} */
 CheckboxGroupField.prototype.grid = function() {
     this.$description.layout = 'grid';
     return this;
 };
 
+/**
+ * @param {number} min
+ * @param {string} [message]
+ * @returns {this}
+ */
 CheckboxGroupField.prototype.minChecked = function(min, message) {
     this.$description.rules.push({
         validate: (values) => {
             if (!Array.isArray(values)) return false;
             return values.length >= min;
         },
-        message: message || `At least ${min} option${min > 1 ? 's' : ''} must be selected`
+        message: message || `At least ${min} option${min > 1 ? 's' : ''} must be selected`,
     });
     return this;
 };
 
+/**
+ * @param {number} max
+ * @param {string} [message]
+ * @returns {this}
+ */
 CheckboxGroupField.prototype.maxChecked = function(max, message) {
     this.$description.rules.push({
         validate: (values) => {
             if (!Array.isArray(values)) return false;
             return values.length <= max;
         },
-        message: message || `Maximum ${max} option${max > 1 ? 's' : ''} allowed`
+        message: message || `Maximum ${max} option${max > 1 ? 's' : ''} allowed`,
     });
     return this;
 };
 
+/**
+ * @param {number} count
+ * @param {string} [message]
+ * @returns {this}
+ */
 CheckboxGroupField.prototype.exactChecked = function(count, message) {
     this.$description.rules.push({
         validate: (values) => {
             if (!Array.isArray(values)) return false;
             return values.length === count;
         },
-        message: message || `Exactly ${count} option${count > 1 ? 's' : ''} must be selected`
+        message: message || `Exactly ${count} option${count > 1 ? 's' : ''} must be selected`,
     });
     return this;
 };