@longline/aqua-ui 1.0.0

package/containers/Form/Field.js

@@ -0,0 +1,168 @@
+import * as React from 'react';
+// Other controls
+import { Hint } from './elements/Hint';
+import { Label } from './elements/Label';
+import { BoxWrapper } from './elements/BoxWrapper';
+import { Validation } from './Validation';
+import { SimpleWrapper } from './elements/SimpleWrapper';
+import { useForm } from './context/useForm';
+/**
+ * A `Form.Field` wraps a form control. It serves several purposes.
+ *
+ * * First, the Field automatically adds `name`, `onChange`, `value` and
+ * `error` props to the control it contains. The `onChange` prop is supplied by
+ * the `Form` content so that the developer does not need to add it.
+ *
+ * * Second, the Field performs validation when it is mounted, whenever its
+ * control's value changes, and when it is unmounted. Validation results are
+ * sent directly to the parent `Form` (a form context is used for this -- a
+ * Field must reside inside a form).
+ *
+ * #### Uncontrolled fields
+ * Note that Fields can be used outside of `Form`. These are known as _uncontrolled_.
+ * In this case, the Field can still benefit from a label, hint, and validation
+ * (since Field keeps an internal value), but `onChange` must be provided by
+ * the developer.
+ *
+ * #### Validations
+ * A Form.Field may add any number of validation `rules`, e.g. `required=`.
+ * Rules include `required`, `isInt`, `minLength` etc. When a
+ * field is first mounted, it is _pristine_. Even when its content is invalid,
+ * it will not show any validation error. When the user edits the field, it
+ * will no longer be pristine and any errors will appear. The parent Form also
+ * provides a `dirty` prop to the Field. When the Form is dirty, so are its
+ * fields, and any validation errors are shown, pristine or not.
+ *
+ * For dark backgrounds, fields may set their contrast prop to true to use
+ * lighter error colors.
+ *
+ * Fields have a `label` and a `hint`. Both are optional. These elements are
+ * displayed in different ways based on the field's `wrapper`. Unwrapped Fields
+ * do not display label or hint. Other wrappers are `simple` and `box`.
+ */
+var Field = function (props) {
+    var form = useForm();
+    var ghost = props.ghost || (form && form.ghost);
+    var _a = React.useState(true), pristine = _a[0], setPristine = _a[1];
+    // Current validation. onValidate is only called when validation state changes.
+    // Perform validation immediately:
+    var _b = React.useState(Validation.getValidation(props.value, props.rules)), validation = _b[0], setValidation = _b[1];
+    // Current field value:
+    var _c = React.useState(props.value), value = _c[0], setValue = _c[1];
+    var handleChange = function (value) {
+        // Set state to NOT pristine.
+        setPristine(false);
+        setValue(value);
+        if (form) {
+            form.onChange(props.name, value, !!props.forceupdate);
+        }
+        else if (props.onChange) {
+            props.onChange(value, !!props.forceupdate);
+        }
+    };
+    // Send initial validation on to parent form
+    React.useEffect(function () {
+        if (form)
+            form.onValidate(props.name, validation == null);
+        // When field is unmounted, tell parent form that it is valid.
+        // Otherwise invalid fields remain in the form's validation state.
+        return function () {
+            if (form)
+                form.onValidate(props.name, true);
+        };
+    }, []);
+    React.useEffect(function () {
+        // Set default messages for validation rules.
+        var rules = props.rules;
+        if (!rules)
+            return;
+        if (rules.required && !rules.required.message)
+            rules.required.message = "This field is required.";
+        if (rules.isInt && !rules.isInt.message)
+            rules.isInt.message = "Value must be a whole number.";
+        if (rules.isFloat && !rules.isFloat.message)
+            rules.isFloat.message = "Value must be a valid number.";
+        if (rules.min && !rules.min.message)
+            rules.min.message = "Value must be at least ".concat(rules.min.value, ".");
+        if (rules.max && !rules.max.message)
+            rules.max.message = "Value must be at most ".concat(rules.max.value, ".");
+        if (rules.between && !rules.between.message)
+            rules.between.message = "Value must be between ".concat(rules.between.min, " and ").concat(rules.between.max, ".");
+        if (rules.lengthBetween && !rules.lengthBetween.message)
+            rules.lengthBetween.message = "Length must be between ".concat(rules.lengthBetween.min, " and ").concat(rules.lengthBetween.max, " characters.");
+        if (rules.minLength && !rules.minLength.message)
+            rules.minLength.message = "Length must be at least ".concat(rules.minLength.length, " characters.");
+        if (rules.maxLength && !rules.maxLength.message)
+            rules.maxLength.message = "Length must be at most ".concat(rules.maxLength.length, " characters.");
+        if (rules.pattern && !rules.pattern.message)
+            rules.pattern.message = "Value does not match expected pattern.";
+        if (rules.noPattern && !rules.noPattern.message)
+            rules.noPattern.message = "Value does not match expected pattern.";
+        if (rules.email && !rules.email.message)
+            rules.email.message = "Value must be a valid email address.";
+        if (rules.nofuture && !rules.nofuture.message)
+            rules.nofuture.message = "Date must not be in the future.";
+        if (rules.before && !rules.before.message)
+            rules.before.message = "Date must be before ".concat(rules.before.date, ".");
+        if (rules.after && !rules.after.message)
+            rules.after.message = "Date must be before ".concat(rules.after.date, ".");
+    }, [props.rules]);
+    //
+    // Perform validation when field value changes.
+    //
+    React.useEffect(function () {
+        // Perform validation on field.
+        var newValidation = Validation.getValidation(value, props.rules);
+        // Only notify parent if validation has changed since last validation.
+        if (validation !== newValidation) {
+            setValidation(newValidation);
+            if (form)
+                form.onValidate(props.name, newValidation == null);
+        }
+    }, [value]);
+    // Update local value when value prop changes.
+    React.useEffect(function () {
+        setValue(props.value);
+    }, [props.value]);
+    //
+    // Get field control.
+    //
+    var getControl = function (hasError, transparent) {
+        return React.cloneElement(props.control, {
+            name: props.name,
+            onChange: handleChange,
+            value: props.value, // Changed from just "value", since that breaks TiptapEditor.
+            checked: props.value,
+            error: hasError,
+            disabled: props.disabled,
+            transparent: transparent,
+            ghost: ghost,
+            // If wrapped, set control to fluid. Otherwise use control's fluid setting:
+            fluid: props.wrapper ? true : props.control.fluid
+        });
+    };
+    var getLabel = function () {
+        return props.label &&
+            React.createElement(Label, { required: !!props.rules && !!props.rules.required, asterisk: props.asterisk, disabled: props.disabled }, props.label);
+    };
+    var getHintOrError = function () {
+        if (hasError && validation)
+            return React.createElement(Hint, { ghost: ghost, error: true }, validation);
+        if (props.hint)
+            return React.createElement(Hint, { optional: !props.rules || !props.rules.required, ghost: ghost }, props.hint);
+        return null;
+    };
+    var dirty = form ? form.dirty : !pristine;
+    var hasError = (!pristine || dirty) && validation != null;
+    switch (props.wrapper) {
+        case 'simple':
+            return (React.createElement(SimpleWrapper, { disabled: props.disabled, weight: props.weight, error: hasError, ghost: ghost, label: getLabel(), hint: getHintOrError() }, getControl(hasError)));
+        case 'box':
+            return (React.createElement(BoxWrapper, { disabled: props.disabled, weight: props.weight, error: hasError, ghost: ghost, label: getLabel(), hint: getHintOrError() }, getControl(hasError, true)));
+        default:
+            // A field with no wrapper is just a control. It does benefit from validation.
+            return getControl(hasError);
+    }
+};
+Field.displayName = "Form.Field";
+export { Field };

