native-document 1.0.165 → 1.0.168

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

@@ -1,5 +1,37 @@
-import Field from "../Field";
-
+import Field from '../../field/Field';
+
+/**
+ * Select/dropdown field supporting single and multiple selection, search, groups,
+ * and multiple display modes (tags, text, count, truncate).
+ * @example
+ * const field = new SelectField('country')
+ *     .label(Span('Country'))
+ *     .options([
+ *         { value: 'fr', label: Span('France') },
+ *         { value: 'de', label: Span('Germany') },
+ *         { value: 'es', label: Span('Spain') },
+ *     ])
+ *     .searchable(true, 'Search a country...')
+ *     .clearable(true)
+ *     .required();
+ *
+ * // Multiple selection with tag display
+ * const tags = new SelectField('tags')
+ *     .multiple(true)
+ *     .multipleDisplayAsTags()
+ *     .removeSelected(true)
+ *     .options([...]);
+ *
+ * SelectField.use((description, instance) => {
+ *     // description.options, description.multiple, description.searchable,
+ *     // description.multipleDisplay, description.groups, description.clearable...
+ *     return Div({ class: 'select' });
+ * });
+ *
+ * @constructor
+ * @param {string} name
+ * @param {GlobalAttributes} [props]
+ */
 export default function SelectField(name, props) {
     if(!(this instanceof SelectField)) {
         return new SelectField(name, props);
@@ -20,12 +52,40 @@ export default function SelectField(name, props) {
         countRender: false,
         selectedLabelRender: false,
         renderItem: null,
-        truncateMax: null
+        truncateMax: null,
     });
 }
 
 SelectField.defaultTemplate = null;
 
+/**
+ * Registers the render template for SelectField.
+ * @param {(description: {
+ *     name: string,
+ *     type: 'select',
+ *     label: NdChild|null,
+ *     options: Array<{ value: *, label: NdChild, props: GlobalAttributes }>,
+ *     multiple: boolean,
+ *     searchable: boolean,
+ *     searchPlaceholder: string|null,
+ *     clearable: boolean,
+ *     groups: Array<{ label: NdChild, options: Array<{ value: *, label: NdChild }> }>|null,
+ *     multipleDisplay: 'text'|'tags'|'count'|'truncate',
+ *     truncateMax: number|null,
+ *     removeSelected: boolean,
+ *     renderItem: ((item: *, isSelected: boolean) => NdChild)|null,
+ *     truncateRender: ((count: number) => NdChild)|false,
+ *     countRender: ((count: number) => NdChild)|false,
+ *     selectedLabelRender: ((selected: *[]) => NdChild)|false,
+ *     value: Observable<*>|null,
+ *     disabled: boolean|Observable<boolean>,
+ *     readonly: boolean|Observable<boolean>,
+ *     hasErrors: Observable<boolean>,
+ *     errors: Observable<string[]>,
+ *     showErrors: Observable<boolean>,
+ *     props: GlobalAttributes
+ * }, instance: SelectField) => NdChild} template
+ */
 SelectField.use = function(template) {
     SelectField.defaultTemplate = template;
 };
