native-document 1.0.165 → 1.0.168

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

@@ -1,6 +1,31 @@
-import {Validation} from "../../validation/Validation";
-import StringField from "./StringField";
+import {Validation} from '../../validation/Validation';
+import StringField from '../../field/types/StringField';
 
+/**
+ * Password input field. Extends StringField with strength rules, strength meter,
+ * visibility toggle, and cross-field same/different validation.
+ * @example
+ * const field = new PasswordField('password')
+ *     .label(Span('Password'))
+ *     .strong()
+ *     .showStrengthMeter(true)
+ *     .visibilityToggle(true, { show: EyeIcon(), hide: EyeOffIcon() })
+ *     .required();
+ *
+ * const confirm = new PasswordField('confirm')
+ *     .label(Span('Confirm password'))
+ *     .same('password', 'Passwords do not match');
+ *
+ * PasswordField.use((description, instance) => {
+ *     // description.visibilityToggle, description.visibilityIcons,
+ *     // description.showStrengthMeter, description.strengthLabels...
+ *     return Input({ type: description.visibilityToggle ? 'text' : 'password' });
+ * });
+ *
+ * @constructor
+ * @param {string} name
+ * @param {GlobalAttributes} [props={}]
+ */
 export default function PasswordField(name, props = {}) {
     if(!(this instanceof PasswordField)) {
         return new PasswordField(name, props);
@@ -17,6 +42,25 @@ export default function PasswordField(name, props = {}) {
 
 PasswordField.defaultTemplate = null;
 
+/**
+ * Registers the render template for PasswordField.
+ * @param {(description: {
+ *     name: string,
+ *     type: 'password',
+ *     label: NdChild|null,
+ *     value: Observable<string>|null,
+ *     visibilityToggle: boolean,
+ *     visibilityIcons: { show: NdChild, hide: NdChild },
+ *     showStrengthMeter: boolean,
+ *     strengthLabels: Record<number, string>|null,
+ *     disabled: boolean|Observable<boolean>,
+ *     readonly: boolean|Observable<boolean>,
+ *     hasErrors: Observable<boolean>,
+ *     errors: Observable<string[]>,
+ *     showErrors: Observable<boolean>,
+ *     props: GlobalAttributes
+ * }, instance: PasswordField) => NdChild} template
+ */
 PasswordField.use = function(template) {
     PasswordField.defaultTemplate = template;
 };
@@ -24,47 +68,73 @@ PasswordField.use = function(template) {
 PasswordField.prototype = Object.create(StringField.prototype);
 PasswordField.prototype.constructor = PasswordField;
 
+/**
+ * Validates uppercase + lowercase + number, min 8 chars.
+ * @param {string} [message]
+ * @returns {this}
+ */
 PasswordField.prototype.strong = function(message) {
     const strongPattern = /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).{8,}$/;
     return this.addRule(
         Validation.pattern,
         [strongPattern],
-        message || 'Password must contain uppercase, lowercase, and number'
+        message || 'Password must contain uppercase, lowercase, and number',
     );
 };
 
+/**
+ * @param {string} [message]
+ * @returns {this}
+ */
 PasswordField.prototype.containsNumber = function(message) {
     return this.addRule(
         Validation.pattern,
         [/\d/],
-        message || 'Must contain at least one number'
+        message || 'Must contain at least one number',
     );
 };
 
+/**
+ * @param {string} [message]
+ * @returns {this}
+ */
 PasswordField.prototype.containsUppercase = function(message) {
     return this.addRule(
         Validation.pattern,
         [/[A-Z]/],
-        message || 'Must contain at least one uppercase letter'
+        message || 'Must contain at least one uppercase letter',
     );
 };
 
+/**
+ * @param {string} [message]
+ * @returns {this}
+ */
 PasswordField.prototype.containsLowercase = function(message) {
     return this.addRule(
         Validation.pattern,
         [/[a-z]/],
-        message || 'Must contain at least one lowercase letter'
+        message || 'Must contain at least one lowercase letter',
     );
 };
 
+/**
+ * @param {string} [message]
+ * @returns {this}
+ */
 PasswordField.prototype.containsSpecialChar = function(message) {
     return this.addRule(
         Validation.pattern,
         [/[!@#$%^&*(),.?":{}|<>]/],
-        message || 'Must contain at least one special character'
+        message || 'Must contain at least one special character',
     );
 };
 
+/**
+ * @param {boolean} [enabled=true]
+ * @param {{ show?: NdChild, hide?: NdChild }} [icons={}]
+ * @returns {this}
+ */
 PasswordField.prototype.visibilityToggle = function(enabled = true, icons = {}) {
     this.$description.visibilityToggle = enabled;
     this.$description.visibilityIcons = {
@@ -73,16 +143,30 @@ PasswordField.prototype.visibilityToggle = function(enabled = true, icons = {})
     };
     return this;
 };
+
+/**
+ * @param {NdChild} show
+ * @param {NdChild} hide
+ * @returns {this}
+ */
 PasswordField.prototype.visibilityIcons = function(show, hide) {
     this.$description.visibilityIcons = {show, hide};
     return this;
 };
 
+/**
+ * @param {boolean} [enabled=true]
+ * @returns {this}
+ */
 PasswordField.prototype.showStrengthMeter = function(enabled = true) {
     this.$description.showStrengthMeter = enabled;
     return this;
 };
 
+/**
+ * @param {{ weak?: string, fair?: string, good?: string, strong?: string, veryStrong?: string }} [labels={}]
+ * @returns {this}
+ */
 PasswordField.prototype.strengthLabels = function(labels = {}) {
     this.$description.strengthLabels = {
         0: labels[0] || '',
@@ -95,10 +179,22 @@ PasswordField.prototype.strengthLabels = function(labels = {}) {
     return this;
 };
 
+/**
+ * Validates that this field equals the value of another field by name.
+ * @param {string} fieldName
+ * @param {string} [message]
+ * @returns {this}
+ */
 PasswordField.prototype.same = function(fieldName, message) {
     return this.addRule(Validation.same, [fieldName], message || 'Passwords must match');
 };
 
+/**
+ * Validates that this field differs from another field by name.
+ * @param {string} fieldName
+ * @param {string} [message]
+ * @returns {this}
+ */
 PasswordField.prototype.different = function(fieldName, message) {
     return this.addRule(Validation.different, [fieldName], message);
 };

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

@@ -1,6 +1,33 @@
-import Field from "../Field";
-import Validator from "../../../../core/utils/validator";
-
+import Field from '../../field/Field';
+import Validator from '../../../../core/utils/validator';
+
+/**
+ * Radio button group for single-value selection from a list of options.
+ * Supports vertical/horizontal/grid layout and reactive model binding.
+ * @example
+ * const field = new RadioField('gender')
+ *     .label(Span('Gender'))
+ *     .option('male', Span('Male'))
+ *     .option('female', Span('Female'))
+ *     .option('other', Span('Other'))
+ *     .horizontal()
+ *     .model(genderObs)
+ *     .required();
+ *
+ * RadioField.use((description, instance) => {
+ *     // description.options — Array<{ value, label, props }>
+ *     // description.layout, description.checked
+ *     return Div({ class: \`radio-group radio-group--\${description.layout}\` },
+ *         ...description.options.map(opt =>
+ *             Label(Input({ type: 'radio', value: opt.value }), opt.label)
+ *         )
+ *     );
+ * });
+ *
+ * @constructor
+ * @param {string} name
+ * @param {GlobalAttributes} [props={}]
+ */
 export default function RadioField(name, props = {}) {
     if(!(this instanceof RadioField)) {
         return new RadioField(name, props);
@@ -11,12 +38,30 @@ export default function RadioField(name, props = {}) {
     Object.assign(this.$description, {
         options: [],
         layout: 'vertical',
-        checked: false
+        checked: false,
     });
 }
 
 RadioField.defaultTemplate = null;
 
+/**
+ * Registers the render template for RadioField.
+ * @param {(description: {
+ *     name: string,
+ *     type: 'radio',
+ *     label: NdChild|null,
+ *     options: Array<{ value: *, label: NdChild, props: GlobalAttributes }>,
+ *     layout: 'vertical'|'horizontal'|'grid',
+ *     checked: Observable<*>|boolean,
+ *     value: Observable<*>|null,
+ *     disabled: boolean|Observable<boolean>,
+ *     readonly: boolean|Observable<boolean>,
+ *     hasErrors: Observable<boolean>,
+ *     errors: Observable<string[]>,
+ *     showErrors: Observable<boolean>,
+ *     props: GlobalAttributes
+ * }, instance: RadioField) => NdChild} template
+ */
 RadioField.use = function(template) {
     RadioField.defaultTemplate = template;
 };
@@ -24,21 +69,40 @@ RadioField.use = function(template) {
 RadioField.prototype = Object.create(Field.prototype);
 RadioField.prototype.constructor = RadioField;
 
+/**
+ * @param {Array<{ value: *, label: NdChild, props?: GlobalAttributes }>} opts
+ * @returns {this}
+ */
 RadioField.prototype.options = function(opts) {
     this.$description.options = opts;
     return this;
 };
 
+/**
+ * @param {*} value
+ * @param {NdChild} label
+ * @param {GlobalAttributes} [props={}]
+ * @returns {this}
+ */
 RadioField.prototype.option = function(value, label, props = {}) {
     this.$description.options.push({ value, label, props });
     return this;
 };
 
+/**
+ * Binds the selected value to an observable.
+ * @param {Observable<*>} observable
+ * @returns {this}
+ */
 RadioField.prototype.model = function(observable) {
     this.$description.checked = observable;
     return this;
 };
 
+/**
+ * Returns the current checked value (resolves the observable if needed).
+ * @returns {*}
+ */
 RadioField.prototype.checked = function() {
     const checked = this.$description.checked;
     if(Validator.isObservable(checked)) {
@@ -47,6 +111,10 @@ RadioField.prototype.checked = function() {
     return checked;
 };
 
+/**
+ * @param {'vertical'|'horizontal'|'grid'} value
+ * @returns {this}
+ */
 RadioField.prototype.layout = function(value) {
     const allowedLayouts = ['vertical', 'horizontal', 'grid'];
 
@@ -58,16 +126,19 @@ RadioField.prototype.layout = function(value) {
     return this;
 };
 
+/** @returns {this} */
 RadioField.prototype.horizontal = function() {
     this.$description.layout = 'horizontal';
     return this;
 };
 
+/** @returns {this} */
 RadioField.prototype.vertical = function() {
     this.$description.layout = 'vertical';
     return this;
 };
 
+/** @returns {this} */
 RadioField.prototype.grid = function() {
     this.$description.layout = 'grid';
     return this;

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

@@ -1,5 +1,28 @@
-import NumberField from "./NumberField";
+import NumberField from '../../field/types/NumberField';
 
+/**
+ * Numeric range/slider field. Extends NumberField with visual slider controls,
+ * marks, tooltip display, and vertical orientation.
+ * @example
+ * const field = new RangeField('volume')
+ *     .label(Span('Volume'))
+ *     .min(0).max(100).step(5)
+ *     .showTooltip(true)
+ *     .marks([0, 25, 50, 75, 100])
+ *     .showMarks(true)
+ *     .model(volumeObs);
+ *
+ * RangeField.use((description, instance) => {
+ *     // description.showValue, description.marks, description.showMarks,
+ *     // description.vertical, description.showTooltip, description.step,
+ *     // description.min, description.max, description.value...
+ *     return Input({ type: 'range', min: description.min, max: description.max });
+ * });
+ *
+ * @constructor
+ * @param {string} name
+ * @param {GlobalAttributes} [props]
+ */
 export default function RangeField(name, props) {
     if(!(this instanceof RangeField)) {
         return new RangeField(name, props);
@@ -18,6 +41,29 @@ export default function RangeField(name, props) {
 
 RangeField.defaultTemplate = null;
 
+/**
+ * Registers the render template for RangeField.
+ * @param {(description: {
+ *     name: string,
+ *     type: 'range',
+ *     label: NdChild|null,
+ *     value: Observable<number>|null,
+ *     step: number|null,
+ *     min: number|null,
+ *     max: number|null,
+ *     showValue: boolean,
+ *     marks: number[]|Array<{ value: number, label?: NdChild }>|null,
+ *     showMarks: boolean,
+ *     vertical: boolean,
+ *     showTooltip: boolean,
+ *     disabled: boolean|Observable<boolean>,
+ *     readonly: boolean|Observable<boolean>,
+ *     hasErrors: Observable<boolean>,
+ *     errors: Observable<string[]>,
+ *     showErrors: Observable<boolean>,
+ *     props: GlobalAttributes
+ * }, instance: RangeField) => NdChild} template
+ */
 RangeField.use = function(template) {
     RangeField.defaultTemplate = template;
 };
@@ -25,26 +71,46 @@ RangeField.use = function(template) {
 RangeField.prototype = Object.create(NumberField.prototype);
 RangeField.prototype.constructor = RangeField;
 
+/**
+ * @param {boolean} [enabled=true]
+ * @returns {this}
+ */
 RangeField.prototype.showValue = function(enabled = true) {
     this.$description.showValue = enabled;
     return this;
 };
 
+/**
+ * @param {number[]|Array<{ value: number, label?: NdChild }>} marks
+ * @returns {this}
+ */
 RangeField.prototype.marks = function(marks) {
     this.$description.marks = marks;
     return this;
 };
 
+/**
+ * @param {boolean} [enabled=true]
+ * @returns {this}
+ */
 RangeField.prototype.showMarks = function(enabled = true) {
     this.$description.showMarks = enabled;
     return this;
 };
 
+/**
+ * @param {boolean} [enabled=true]
+ * @returns {this}
+ */
 RangeField.prototype.vertical = function(enabled = true) {
     this.$description.vertical = enabled;
     return this;
 };
 
+/**
+ * @param {boolean} [enabled=true]
+ * @returns {this}
+ */
 RangeField.prototype.showTooltip = function(enabled = true) {
     this.$description.showTooltip = enabled;
     return this;

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

@@ -1,5 +1,23 @@
-import StringField from "./StringField";
+import StringField from '../../field/types/StringField';
 
+/**
+ * Search input field with built-in debounce support.
+ * @example
+ * const field = new SearchField('query')
+ *     .label(Span('Search'))
+ *     .placeholder('Type to search...')
+ *     .debounce(400)
+ *     .model(searchQuery);
+ *
+ * SearchField.use((description, instance) => {
+ *     // description.debounce, description.value, description.placeholder...
+ *     return Input({ type: 'search', placeholder: description.placeholder });
+ * });
+ *
+ * @constructor
+ * @param {string} name
+ * @param {GlobalAttributes} [props]
+ */
 export default function SearchField(name, props) {
     if(!(this instanceof SearchField)) {
         return new SearchField(name, props);
@@ -8,12 +26,29 @@ export default function SearchField(name, props) {
     StringField.call(this, name, 'search', props);
 
     Object.assign(this.$description, {
-        debounce: 300
+        debounce: 300,
     });
 }
 
 SearchField.defaultTemplate = null;
 
+/**
+ * Registers the render template for SearchField.
+ * @param {(description: {
+ *     name: string,
+ *     type: 'search',
+ *     label: NdChild|null,
+ *     placeholder: NdChild|null,
+ *     value: Observable<string>|null,
+ *     debounce: number,
+ *     disabled: boolean|Observable<boolean>,
+ *     readonly: boolean|Observable<boolean>,
+ *     hasErrors: Observable<boolean>,
+ *     errors: Observable<string[]>,
+ *     showErrors: Observable<boolean>,
+ *     props: GlobalAttributes
+ * }, instance: SearchField) => NdChild} template
+ */
 SearchField.use = function(template) {
     SearchField.defaultTemplate = template;
 };
@@ -21,6 +56,10 @@ SearchField.use = function(template) {
 SearchField.prototype = Object.create(StringField.prototype);
 SearchField.prototype.constructor = SearchField;
 
+/**
+ * @param {number} ms - Debounce delay in milliseconds
+ * @returns {this}
+ */
 SearchField.prototype.debounce = function(ms) {
     this.$description.debounce = ms;
     return this;