package/containers/Form/Form.d.ts

@@ -0,0 +1,51 @@
+import * as React from 'react';
+interface IProps {
+    /**
+     * @ignore
+     */
+    children?: React.ReactNode;
+    data: any;
+    /**
+     * Called whenever form data changes.
+     */
+    onChange: (data: any, forceupdate: boolean) => void;
+    /**
+     * Called whenever a field validates. Returns validation state for whole form.
+     */
+    onValidate: (valid: boolean) => void;
+    /**
+     * When a form is dirty, it shows all validation errors, even
+     * on pristine fields.
+     * @default false
+     */
+    dirty?: boolean;
+    /**
+     * If set, ghost state will be applied to all `Field` elements in the form.
+     */
+    ghost?: boolean;
+}
+/**
+ * The `Form` element must be used to wrap all forms. All controls inside a
+ * form must be wrapped in `Form.Field` elements.
+ *
+ * The data that must be shown in the form is provided through the `data` prop,
+ * which should be an object.
+ *
+ * `Form` uses a context to set `onChange` and `onValidate` handlers on all
+ * `Form.Field` elements inside the form, whatever their nesting depth. When
+ * form data is changed, `onChange` is triggered with the new form content.
+ *
+ * The `Form.Field` element keeps its own state so that updates to the form are
+ * reflected without changing the form's `data` prop. This way, should a caller
+ * of `Form` choose to, they may update the form data only when required (such
+ * as when setting the `dirty` flag), which avoid rerendering all form elements
+ * on every interaction.
+ */
+declare const Form: {
+    (props: IProps): React.JSX.Element;
+    Field: {
+        (props: import("./Field").IProps): React.JSX.Element;
+        displayName: string;
+    };
+};
+export { Form, IProps };

