native-document 1.0.165 → 1.0.168

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

@@ -1,7 +1,35 @@
-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';
+
+/**
+ * Time picker field with format, step, range mode, and time validation.
+ * @example
+ * const field = new TimeField('meetingTime')
+ *     .label(Span('Meeting time'))
+ *     .format('HH:mm')
+ *     .step(900) // 15 minute steps
+ *     .between('08:00', '18:00', 'Business hours only')
+ *     .required();
+ *
+ * // Time range
+ * const range = new TimeField('workingHours')
+ *     .range(true)
+ *     .modelStart(startObs)
+ *     .modelEnd(endObs)
+ *     .rangeSeparator(' - ');
+ *
+ * TimeField.use((description, instance) => {
+ *     // description.format, description.step, description.range,
+ *     // description.clearable, description.valueStart, description.valueEnd,
+ *     // description.rangeSeparator...
+ *     return Input({ type: 'time', step: description.step ?? undefined });
+ * });
+ *
+ * @constructor
+ * @param {string} name
+ * @param {GlobalAttributes} [props={}]
+ */
 export default function TimeField(name, props = {}) {
     if(!(this instanceof TimeField)) {
         return new TimeField(name, props);
@@ -17,12 +45,35 @@ export default function TimeField(name, props = {}) {
         valueStart:     null,
         valueEnd:       null,
         rangeSeparator: null,
-        props
+        props,
     });
 }
 
 TimeField.defaultTemplate = null;
 
+
+/**
+ * Registers the render template for TimeField.
+ * @param {(description: {
+ *     name: string,
+ *     type: 'time',
+ *     label: NdChild|null,
+ *     format: string,
+ *     step: number|null,
+ *     clearable: Observable<boolean>,
+ *     range: Observable<boolean>,
+ *     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: TimeField) => NdChild} template
+ */
 TimeField.use = function(template) {
     TimeField.defaultTemplate = template;
 };
