native-document 1.0.165 → 1.0.168

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

@@ -1,8 +1,32 @@
-import Field from "../Field";
-import {Validation} from "../../validation/Validation";
+import Field from '../../field/Field';
+import {Validation} from '../../validation/Validation';
 import { $ } from '../../../../core/data/Observable';
-import FileItemPreview from "./file-field-mode/FileItemPreview";
+import FileItemPreview from '../../field/types/file-field-mode/FileItemPreview';
 
+/**
+ * File upload field. Supports single/multiple files, MIME type and extension filtering,
+ * size validation, file count limits, and multiple display modes (native, dropzone, button, wall, avatar).
+ * @example
+ * const field = new FileField('documents')
+ *     .label(Span('Upload documents'))
+ *     .multiple(true)
+ *     .accept(['application/pdf', 'image/png'])
+ *     .maxSize(5 * 1024 * 1024, 'Max 5MB per file')
+ *     .maxFiles(3, 'Max 3 files')
+ *     .mode('dropzone')
+ *     .onFileAdd((file) => console.log('added', file.name))
+ *     .onFileRemove((file) => console.log('removed', file.name));
+ *
+ * FileField.use((description, instance) => {
+ *     // description.accept, description.multiple, description.mode,
+ *     // description.files — Observable<FileItemPreview[]>, description.fileIcons...
+ *     return Input({ type: 'file', multiple: description.multiple });
+ * });
+ *
+ * @constructor
+ * @param {string} name
+ * @param {GlobalAttributes} [props={}]
+ */
 export default function FileField(name, props = {}) {
     if(!(this instanceof FileField)) {
         return new FileField(name, props);
@@ -16,12 +40,31 @@ export default function FileField(name, props = {}) {
         mode:     null,
         files:    $.array([]),
         fileIcons: [],
-        props
+        props,
     });
 }
 
 FileField.defaultTemplate = null;
 
+/**
+ * Registers the render template for FileField.
+ * @param {(description: {
+ *     name: string,
+ *     type: 'file',
+ *     label: NdChild|null,
+ *     accept: string|null,
+ *     multiple: boolean,
+ *     mode: 'native'|'dropzone'|'button'|'wall'|'avatar'|null,
+ *     files: Observable<FileItemPreview[]>,
+ *     fileIcons: Array<(file: File) => NdChild>,
+ *     disabled: boolean|Observable<boolean>,
+ *     readonly: boolean|Observable<boolean>,
+ *     hasErrors: Observable<boolean>,
+ *     errors: Observable<string[]>,
+ *     showErrors: Observable<boolean>,
+ *     props: GlobalAttributes
+ * }, instance: FileField) => NdChild} template
+ */
 FileField.use = function(template) {
     FileField.defaultTemplate = template;
 };