package/containers/Form/Form.js

@@ -0,0 +1,89 @@
+import * as React from 'react';
+// Other controls
+import { Field } from './Field';
+import { FormContext } from './context/FormContext';
+/**
+ * The `Form` element must be used to wrap all forms. All controls inside a
+ * form must be wrapped in `Form.Field` elements.
+ *
+ * The data that must be shown in the form is provided through the `data` prop,
+ * which should be an object.
+ *
+ * `Form` uses a context to set `onChange` and `onValidate` handlers on all
+ * `Form.Field` elements inside the form, whatever their nesting depth. When
+ * form data is changed, `onChange` is triggered with the new form content.
+ *
+ * The `Form.Field` element keeps its own state so that updates to the form are
+ * reflected without changing the form's `data` prop. This way, should a caller
+ * of `Form` choose to, they may update the form data only when required (such
+ * as when setting the `dirty` flag), which avoid rerendering all form elements
+ * on every interaction.
+ */
+var Form = function (props) {
+    // Build a form-wide validation object, with 
+    // an entry for each field.
+    var validations = React.useRef(new Map());
+    // Form is assumed to be valid on the outset. When fields are mounted, they'll
+    // run their own validations and notify this form. The validation state may
+    // change then.
+    var _a = React.useState(true), valid = _a[0], setValid = _a[1];
+    var handleChange = function (name, value, forceupdate) {
+        // Break up field name into fields:
+        // E.g. if name is "investigators[0].name"
+        var fields = name.split('.');
+        // .. fields will be: 
+        // * field[0] = "investigators[0]"
+        // * fields[1] = "name"
+        // Start off at the main data object:
+        var current = {};
+        // Loop through fields:
+        fields.forEach(function (field) {
+            // If field has brackets, then set current to 
+            // object that the array index points to:
+            var bracketIdx = field.indexOf('[');
+            if (bracketIdx != -1) {
+                var fieldName = field.substring(0, bracketIdx);
+                var index = parseInt(field.substring(bracketIdx + 1, field.length - 1));
+                current = current[fieldName][index];
+            }
+            // If there are no brackets (which would be the 
+            // case for the last field) then assign the new
+            // value to current.
+            else {
+                current[field] = value;
+            }
+        });
+        // Inform parent of data change:
+        props.onChange(current, forceupdate);
+    };
+    var handleValidate = function (name, _valid) {
+        validations.current.set(name, _valid);
+        var isValid = true;
+        validations.current.forEach(function (x) {
+            isValid = isValid && x;
+        });
+        // Parent component is only notified if validation state changes,
+        // in order to avoid an infinite loop of updates.
+        if (isValid !== valid) {
+            setValid(isValid);
+            props.onValidate(isValid);
+        }
+    };
+    // Test code to show currently-focused element:
+    /*
+      const showActive = () => {
+      console.log(document.activeElement);
+      setTimeout(() => {
+        showActive();
+      }, 1000);
+    }
+    setTimeout(() => { showActive(); }, 1000); */
+    return (React.createElement(FormContext.Provider, { value: {
+            onChange: handleChange,
+            onValidate: handleValidate,
+            dirty: props.dirty,
+            ghost: props.ghost
+        } }, props.children));
+};
+Form.Field = Field;
+export { Form };

package/containers/Form/Validation.d.ts

