native-document 1.0.15 → 1.0.16-8.1

package/src/components/form/field/Field.js

@@ -0,0 +1,419 @@
+import { $ } from '../../../core/data/Observable';
+import Validator from '../../../core/utils/validator';
+import BaseComponent from '../../BaseComponent';
+import HasEventEmitter from '../../../core/utils/HasEventEmitter';
+import HasValidation from '../../$traits/has-validation/HasValidation';
+
+/**
+ * Base form field with label, hint, placeholder, validation rules, clearable state, and reactive value binding. Extended by all typed field variants.
+ *
+ *
+ * @example
+ * const field = new Field('username', 'text')
+ *     .label(Span('Username'))
+ *     .placeholder('Enter your username')
+ *     .required('Username is required')
+ *     .minLength(3)
+ *     .model(usernameObs)
+ *     .clearable(true);
+ *
+ * @constructor
+ * @param {string} name
+ * @param {string} [type]
+ * @param {GlobalAttributes} [props]
+ */
+export default function Field(name, type, props) {
+    if(!(this instanceof Field)) {
+        return new Field(name, type, props);
+    }
+
+    BaseComponent.call(this, props);
+
+    this.$description = {
+        name:          name,
+        type:          type,
+        key:           name,
+        label:         null,
+        placeholder:   null,
+        help:          null,
+        defaultValue:  null,
+        disabled:      false,
+        readonly:      false,
+        rules: [],
+        clearErrorOn:  'focus',
+        validateOn:    'blur',
+        requiredIf:    null,
+        value:         null,
+        clearable:     null,
+        hasErrors:     $(false),
+        errors:        $.array(),
+        showErrors:    $(true),
+        suffix:        'field',
+        elementsProps: {
+            wrapper: null,
+            label:   null,
+            input:   null,
+            error:   null,
+            hint:    null,
+        },
+        render:          null,
+        clearButtonIcon: null,
+        focus: $(false),
+        isDirty:  $(false),
+        isTouched:  $(false),
+        slots: {},
+        props,
+    };
+
+    this.$description.errors.intercept((nextValue) => nextValue === null ? [] : nextValue);
+}
+
+Field.defaultTemplate = null;
+BaseComponent.extends(Field);
+BaseComponent.use(Field, HasEventEmitter);
+BaseComponent.use(Field, HasValidation);
+
+/**
+ * Registers the render template for Field.
+ * @param {(description: {
+ *     name: string,
+ *     type: string,
+ *     key: string,
+ *     label: NdChild|null,
+ *     placeholder: NdChild|null,
+ *     help: NdChild|null,
+ *     defaultValue: *,
+ *     disabled: boolean|Observable<boolean>,
+ *     readonly: boolean|Observable<boolean>,
+ *     rules: Array<{ fn: Function, params: *, message: string }>,
+ *     clearErrorOn: string,
+ *     validateOn: string,
+ *     value: Observable<*>|null,
+ *     clearable: boolean|Observable<boolean>|null,
+ *     hasErrors: Observable<boolean>,
+ *     errors: Observable<string[]>,
+ *     showErrors: Observable<boolean>,
+ *     render: ((desc: *, instance: Field) => NdChild)|null,
+ *     clearButtonIcon: NdChild|null,
+ *     focus: Observable<boolean>,
+ *     isDirty: Observable<boolean>,
+ * }, instance: Field) => NdChild} template
+ */
+Field.use = function(template) {
+    Field.defaultTemplate = template;
+};
+
+// ---------------------------------------------
+// COMMON METHODS
+// ---------------------------------------------
+
+Field.prototype.$model = function() {
+    return this.$description.value || this.$description.checked;
+};
+
+/**
+ * @param {*} forceValue
+ * @returns {void}
+ */
+Field.prototype.forceShowErrors = function(forceValue) {
+    this.$description.showErrors.intercept(() => forceValue);
+};
+
+/**
+ * @param {string} key
+ * @returns {this}
+ */
+Field.prototype.key = function(key) {
+    this.$description.key = key;
+    return this;
+};
+
+/**
+ * @param {string} suffix
+ * @returns {this}
+ */
+Field.prototype.suffix = function(suffix) {
+    this.$description.suffix = suffix;
+    return this;
+};
+
+/**
+ * @returns {HTMLElement|DocumentFragment}
+ */
+Field.prototype.field = function() {
+    if(!this.$element) {
+        this.$element = this.toNdElement();
+    }
+    return this.$element;
+};
+Field.prototype.node = Field.prototype.field;
+
+/**
+ * @param {Function} callback
+ * @returns {this}
+ */
+Field.prototype.input = function(callback) {
+    if(!this.$input) {
+        this.field();
+    }
+    callback && callback(this.$input);
+    return this;
+};
+
+/**
+ * @param {Observable<*>} observable
+ * @returns {this}
+ */
+Field.prototype.model = function(observable) {
+    this.$description.value        = observable;
+    this.$description.initialValue = Validator.isObservable(observable)
+        ? observable.val()
+        : observable;
+    return this;
+};
+
+Field.prototype.bind = Field.prototype.model;
+
+/**
+ * @param {Observable<string[]>} errors
+ * @returns {this}
+ */
+Field.prototype.errors = function(errors) {
+    if(!Validator.isObservable(errors)) {
+        throw new Error('Errors must be an observable');
+    }
+    this.$description.errors = errors;
+    return this;
+};
+
+/**
+ * @param {string} type
+ * @returns {this}
+ */
+Field.prototype.type = function(type) {
+    this.$description.type = type;
+    return this;
+};
+
+/**
+ * @param {*} defaultValue
+ * @returns {this}
+ */
+Field.prototype.default = function(defaultValue) {
+    this.$description.defaultValue = defaultValue;
+    return this;
+};
+
+/**
+ * @param {NdChild} text
+ * @returns {this}
+ */
+Field.prototype.label = function(text) {
+    this.$description.label = text;
+    return this;
+};
+
+/**
+ * @param {NdChild} text
+ * @returns {this}
+ */
+Field.prototype.help = function(text) {
+    this.$description.help = text;
+    return this;
+};
+
+/**
+ * @param {NdChild} text
+ * @returns {this}
+ */
+Field.prototype.hint = function(text) {
+    this.$description.help = text;
+    return this;
+};
+
+/**
+ * @param {NdChild} text
+ * @returns {this}
+ */
+Field.prototype.placeholder = function(text) {
+    this.$description.placeholder = text;
+    return this;
+};
+
+/**
+ * @param {boolean|Observable<boolean>} [disabled]
+ * @returns {this}
+ */
+Field.prototype.disabled = function(disabled) {
+    this.$description.disabled = BaseComponent.obs(disabled);
+    return this;
+};
+
+/**
+ * @param {boolean|Observable<boolean>} [readonly]
+ * @returns {this}
+ */
+Field.prototype.readonly = function(readonly) {
+    this.$description.readonly = BaseComponent.obs(readonly);
+    return this;
+};
+
+/**
+ * @returns {*}
+ */
+Field.prototype.value = function() {
+    const value = this.$model();
+    return Validator.isObservable(value) ? value.val() : value;
+};
+
+/**
+ * @param {*} newValue
+ * @returns {this}
+ */
+Field.prototype.setValue = function(newValue) {
+    const value = this.$model();
+    if(Validator.isObservable(value)) {
+        value.set(newValue);
+        return this;
+    }
+    this.$description.value = BaseComponent.obs(newValue);
+    return this;
+};
+
+/**
+ * @param {*} wrapperProps
+ * @returns {this}
+ */
+Field.prototype.wrapperProps = function(wrapperProps) {
+    this.$description.elementsProps.wrapper = wrapperProps;
+    return this;
+};
+
+/**
+ * @param {*} inputProps
+ * @returns {this}
+ */
+Field.prototype.inputProps = function(inputProps) {
+    this.$description.elementsProps.input = inputProps;
+    return this;
+};
+
+/**
+ * @param {*} labelProps
+ * @returns {this}
+ */
+Field.prototype.labelProps = function(labelProps) {
+    this.$description.elementsProps.label = labelProps;
+    return this;
+};
+
+/**
+ * @param {*} errorProps
+ * @returns {this}
+ */
+Field.prototype.errorProps = function(errorProps) {
+    this.$description.elementsProps.error = errorProps;
+    return this;
+};
+
+/**
+ * @param {*} hintProps
+ * @returns {this}
+ */
+Field.prototype.hintProps = function(hintProps) {
+    this.$description.elementsProps.hint = hintProps;
+    return this;
+};
+
+/**
+ * @returns {this}
+ */
+Field.prototype.focus = function() {
+    this.$description.focus.set(true);
+    return this;
+};
+
+/**
+ * @returns {this}
+ */
+Field.prototype.blur = function() {
+    this.$description.focus.set(false);
+    return this;
+};
+
+/**
+ * @param {NdChild} content
+ * @returns {this}
+ */
+Field.prototype.leading = function(content) {
+    this.$description.slots.leading = content;
+    return this;
+};
+
+/**
+ * @param {NdChild} content
+ * @returns {this}
+ */
+Field.prototype.trailing = function(content) {
+    this.$description.slots.trailing = content;
+    return this;
+};
+
+/**
+ * @param {NdChild} content
+ * @returns {this}
+ */
+Field.prototype.bottom = function(content) {
+    this.$description.slots.bottom = content;
+    return this;
+};
+
+/**
+ * @param {*} [mode]
+ * @returns {this}
+ */
+Field.prototype.clearable = function(mode = true) {
+    this.$description.clearable = BaseComponent.obs(mode);
+    return this;
+};
+
+/**
+ * @param {*} clearButtonIcon
+ * @returns {this}
+ */
+Field.prototype.clearButtonIcon = function(clearButtonIcon) {
+    this.$description.slots.clearButtonIcon = clearButtonIcon;
+    return this;
+};
+
+/**
+ * @returns {this}
+ */
+Field.prototype.reset = function() {
+    const value = this.$model();
+    if(Validator.isObservable(value)) {
+        value.set(this.$description.initialValue ?? this.$description.defaultValue ?? null);
+    }
+
+    this.$description.errors.clear();
+    this.$description.hasErrors.set(false);
+    this.$description.showErrors.set(true);
+    this.$description.isDirty.set(false);
+    this.$description.isTouched.set(false);
+
+    this.$description.focus.set(false);
+
+    this.emit('reset');
+    return this;
+};
+
+/**
+ *
+ * @param {string|string[]} error
+ */
+Field.prototype.setError =  function(error) {
+    const errs = Array.isArray(error) ? error : [error];
+    this.$description.errors.set(errs);
+    this.$description.hasErrors.set(!!error);
+    this.$description.showErrors.set(!!error);
+};

