native-document 1.0.165 → 1.0.168

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

@@ -1,7 +1,27 @@
 // ColorField.js
-import Field from "../Field";
-import {Validation} from "../../validation/Validation";
+import Field from '../../field/Field';
+import {Validation} from '../../validation/Validation';
 
+/**
+ * Color picker field supporting hex, RGB, and HSL formats.
+ * Optionally displays a preset color palette.
+ * @example
+ * const field = new ColorField('brandColor')
+ *     .label(Span('Brand color'))
+ *     .format('hex')
+ *     .presets(['#FF0000', '#00FF00', '#0000FF'])
+ *     .hex('Must be a valid hex color')
+ *     .required();
+ *
+ * ColorField.use((description, instance) => {
+ *     // description.format, description.presets
+ *     return Input({ type: 'color' });
+ * });
+ *
+ * @constructor
+ * @param {string} name
+ * @param {GlobalAttributes} [props]
+ */
 export default function ColorField(name, props) {
     if(!(this instanceof ColorField)) {
         return new ColorField(name, props);
@@ -11,12 +31,29 @@ export default function ColorField(name, props) {
 
     Object.assign(this.$description, {
         format: 'hex',
-        presets: null
+        presets: null,
     });
 }
 
 ColorField.defaultTemplate = null;
 
+/**
+ * Registers the render template for ColorField.
+ * @param {(description: {
+ *     name: string,
+ *     type: 'color',
+ *     label: NdChild|null,
+ *     value: Observable<string>|null,
+ *     format: 'hex'|'rgb'|'hsl',
+ *     presets: string[]|null,
+ *     disabled: boolean|Observable<boolean>,
+ *     readonly: boolean|Observable<boolean>,
+ *     hasErrors: Observable<boolean>,
+ *     errors: Observable<string[]>,
+ *     showErrors: Observable<boolean>,
+ *     props: GlobalAttributes
+ * }, instance: ColorField) => NdChild} template
+ */
 ColorField.use = function(template) {
     ColorField.defaultTemplate = template;
 };
@@ -24,6 +61,10 @@ ColorField.use = function(template) {
 ColorField.prototype = Object.create(Field.prototype);
 ColorField.prototype.constructor = ColorField;
 
+/**
+ * @param {'hex'|'rgb'|'hsl'} formatType
+ * @returns {this}
+ */
 ColorField.prototype.format = function(formatType) {
     const allowedFormats = ['hex', 'rgb', 'hsl'];
 
@@ -35,15 +76,27 @@ ColorField.prototype.format = function(formatType) {
     return this;
 };
 
+/**
+ * @param {string[]} colors
+ * @returns {this}
+ */
 ColorField.prototype.presets = function(colors) {
     this.$description.presets = colors;
     return this;
 };
 
+/**
+ * @param {string} [message]
+ * @returns {this}
+ */
 ColorField.prototype.hex = function(message) {
     return this.addRule(Validation.hexColor, [], message);
 };
 
+/**
+ * @param {string} [message]
+ * @returns {this}
+ */
 ColorField.prototype.rgb = function(message) {
     return this.addRule(Validation.rgbColor, [], message);
 };

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

@@ -1,7 +1,36 @@
-import Field from "../Field";
-import {Validation} from "../../validation/Validation";
-import BaseComponent from "../../../BaseComponent";
+import Field from '../../field/Field';
+import {Validation} from '../../validation/Validation';
+import BaseComponent from '../../../BaseComponent';
 
+/**
+ * Date picker field with format, min/max, disabled dates, range mode, timezone,
+ * and locale support. Use modelStart/modelEnd for range mode.
+ * @example
+ * const field = new DateField('birthdate')
+ *     .label(Span('Date of birth'))
+ *     .format('DD/MM/YYYY')
+ *     .untilToday()
+ *     .required();
+ *
+ * // Date range
+ * const range = new DateField('period')
+ *     .range(true)
+ *     .modelStart(startObs)
+ *     .modelEnd(endObs)
+ *     .rangeSeparator(' to ');
+ *
+ * DateField.use((description, instance) => {
+ *     // description.format, description.minDate, description.maxDate,
+ *     // description.disabledDates, description.range, description.withTime,
+ *     // description.firstDayOfWeek, description.locale, description.timezone,
+ *     // description.valueStart, description.valueEnd, description.rangeSeparator...
+ *     return Input({ type: 'text', placeholder: description.format });
+ * });
+ *
+ * @constructor
+ * @param {string} name
+ * @param {GlobalAttributes} [props={}]
+ */
 export default function DateField(name, props = {}) {
     if(!(this instanceof DateField)) {
         return new DateField(name, props);
@@ -24,12 +53,41 @@ export default function DateField(name, props = {}) {
         valueStart:     null,
         valueEnd:       null,
         rangeSeparator:       null,
-        props
+        props,
     });
 }
 
 DateField.defaultTemplate = null;
 
+/**
+ * Registers the render template for DateField.
+ * @param {(description: {
+ *     name: string,
+ *     type: 'date',
+ *     label: NdChild|null,
+ *     format: string,
+ *     minDate: Observable<string|Date>|null,
+ *     maxDate: Observable<string|Date>|null,
+ *     disabledDates: Observable<(string|Date)[]>|null,
+ *     clearable: boolean,
+ *     withTime: Observable<boolean>,
+ *     range: Observable<boolean>,
+ *     firstDayOfWeek: 'monday'|'sunday',
+ *     locale: string|null,
+ *     timeStep: number|null,
+ *     timezone: string|null,
+ *     valueStart: Observable<*>|null,
+ *     valueEnd: Observable<*>|null,
+ *     rangeSeparator: string|null,
+ *     value: Observable<*>|null,
+ *     disabled: boolean|Observable<boolean>,
+ *     readonly: boolean|Observable<boolean>,
+ *     hasErrors: Observable<boolean>,
+ *     errors: Observable<string[]>,
+ *     showErrors: Observable<boolean>,
+ *     props: GlobalAttributes
+ * }, instance: DateField) => NdChild} template
+ */
 DateField.use = function(template) {
     DateField.defaultTemplate = template;
 };
@@ -37,81 +95,131 @@ DateField.use = function(template) {
 DateField.prototype = Object.create(Field.prototype);
 DateField.prototype.constructor = DateField;
 
+/**
+ * @param {string} rangeSeparator
+ * @returns {this}
+ */
 DateField.prototype.rangeSeparator = function(rangeSeparator) {
     this.$description.rangeSeparator = rangeSeparator;
     return this;
 };
 
+/**
+ * @param {string} formatString - e.g. 'YYYY-MM-DD', 'DD/MM/YYYY'
+ * @returns {this}
+ */
 DateField.prototype.format = function(formatString) {
     this.$description.format = formatString;
     return this;
 };
 
+/**
+ * @param {Date|string} date
+ * @returns {this}
+ */
 DateField.prototype.minDate = function(date) {
     this.$description.minDate = BaseComponent.obs(date);
     return this;
 };
 
+/**
+ * @param {Date|string} date
+ * @returns {this}
+ */
 DateField.prototype.maxDate = function(date) {
     this.$description.maxDate = BaseComponent.obs(date);
     return this;
 };
 
+/**
+ * @param {(Date|string)[]} dates
+ * @returns {this}
+ */
 DateField.prototype.disabledDates = function(dates) {
     this.$description.disabledDates = BaseComponent.obs(dates);
     return this;
 };
 
+/**
+ * @param {boolean} [enabled=true]
+ * @returns {this}
+ */
 DateField.prototype.withTime = function(enabled = true) {
     this.$description.withTime = BaseComponent.obs(enabled);
     return this;
 };
 
+/**
+ * @param {boolean} [enabled=true]
+ * @returns {this}
+ */
 DateField.prototype.range = function(enabled = true) {
     this.$description.range = BaseComponent.obs(enabled);
     return this;
 };
 
+/** @returns {this} */
 DateField.prototype.mondayAsFirstDay = function() {
     this.$description.firstDayOfWeek = 'monday';
     return this;
 };
 
+/** @returns {this} */
 DateField.prototype.sundayAsFirstDay = function() {
     this.$description.firstDayOfWeek = 'sunday';
     return this;
 };
 
+/**
+ * @param {string} locale - BCP 47 locale tag (e.g. 'fr-FR', 'en-US')
+ * @returns {this}
+ */
 DateField.prototype.locale = function(locale) {
     this.$description.locale = locale;
     return this;
 };
 
+/**
+ * @param {number} secondes - Step in seconds for time picker
+ * @returns {this}
+ */
 DateField.prototype.timeStep = function(secondes) {
     this.$description.timeStep = secondes;
     return this;
 };
 
+/** Sets minDate to today. @returns {this} */
 DateField.prototype.fromToday = function() {
     this.$description.minDate = BaseComponent.obs(new Date().toISOString().split('T')[0]);
     return this;
 };
 
+/** Sets maxDate to today. @returns {this} */
 DateField.prototype.untilToday = function() {
     this.$description.maxDate = BaseComponent.obs(new Date().toISOString().split('T')[0]);
     return this;
 };
 
+/**
+ * @param {string} tz - IANA timezone (e.g. 'Europe/Paris')
+ * @returns {this}
+ */
 DateField.prototype.timezone = function(tz) {
     this.$description.timezone = tz;
     return this;
 };
 
+/** Uses the browser's local timezone. @returns {this} */
 DateField.prototype.useLocalTimezone = function() {
     this.$description.timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
     return this;
 };
 
+/**
+ * Binds the start date in range mode to an observable.
+ * @param {Observable<*>} observable
+ * @returns {this}
+ */
 DateField.prototype.modelStart = function(observable) {
     if(!this.$description.range) {
         console.warn('DateField: modelStart is only available in range mode');
@@ -120,6 +228,11 @@ DateField.prototype.modelStart = function(observable) {
     return this;
 };
 
+/**
+ * Binds the end date in range mode to an observable.
+ * @param {Observable<*>} observable
+ * @returns {this}
+ */
 DateField.prototype.modelEnd = function(observable) {
     if(!this.$description.range) {
         console.warn('DateField: modelEnd is only available in range mode');
@@ -128,37 +241,75 @@ DateField.prototype.modelEnd = function(observable) {
     return this;
 };
 
+/**
+ * @param {(date: *) => void} handler
+ * @returns {this}
+ */
 DateField.prototype.onChange = function(handler) {
     this.on('change', handler);
     return this;
 };
 
+/**
+ * @param {() => void} handler
+ * @returns {this}
+ */
 DateField.prototype.onClear = function(handler) {
     this.on('clear', handler);
     return this;
 };
 
 // Validation
+/**
+ * @param {Date|string} date
+ * @param {string} [message]
+ * @returns {this}
+ */
 DateField.prototype.min = function(date, message) {
     return this.addRule(Validation.afterDate, [date], message);
 };
 
+/**
+ * @param {Date|string} date
+ * @param {string} [message]
+ * @returns {this}
+ */
 DateField.prototype.max = function(date, message) {
     return this.addRule(Validation.beforeDate, [date], message);
 };
 
+/**
+ * @param {Date|string} startDate
+ * @param {Date|string} endDate
+ * @param {string} [message]
+ * @returns {this}
+ */
 DateField.prototype.between = function(startDate, endDate, message) {
     return this.addRule(Validation.betweenDates, [startDate, endDate], message);
 };
 
+/**
+ * @param {Date|string} date
+ * @param {string} [message]
+ * @returns {this}
+ */
 DateField.prototype.before = function(date, message) {
     return this.addRule(Validation.beforeDate, [date], message);
 };
 
+/**
+ * @param {string} [message]
+ * @returns {this}
+ */
 DateField.prototype.weekday = function(message) {
     return this.addRule(Validation.weekday, [], message);
 };
 
+/**
+ * @param {Date|string} date
+ * @param {string} [message]
+ * @returns {this}
+ */
 DateField.prototype.after = function(date, message) {
     return this.addRule(Validation.afterDate, [date], message);
 };

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

@@ -1,6 +1,25 @@
-import Field from "../Field";
-import {Validation} from "../../validation/Validation";
+import Field from '../../field/Field';
+import {Validation} from '../../validation/Validation';
 
+/**
+ * Email input field. Automatically applies email format validation on creation.
+ * Supports domain allowlist/blocklist rules.
+ * @example
+ * const field = new EmailField('email')
+ *     .label(Span('Email'))
+ *     .allowedDomain(['company.com'], 'Only company emails allowed')
+ *     .required();
+ *
+ * EmailField.use((description, instance) => {
+ *     // description.name, description.value, description.errors,
+ *     // description.label, description.placeholder...
+ *     return Input({ type: 'email', placeholder: description.placeholder });
+ * });
+ *
+ * @constructor
+ * @param {string} name
+ * @param {GlobalAttributes} [defaultConfig]
+ */
 export default function EmailField(name, defaultConfig) {
     if(!(this instanceof EmailField)) {
         return new EmailField(name, defaultConfig);
@@ -14,6 +33,22 @@ export default function EmailField(name, defaultConfig) {
 
 EmailField.defaultTemplate = null;
 
+/**
+ * Registers the render template for EmailField.
+ * @param {(description: {
+ *     name: string,
+ *     type: 'email',
+ *     label: NdChild|null,
+ *     placeholder: NdChild|null,
+ *     value: Observable<string>|null,
+ *     disabled: boolean|Observable<boolean>,
+ *     readonly: boolean|Observable<boolean>,
+ *     hasErrors: Observable<boolean>,
+ *     errors: Observable<string[]>,
+ *     showErrors: Observable<boolean>,
+ *     props: GlobalAttributes
+ * }, instance: EmailField) => NdChild} template
+ */
 EmailField.use = function(template) {
     EmailField.defaultTemplate = template;
 };
@@ -21,6 +56,11 @@ EmailField.use = function(template) {
 EmailField.prototype = Object.create(Field.prototype);
 EmailField.prototype.constructor = EmailField;
 
+/**
+ * Customises the email format validation message.
+ * @param {string} [message]
+ * @returns {this}
+ */
 EmailField.prototype.email = function(message) {
     const existingRule = this.$description.rules.find(r => r.fn === Validation.email);
     if (existingRule && message) {
@@ -29,6 +69,11 @@ EmailField.prototype.email = function(message) {
     return this;
 };
 
+/**
+ * @param {string[]} allowedDomains
+ * @param {string} [message]
+ * @returns {this}
+ */
 EmailField.prototype.allowedDomain = function(allowedDomains, message) {
     this.$description.rules.push({
         validate: (value) => {
@@ -36,11 +81,16 @@ EmailField.prototype.allowedDomain = function(allowedDomains, message) {
             const domain = value.split('@')[1];
             return allowedDomains.includes(domain);
         },
-        message: message || `Allowed domains: ${allowedDomains.join(', ')}`
+        message: message || `Allowed domains: ${allowedDomains.join(', ')}`,
     });
     return this;
 };
 
+/**
+ * @param {string[]} blockedDomains
+ * @param {string} [message]
+ * @returns {this}
+ */
 EmailField.prototype.notAllowedDomain = function(blockedDomains, message) {
     this.$description.rules.push({
         validate: (value) => {
@@ -48,7 +98,7 @@ EmailField.prototype.notAllowedDomain = function(blockedDomains, message) {
             const domain = value.split('@')[1];
             return !blockedDomains.includes(domain);
         },
-        message: message || `Domain not allowed`
+        message: message || 'Domain not allowed',
     });
     return this;
 };