native-document 1.0.15 → 1.0.16-8.2

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

@@ -0,0 +1,168 @@
+import StringField from '../../field/types/StringField';
+
+/**
+ * Text field with asynchronous autocomplete suggestions. Supports static arrays
+ * and async data sources, configurable debounce, min chars, and item rendering.
+ * @example
+ * const field = new AutocompleteField('city')
+ *     .label(Span('City'))
+ *     .source((query) => fetch(\`/api/cities?q=\${query}\`).then(r => r.json()))
+ *     .minChars(2)
+ *     .debounce(300)
+ *     .valueKey('id')
+ *     .labelKey('name')
+ *     .renderItem((item) => Div(Span(item.name), Span({ class: 'hint' }, item.country)))
+ *     .onSelect((item) => console.log('selected', item));
+ *
+ * AutocompleteField.use((description, instance) => {
+ *     // description.source, description.minChars, description.debounce,
+ *     // description.valueKey, description.labelKey, description.renderItem...
+ *     return Input({ type: 'text', placeholder: description.placeholder });
+ * });
+ *
+ * @constructor
+ * @param {string} name
+ * @param {GlobalAttributes} [props]
+ */
+export default function AutocompleteField(name, props) {
+    if(!(this instanceof AutocompleteField)) {
+        return new AutocompleteField(name, props);
+    }
+
+    StringField.call(this, name, 'autocomplete', props);
+
+    Object.assign(this.$description, {
+        source: null,
+        minChars: 2,
+        debounce: 300,
+        maxResults: 10,
+        valueKey: 'id',
+        labelKey: 'label',
+        renderItem: null,
+    });
+}
+
+AutocompleteField.defaultTemplate = null;
+
+/**
+ * Registers the render template for AutocompleteField.
+ * @param {(description: {
+ *     name: string,
+ *     type: 'autocomplete',
+ *     label: NdChild|null,
+ *     placeholder: NdChild|null,
+ *     value: Observable<*>|null,
+ *     source: *[]|((query: string) => Promise<*[]>)|null,
+ *     minChars: number,
+ *     debounce: number,
+ *     maxResults: number,
+ *     valueKey: string,
+ *     labelKey: string,
+ *     renderItem: ((item: *) => NdChild)|null,
+ *     disabled: boolean|Observable<boolean>,
+ *     readonly: boolean|Observable<boolean>,
+ *     hasErrors: Observable<boolean>,
+ *     errors: Observable<string[]>,
+ *     showErrors: Observable<boolean>,
+ *     props: GlobalAttributes
+ * }, instance: AutocompleteField) => NdChild} template
+ */
+AutocompleteField.use = function(template) {
+    AutocompleteField.defaultTemplate = template;
+};
+
+
+AutocompleteField.prototype = Object.create(StringField.prototype);
+AutocompleteField.prototype.constructor = AutocompleteField;
+
+/**
+ * @param {*[]|((query: string) => Promise<*[]>)} dataSource
+ * @returns {this}
+ */
+AutocompleteField.prototype.source = function(dataSource) {
+    this.$description.source = dataSource;
+    return this;
+};
+
+/**
+ * @param {number} min - Minimum characters before triggering the source
+ * @returns {this}
+ */
+AutocompleteField.prototype.minChars = function(min) {
+    this.$description.minChars = min;
+    return this;
+};
+
+/**
+ * @param {number} ms
+ * @returns {this}
+ */
+AutocompleteField.prototype.debounce = function(ms) {
+    this.$description.debounce = ms;
+    return this;
+};
+
+/**
+ * @param {number} max
+ * @returns {this}
+ */
+AutocompleteField.prototype.maxResults = function(max) {
+    this.$description.maxResults = max;
+    return this;
+};
+
+/**
+ * Validates that the entered value exists in the allowed list.
+ * @param {*[]} allowedValues
+ * @param {string} [message]
+ * @returns {this}
+ */
+AutocompleteField.prototype.oneOf = function(allowedValues, message) {
+    this.$description.rules.push({
+        validate: (value) => {
+            if (!value) return true;
+            return allowedValues.includes(value);
+        },
+        message: message || `Must be one of: ${allowedValues.join(', ')}`,
+    });
+    return this;
+};
+
+/**
+ * Key in the data object used as the field value.
+ * @param {string} key
+ * @returns {this}
+ */
+AutocompleteField.prototype.valueKey = function(key) {
+    this.$description.valueKey = key;
+    return this;
+};
+
+/**
+ * Key in the data object used as the display label.
+ * @param {string} key
+ * @returns {this}
+ */
+AutocompleteField.prototype.labelKey = function(key) {
+    this.$description.labelKey = key;
+    return this;
+};
+
+/**
+ * @param {(item: *) => void} handler
+ * @returns {this}
+ */
+AutocompleteField.prototype.onSelect = function(handler) {
+    this.on('select', handler);
+    return this;
+};
+
+/**
+ * Custom render for each suggestion item in the dropdown.
+ * @param {(item: *) => NdChild} callback
+ * @returns {this}
+ */
+AutocompleteField.prototype.renderItem = function(callback) {
+    this.$description.renderItem = callback;
+    return this;
+};

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