@@ -0,0 +1,212 @@
+interface IValidation {
+    /**
+     * Validation message. Can be JSX.
+     */
+    message?: React.ReactNode;
+}
+interface IFloatValidation extends IValidation {
+    /**
+     * Optional floating point separator.
+     * @default .
+     */
+    separator?: string;
+}
+interface IValueValidation extends IValidation {
+    /**
+     * Value to check against.
+     */
+    value: number;
+}
+interface IBetweenValidation extends IValidation {
+    /**
+     * Minimum value.
+     */
+    min: number;
+    /**
+     * Maximum value.
+     */
+    max: number;
+}
+interface ILengthValidation extends IValidation {
+    /**
+     * Length value to check against.
+     */
+    length: number;
+}
+interface IPatternValidation extends IValidation {
+    /**
+     * Regular expression pattern to check (as a string).
+     */
+    pattern: string;
+}
+interface IDateValidation extends IValidation {
+    date: string;
+}
+interface IValidationProps {
+    /**
+     * Required validation. Field must be filled out.
+     *
+     * @example
+     * <Field ... required={{message: "Required field"}}>
+     */
+    required?: IValidation;
+    /**
+     * Integer validation.
+     *
+     * @example
+     * <Field ... isInt={{message: "Must be an integer value"}}>
+     */
+    isInt?: IValidation;
+    /**
+     * Float validation.
+     *
+     * @example
+     * <Field ... isFloat={{message: "Must be a float value"}}>
+     */
+    isFloat?: IFloatValidation;
+    /**
+     * Minimum number value validation.
+     *
+     * @example
+     * <Field ... min={{value:3, message: "Must be at least 3."}}>
+     */
+    min?: IValueValidation;
+    /**
+     * Maximum number value validation.
+     *
+     * @example
+     * <Field ... max={{value:100, message: "Must be at most 100."}}>
+     */
+    max?: IValueValidation;
+    /**
+     * Between numbers valdation.
+     *
+     * @example
+     * <Field ... between={{min:3, max:25, message: "Must be 3..25 inclusive"}}>
+     */
+    between?: IBetweenValidation;
+    /**
+     * String length range validation.
+     *
+     * @example
+     * <Field ... lengthBetween={{min: 3, max: 25; message: "Must be 3..25 characters."}}>
+     */
+    lengthBetween?: IBetweenValidation;
+    /**
+     * String length minimum validation.
+     *
+     * @example
+     * <Field ... minLength={{length: 3, message: "Must be at least 3 characters."}}>
+     */
+    minLength?: ILengthValidation;
+    /**
+     * String length maximum validation.
+     *
+     * @example
+     * <Field ... maxLength={{length: 25, message: "Must be no more than 25 characters."}}>
+     */
+    maxLength?: ILengthValidation;
+    /**
+     * Pattern validation.
+     *
+     * @example
+     * <Field ... pattern={{pattern: "a+", message: "Must have pattern a+"}}>
+     */
+    pattern?: IPatternValidation;
+    /**
+     * Negative pattern validation.
+     *
+     * @example
+     * <Field ... noPattern={{pattern: "a+", message: "Must NOT have pattern a+"}}>
+     */
+    noPattern?: IPatternValidation;
+    /**
+     * Email validation.
+     *
+     * @example
+     * <Field ... email={{message: "Must be a valid email address."}}>
+     */
+    email?: IValidation;
+    /**
+     * Date validation: cannot be future date.
+     *
+     * @example
+     * <Field ... nofuture={{message: "Date must not be in the future."}}>
+     */
+    nofuture?: IValidation;
+    /**
+     * Date validation: date must be before or equal to specified date.
+     *
+     * @example
+     * <Field ... before={{day: "2004-01-01", message: "Date must not be before 2004-01-01."}}>
+     */
+    before?: IDateValidation;
+    /**
+     * Date validation: date must be after or equal to specified date.
+     *
+     * @example
+     * <Field ... after={{day: "2004-01-01", message: "Date must not be after 2004-01-01."}}>
+     */
+    after?: IDateValidation;
+}
+declare class Validation {
+    /**
+     * Verify that field has a value.
+     */
+    private static validateRequired;
+    /**
+     * Verify that value is an integer number.
+     */
+    private static validateInt;
+    private static validateFloat;
+    /**
+     * Verify that value has a minimum numerical value.
+     */
+    private static validateMin;
+    /**
+     * Verify that value has a maximum numerical value.
+     */
+    private static validateMax;
+    /**
+     * Verify that value falls in a numerical range (inclusive).
+     */
+    private static validateBetween;
+    /**
+     * Verify that value is a string of minimum length.
+     */
+    private static validateMinLength;
+    /**
+     * Verify that value is a string of maximum length.
+     */
+    private static validateMaxLength;
+    /**
+     * Verify that value is a string of length between minimum and maximum.
+     */
+    private static validateLengthBetween;
+    /**
+     * Verify that value satisfies a pattern.
+     */
+    private static validatePattern;
+    /**
+     * Verify that value does not satisfy a pattern.
+     */
+    private static validateNotPattern;
+    /**
+     * Verify that values is a valid email address.
+     */
+    private static validateEmail;
+    /**
+     * Verify that value is before today.
+     */
+    private static validateNofuture;
+    /**
+     * Verify that value is before date.
+     */
+    private static validateBefore;
+    /**
+     * Verify that value is after date.
+     */
+    private static validateAfter;
+    static getValidation: (value: any, rules: IValidationProps) => React.ReactNode;
+}
+export { IValidationProps, Validation };