@@ -33,86 +93,155 @@ SelectField.use = function(template) {
 SelectField.prototype = Object.create(Field.prototype);
 SelectField.prototype.constructor = SelectField;
 
+/**
+ * @param {Array<{ value: *, label: NdChild, props?: GlobalAttributes }>} opts
+ * @returns {this}
+ */
 SelectField.prototype.options = function(opts) {
     this.$description.options = opts;
     return this;
 };
 
+/**
+ * @param {*} value
+ * @param {NdChild} label
+ * @param {GlobalAttributes} [props={}]
+ * @returns {this}
+ */
 SelectField.prototype.option = function(value, label, props = {}) {
     this.$description.options.push({ label, value, props });
     return this;
 };
 
+/**
+ * @param {boolean} [enabled=true]
+ * @returns {this}
+ */
 SelectField.prototype.multiple = function(enabled = true) {
     this.$description.multiple = enabled;
     return this;
 };
 
+/**
+ * @param {boolean} [enabled=true]
+ * @param {string|null} [placeholder=null]
+ * @returns {this}
+ */
 SelectField.prototype.searchable = function(enabled = true, placeholder = null) {
     this.$description.searchable = enabled;
     this.$description.searchPlaceholder = placeholder;
     return this;
 };
 
+/**
+ * @param {boolean} [enabled=true]
+ * @returns {this}
+ */
 SelectField.prototype.clearable = function(enabled = true) {
     this.$description.clearable = enabled;
     return this;
 };
 
+/**
+ * @param {Array<{ label: NdChild, options: Array<{ value: *, label: NdChild }> }>} groupsConfig
+ * @returns {this}
+ */
 SelectField.prototype.groups = function(groupsConfig) {
     this.$description.groups = groupsConfig;
     return this;
 };
 
+/**
+ * @param {'text'|'tags'|'count'|'truncate'} mode
+ * @returns {this}
+ */
 SelectField.prototype.multipleDisplay = function(mode) {
     this.$description.multipleDisplay = mode;
     return this;
 };
+
+/** @returns {this} */
 SelectField.prototype.multipleDisplayAsTags = function() {
     this.$description.multipleDisplay = 'tags';
     return this;
 };
 
+/** @returns {this} */
 SelectField.prototype.multipleDisplayAsText = function() {
     this.$description.multipleDisplay = 'text';
     return this;
 };
 
+/** @returns {this} */
 SelectField.prototype.multipleDisplayAsCount = function() {
     this.$description.multipleDisplay = 'count';
     return this;
 };
 
+/**
+ * @param {number} [max=2]
+ * @returns {this}
+ */
 SelectField.prototype.multipleDisplayAsTruncate = function(max = 2) {
     this.$description.multipleDisplay = 'truncate';
     this.$description.truncateMax = max;
     return this;
 };
 
+/**
+ * @param {boolean} [enabled=true]
+ * @returns {this}
+ */
 SelectField.prototype.removeSelected = function(enabled = true) {
     this.$description.removeSelected = enabled;
     return this;
 };
 
+/**
+ * Custom render for the truncated overflow label (e.g. "+3 more").
+ * @param {(count: number) => NdChild} callback
+ * @returns {this}
+ */
 SelectField.prototype.truncateRender = function(callback) {
     this.$description.truncateRender = callback;
     return this;
 };
 
+/**
+ * Custom render for the count display (e.g. "3 selected").
+ * @param {(count: number) => NdChild} callback
+ * @returns {this}
+ */
 SelectField.prototype.countRender = function(callback) {
     this.$description.countRender = callback;
     return this;
 };
 
+/**
+ * Custom render for the selected label in text mode.
+ * @param {(selected: *[]) => NdChild} callback
+ * @returns {this}
+ */
 SelectField.prototype.selectedLabelRender = function(callback) {
     this.$description.selectedLabelRender = callback;
     return this;
 };
+
+/**
+ * Custom render for each option in the dropdown list.
+ * @param {(item: *, isSelected: boolean) => NdChild} callback
+ * @returns {this}
+ */
 SelectField.prototype.renderItem = function(callback) {
     this.$description.renderItem = callback;
     return this;
 };
+
+/**
+ * @param {(value: *) => void} handler
+ * @returns {this}
+ */
 SelectField.prototype.onChange = function(handler) {
     this.on('change', handler);
     return this;
-}
+};

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

@@ -1,6 +1,29 @@
-import Field from "../Field";
-import {Validation} from "../../validation/Validation";
+import Field from '../../field/Field';
+import {Validation} from '../../validation/Validation';
 