@@ -29,60 +72,120 @@ FileField.use = function(template) {
 FileField.prototype = Object.create(Field.prototype);
 FileField.prototype.constructor = FileField;
 
+/**
+ * @param {string|string[]} mimeTypes
+ * @returns {this}
+ */
 FileField.prototype.accept = function(mimeTypes) {
     this.$description.accept = Array.isArray(mimeTypes) ? mimeTypes.join(',') : mimeTypes;
     return this;
 };
 
+/**
+ * @param {boolean} [enabled=true]
+ * @returns {this}
+ */
 FileField.prototype.multiple = function(enabled = true) {
     this.$description.multiple = enabled;
     return this;
 };
 
+/**
+ * @param {'native'|'dropzone'|'button'|'wall'|'avatar'} mode
+ * @returns {this}
+ */
 FileField.prototype.mode = function(mode) {
     this.$description.mode = mode;
     return this;
 };
 
+/**
+ * @param {number} bytes
+ * @param {string} [message]
+ * @returns {this}
+ */
 FileField.prototype.maxSize = function(bytes, message) {
     return this.addRule(Validation.maxFileSize, [bytes], message);
 };
 
+/**
+ * @param {number} bytes
+ * @param {string} [message]
+ * @returns {this}
+ */
 FileField.prototype.minSize = function(bytes, message) {
     return this.addRule(Validation.minFileSize, [bytes], message);
 };
 
+/**
+ * @param {string[]} types - e.g. ['image/png', 'application/pdf']
+ * @param {string} [message]
+ * @returns {this}
+ */
 FileField.prototype.mimeTypes = function(types, message) {
     return this.addRule(Validation.mimeTypes, [types], message);
 };
 
+/**
+ * @param {string[]} extensions - e.g. ['.pdf', '.docx']
+ * @param {string} [message]
+ * @returns {this}
+ */
 FileField.prototype.extensions = function(extensions, message) {
     return this.addRule(Validation.extensions, [extensions], message);
 };
 
+/**
+ * @param {number} max
+ * @param {string} [message]
+ * @returns {this}
+ */
 FileField.prototype.maxFiles = function(max, message) {
     return this.addRule(Validation.maxFiles, [max], message);
 };
 
+/**
+ * @param {number} min
+ * @param {string} [message]
+ * @returns {this}
+ */
 FileField.prototype.minFiles = function(min, message) {
     return this.addRule(Validation.minFiles, [min], message);
 };
 
+/**
+ * @param {(file: File) => void} handler
+ * @returns {this}
+ */
 FileField.prototype.onFileAdd = function(handler) {
     this.on('fileAdd', handler);
     return this;
 };
 
+/**
+ * @param {() => void} handler
+ * @returns {this}
+ */
 FileField.prototype.onReset = function(handler) {
     this.on('reset', handler);
     return this;
 };
 
+/**
+ * @param {(file: File) => void} handler
+ * @returns {this}
+ */
 FileField.prototype.onFileRemove = function(handler) {
     this.on('fileRemove', handler);
     return this;
 };
 
+/**
+ * Adds a single file and optionally triggers a value update.
+ * @param {File} file
+ * @param {boolean} [update=true]
+ * @returns {this}
+ */
 FileField.prototype.addFile = function(file, update = true) {
     const item = new FileItemPreview(file);
     this.$description.files.push(item);
@@ -91,11 +194,21 @@ FileField.prototype.addFile = function(file, update = true) {
     return this;
 };
 
+/**
+ * Replaces all current files with the given list.
+ * @param {File[]} files
+ * @returns {this}
+ */
 FileField.prototype.setFiles = function(files) {
     this.$description.files.clear();
     this.addFiles(files);
     return this;
-}
+};
+
+/**
+ * @param {File[]} files
+ * @returns {this}
+ */
 FileField.prototype.addFiles = function(files) {
     if (!Array.isArray(files)) {
         throw new Error('addFiles expects an array of files');
@@ -113,6 +226,10 @@ FileField.prototype.$update = function() {
     this.validate();
 };
 
+/**
+ * @param {File} file
+ * @returns {this}
+ */
 FileField.prototype.removeFile = function(file) {
     this.$description.files.remove(file);
     this.emit('fileRemove', file);
@@ -120,10 +237,17 @@ FileField.prototype.removeFile = function(file) {
     return this;
 };
 
+/**
+ * @returns {File[]}
+ */
 FileField.prototype.getFiles = function() {
     return this.$description.files.val();
 };
 
+/**
+ * Clears all files and emits the reset event.
+ * @returns {this}
+ */
 FileField.prototype.reset = function() {
     this.$description.files.clear();
     this.emit('reset');
@@ -131,12 +255,22 @@ FileField.prototype.reset = function() {
     return this;
 };
 
+/**
+ * Adds a custom icon resolver for a specific file.
+ * @param {(file: File) => NdChild} desc
+ * @returns {this}
+ */
 FileField.prototype.fileIcon = function(desc) {
     this.$description.fileIcons.push(desc);
     return this;
 };
 
+/**
+ * Sets icon resolvers by file extension or MIME type.
+ * @param {Record<string, NdChild>} icons
+ * @returns {this}
+ */
 FileField.prototype.fileIcons = function(icons) {
     this.$description.fileIcons = icons;
     return this;
-}
+};

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

@@ -1,5 +1,21 @@
-import Field from "../Field";
+import Field from '../../field/Field';
 
+/**
+ * Hidden field for carrying form values that are not displayed to the user.
+ * Participates in FormControl validation and value collection.
+ * @example
+ * const field = new HiddenField('userId')
+ *     .model(userIdObs);
+ *
+ * HiddenField.use((description, instance) => {
+ *     // description.name, description.value
+ *     return Input({ type: 'hidden', name: description.name });
+ * });
+ *
+ * @constructor
+ * @param {string} name
+ * @param {GlobalAttributes} [props]
+ */
 export default function HiddenField(name, props) {
     if(!(this instanceof HiddenField)) {
         return new HiddenField(name, props);
@@ -10,6 +26,16 @@ export default function HiddenField(name, props) {
 
 HiddenField.defaultTemplate = null;
 
+/**
+ * Registers the render template for HiddenField.
+ * @param {(description: {
+ *     name: string,
+ *     type: 'hidden',
+ *     value: Observable<*>|null,
+ *     defaultValue: *,
+ *     props: GlobalAttributes
+ * }, instance: HiddenField) => NdChild} template
+ */
 HiddenField.use = function(template) {
     HiddenField.defaultTemplate = template;
 };

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

@@ -1,6 +1,29 @@
-import FileField from "./FileField";
-import {Validation} from "../../validation/Validation";
+import FileField from '../../field/types/FileField';
+import {Validation} from '../../validation/Validation';
 
+/**
+ * Image upload field. Extends FileField with image-specific validation:
+ * dimensions, aspect ratio, max dimensions, min dimensions, and crop mode.
+ * Automatically restricts accepted MIME types to jpeg, png, gif, webp.
+ * @example
+ * const field = new ImageField('avatar')
+ *     .label(Span('Profile picture'))
+ *     .maxSize(2 * 1024 * 1024, 'Max 2MB')
+ *     .maxDimensions(1200, 1200, 'Max 1200x1200px')
+ *     .aspectRatio(1, 'Must be square')
+ *     .crop(true)
+ *     .required();
+ *
+ * ImageField.use((description, instance) => {
+ *     // description.maxWidth, description.maxHeight, description.crop,
+ *     // description.files, description.multiple, description.accept...
+ *     return Input({ type: 'file', accept: 'image/*' });
+ * });
+ *
+ * @constructor
+ * @param {string} name
+ * @param {GlobalAttributes} [props]
+ */
 export default function ImageField(name, props) {
     if(!(this instanceof ImageField)) {
         return new ImageField(name, props);
@@ -11,7 +34,7 @@ export default function ImageField(name, props) {
     Object.assign(this.$description, {
         maxWidth: null,
         maxHeight: null,
-        crop: false
+        crop: false,
     });
 
     // Auto-apply image mime types
@@ -20,6 +43,27 @@ export default function ImageField(name, props) {
 
 ImageField.defaultTemplate = null;
 
+/**
+ * Registers the render template for ImageField.
+ * @param {(description: {
+ *     name: string,
+ *     type: 'image',
+ *     label: NdChild|null,
+ *     accept: string,
+ *     multiple: boolean,
+ *     mode: string|null,
+ *     files: Observable<FileItemPreview[]>,
+ *     maxWidth: number|null,
+ *     maxHeight: number|null,
+ *     crop: boolean,
+ *     disabled: boolean|Observable<boolean>,
+ *     readonly: boolean|Observable<boolean>,
+ *     hasErrors: Observable<boolean>,
+ *     errors: Observable<string[]>,
+ *     showErrors: Observable<boolean>,
+ *     props: GlobalAttributes
+ * }, instance: ImageField) => NdChild} template
+ */
 ImageField.use = function(template) {
     ImageField.defaultTemplate = template;
 };
@@ -27,33 +71,68 @@ ImageField.use = function(template) {
 ImageField.prototype = Object.create(FileField.prototype);
 ImageField.prototype.constructor = ImageField;
 
+/**
+ * @param {number} width - Max width in pixels
+ * @returns {this}
+ */
 ImageField.prototype.maxWidth = function(width) {
     this.$description.maxWidth = width;
     return this;
 };
 
+/**
+ * @param {number} height - Max height in pixels
+ * @returns {this}
+ */
 ImageField.prototype.maxHeight = function(height) {
     this.$description.maxHeight = height;
     return this;
 };
 
+/**
+ * @param {boolean} [enabled=true]
+ * @returns {this}
+ */
 ImageField.prototype.crop = function(enabled = true) {
     this.$description.crop = enabled;
     return this;
 };
 
+/**
+ * @param {number} width
+ * @param {number} height
+ * @param {string} [message]
+ * @returns {this}
+ */
 ImageField.prototype.dimensions = function(width, height, message) {
     return this.addRule(Validation.dimensions, [width, height], message);
 };
 
+/**
+ * @param {number} width
+ * @param {number} height
+ * @param {string} [message]
+ * @returns {this}
+ */
 ImageField.prototype.maxDimensions = function(width, height, message) {
     return this.addRule(Validation.maxDimensions, [width, height], message);
 };
 
+/**
+ * @param {number} width
+ * @param {number} height
+ * @param {string} [message]
+ * @returns {this}
+ */
 ImageField.prototype.minDimensions = function(width, height, message) {
     return this.addRule(Validation.minDimensions, [width, height], message);
 };
 
+/**
+ * @param {number} ratio - e.g. 1 for square, 16/9 for widescreen
+ * @param {string} [message]
+ * @returns {this}
+ */
 ImageField.prototype.aspectRatio = function(ratio, message) {
     return this.addRule(Validation.aspectRatio, [ratio], message);
 };

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

@@ -1,6 +1,29 @@
-import {Validation} from "../../validation/Validation";
-import Field from "../Field";
-
+import {Validation} from '../../validation/Validation';
+import Field from '../../field/Field';
+
+/**
+ * Numeric input field. Supports min/max/between validation, integer, positive/negative,
+ * multipleOf, decimal precision, step, and prefix/suffix display.
+ * @example
+ * const field = new NumberField('price')
+ *     .label(Span('Price'))
+ *     .min(0, 'Must be positive')
+ *     .max(9999)
+ *     .decimals(2)
+ *     .prefix(Span('€'))
+ *     .required();
+ *
+ * NumberField.use((description, instance) => {
+ *     // description.name, description.step, description.decimals,
+ *     // description.prefix, description.suffix, description.value...
+ *     return Input({ type: 'number', step: description.step ?? 1 });
+ * });
+ *
+ * @constructor
+ * @param {string} name
+ * @param {string} [type='number']
+ * @param {GlobalAttributes} [props={}]
+ */
 export default function NumberField(name, type = 'number', props = {}) {
     if(!(this instanceof NumberField)) {
         return new NumberField(name, type, props);
@@ -19,6 +42,26 @@ export default function NumberField(name, type = 'number', props = {}) {
 
 NumberField.defaultTemplate = null;
 
+/**
+ * Registers the render template for NumberField.
+ * @param {(description: {
+ *     name: string,
+ *     type: string,
+ *     label: NdChild|null,
+ *     placeholder: NdChild|null,
+ *     value: Observable<number>|null,
+ *     step: number|null,
+ *     decimals: number|null,
+ *     prefix: NdChild|null,
+ *     suffix: NdChild|null,
+ *     disabled: boolean|Observable<boolean>,
+ *     readonly: boolean|Observable<boolean>,
+ *     hasErrors: Observable<boolean>,
+ *     errors: Observable<string[]>,
+ *     showErrors: Observable<boolean>,
+ *     props: GlobalAttributes
+ * }, instance: NumberField) => NdChild} template
+ */
 NumberField.use = function(template) {
     NumberField.defaultTemplate = template;
 };
@@ -26,58 +69,108 @@ NumberField.use = function(template) {
 NumberField.prototype = Object.create(Field.prototype);
 NumberField.prototype.constructor = NumberField;
 
+/**
+ * @param {number} min
+ * @param {string} [message]
+ * @returns {this}
+ */
 NumberField.prototype.min = function(min, message) {
     return this.addRule(Validation.min, [min], message);
 };
 
+/**
+ * @param {number} max
+ * @param {string} [message]
+ * @returns {this}
+ */
 NumberField.prototype.max = function(max, message) {
     return this.addRule(Validation.max, [max], message);
 };
 
+/**
+ * @param {number} min
+ * @param {number} max
+ * @param {string} [message]
+ * @returns {this}
+ */
 NumberField.prototype.between = function(min, max, message) {
     return this.addRule(Validation.between, [min, max], message);
 };
 
+/**
+ * @param {string} [message]
+ * @returns {this}
+ */
 NumberField.prototype.integer = function(message) {
     return this.addRule(Validation.integer, [], message);
 };
 
+/**
+ * @param {string} [message]
+ * @returns {this}
+ */
 NumberField.prototype.positive = function(message) {
     return this.addRule(Validation.positive, [], message);
 };
 
+/** Alias for positive() */
 NumberField.prototype.unsigned = NumberField.prototype.positive;
 
+/**
+ * @param {string} [message]
+ * @returns {this}
+ */
 NumberField.prototype.negative = function(message) {
     return this.addRule(Validation.negative, [], message);
 };
 
+/**
+ * @param {number} n
+ * @param {string} [message]
+ * @returns {this}
+ */
 NumberField.prototype.multipleOf = function(n, message) {
     this.$description.rules.push({
         validate: (value) => {
             if (!value && value !== 0) return true;
             return Number(value) % n === 0;
         },
-        message: message || `Must be a multiple of ${n}`
+        message: message || `Must be a multiple of ${n}`,
     });
     return this;
 };
 
+/**
+ * @param {number} value
+ * @returns {this}
+ */
 NumberField.prototype.step = function(value) {
     this.$description.step = value;
     return this;
 };
 
+/**
+ * @param {number} [value=2]
+ * @returns {this}
+ */
 NumberField.prototype.decimals = function(value = 2) {
     this.$description.decimals = value;
     return this;
 };
 
+/**
+ * @param {NdChild} text
+ * @returns {this}
+ */
 NumberField.prototype.prefix = function(text) {
     this.$description.prefix = text;
     return this;
 };
 
+/**
+ * @param {NdChild} text
+ * @returns {this}
+ */
 NumberField.prototype.suffix = function(text) {
     this.$description.suffix = text;
     return this;