@@ -0,0 +1,77 @@
+import Field from '../../field/Field';
+import Validator from '../../../../core/utils/validator';
+
+/**
+ * Single checkbox field for boolean values. Supports reactive model binding.
+ * @example
+ * const field = new CheckboxField('agree')
+ *     .label(Span('I agree to the terms'))
+ *     .model(agreeObs)
+ *     .required('You must agree');
+ *
+ * CheckboxField.use((description, instance) => {
+ *     // description.checked — Observable<boolean> or boolean
+ *     return Input({ type: 'checkbox', checked: description.checked });
+ * });
+ *
+ * @constructor
+ * @param {string} name
+ * @param {GlobalAttributes} [props]
+ */
+export default function CheckboxField(name, props) {
+    if(!(this instanceof CheckboxField)) {
+        return new CheckboxField(name, props);
+    }
+
+    Field.call(this, name, 'checkbox', props);
+
+    Object.assign(this.$description, {
+        checked: false,
+    });
+}
+
+CheckboxField.defaultTemplate = null;
+
+/**
+ * Registers the render template for CheckboxField.
+ * @param {(description: {
+ *     name: string,
+ *     type: 'checkbox',
+ *     label: NdChild|null,
+ *     checked: Observable<boolean>|boolean,
+ *     disabled: boolean|Observable<boolean>,
+ *     readonly: boolean|Observable<boolean>,
+ *     hasErrors: Observable<boolean>,
+ *     errors: Observable<string[]>,
+ *     showErrors: Observable<boolean>,
+ *     props: GlobalAttributes
+ * }, instance: CheckboxField) => NdChild} template
+ */
+CheckboxField.use = function(template) {
+    CheckboxField.defaultTemplate = template;
+};
+
+CheckboxField.prototype = Object.create(Field.prototype);
+CheckboxField.prototype.constructor = CheckboxField;
+
+/**
+ * Binds the checked state to an observable.
+ * @param {Observable<boolean>} observable
+ * @returns {this}
+ */
+CheckboxField.prototype.model = function(observable) {
+    this.$description.checked = observable;
+    return this;
+};
+
+/**
+ * Returns the current checked value (resolves the observable if needed).
+ * @returns {boolean}
+ */
+CheckboxField.prototype.checked = function() {
+    const checked = this.$description.checked;
+    if(Validator.isObservable(checked)) {
+        return checked.val();
+    }
+    return checked;
+};

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