package/src/components/form/field/FieldCollection.js

@@ -0,0 +1,292 @@
+import BaseComponent from '../../BaseComponent';
+import HasEventEmitter from '../../../core/utils/HasEventEmitter';
+import HasValidation from '../../$traits/has-validation/HasValidation';
+import { $ } from '../../../core/data/Observable';
+import Validator from '../../../core/utils/validator';
+import NativeDocumentError from '../../../core/errors/NativeDocumentError';
+
+/**
+ * Repeatable field group. Allows adding/removing instances dynamically with validation rules on the collection (min/max count).
+ *
+ *
+ * @example
+ * const phones = new FieldCollection('phones')
+ *     .fields((fields, index) =>
+ *         new Field(\`phones[\${index}]\`, 'tel').label(Span(\`Phone \${index + 1}\`))
+ *     )
+ *     .renderAdd(() => Button(Span('+ Add phone')))
+ *     .min(1, 'At least one phone is required')
+ *     .max(5, 'Maximum 5 phones allowed');
+ *
+ * @constructor
+ * @param {string} [name]
+ * @param {GlobalAttributes} [props={}]
+ */
+export default function FieldCollection(name, props = {}) {
+    if(!(this instanceof FieldCollection)) {
+        return new FieldCollection(name, props);
+    }
+
+    BaseComponent.call(this, props);
+
+    this.$description = {
+        name: name,
+        value: $.array([]),
+        rules: [],
+        fields: {},
+        hasErrors: $(false),
+        errors: $.array(),
+        showErrors: $(true),
+        defaultItem: null,
+        fieldBuilder: null,
+        renderItem: null,
+        renderAdd: null,
+        transition: null,
+        props,
+    };
+
+    this.$description.value.interceptMutations((items) =>
+        items.map(item => Validator.isObservable(item) ? item : $.object(item)),
+    );
+}
+
+BaseComponent.extends(FieldCollection);
+BaseComponent.use(FieldCollection, HasEventEmitter);
+BaseComponent.use(FieldCollection, HasValidation);
+
+FieldCollection.defaultTemplate = null;
+
+/**
+ * Registers the render template for FieldCollection.
+ * @param {(description: {
+ *     name: string,
+ *     value: Observable<*[]>,
+ *     hasErrors: Observable<boolean>,
+ *     errors: Observable<string[]>,
+ *     defaultItem: *,
+ *     fieldBuilder: ((fields: FieldCollection, index: number) => NdChild)|null,
+ *     renderItem: ((item: *, index: number) => NdChild)|null,
+ *     renderAdd: (() => NdChild)|null,
+ *     transition: string|null,
+ *     props: GlobalAttributes,
+ * }, instance: FieldCollection) => NdChild} template
+ */
+FieldCollection.use = function(template) {
+    FieldCollection.defaultTemplate = template;
+};
+
+/**
+ * @param {(fields: FieldCollection, index: number) => NdChild} fieldBuilder
+ * @returns {this}
+ */
+FieldCollection.prototype.fields = function(fieldBuilder) {
+    if(typeof fieldBuilder !== 'function') {
+        throw new NativeDocumentError('FieldCollection.fields() expects a function');
+    }
+    this.$description.fieldBuilder = fieldBuilder;
+    return this;
+};
+
+/**
+ * @param {*} defaultItem
+ * @returns {this}
+ */
+FieldCollection.prototype.data = function(defaultItem) {
+    if(typeof defaultItem !== 'function') {
+        throw new NativeDocumentError('FieldCollection.data() expects a factory function');
+    }
+    this.$description.defaultItem = defaultItem;
+    return this;
+};
+
+/**
+ * @param {(item: *, index: number) => NdChild} fn
+ * @returns {this}
+ */
+FieldCollection.prototype.renderItem = function(fn) {
+    this.$description.renderItem = fn;
+    return this;
+};
+
+/**
+ * @param {() => NdChild} fn
+ * @returns {this}
+ */
+FieldCollection.prototype.renderAdd = function(fn) {
+    this.$description.renderAdd = fn;
+    return this;
+};
+
+/**
+ * @param {string} transitionName
+ * @returns {this}
+ */
+FieldCollection.prototype.transition = function(transitionName) {
+    this.$description.transition = transitionName;
+    return this;
+};
+
+/**
+ * @param {Observable<*[]>} observable
+ * @returns {this}
+ */
+FieldCollection.prototype.model = function(observable) {
+    if(Validator.isObservable(observable)) {
+        this.$description.value = observable;
+        this.$description.value.interceptMutations((items) =>
+            items.map(item => Validator.isObservable(item) ? item : $.object(item)),
+        );
+        return this;
+    }
+    this.$description.value.set(observable);
+    return this;
+};
+
+/**
+ * @returns {this}
+ */
+FieldCollection.prototype.add = function() {
+    if(!this.$description.fieldBuilder) {
+        throw new NativeDocumentError('FieldCollection: fields() must be defined before add()');
+    }
+    const raw  = this.$description.defaultItem
+        ? this.$description.defaultItem()
+        : {};
+    const item = Validator.isObservable(raw) ? raw : $.object(raw);
+
+    this.$description.value.push(item);
+    this.emit('add', item);
+    return this;
+};
+
+/**
+ * @param {*} item
+ * @returns {this}
+ */
+FieldCollection.prototype.remove = function(item) {
+    this.$description.value.removeItem(item);
+    this.emit('remove', item);
+    return this;
+};
+
+/**
+ * @returns {this}
+ */
+FieldCollection.prototype.clear = function() {
+    this.$description.value.clear();
+    return this;
+};
+
+/**
+ * @returns {this}
+ */
+FieldCollection.prototype.reset = function() {
+    this.clear();
+    return this;
+};
+
+/**
+ * @returns {*[]}
+ */
+FieldCollection.prototype.value = function() {
+    return this.$description.value.map(item =>
+        Validator.isObservable(item) ? item.val() : item,
+    );
+};
+
+/**
+ * @returns {number}
+ */
+FieldCollection.prototype.count = function() {
+    return this.$description.value.val().length;
+};
+
+/**
+ * @returns {boolean}
+ */
+FieldCollection.prototype.isEmpty = function() {
+    return this.$description.value.val().length === 0;
+};
+
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
+FieldCollection.prototype.onChange = function(handler) {
+    this.on('change', handler);
+    return this;
+};
+
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
+FieldCollection.prototype.onAdd = function(handler) {
+    this.on('add', handler);
+    return this;
+};
+
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
+FieldCollection.prototype.onRemove = function(handler) {
+    this.on('remove', handler);
+    return this;
+};
+
+/**
+ * @param {number} minCount
+ * @param {string} [message]
+ * @returns {this}
+ */
+FieldCollection.prototype.min = function(minCount, message) {
+    return this.addRule(
+        (values) => ({
+            valid:   values.length >= minCount,
+            message: `Minimum ${minCount} item(s) required`,
+        }),
+        [],
+        message,
+    );
+};
+
+/**
+ * @param {number} maxCount
+ * @param {string} [message]
+ * @returns {this}
+ */
+FieldCollection.prototype.max = function(maxCount, message) {
+    return this.addRule(
+        (values) => ({
+            valid:   values.length <= maxCount,
+            message: `Maximum ${maxCount} item(s) allowed`,
+        }),
+        [],
+        message,
+    );
+};
+
+// Override validate
+/**
+ * @param {*} [allValues]
+ * @returns {{ key: string, errors: string[] }}
+ */
+FieldCollection.prototype.validate = function(allValues) {
+    const errors     = [];
+    const rowsValues = this.value();
+
+    if(this.$description.rules) {
+        for(const rule of this.$description.rules) {
+            const result = rule.fn(rowsValues, allValues);
+            if(!result.valid) {
+                errors.push(rule.message || result.message);
+            }
+        }
+    }
+
+    this.$description.errors.set(errors);
+    this.$description.hasErrors.set(errors.length > 0);
+
+    return errors;
+};