native-document 1.0.165 → 1.0.168

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

@@ -1,7 +1,36 @@
-import BaseComponent from "../../../../BaseComponent";
-import HasEventEmitter from "../../../../../core/utils/HasEventEmitter";
+import BaseComponent from '../../../../BaseComponent';
+import HasEventEmitter from '../../../../../core/utils/HasEventEmitter';
 import { $ } from '../../../../../core/data/Observable';
 
+/**
+ * Represents a single file in a FileField upload list.
+ * Tracks upload status, progress, and error state reactively.
+ * Used internally by FileField modes to display per-file feedback.
+ * @example
+ * const preview = new FileItemPreview(file)
+ *     .uploading()
+ *     .progress(45)
+ *     .done()
+ *     .onClick((file, e) => console.log('clicked', file.name))
+ *     .onRemove((file) => fileField.removeFile(file));
+ *
+ * FileItemPreview.use((description, instance) => {
+ *     // description.file    — File object
+ *     // description.status  — Observable<'idle'|'uploading'|'done'|'error'>
+ *     // description.progress — Observable<number> (0-100)
+ *     // description.error   — Observable<string|null>
+ *     return Div({ class: 'file-preview' },
+ *         Span(description.file.name),
+ *         ShowIf(description.status.isEqualTo('uploading'), () =>
+ *             Div({ class: 'progress' }, Span(description.progress))
+ *         ),
+ *     );
+ * });
+ *
+ * @constructor
+ * @param {File} file
+ * @param {GlobalAttributes} [props={}]
+ */
 export default function FileItemPreview(file, props = {}) {
     if(!(this instanceof FileItemPreview)) {
         return new FileItemPreview(file, props);
@@ -14,7 +43,7 @@ export default function FileItemPreview(file, props = {}) {
         status:   $('idle'),
         progress: $(0),
         error:    $(null),
-        props
+        props,
     };
 }
 
@@ -23,51 +52,98 @@ BaseComponent.use(FileItemPreview, HasEventEmitter);
 
 FileItemPreview.defaultTemplate = null;
 
+/**
+ * Registers the render template for FileItemPreview.
+ * @param {(description: {
+ *     file: File|null,
+ *     status: Observable<'idle'|'uploading'|'done'|'error'>,
+ *     progress: Observable<number>,
+ *     error: Observable<string|null>,
+ *     props: GlobalAttributes
+ * }, instance: FileItemPreview) => NdChild} template
+ */
 FileItemPreview.use = function(template) {
     FileItemPreview.defaultTemplate = template;
 };
 
+/**
+ * Returns the File object associated with this preview.
+ * @returns {File}
+ */
 FileItemPreview.prototype.file = function() {
     return this.$description.file;
 };
 
+/**
+ * @param {'idle'|'uploading'|'done'|'error'} status
+ * @returns {this}
+ */
 FileItemPreview.prototype.status = function(status) {
     this.$description.status.set(status);
     return this;
 };
 
+/**
+ * @param {number} value - Upload progress from 0 to 100
+ * @returns {this}
+ */
 FileItemPreview.prototype.progress = function(value) {
     this.$description.progress.set(value);
     return this;
 };
 
+/**
+ * Sets an error message and transitions status to 'error'.
+ * @param {string} message
+ * @returns {this}
+ */
 FileItemPreview.prototype.error = function(message) {
     this.$description.error.set(message);
     this.$description.status.set('error');
     return this;
 };
 
+/**
+ * Marks the upload as done and sets progress to 100.
+ * @returns {this}
+ */
 FileItemPreview.prototype.done = function() {
     this.$description.status.set('done');
     this.$description.progress.set(100);
     return this;
 };
 
+/**
+ * Transitions status to 'uploading'.
+ * @returns {this}
+ */
 FileItemPreview.prototype.uploading = function() {
     this.$description.status.set('uploading');
     return this;
 };
 
+/**
+ * @param {(file: File, event: MouseEvent) => void} handler
+ * @returns {this}
+ */
 FileItemPreview.prototype.onClick = function(handler) {
     this.on('click', handler);
     return this;
 };
 
+/**
+ * @param {(file: File) => void} handler
+ * @returns {this}
+ */
 FileItemPreview.prototype.onRemove = function(handler) {
     this.on('remove', handler);
     return this;
 };
 
+/**
+ * @param {(file: File) => void} handler
+ * @returns {this}
+ */
 FileItemPreview.prototype.onReplace = function(handler) {
     this.on('replace', handler);
     return this;

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

@@ -1,5 +1,21 @@
-import BaseComponent from "../../../../BaseComponent";
+import BaseComponent from '../../../../BaseComponent';
 
+/**
+ * Native browser file input mode for FileField.
+ * Renders a standard <input type="file"> with no custom UI.
+ * Useful when browser defaults are sufficient or as a baseline.
+ * @example
+ * new FileField('document')
+ *     .mode('native');
+ *
+ * FileNativeMode.use((description, instance) => {
+ *     // description.props
+ *     return Input({ type: 'file' });
+ * });
+ *
+ * @constructor
+ * @param {GlobalAttributes} [props={}]
+ */
 export default function FileNativeMode(props = {}) {
     if(!(this instanceof FileNativeMode)) {
         return new FileNativeMode(props);
@@ -8,7 +24,7 @@ export default function FileNativeMode(props = {}) {
     BaseComponent.call(this, props);
 
     this.$description = {
-        props
+        props,
     };
 }
 
@@ -16,6 +32,12 @@ BaseComponent.extends(FileNativeMode);
 
 FileNativeMode.defaultTemplate = null;
 
+/**
+ * Registers the render template for FileNativeMode.
+ * @param {(description: {
+ *     props: GlobalAttributes
+ * }, instance: FileNativeMode) => NdChild} template
+ */
 FileNativeMode.use = function(template) {
     FileNativeMode.defaultTemplate = template;
 };

package/src/components/form/field/types/file-field-mode/FileUploadButtonMode.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';
 
+/**
+ * Button-triggered file upload mode for FileField.
+ * Renders a button to open the file picker and a list of uploaded files below it.
+ * Each file is represented by a FileItemPreview instance.
+ * @example
+ * new FileField('attachments')
+ *     .mode('button')
+ *     .multiple(true);
+ *
+ * FileUploadButtonMode.use((description, instance) => {
+ *     // description.buttonLabel, description.buttonIcon,
+ *     // description.showProgress, description.renderItem,
+ *     // description.renderButton, description.renderList
+ *     return Div({ class: 'upload-button' },
+ *         Button(description.buttonLabel),
+ *         Div({ class: 'file-list' }),
+ *     );
+ * });
+ *
+ * @constructor
+ * @param {GlobalAttributes} [props={}]
+ */
 export default function FileUploadButtonMode(props = {}) {
     if(!(this instanceof FileUploadButtonMode)) {
         return new FileUploadButtonMode(props);
@@ -15,7 +37,7 @@ export default function FileUploadButtonMode(props = {}) {
         renderItem:   null,
         renderButton: null,
         renderList:   null,
-        props
+        props,
     };
 }
 
@@ -24,35 +46,74 @@ BaseComponent.use(FileUploadButtonMode, HasEventEmitter);
 
 FileUploadButtonMode.defaultTemplate = null;
 
+/**
+ * Registers the render template for FileUploadButtonMode.
+ * @param {(description: {
+ *     buttonLabel: NdChild,
+ *     buttonIcon: NdChild|null,
+ *     showProgress: boolean,
+ *     renderItem: ((file: File, preview: FileItemPreview) => NdChild)|null,
+ *     renderButton: ((desc: *, instance: FileUploadButtonMode) => NdChild)|null,
+ *     renderList: ((files: File[]) => NdChild)|null,
+ *     props: GlobalAttributes
+ * }, instance: FileUploadButtonMode) => NdChild} template
+ */
 FileUploadButtonMode.use = function(template) {
     FileUploadButtonMode.defaultTemplate = template;
 };
 
+/**
+ * @param {NdChild} label
+ * @returns {this}
+ */
 FileUploadButtonMode.prototype.buttonLabel = function(label) {
     this.$description.buttonLabel = label;
     return this;
 };
 
+/**
+ * @param {NdChild} icon
+ * @returns {this}
+ */
 FileUploadButtonMode.prototype.buttonIcon = function(icon) {
     this.$description.buttonIcon = icon;
     return this;
 };
 
+/**
+ * @param {boolean} [enabled=true]
+ * @returns {this}
+ */
 FileUploadButtonMode.prototype.showProgress = function(enabled = true) {
     this.$description.showProgress = enabled;
     return this;
 };
 
+/**
+ * Custom render for each uploaded file row.
+ * @param {(file: File, preview: FileItemPreview) => NdChild} fn
+ * @returns {this}
+ */
 FileUploadButtonMode.prototype.renderItem = function(fn) {
     this.$description.renderItem = fn;
     return this;
 };
 
+/**
+ * Custom render for the upload button itself.
+ * @param {(desc: *, instance: FileUploadButtonMode) => NdChild} fn
+ * @returns {this}
+ */
 FileUploadButtonMode.prototype.renderButton = function(fn) {
     this.$description.renderButton = fn;
     return this;
 };
 
+/**
+ * Custom render for the entire file list.
+ * @param {(files: File[]) => NdChild} fn
+ * @returns {this}
+ */
 FileUploadButtonMode.prototype.renderList = function(fn) {
     this.$description.renderList = fn;
     return this;

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

@@ -1,6 +1,25 @@
-import BaseComponent from "../../../../BaseComponent";
-import HasEventEmitter from "../../../../../core/utils/HasEventEmitter";
+import BaseComponent from '../../../../BaseComponent';
+import HasEventEmitter from '../../../../../core/utils/HasEventEmitter';
 
+/**
+ * Grid/wall layout mode for FileField.
+ * Displays uploaded files as a grid of cells with a fixed cell size,
+ * plus an "Add" cell at the end to trigger new uploads.
+ * Ideal for image galleries and media libraries.
+ * @example
+ * new FileField('gallery')
+ *     .mode('wall')
+ *     .multiple(true);
+ *
+ * FileWallMode.use((description, instance) => {
+ *     // description.cellSize, description.addLabel, description.addIcon,
+ *     // description.renderCell, description.renderAdd
+ *     return Div({ class: 'wall', style: { gridTemplateColumns: \`repeat(auto-fill, \${description.cellSize}px)\` } });
+ * });
+ *
+ * @constructor
+ * @param {GlobalAttributes} [props={}]
+ */
 export default function FileWallMode(props = {}) {
     if(!(this instanceof FileWallMode)) {
         return new FileWallMode(props);
@@ -14,7 +33,7 @@ export default function FileWallMode(props = {}) {
         addIcon:    null,
         renderCell: null,
         renderAdd:  null,
-        props
+        props,
     };
 }
 
@@ -23,30 +42,64 @@ BaseComponent.use(FileWallMode, HasEventEmitter);
 
 FileWallMode.defaultTemplate = null;
 
+/**
+ * Registers the render template for FileWallMode.
+ * @param {(description: {
+ *     cellSize: string|number,
+ *     addLabel: NdChild,
+ *     addIcon: NdChild|null,
+ *     renderCell: ((file: File, preview: FileItemPreview) => NdChild)|null,
+ *     renderAdd: (() => NdChild)|null,
+ *     props: GlobalAttributes
+ * }, instance: FileWallMode) => NdChild} template
+ */
 FileWallMode.use = function(template) {
     FileWallMode.defaultTemplate = template;
 };
 
+
+/**
+ * @param {string|number} size - Cell size in pixels or CSS value
+ * @returns {this}
+ */
 FileWallMode.prototype.cellSize = function(size) {
     this.$description.cellSize = size;
     return this;
 };
 
+/**
+ * @param {NdChild} label
+ * @returns {this}
+ */
 FileWallMode.prototype.addLabel = function(label) {
     this.$description.addLabel = label;
     return this;
 };
 
+/**
+ * @param {NdChild} icon
+ * @returns {this}
+ */
 FileWallMode.prototype.addIcon = function(icon) {
     this.$description.addIcon = icon;
     return this;
 };
 
+/**
+ * Custom render for each file cell.
+ * @param {(file: File, preview: FileItemPreview) => NdChild} fn
+ * @returns {this}
+ */
 FileWallMode.prototype.renderCell = function(fn) {
     this.$description.renderCell = fn;
     return this;
 };
 
+/**
+ * Custom render for the "Add" cell.
+ * @param {() => NdChild} fn
+ * @returns {this}
+ */
 FileWallMode.prototype.renderAdd = function(fn) {
     this.$description.renderAdd = fn;
     return this;

package/src/components/form/index.js

@@ -1,30 +1,30 @@
-import Field from "./field/Field";
-import FormControl from "./FormControl";
-import StringField from "./field/types/StringField";
-import EmailField from "./field/types/EmailField";
-import PasswordField from "./field/types/PasswordField";
-import NumberField from "./field/types/NumberField";
-import TextAreaField from "./field/types/TextAreaField";
-import CheckboxField from "./field/types/CheckboxField";
-import RadioField from "./field/types/RadioField";
-import SelectField from "./field/types/SelectField";
-import HiddenField from "./field/types/HiddenField";
-import FileField from "./field/types/FileField";
-import DateField from "./field/types/DateField";
-import TimeField from "./field/types/TimeField";
-import TelField from "./field/types/TelField";
-import UrlField from "./field/types/UrlField";
-import ColorField from "./field/types/ColorField";
-import RangeField from "./field/types/RangeField";
-import ImageField from "./field/types/ImageField";
-import CheckboxGroupField from "./field/types/CheckboxGroupField";
-import AutocompleteField from "./field/types/AutocompleteField";
-import FieldCollection from "./field/FieldCollection";
-import FileNativeMode from "./field/types/file-field-mode/FileNativeMode";
-import FileDropzoneMode from "./field/types/file-field-mode/FileDropzoneMode";
-import FileUploadButtonMode from "./field/types/file-field-mode/FileUploadButtonMode";
-import FileWallMode from "./field/types/file-field-mode/FileWallMode";
-import FileAvatarMode from "./field/types/file-field-mode/FileAvatarMode";
+import Field from './field/Field';
+import FormControl from './FormControl';
+import StringField from './field/types/StringField';
+import EmailField from './field/types/EmailField';
+import PasswordField from './field/types/PasswordField';
+import NumberField from './field/types/NumberField';
+import TextAreaField from './field/types/TextAreaField';
+import CheckboxField from './field/types/CheckboxField';
+import RadioField from './field/types/RadioField';
+import SelectField from './field/types/SelectField';
+import HiddenField from './field/types/HiddenField';
+import FileField from './field/types/FileField';
+import DateField from './field/types/DateField';
+import TimeField from './field/types/TimeField';
+import TelField from './field/types/TelField';
+import UrlField from './field/types/UrlField';
+import ColorField from './field/types/ColorField';
+import RangeField from './field/types/RangeField';
+import ImageField from './field/types/ImageField';
+import CheckboxGroupField from './field/types/CheckboxGroupField';
+import AutocompleteField from './field/types/AutocompleteField';
+import FieldCollection from './field/FieldCollection';
+import FileNativeMode from './field/types/file-field-mode/FileNativeMode';
+import FileDropzoneMode from './field/types/file-field-mode/FileDropzoneMode';
+import FileUploadButtonMode from './field/types/file-field-mode/FileUploadButtonMode';
+import FileWallMode from './field/types/file-field-mode/FileWallMode';
+import FileAvatarMode from './field/types/file-field-mode/FileAvatarMode';
 
 // import './field/FieldFactory';
 
@@ -58,4 +58,4 @@ export {
     FileUploadButtonMode,
     FileDropzoneMode,
 
-}
+};

package/src/components/form/types/Field.d.ts

@@ -0,0 +1,73 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { ObservableItem } from '../../../../types/observable';
+import type { BaseComponent } from '../../BaseComponent';
+import type { HasValidation } from '../../$traits/has-validation/HasValidation';
+
+export type FieldDescription = {
+        name: string;
+        type: string;
+        key: string;
+        label: ValidChild | null;
+        placeholder: ValidChild | null;
+        help: ValidChild | null;
+        defaultValue: unknown;
+        disabled: boolean | ObservableItem<boolean>;
+        readonly: boolean | ObservableItem<boolean>;
+        rules: Array<{ fn: Function; params: unknown; message: string }>;
+        clearErrorOn: string;
+        validateOn: string;
+        value: ObservableItem | null;
+        clearable: boolean | ObservableItem<boolean> | null;
+        hasErrors: ObservableItem<boolean>;
+        errors: ObservableItem<string[]>;
+        showErrors: ObservableItem<boolean>;
+        render: ((desc: FieldDescription, instance: FieldInterface) => ValidChild) | null;
+        clearButtonIcon: ValidChild | null;
+        focus: ObservableItem<boolean>;
+        isDirty: ObservableItem<boolean>;
+    };
+
+export interface FieldInterface extends BaseComponent, HasValidation {
+    forceShowErrors(forceValue: boolean): void;
+    key(key: string): this;
+    suffix(suffix: string): this;
+    field(): HTMLElement | DocumentFragment;
+    input(callback: (input: HTMLElement) => void): this;
+    model(observable: ObservableItem): this;
+    bind(observable: ObservableItem): this;
+    errors(errors: ObservableItem<string[]>): this;
+    type(type: string): this;
+    default(defaultValue: unknown): this;
+    label(text: ValidChild): this;
+    help(text: ValidChild): this;
+    hint(text: ValidChild): this;
+    placeholder(text: ValidChild): this;
+    disabled(disabled?: boolean | ObservableItem<boolean>): this;
+    readonly(readonly?: boolean | ObservableItem<boolean>): this;
+    value(): any;
+    setValue(newValue: unknown): this;
+    wrapperProps(wrapperProps: Record<string, string|number|ObservableItem>): this;
+    inputProps(inputProps: Record<string, string|number|ObservableItem>): this;
+    labelProps(labelProps: Record<string, string|number|ObservableItem>): this;
+    errorProps(errorProps: Record<string, string|number|ObservableItem>): this;
+    hintProps(hintProps: Record<string, string|number|ObservableItem>): this;
+    focus(): this;
+    blur(): this;
+    leading(content: ValidChild): this;
+    trailing(content: ValidChild): this;
+    bottom(content: ValidChild): this;
+    clearable(mode?: boolean | ObservableItem<boolean>): this;
+    clearButtonIcon(clearButtonIcon: ValidChild): this;
+    reset(): this;
+    render(template: (description: FieldDescription, instance: FieldInterface) => ValidChild): this;
+}
+
+
+export declare function Field(name: string, type?: string, props?: Record<string, string|number|ObservableItem>): FieldInterface;
+export declare namespace Field {
+
+
+    function use(template: (description: FieldDescription, instance: FieldInterface) => ValidChild): void;
+
+
+}

package/src/components/form/types/FieldCollection.d.ts

@@ -0,0 +1,53 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { ObservableItem } from '../../../../types/observable';
+import type { BaseComponent } from '../../BaseComponent';
+import type { HasValidation } from '../../$traits/has-validation/HasValidation';
+import type { FieldInterface } from './Field';
+import type { GlobalAttributes } from '../../../../types/globals';
+
+export type FieldCollectionDescription = {
+        name: string;
+        value: ObservableItem<unknown[]>;
+        rules: Array<{ fn: Function; params: unknown; message: string }>;
+        hasErrors: ObservableItem<boolean>;
+        errors: ObservableItem<string[]>;
+        showErrors: ObservableItem<boolean>;
+        defaultItem: unknown;
+        fieldBuilder: ((fields: FieldCollectionInterface, index: number) => ValidChild) | null;
+        renderItem: ((item: unknown, index: number) => ValidChild) | null;
+        renderAdd: (() => ValidChild) | null;
+        transition: string | null;
+        props: GlobalAttributes;
+    };
+
+export interface FieldCollectionInterface extends BaseComponent, HasValidation {
+    fields(fieldBuilder: (fields: FieldCollectionInterface, index: number) => ValidChild): this;
+    data(defaultItem: unknown): this;
+    renderItem(fn: (item: unknown, index: number) => ValidChild): this;
+    renderAdd(fn: () => ValidChild): this;
+    transition(transitionName: string): this;
+    model(observable: ObservableItem<unknown[]>): this;
+    add(): void;
+    remove(item: unknown): this;
+    clear(): this;
+    reset(): this;
+    value(): unknown[];
+    count(): number;
+    isEmpty(): boolean;
+    onChange(handler: () => void): this;
+    onAdd(handler: () => void): this;
+    onRemove(handler: (item: unknown) => void): this;
+    min(minCount: number, message?: string): this;
+    max(maxCount: number, message?: string): this;
+    render(template: (description: FieldCollectionDescription, instance: FieldCollectionInterface) => ValidChild): this;
+}
+
+
+export declare function FieldCollection(name?: string, props?: Record<string, unknown>): FieldCollectionInterface;
+export declare namespace FieldCollection {
+
+
+    function use(template: (description: FieldCollectionDescription, instance: FieldCollectionInterface) => ValidChild): void;
+
+
+}

package/src/components/form/types/FormControl.d.ts

@@ -0,0 +1,64 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { ObservableItem } from '../../../../types/observable';
+import type { BaseComponent } from '../../BaseComponent';
+import type { FieldInterface } from './Field';
+import type { GlobalAttributes } from '../../../../types/globals';
+
+export type FormControlDescription = {
+        data: unknown | null;
+        fieldBuilder: ((form: FormControlInterface) => void) | null;
+        layout: ((fields: Record<string, FieldInterface>) => ValidChild) | null;
+        errorsMode: 'dispatch' | 'inline' | 'summary' | 'none';
+        errorsPosition: 'top' | 'bottom';
+        errorsMapper: Record<string, string> | null;
+        renderErrors: ((errors: Record<string, string[]>) => ValidChild) | null;
+        submitting: ObservableItem<boolean>;
+        errors: ObservableItem<Record<string, string[]> | null>;
+        isDirty: ObservableItem<boolean>;
+        isValid: ObservableItem<boolean>;
+        props: GlobalAttributes;
+    };
+
+export interface FormControlInterface extends BaseComponent {
+    fields(fieldBuilder: (form: FormControlInterface) => void): this;
+    get(fieldName: string): FieldInterface | null;
+    layout(layoutCallback: (fields: Record<string, FieldInterface>) => ValidChild): this;
+    errorsMode(mode: 'inline' | 'summary' | 'none'): this;
+    dispatchErrors(mapper?: Record<string, string> | null): this;
+    summarizeErrors(): Record<string, string[]>;
+    dispatchAndSummarize(mapper?: Record<string, string> | null): this;
+    errorsPosition(position: 'top' | 'bottom'): this;
+    errorsAtTop(): this;
+    errorsAtBottom(): this;
+    renderErrors(renderFn: (errors: Record<string, string[]>) => ValidChild): this;
+    reset(): this;
+    resetField(name: string): this;
+    submit(event?: Event): this;
+    trigger(...fieldNames: string[]): this;
+    disable(fieldName?: string | null): this;
+    enable(fieldName?: string | null): this;
+    values(): Record<string, unknown>;
+    watch(fieldName: string, handler: (value: unknown, field: FieldInterface) => void): this;
+    onSubmit(callback: (values: Record<string, unknown>, form: FormControlInterface) => void | Promise<void>): this;
+    onPreventSubmit(callback: (event: Event) => void): this;
+    onDebouncedSubmit(callback: (values: Record<string, unknown>) => void, delay?: number): this;
+    onSuccess(callback: (values: Record<string, unknown>) => void): this;
+    onError(callback: (errors: Record<string, string[]>) => void): this;
+    onChange(callback: () => void): this;
+    onReset(callback: () => void): this;
+    onBeforeSubmit(callback: () => void): this;
+    onAfterSubmit(callback: () => void): this;
+    onValidationError(callback: (errors: Record<string, string[]>) => void): this;
+    render(template: (description: FormControlDescription, instance: FormControlInterface) => ValidChild): this;
+}
+
+
+export declare function FormControl(props?: Record<string, unknown>): FormControlInterface;
+export declare namespace FormControl {
+
+
+    function use(template: (description: FormControlDescription, instance: FormControlInterface) => ValidChild): void;
+    function create(props?: Record<string, unknown>): FormControlInterface;
+
+
+}