+/**
+ * Text input field. Base for all string-based field types (email, password, search, tel, url).
+ * Inherits all Field methods (label, placeholder, required, model, clearable, etc.).
+ * @example
+ * const field = new StringField('username')
+ *     .label(Span('Username'))
+ *     .placeholder('Enter your username')
+ *     .minLength(3, 'Too short')
+ *     .maxLength(32)
+ *     .alphaNumeric('Letters and numbers only')
+ *     .required();
+ *
+ * StringField.use((description, instance) => {
+ *     // description.name, description.type, description.label,
+ *     // description.placeholder, description.value, description.errors...
+ *     return Input({ type: description.type, placeholder: description.placeholder });
+ * });
+ *
+ * @constructor
+ * @param {string} name
+ * @param {string} [type='text']
+ * @param {GlobalAttributes} [props={}]
+ */
 export default function StringField(name, type = 'text', props = {}) {
     if(!(this instanceof StringField)) {
         return new StringField(name, props);
@@ -11,6 +34,28 @@ export default function StringField(name, type = 'text', props = {}) {
 
 StringField.defaultTemplate = null;
 
+/**
+ * Registers the render template for StringField.
+ * @param {(description: {
+ *     name: string,
+ *     type: string,
+ *     label: NdChild|null,
+ *     placeholder: NdChild|null,
+ *     help: NdChild|null,
+ *     defaultValue: *,
+ *     disabled: boolean|Observable<boolean>,
+ *     readonly: boolean|Observable<boolean>,
+ *     value: Observable<string>|null,
+ *     clearable: boolean|Observable<boolean>|null,
+ *     hasErrors: Observable<boolean>,
+ *     errors: Observable<string[]>,
+ *     showErrors: Observable<boolean>,
+ *     clearButtonIcon: NdChild|null,
+ *     focus: Observable<boolean>,
+ *     isDirty: Observable<boolean>,
+ *     props: GlobalAttributes
+ * }, instance: StringField) => NdChild} template
+ */
 StringField.use = function(template) {
     StringField.defaultTemplate = template;
 };
@@ -18,42 +63,86 @@ StringField.use = function(template) {
 StringField.prototype = Object.create(Field.prototype);
 StringField.prototype.constructor = StringField;
 
+/**
+ * @param {number} min
+ * @param {string} [message]
+ * @returns {this}
+ */
 StringField.prototype.minLength = function(min, message) {
     return this.addRule(Validation.minLength, [min], message);
 };
 
+/**
+ * @param {number} max
+ * @param {string} [message]
+ * @returns {this}
+ */
 StringField.prototype.maxLength = function(max, message) {
     return this.addRule(Validation.maxLength, [max], message);
 };
 
+/**
+ * @param {number} length
+ * @param {string} [message]
+ * @returns {this}
+ */
 StringField.prototype.length = function(length, message) {
     return this.addRule(Validation.length, [length], message);
 };
 
+/**
+ * @param {RegExp} regex
+ * @param {string} [message]
+ * @returns {this}
+ */
 StringField.prototype.pattern = function(regex, message) {
     return this.addRule(Validation.pattern, [regex], message);
 };
 
+/**
+ * @param {string} [message]
+ * @returns {this}
+ */
 StringField.prototype.alphaOnly = function(message) {
     return this.addRule(Validation.alphaOnly, [], message);
 };
 
+/**
+ * @param {string} [message]
+ * @returns {this}
+ */
 StringField.prototype.numericOnly = function(message) {
     return this.addRule(Validation.numericOnly, [], message);
 };
 
+/**
+ * @param {string} [message]
+ * @returns {this}
+ */
 StringField.prototype.alphaNumeric = function(message) {
     return this.addRule(Validation.alphaNumeric, [], message);
 };
 
+/**
+ * @param {string} [message]
+ * @returns {this}
+ */
 StringField.prototype.noSpaces = function(message) {
     return this.addRule(Validation.noSpaces, [], message);
 };
 
+/**
+ * @param {string} [message]
+ * @returns {this}
+ */
 StringField.prototype.lowercase = function(message) {
     return this.addRule(Validation.lowercase, [], message);
 };
 
+/**
+ * @param {string} [message]
+ * @returns {this}
+ */
 StringField.prototype.uppercase = function(message) {
     return this.addRule(Validation.uppercase, [], message);
 };

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

@@ -1,6 +1,25 @@
-import StringField from "./StringField";
-import {Validation} from "../../validation/Validation";
+import StringField from '../../field/types/StringField';
+import {Validation} from '../../validation/Validation';
 
+/**
+ * Telephone input field. Supports phone format validation, country code prefix,
+ * and mask patterns using # as digit placeholder.
+ * @example
+ * const field = new TelField('phone')
+ *     .label(Span('Phone'))
+ *     .countryCode(true)
+ *     .mask('+33 ## ## ## ## ##')
+ *     .required();
+ *
+ * TelField.use((description, instance) => {
+ *     // description.countryCode, description.mask, description.value...
+ *     return Input({ type: 'tel', placeholder: description.mask ?? undefined });
+ * });
+ *
+ * @constructor
+ * @param {string} name
+ * @param {GlobalAttributes} [props]
+ */
 export default function TelField(name, props) {
     if(!(this instanceof TelField)) {
         return new TelField(name, props);
@@ -10,12 +29,30 @@ export default function TelField(name, props) {
 
     Object.assign(this.$description, {
         countryCode: false,
-        mask: null
+        mask: null,
     });
 }
 
 TelField.defaultTemplate = null;
 
+/**
+ * Registers the render template for TelField.
+ * @param {(description: {
+ *     name: string,
+ *     type: 'tel',
+ *     label: NdChild|null,
+ *     placeholder: NdChild|null,
+ *     value: Observable<string>|null,
+ *     countryCode: boolean,
+ *     mask: string|null,
+ *     disabled: boolean|Observable<boolean>,
+ *     readonly: boolean|Observable<boolean>,
+ *     hasErrors: Observable<boolean>,
+ *     errors: Observable<string[]>,
+ *     showErrors: Observable<boolean>,
+ *     props: GlobalAttributes
+ * }, instance: TelField) => NdChild} template
+ */
 TelField.use = function(template) {
     TelField.defaultTemplate = template;
 };
@@ -23,15 +60,29 @@ TelField.use = function(template) {
 TelField.prototype = Object.create(StringField.prototype);
 TelField.prototype.constructor = TelField;
 
+/**
+ * @param {string} [message]
+ * @returns {this}
+ */
 TelField.prototype.phone = function(message) {
     return this.addRule(Validation.phone, [], message);
 };
 
+/**
+ * @param {boolean} [enabled=true]
+ * @returns {this}
+ */
 TelField.prototype.countryCode = function(enabled = true) {
     this.$description.countryCode = enabled;
     return this;
 };
 
+/**
+ * Applies a mask pattern using # as digit placeholder (e.g. '+33 ## ## ## ## ##').
+ * Also registers a validation rule matching the pattern.
+ * @param {string} pattern
+ * @returns {this}
+ */
 TelField.prototype.mask = function(pattern) {
     this.$description.mask = pattern;
 
@@ -40,7 +91,7 @@ TelField.prototype.mask = function(pattern) {
         .replace(/#/g, '\\d');
 
     this.addRule(Validation.pattern, [new RegExp(`^${regex}$`)],
-        `Invalid phone format. Expected: ${pattern}`
+        `Invalid phone format. Expected: ${pattern}`,
     );
 
     return this;

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

@@ -1,5 +1,31 @@
-import StringField from "./StringField";
+import StringField from '../../field/types/StringField';
 
+/**
+ * Multi-line text input field. Supports rows/cols, resize mode, auto-grow,
+ * character counter, and word count validation.
+ * @example
+ * const field = new TextAreaField('bio')
+ *     .label(Span('Biography'))
+ *     .rows(6)
+ *     .autoGrow(true)
+ *     .characterCounter(true)
+ *     .wordCount(10, 500, 'Between 10 and 500 words')
+ *     .maxLength(2000)
+ *     .required();
+ *
+ * TextAreaField.use((description, instance) => {
+ *     // description.rows, description.cols, description.resize,
+ *     // description.autoGrow, description.characterCounter, description.wordCount...
+ *     return Textarea({
+ *         rows: description.rows,
+ *         resize: description.resize
+ *     });
+ * });
+ *
+ * @constructor
+ * @param {string} name
+ * @param {GlobalAttributes} [props]
+ */
 export default function TextAreaField(name, props) {
     if(!(this instanceof TextAreaField)) {
         return new TextAreaField(name, props);
@@ -20,6 +46,28 @@ export default function TextAreaField(name, props) {
 
 TextAreaField.defaultTemplate = null;
 
+/**
+ * Registers the render template for TextAreaField.
+ * @param {(description: {
+ *     name: string,
+ *     type: 'textarea',
+ *     label: NdChild|null,
+ *     placeholder: NdChild|null,
+ *     value: Observable<string>|null,
+ *     rows: number,
+ *     cols: number|null,
+ *     resize: 'none'|'horizontal'|'vertical'|'both',
+ *     autoGrow: boolean,
+ *     characterCounter: boolean,
+ *     wordCount: boolean,
+ *     disabled: boolean|Observable<boolean>,
+ *     readonly: boolean|Observable<boolean>,
+ *     hasErrors: Observable<boolean>,
+ *     errors: Observable<string[]>,
+ *     showErrors: Observable<boolean>,
+ *     props: GlobalAttributes
+ * }, instance: TextAreaField) => NdChild} template
+ */
 TextAreaField.use = function(template) {
     TextAreaField.defaultTemplate = template;
 };
@@ -27,31 +75,57 @@ TextAreaField.use = function(template) {
 TextAreaField.prototype = Object.create(StringField.prototype);
 TextAreaField.prototype.constructor = TextAreaField;
 
+/**
+ * @param {number} value
+ * @returns {this}
+ */
 TextAreaField.prototype.rows = function(value) {
     this.$description.rows = value;
     return this;
 };
 
+/**
+ * @param {number} value
+ * @returns {this}
+ */
 TextAreaField.prototype.cols = function(value) {
     this.$description.cols = value;
     return this;
 };
 
+/**
+ * @param {'none'|'horizontal'|'vertical'|'both'} value
+ * @returns {this}
+ */
 TextAreaField.prototype.resize = function(value) {
     this.$description.resize = value;
     return this;
 };
 
+/**
+ * @param {boolean} [enabled=true]
+ * @returns {this}
+ */
 TextAreaField.prototype.autoGrow = function(enabled = true) {
     this.$description.autoGrow = enabled;
     return this;
 };
 
+/**
+ * @param {boolean} [enabled=true]
+ * @returns {this}
+ */
 TextAreaField.prototype.characterCounter = function(enabled = true) {
     this.$description.characterCounter = enabled;
     return this;
 };
 
+/**
+ * @param {number} min
+ * @param {number} max
+ * @param {string} [message]
+ * @returns {this}
+ */
 TextAreaField.prototype.wordCount = function(min, max, message) {
     this.$description.wordCount = true;
     this.$description.rules.push({
@@ -62,7 +136,7 @@ TextAreaField.prototype.wordCount = function(min, max, message) {
             if (max && words > max) return false;
             return true;
         },
-        message: message || `Word count must be between ${min || 0} and ${max || '∞'}`
+        message: message || `Word count must be between ${min || 0} and ${max || '∞'}`,
     });
     return this;
 };