@@ -30,26 +81,47 @@ TimeField.use = function(template) {
 TimeField.prototype = Object.create(Field.prototype);
 TimeField.prototype.constructor = TimeField;
 
+/**
+ * @param {string} formatString - e.g. 'HH:mm', 'HH:mm:ss'
+ * @returns {this}
+ */
 TimeField.prototype.format = function(formatString) {
     this.$description.format = formatString;
     return this;
 };
 
+/**
+ * @param {number} seconds - Step in seconds (e.g. 900 = 15 min)
+ * @returns {this}
+ */
 TimeField.prototype.step = function(seconds) {
     this.$description.step = seconds;
     return this;
 };
 
+/**
+ * @param {boolean} [enabled=true]
+ * @returns {this}
+ */
 TimeField.prototype.clearable = function(enabled = true) {
     this.$description.clearable = BaseComponent.obs(enabled);
     return this;
 };
 
+/**
+ * @param {boolean} [enabled=true]
+ * @returns {this}
+ */
 TimeField.prototype.range = function(enabled = true) {
     this.$description.range = BaseComponent.obs(enabled);
     return this;
 };
 
+/**
+ * Binds the start time in range mode to an observable.
+ * @param {Observable<*>} observable
+ * @returns {this}
+ */
 TimeField.prototype.modelStart = function(observable) {
     if(!this.$description.range) {
         console.warn('TimeField: modelStart is only available in range mode');
@@ -58,43 +130,86 @@ TimeField.prototype.modelStart = function(observable) {
     return this;
 };
 
+/**
+ * Binds the end time in range mode to an observable.
+ * @param {Observable<*>} observable
+ * @returns {this}
+ */
 TimeField.prototype.modelEnd = function(observable) {
     this.$description.valueEnd = observable;
     return this;
 };
 
+/**
+ * @param {string} sep
+ * @returns {this}
+ */
 TimeField.prototype.rangeSeparator = function(sep) {
     this.$description.rangeSeparator = sep;
     return this;
 };
 
+/**
+ * @param {(value: *) => void} handler
+ * @returns {this}
+ */
 TimeField.prototype.onChange = function(handler) {
     this.on('change', handler);
     return this;
 };
 
+/**
+ * @param {() => void} handler
+ * @returns {this}
+ */
 TimeField.prototype.onClear = function(handler) {
     this.on('clear', handler);
     return this;
 };
 
 // Validation
+/**
+ * @param {string} time - e.g. '08:00'
+ * @param {string} [message]
+ * @returns {this}
+ */
 TimeField.prototype.min = function(time, message) {
     return this.addRule(Validation.afterTime, [time], message);
 };
 
+/**
+ * @param {string} time
+ * @param {string} [message]
+ * @returns {this}
+ */
 TimeField.prototype.max = function(time, message) {
     return this.addRule(Validation.beforeTime, [time], message);
 };
 
+/**
+ * @param {string} startTime
+ * @param {string} endTime
+ * @param {string} [message]
+ * @returns {this}
+ */
 TimeField.prototype.between = function(startTime, endTime, message) {
     return this.addRule(Validation.betweenTimes, [startTime, endTime], message);
 };
 
+/**
+ * @param {string} time
+ * @param {string} [message]
+ * @returns {this}
+ */
 TimeField.prototype.after = function(time, message) {
     return this.addRule(Validation.afterTime, [time], message);
 };
 
+/**
+ * @param {string} time
+ * @param {string} [message]
+ * @returns {this}
+ */
 TimeField.prototype.before = function(time, message) {
     return this.addRule(Validation.beforeTime, [time], message);
 };

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

@@ -1,6 +1,27 @@
-import StringField from "./StringField";
-import {Validation} from "../../validation/Validation";
+import StringField from '../../field/types/StringField';
+import {Validation} from '../../validation/Validation';
 
+/**
+ * URL input field. Automatically validates URL format on creation.
+ * Supports protocol and domain allowlist rules.
+ * @example
+ * const field = new UrlField('website')
+ *     .label(Span('Website'))
+ *     .protocol(['https'], 'HTTPS only')
+ *     .domain(['example.com', 'example.org'])
+ *     .required();
+ *
+ * UrlField.use((description, instance) => {
+ *     // description.value, description.errors, description.label...
+ *     return Input({ type: 'url', placeholder: 'https://' });
+ * });
+ */
+
+/**
+ * @constructor
+ * @param {string} name
+ * @param {GlobalAttributes} [props]
+ */
 export default function UrlField(name, props) {
     if(!(this instanceof UrlField)) {
         return new UrlField(name, props);
@@ -12,6 +33,23 @@ export default function UrlField(name, props) {
 
 UrlField.defaultTemplate = null;
 
+
+/**
+ * Registers the render template for UrlField.
+ * @param {(description: {
+ *     name: string,
+ *     type: 'url',
+ *     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: UrlField) => NdChild} template
+ */
 UrlField.use = function(template) {
     UrlField.defaultTemplate = template;
 };
@@ -19,6 +57,12 @@ UrlField.use = function(template) {
 UrlField.prototype = Object.create(StringField.prototype);
 UrlField.prototype.constructor = UrlField;
 
+
+/**
+ * Customises the URL validation message.
+ * @param {string} message
+ * @returns {this}
+ */
 UrlField.prototype.url = function(message) {
     const existingRule = this.$description.rules.find(r => r.fn === Validation.url);
     if (existingRule && message) {
@@ -27,6 +71,12 @@ UrlField.prototype.url = function(message) {
     return this;
 };
 
+
+/**
+ * @param {string[]} allowedProtocols - e.g. ['https', 'http']
+ * @param {string} message
+ * @returns {this}
+ */
 UrlField.prototype.protocol = function(allowedProtocols, message) {
     this.$description.rules.push({
         validate: (value) => {
@@ -38,11 +88,16 @@ UrlField.prototype.protocol = function(allowedProtocols, message) {
                 return false;
             }
         },
-        message: message || `Allowed protocols: ${allowedProtocols.join(', ')}`
+        message: message || `Allowed protocols: ${allowedProtocols.join(', ')}`,
     });
     return this;
 };
 
+/**
+ * @param {string[]} allowedDomains
+ * @param {string} message
+ * @returns {this}
+ */
 UrlField.prototype.domain = function(allowedDomains, message) {
     this.$description.rules.push({
         validate: (value) => {
@@ -54,7 +109,7 @@ UrlField.prototype.domain = function(allowedDomains, message) {
                 return false;
             }
         },
-        message: message || `Allowed domains: ${allowedDomains.join(', ')}`
+        message: message || `Allowed domains: ${allowedDomains.join(', ')}`,
     });
     return this;
 };

package/src/components/form/field/types/file-field-mode/FileAvatarMode.js

@@ -1,6 +1,27 @@
-import BaseComponent from "../../../../BaseComponent";
-import HasEventEmitter from "../../../../../core/utils/HasEventEmitter";
-
+import BaseComponent from '../../../../BaseComponent';
+import HasEventEmitter from '../../../../../core/utils/HasEventEmitter';
+
+/**
+ * Avatar-style single file upload mode for FileField.
+ * Displays a circular or square avatar with hover/badge/button interaction variants.
+ * Ideal for profile picture uploads.
+ * @example
+ * new FileField('avatar')
+ *     .mode('avatar');
+ *
+ * FileAvatarMode.use((description, instance) => {
+ *     // description.variant — 'hover-overlay' | 'corner-badge' | 'action-buttons'
+ *     // description.shape   — 'circle' | 'square'
+ *     // description.size, description.placeholderIcon, description.overlayIcon,
+ *     // description.editImageIcon, description.changeLabel, description.removeLabel,
+ *     // description.renderAvatar, description.renderOverlay, description.renderActions
+ *     return Div({ class: \`avatar-upload avatar-upload--\${description.variant}\`,
+ *                  style: { width: description.size, height: description.size } });
+ * });
+ *
+ * @constructor
+ * @param {GlobalAttributes} [props={}]
+ */
 export default function FileAvatarMode(props = {}) {
     if(!(this instanceof FileAvatarMode)) {
         return new FileAvatarMode(props);
@@ -20,7 +41,7 @@ export default function FileAvatarMode(props = {}) {
         renderAvatar: null,
         renderOverlay: null,
         renderActions: null,
-        props
+        props,
     };
 }
 
@@ -29,75 +50,133 @@ BaseComponent.use(FileAvatarMode, HasEventEmitter);
 
 FileAvatarMode.defaultTemplate = null;
 
+/**
+ * Registers the render template for FileAvatarMode.
+ * @param {(description: {
+ *     variant: 'hover-overlay'|'corner-badge'|'action-buttons',
+ *     shape: 'circle'|'square',
+ *     size: number|string,
+ *     placeholderIcon: NdChild|null,
+ *     overlayIcon: NdChild|null,
+ *     editImageIcon: NdChild|null,
+ *     changeLabel: NdChild,
+ *     removeLabel: NdChild,
+ *     renderAvatar: ((desc: *, instance: FileAvatarMode) => NdChild)|null,
+ *     renderOverlay: ((desc: *, instance: FileAvatarMode) => NdChild)|null,
+ *     renderActions: ((desc: *, instance: FileAvatarMode) => NdChild)|null,
+ *     props: GlobalAttributes
+ * }, instance: FileAvatarMode) => NdChild} template
+ */
 FileAvatarMode.use = function(template) {
     FileAvatarMode.defaultTemplate = template;
 };
 
+/** @returns {this} */
 FileAvatarMode.prototype.hoverOverlay = function() {
     this.$description.variant = 'hover-overlay';
     return this;
 };
 
+/** @returns {this} */
 FileAvatarMode.prototype.cornerBadge = function() {
     this.$description.variant = 'corner-badge';
     return this;
 };
 
+/** @returns {this} */
 FileAvatarMode.prototype.actionButtons = function() {
     this.$description.variant = 'action-buttons';
     return this;
 };
 
+/** @returns {this} */
 FileAvatarMode.prototype.circle = function() {
     this.$description.shape = 'circle';
     return this;
 };
 
+/** @returns {this} */
 FileAvatarMode.prototype.square = function() {
     this.$description.shape = 'square';
     return this;
 };
 
+/**
+ * @param {number|string} size - Size in pixels or CSS value
+ * @returns {this}
+ */
 FileAvatarMode.prototype.size = function(size) {
     this.$description.size = size;
     return this;
 };
 
+/**
+ * @param {NdChild} icon
+ * @returns {this}
+ */
 FileAvatarMode.prototype.placeholderIcon = function(icon) {
     this.$description.placeholderIcon = icon;
     return this;
 };
 
+/**
+ * @param {NdChild} icon
+ * @returns {this}
+ */
 FileAvatarMode.prototype.overlayIcon = function(icon) {
     this.$description.overlayIcon = icon;
     return this;
 };
 
+/**
+ * @param {NdChild} icon
+ * @returns {this}
+ */
 FileAvatarMode.prototype.editImageIcon = function(icon) {
     this.$description.editImageIcon = icon;
     return this;
 };
 
+/**
+ * @param {NdChild} label
+ * @returns {this}
+ */
 FileAvatarMode.prototype.changeLabel = function(label) {
     this.$description.changeLabel = label;
     return this;
 };
 
+/**
+ * @param {NdChild} label
+ * @returns {this}
+ */
 FileAvatarMode.prototype.removeLabel = function(label) {
     this.$description.removeLabel = label;
     return this;
 };
 
+/**
+ * @param {(desc: *, instance: FileAvatarMode) => NdChild} fn
+ * @returns {this}
+ */
 FileAvatarMode.prototype.renderAvatar = function(fn) {
     this.$description.renderAvatar = fn;
     return this;
 };
 
+/**
+ * @param {(desc: *, instance: FileAvatarMode) => NdChild} fn
+ * @returns {this}
+ */
 FileAvatarMode.prototype.renderOverlay = function(fn) {
     this.$description.renderOverlay = fn;
     return this;
 };
 
+/**
+ * @param {(desc: *, instance: FileAvatarMode) => NdChild} fn
+ * @returns {this}
+ */
 FileAvatarMode.prototype.renderActions = function(fn) {
     this.$description.renderActions = fn;
     return this;

package/src/components/form/field/types/file-field-mode/FileDropzoneMode.js

@@ -1,6 +1,28 @@
-import BaseComponent from "../../../../BaseComponent";
-import HasEventEmitter from "../../../../../core/utils/HasEventEmitter";
+import BaseComponent from '../../../../BaseComponent';
+import HasEventEmitter from '../../../../../core/utils/HasEventEmitter';
 
+/**
+ * Drag-and-drop zone mode for FileField.
+ * Renders a clickable dropzone with configurable icon, text, hint, and height.
+ * @example
+ * new FileField('documents')
+ *     .mode('dropzone');
+ *
+ * FileDropzoneMode.use((description, instance) => {
+ *     // description.icon, description.text, description.hint,
+ *     // description.height, description.removeIcon
+ *     return Div({ class: 'dropzone', style: { height: description.height } },
+ *         description.icon,
+ *         Span(description.text),
+ *         ShowIf(description.hint, () => Span({ class: 'hint' }, description.hint)),
+ *     );
+ * });
+ */
+
+/**
+ * @constructor
+ * @param {GlobalAttributes} [props={}]
+ */
 export default function FileDropzoneMode(props = {}) {
     if(!(this instanceof FileDropzoneMode)) {
         return new FileDropzoneMode(props);
@@ -15,7 +37,7 @@ export default function FileDropzoneMode(props = {}) {
         height:     null,
         renderZone: null,
         removeIcon: null,
-        props
+        props,
     };
 }
 
@@ -24,35 +46,71 @@ BaseComponent.use(FileDropzoneMode, HasEventEmitter);
 
 FileDropzoneMode.defaultTemplate = null;
 
+/**
+ * Registers the render template for FileDropzoneMode.
+ * @param {(description: {
+ *     icon: NdChild|null,
+ *     text: NdChild,
+ *     hint: NdChild|null,
+ *     height: string|number|null,
+ *     renderZone: ((desc: *, instance: FileDropzoneMode) => NdChild)|null,
+ *     removeIcon: NdChild|null,
+ *     props: GlobalAttributes
+ * }, instance: FileDropzoneMode) => NdChild} template
+ */
 FileDropzoneMode.use = function(template) {
     FileDropzoneMode.defaultTemplate = template;
 };
 
+/**
+ * @param {NdChild} icon
+ * @returns {this}
+ */
 FileDropzoneMode.prototype.icon = function(icon) {
     this.$description.icon = icon;
     return this;
 };
 
+/**
+ * @param {NdChild} text
+ * @returns {this}
+ */
 FileDropzoneMode.prototype.text = function(text) {
     this.$description.text = text;
     return this;
 };
 
+/**
+ * @param {NdChild} hint
+ * @returns {this}
+ */
 FileDropzoneMode.prototype.hint = function(hint) {
     this.$description.hint = hint;
     return this;
 };
 
+/**
+ * @param {string|number} value
+ * @returns {this}
+ */
 FileDropzoneMode.prototype.height = function(value) {
     this.$description.height = value;
     return this;
 };
 
+/**
+ * @param {(desc: *, instance: FileDropzoneMode) => NdChild} fn
+ * @returns {this}
+ */
 FileDropzoneMode.prototype.renderZone = function(fn) {
     this.$description.renderZone = fn;
     return this;
 };
 
+/**
+ * @param {NdChild} icon
+ * @returns {this}
+ */
 FileDropzoneMode.prototype.removeIcon = function(icon) {
     this.$description.removeIcon = icon;
     return this;