@@ -0,0 +1,171 @@
+import Field from '../../field/Field';
+
+/**
+ * Group of checkboxes for multi-value selection. Supports vertical/horizontal/grid layout
+ * and min/max/exact count validation.
+ * @example
+ * const field = new CheckboxGroupField('roles')
+ *     .label(Span('Roles'))
+ *     .option('admin', Span('Administrator'))
+ *     .option('editor', Span('Editor'))
+ *     .option('viewer', Span('Viewer'))
+ *     .horizontal()
+ *     .minChecked(1, 'Select at least one role')
+ *     .maxChecked(2);
+ *
+ * CheckboxGroupField.use((description, instance) => {
+ *     // description.options — Array<{ value, label, props }>
+ *     // description.layout — 'vertical' | 'horizontal' | 'grid'
+ *     return Div({ class: \`checkbox-group checkbox-group--\${description.layout}\` },
+ *         ...description.options.map(opt =>
+ *             Label(Input({ type: 'checkbox', value: opt.value }), opt.label)
+ *         )
+ *     );
+ * });
+ *
+ * @constructor
+ * @param {string} name
+ * @param {GlobalAttributes} [props]
+ */
+export default function CheckboxGroupField(name, props) {
+    if(!(this instanceof CheckboxGroupField)) {
+        return new CheckboxGroupField(name, props);
+    }
+
+    Field.call(this, name, 'checkbox-group', props);
+
+    Object.assign(this.$description, {
+        options: [],
+        layout: 'vertical',
+        validateOn: 'change',
+        defaultValue: [],
+    });
+}
+
+CheckboxGroupField.defaultTemplate = null;
+
+/**
+ * Registers the render template for CheckboxGroupField.
+ * @param {(description: {
+ *     name: string,
+ *     type: 'checkbox-group',
+ *     label: NdChild|null,
+ *     options: Array<{ value: *, label: NdChild, props: GlobalAttributes }>,
+ *     layout: 'vertical'|'horizontal'|'grid',
+ *     value: Observable<*[]>|null,
+ *     defaultValue: *[],
+ *     disabled: boolean|Observable<boolean>,
+ *     readonly: boolean|Observable<boolean>,
+ *     hasErrors: Observable<boolean>,
+ *     errors: Observable<string[]>,
+ *     showErrors: Observable<boolean>,
+ *     props: GlobalAttributes
+ * }, instance: CheckboxGroupField) => NdChild} template
+ */
+CheckboxGroupField.use = function(template) {
+    CheckboxGroupField.defaultTemplate = template;
+};
+
+CheckboxGroupField.prototype = Object.create(Field.prototype);
+CheckboxGroupField.prototype.constructor = CheckboxGroupField;
+
+/**
+ * @param {Array<{ value: *, label: NdChild, props?: GlobalAttributes }>} opts
+ * @returns {this}
+ */
+CheckboxGroupField.prototype.options = function(opts) {
+    this.$description.options = opts;
+    return this;
+};
+
+/**
+ * @param {*} value
+ * @param {NdChild} label
+ * @param {GlobalAttributes} [props={}]
+ * @returns {this}
+ */
+CheckboxGroupField.prototype.option = function(value, label, props = {}) {
+    this.$description.options.push({ value, label, props });
+    return this;
+};
+
+/**
+ * @param {'vertical'|'horizontal'|'grid'} value
+ * @returns {this}
+ */
+CheckboxGroupField.prototype.layout = function(value) {
+    const allowedLayouts = ['vertical', 'horizontal', 'grid'];
+
+    if (!allowedLayouts.includes(value)) {
+        throw new Error(`Invalid layout "${value}". Must be one of: ${allowedLayouts.join(', ')}`);
+    }
+
+    this.$description.layout = value;
+    return this;
+};
+
+/** @returns {this} */
+CheckboxGroupField.prototype.horizontal = function() {
+    this.$description.layout = 'horizontal';
+    return this;
+};
+
+/** @returns {this} */
+CheckboxGroupField.prototype.vertical = function() {
+    this.$description.layout = 'vertical';
+    return this;
+};
+
+/** @returns {this} */
+CheckboxGroupField.prototype.grid = function() {
+    this.$description.layout = 'grid';
+    return this;
+};
+
+/**
+ * @param {number} min
+ * @param {string} [message]
+ * @returns {this}
+ */
+CheckboxGroupField.prototype.minChecked = function(min, message) {
+    this.$description.rules.push({
+        validate: (values) => {
+            if (!Array.isArray(values)) return false;
+            return values.length >= min;
+        },
+        message: message || `At least ${min} option${min > 1 ? 's' : ''} must be selected`,
+    });
+    return this;
+};
+
+/**
+ * @param {number} max
+ * @param {string} [message]
+ * @returns {this}
+ */
+CheckboxGroupField.prototype.maxChecked = function(max, message) {
+    this.$description.rules.push({
+        validate: (values) => {
+            if (!Array.isArray(values)) return false;
+            return values.length <= max;
+        },
+        message: message || `Maximum ${max} option${max > 1 ? 's' : ''} allowed`,
+    });
+    return this;
+};
+
+/**
+ * @param {number} count
+ * @param {string} [message]
+ * @returns {this}
+ */
+CheckboxGroupField.prototype.exactChecked = function(count, message) {
+    this.$description.rules.push({
+        validate: (values) => {
+            if (!Array.isArray(values)) return false;
+            return values.length === count;
+        },
+        message: message || `Exactly ${count} option${count > 1 ? 's' : ''} must be selected`,
+    });
+    return this;
+};

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

@@ -0,0 +1,102 @@
+// ColorField.js
+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);
+    }
+
+    Field.call(this, name, 'color', props);
+
+    Object.assign(this.$description, {
+        format: 'hex',
+        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;
+};
+
+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'];
+
+    if (!allowedFormats.includes(formatType)) {
+        throw new Error(`Invalid format "${formatType}". Must be one of: ${allowedFormats.join(', ')}`);
+    }
+
+    this.$description.format = 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);
+};