native-document 1.0.15 → 1.0.16-8.2

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

@@ -0,0 +1,117 @@
+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);
+    }
+
+    BaseComponent.call(this, props);
+
+    this.$description = {
+        icon:       null,
+        text:       'Click or drag & drop files here',
+        hint:       null,
+        height:     null,
+        renderZone: null,
+        removeIcon: null,
+        props,
+    };
+}
+
+BaseComponent.extends(FileDropzoneMode);
+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;
+};

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

@@ -0,0 +1,150 @@
+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);
+    }
+
+    BaseComponent.call(this, props);
+
+    this.$description = {
+        file:     file || null,
+        status:   $('idle'),
+        progress: $(0),
+        error:    $(null),
+        props,
+    };
+}
+
+BaseComponent.extends(FileItemPreview);
+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

@@ -0,0 +1,43 @@
+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);
+    }
+
+    BaseComponent.call(this, props);
+
+    this.$description = {
+        props,
+    };
+}
+
+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

@@ -0,0 +1,120 @@
+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);
+    }
+
+    BaseComponent.call(this, props);
+
+    this.$description = {
+        buttonLabel:  'Add file',
+        buttonIcon:   null,
+        showProgress: true,
+        renderItem:   null,
+        renderButton: null,
+        renderList:   null,
+        props,
+    };
+}
+
+BaseComponent.extends(FileUploadButtonMode);
+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

@@ -0,0 +1,106 @@
+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);
+    }
+
+    BaseComponent.call(this, props);
+
+    this.$description = {
+        cellSize:   96,
+        addLabel:   'Upload',
+        addIcon:    null,
+        renderCell: null,
+        renderAdd:  null,
+        props,
+    };
+}
+
+BaseComponent.extends(FileWallMode);
+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

@@ -0,0 +1,61 @@
+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';
+
+export {
+    Field,
+    FormControl,
+    StringField,
+    EmailField,
+    PasswordField,
+    NumberField,
+    TextAreaField,
+    CheckboxField,
+    RadioField,
+    SelectField,
+    HiddenField,
+    FileField,
+    DateField,
+    TimeField,
+    TelField,
+    UrlField,
+    ColorField,
+    RangeField,
+    ImageField,
+    CheckboxGroupField,
+    AutocompleteField,
+    FieldCollection,
+
+    FileNativeMode,
+    FileAvatarMode,
+    FileWallMode,
+    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;
+
+
+}