envoc-form 4.0.1-9 → 4.2.0

package/lib/DatePicker/StringDateOnlyPickerGroup.js

@@ -16,6 +16,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 var jsx_runtime_1 = require("react/jsx-runtime");
 var DatePickerGroup_1 = __importDefault(require("./DatePickerGroup"));
+/**
+ * Date picker input that consumes and outputs as a date only string in ISO format `YYYY-MM-DD`.
+ *
+ * Default display to the user is in `MM/DD/YYYY` format.
+ */
 function StringDatePickerGroup(props) {
     return (0, jsx_runtime_1.jsx)(DatePickerGroup_1.default, __assign({}, props, { convert: convertToDateOnly }));
 }

package/lib/DatePicker/StringDatePickerGroup.d.ts

@@ -1,5 +1,10 @@
 /// <reference types="react" />
 import { DatePickerHelper } from './DatePickerHelper';
-export interface StringDatePickerGroupProps extends DatePickerHelper<string | undefined> {
+export interface StringDatePickerGroupProps extends DatePickerHelper<string | undefined | null> {
 }
+/**
+ * Date picker input that consumes and outputs as a date only string in ISO format `YYYY-MM-DDTHH:mm:ss.sssZ` or `±YYYYYY-MM-DDTHH:mm:ss.sssZ`
+ *
+ * If you need `YYYY-MM-DD` format use `<StringDateOnlyPickerGroup/>`.
+ */
 export default function StringDatePickerGroup(props: StringDatePickerGroupProps): JSX.Element;

package/lib/DatePicker/StringDatePickerGroup.js

@@ -16,6 +16,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 var jsx_runtime_1 = require("react/jsx-runtime");
 var DatePickerGroup_1 = __importDefault(require("./DatePickerGroup"));
+/**
+ * Date picker input that consumes and outputs as a date only string in ISO format `YYYY-MM-DDTHH:mm:ss.sssZ` or `±YYYYYY-MM-DDTHH:mm:ss.sssZ`
+ *
+ * If you need `YYYY-MM-DD` format use `<StringDateOnlyPickerGroup/>`.
+ */
 function StringDatePickerGroup(props) {
     return (0, jsx_runtime_1.jsx)(DatePickerGroup_1.default, __assign({}, props, { convert: convertToDateOnly }));
 }

package/lib/DateTimePicker/DateTimePickerGroup.d.ts

@@ -0,0 +1,13 @@
+/// <reference types="react" />
+import { DateTimePickerProps } from 'react-datetime-picker';
+import { InjectedFieldProps } from '../Field/InjectedFieldProps';
+import { GroupProps } from '../Group';
+export interface DateTimePickerGroupProps<T> extends InjectedFieldProps<T | undefined | null>, Omit<DateTimePickerProps, keyof InjectedFieldProps<T> | 'name' | 'value' | 'className'>, Omit<GroupProps, keyof InjectedFieldProps<T> | 'children'> {
+    convert: (date: Date) => T;
+}
+/**
+ * Field for inputting date and time. Uses `<Group/>` and `<DateTimePicker/>`.
+ *
+ * Uses [react-datetime-picker](https://www.npmjs.com/package/react-datetime-picker)
+ */
+export default function DateTimePickerGroup<T>({ input, meta, label, helpText, className, required, disabled, convert, ...rest }: DateTimePickerGroupProps<T>): JSX.Element;

package/lib/DateTimePicker/DateTimePickerGroup.js

@@ -0,0 +1,93 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var jsx_runtime_1 = require("react/jsx-runtime");
+var react_1 = require("react");
+var react_datetime_picker_1 = require("react-datetime-picker");
+var classnames_1 = __importDefault(require("classnames"));
+var parseISO_1 = __importDefault(require("date-fns/parseISO"));
+var FormDefaults_1 = require("../FormDefaults");
+var Group_1 = __importDefault(require("../Group"));
+/**
+ * Field for inputting date and time. Uses `<Group/>` and `<DateTimePicker/>`.
+ *
+ * Uses [react-datetime-picker](https://www.npmjs.com/package/react-datetime-picker)
+ */
+function DateTimePickerGroup(_a) {
+    var input = _a.input, meta = _a.meta, label = _a.label, helpText = _a.helpText, className = _a.className, required = _a.required, disabled = _a.disabled, convert = _a.convert, rest = __rest(_a, ["input", "meta", "label", "helpText", "className", "required", "disabled", "convert"]);
+    var _b = (0, react_1.useState)(null), displayDateTime = _b[0], setDisplayDateTime = _b[1];
+    (0, react_1.useEffect)(function () {
+        var inputValue = input.value;
+        if (!inputValue) {
+            setDisplayDateTime(null);
+        }
+        else if (typeof inputValue === 'string') {
+            var parsedDateTime = convertISODateTimeStringToDate(inputValue);
+            setDisplayDateTime(parsedDateTime);
+        }
+        else if (inputValue instanceof Date) {
+            setDisplayDateTime(inputValue);
+        }
+    }, [setDisplayDateTime, input.value]);
+    return ((0, jsx_runtime_1.jsx)(Group_1.default, __assign({ input: input, meta: meta, label: label, helpText: helpText, className: (0, classnames_1.default)(className, FormDefaults_1.FormDefaults.cssClassPrefix + 'date-time-picker'), required: required, disabled: disabled }, { children: (0, jsx_runtime_1.jsx)(react_datetime_picker_1.DateTimePicker, __assign({}, rest, { className: (0, classnames_1.default)(FormDefaults_1.FormDefaults.cssClassPrefix + 'date-time-picker', className), value: displayDateTime, onChange: handleChange })) })));
+    function handleChange(newDateTime) {
+        var onChange = input.onChange;
+        if (onChange === null) {
+            return;
+        }
+        if (!newDateTime) {
+            onChange(undefined);
+            setDisplayDateTime(null);
+            return;
+        }
+        else if (typeof newDateTime === 'string') {
+            var parsedDateTime = (0, parseISO_1.default)(newDateTime);
+            setDisplayDateTime(parsedDateTime);
+            onChange(convert(parsedDateTime));
+        }
+        else if (newDateTime instanceof Date) {
+            setDisplayDateTime(newDateTime);
+            onChange(convert(newDateTime));
+        }
+    }
+}
+exports.default = DateTimePickerGroup;
+function convertISODateTimeStringToDate(isoDateTimeString) {
+    var isoDateTimeRegex = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?)([+-]\d{2}:\d{2}|Z)?$/;
+    var isValidIsoDateTimeString = isoDateTimeRegex.test(isoDateTimeString);
+    if (isValidIsoDateTimeString) {
+        return new Date(isoDateTimeString);
+    }
+    var errorMessage = "Invalid \"date time\" value of ".concat(isoDateTimeString, " provided to DateTimePickerGroup component. Please provide ISO 8601 string that includes the time zone designator. Sample strings: 2022-09-24T:08:54:12+00:00, 2022-09-24T:08:54:12Z, 2022-09-24T:08:54:12.123-05:00");
+    if (process.env.NODE_ENV !== 'production') {
+        throw new Error(errorMessage);
+    }
+    else {
+        console.error(errorMessage);
+    }
+    return null;
+}

package/lib/DateTimePicker/DateTimePickerHelper.d.ts

@@ -0,0 +1,3 @@
+import { DateTimePickerGroupProps } from './DateTimePickerGroup';
+export interface DateTimePickerHelper<T> extends Omit<DateTimePickerGroupProps<T>, 'convert'> {
+}

package/lib/DateTimePicker/DateTimePickerHelper.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/DateTimePicker/StringDateTimePickerGroup.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="react" />
+import { DateTimePickerHelper } from './DateTimePickerHelper';
+export interface StringDateTimePickerGroupProps extends DateTimePickerHelper<string | undefined | null> {
+}
+/**
+ * Date Time picker input that consumes JS Date object and outputs as a date time offset string in ISO format `YYYY-MM-DDTHH:mm:ss.sss±hh:mm`.
+ *
+ * Default display to the user is in `MM/DD/YYYY HH:mm:ss AM/PM` format.
+ */
+export default function StringDateTimePickerGroup(props: StringDateTimePickerGroupProps): JSX.Element;

package/lib/DateTimePicker/StringDateTimePickerGroup.js

@@ -0,0 +1,59 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var jsx_runtime_1 = require("react/jsx-runtime");
+var DateTimePickerGroup_1 = __importDefault(require("./DateTimePickerGroup"));
+/**
+ * Date Time picker input that consumes JS Date object and outputs as a date time offset string in ISO format `YYYY-MM-DDTHH:mm:ss.sss±hh:mm`.
+ *
+ * Default display to the user is in `MM/DD/YYYY HH:mm:ss AM/PM` format.
+ */
+function StringDateTimePickerGroup(props) {
+    return (0, jsx_runtime_1.jsx)(DateTimePickerGroup_1.default, __assign({}, props, { convert: convertToISOString }));
+}
+exports.default = StringDateTimePickerGroup;
+function convertToISOString(date) {
+    // Get the offset in minutes
+    var offsetMinutes = date.getTimezoneOffset();
+    // Calculate the offset in hours and minutes
+    var offsetHours = Math.floor(Math.abs(offsetMinutes) / 60);
+    var offsetMinutesPart = Math.abs(offsetMinutes) % 60;
+    // Format the offset in the required format (+/-hh:mm)
+    var offsetString = (offsetMinutes >= 0 ? '-' : '+') +
+        String(offsetHours).padStart(2, '0') +
+        ':' +
+        String(offsetMinutesPart).padStart(2, '0');
+    // Format the date in the required format using `intl.DateTimeFormat`
+    var year = new Intl.DateTimeFormat('en', { year: 'numeric' })
+        .format(date)
+        .padStart(4, '0');
+    var month = new Intl.DateTimeFormat('en', { month: '2-digit' }).format(date);
+    var day = new Intl.DateTimeFormat('en', { day: '2-digit' }).format(date);
+    var hour = new Intl.DateTimeFormat('en', {
+        hour: '2-digit',
+        hourCycle: 'h23',
+    }).format(date);
+    var minute = new Intl.DateTimeFormat('en', { minute: '2-digit' })
+        .format(date)
+        .padStart(2, '0');
+    var second = new Intl.DateTimeFormat('en', {
+        second: '2-digit',
+        fractionalSecondDigits: 3,
+    })
+        .format(date)
+        .padStart(6, '0');
+    return "".concat(year, "-").concat(month, "-").concat(day, "T").concat(hour, ":").concat(minute, ":").concat(second).concat(offsetString);
+}

package/lib/Field/Field.d.ts

@@ -2,21 +2,27 @@ import { ComponentProps, ElementType, LegacyRef } from 'react';
 import { InjectedFieldProps } from './InjectedFieldProps';
 import { NormalizationFunction } from '../Normalization/NormalizationFunction';
 import { ValidationFunction } from '../Validation/ValidationFunction';
-export declare type RenderComponent<TValue, TRenderComponent extends ElementType> = Partial<ComponentProps<TRenderComponent>> extends Partial<InjectedFieldProps<TValue | undefined>> ? TRenderComponent : never;
-export declare type RenderComponentProps<TValue, TRenderComponent extends ElementType> = Partial<ComponentProps<TRenderComponent>> extends Partial<InjectedFieldProps<TValue | undefined>> ? ComponentProps<TRenderComponent> : never;
+export declare type RenderComponent<TValue, TRenderComponent extends ElementType> = Partial<ComponentProps<TRenderComponent>> extends Partial<InjectedFieldProps<TValue | undefined | null>> ? TRenderComponent : never;
+export declare type RenderComponentProps<TValue, TRenderComponent extends ElementType> = Partial<ComponentProps<TRenderComponent>> extends Partial<InjectedFieldProps<TValue | undefined | null>> ? ComponentProps<TRenderComponent> : never;
 /** A specific Field instance to be rendered by the given TRenderComponent or by whatever default is reasonable */
 export declare type FieldProps<TForm extends object, TProp extends keyof TForm, TRenderComponent extends ElementType> = {
+    /** Name of the field. Used on submission. */
     name: TProp;
+    /** Component to be rendered. Usually this is a type of input group e.g. `<StringInputGroup/>` */
     Component: RenderComponent<TForm[TProp], TRenderComponent>;
+    /** Id of the field. */
     id?: string;
+    /** Whether the field should be disabled. */
     disabled?: boolean;
+    /** Client side validation functions */
     validate?: ValidationFunction<TForm[TProp]> | ValidationFunction<TForm[TProp]>[];
+    /** Function to modify the field value without making the form dirty. (e.g. phone number) */
     normalize?: NormalizationFunction<TForm[TProp]>;
 } & Omit<RenderComponentProps<TForm[TProp], TRenderComponent>, keyof InjectedFieldProps<TForm[TProp]>>;
 /**
  * Renders whatever Component is passed - injecting the formik values needed to finish wiring up that individual field.
  * Should no Component be used then the default will be provided by the default lookup based on typeof(TForm[TProp])
  */
-declare function Field<TForm extends object, TProp extends keyof TForm, TRenderComponent extends ElementType>({ name, Component, id, normalize, validate, disabled, ...rest }: FieldProps<TForm, TProp, TRenderComponent>, ref: LegacyRef<any>): JSX.Element;
+declare function Field<TForm extends object, TProp extends keyof TForm, TRenderComponent extends ElementType>({ name, Component, id, disabled, validate, normalize, ...rest }: FieldProps<TForm, TProp, TRenderComponent>, ref: LegacyRef<any>): JSX.Element;
 declare const _default: typeof Field;
 export default _default;

package/lib/Field/Field.js

@@ -29,22 +29,27 @@ var jsx_runtime_1 = require("react/jsx-runtime");
 var react_1 = __importDefault(require("react"));
 var FieldNameContext_1 = require("./FieldNameContext");
 var useStandardField_1 = __importDefault(require("./useStandardField"));
+var validators_1 = require("../Validation/validators");
 /**
  * Renders whatever Component is passed - injecting the formik values needed to finish wiring up that individual field.
  * Should no Component be used then the default will be provided by the default lookup based on typeof(TForm[TProp])
  */
 function Field(_a, ref) {
-    var name = _a.name, Component = _a.Component, id = _a.id, normalize = _a.normalize, validate = _a.validate, disabled = _a.disabled, rest = __rest(_a, ["name", "Component", "id", "normalize", "validate", "disabled"]);
+    var name = _a.name, Component = _a.Component, id = _a.id, disabled = _a.disabled, validate = _a.validate, normalize = _a.normalize, rest = __rest(_a, ["name", "Component", "id", "disabled", "validate", "normalize"]);
     var _b = (0, useStandardField_1.default)({
         name: String(name),
         id: id,
-        normalize: normalize,
-        validate: validate,
         disabled: disabled,
+        validate: validate,
+        normalize: normalize,
     }), input = _b[0], meta = _b[1];
+    var isRequired = (rest === null || rest === void 0 ? void 0 : rest.required) !== undefined
+        ? rest.required
+        : validate === validators_1.required ||
+            (Array.isArray(validate) && validate.includes(validators_1.required));
     // a bit of a hack so JSX is happy with us
     var Wrapped = Component;
-    return ((0, jsx_runtime_1.jsx)(FieldNameContext_1.FieldNameContext.Provider, __assign({ value: input.name }, { children: (0, jsx_runtime_1.jsx)(Wrapped, __assign({}, rest, { ref: ref, id: input.id, input: input, meta: meta, disabled: disabled })) })));
+    return ((0, jsx_runtime_1.jsx)(FieldNameContext_1.FieldNameContext.Provider, __assign({ value: input.name }, { children: (0, jsx_runtime_1.jsx)(Wrapped, __assign({}, rest, { ref: ref, id: input.id, input: input, meta: meta, required: isRequired, disabled: disabled })) })));
 }
 // hack to get forwarded refs to work
 var FieldWithRef = react_1.default.forwardRef(Field);

package/lib/Field/FieldErrorScrollTarget.d.ts

@@ -1,2 +1,3 @@
 /// <reference types="react" />
+/** Hidden `<div/>` that acts as an anchor to scroll to when a form error occurs. */
 export default function FieldErrorScrollTarget(): JSX.Element | null;

package/lib/Field/FieldErrorScrollTarget.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 var jsx_runtime_1 = require("react/jsx-runtime");
 var react_1 = require("react");
 var FieldNameContext_1 = require("./FieldNameContext");
+/** Hidden `<div/>` that acts as an anchor to scroll to when a form error occurs. */
 function FieldErrorScrollTarget() {
     var name = (0, react_1.useContext)(FieldNameContext_1.FieldNameContext);
     if (!name) {

package/lib/Field/StandAloneInput.d.ts

@@ -2,8 +2,12 @@ import { ElementType } from 'react';
 import { RenderComponent, RenderComponentProps } from './Field';
 import { InjectedFieldProps } from './InjectedFieldProps';
 export declare type StandAloneInputProps<TValue, TRenderComponent extends ElementType> = {
+    /** Component to render inside of the field. */
     Component: RenderComponent<TValue, TRenderComponent>;
+    /** Value of the field. */
     value: TValue;
+    /** Function to change the value of the field. */
     onChange: (arg: TValue) => void;
 } & Omit<RenderComponentProps<TValue, TRenderComponent>, keyof InjectedFieldProps<TValue> | 'value' | 'onChange' | 'normalize' | 'validate'>;
+/** The stand alone version of `<Field/>`. Can use a type of input component outside of a `<Form/>`. */
 export default function StandAloneInput<TValue, TComponent extends ElementType>(props: StandAloneInputProps<TValue, TComponent>): JSX.Element;

package/lib/Field/StandAloneInput.js

@@ -48,6 +48,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 var jsx_runtime_1 = require("react/jsx-runtime");
 var react_1 = require("react");
 var uuid = __importStar(require("uuid"));
+/** The stand alone version of `<Field/>`. Can use a type of input component outside of a `<Form/>`. */
 function StandAloneInput(props) {
     var Component = props.Component, value = props.value, onChange = props.onChange, disabled = props.disabled, rest = __rest(props, ["Component", "value", "onChange", "disabled"]);
     var handleChange = function (arg) {

package/lib/Field/useStandardField.d.ts

@@ -3,12 +3,18 @@ import { CustomFieldMetaProps } from './CustomFieldMetaProps';
 import { NormalizationFunction } from '../Normalization/NormalizationFunction';
 import { ValidationFunction } from '../Validation/ValidationFunction';
 export interface useStandardFieldProps<TValue> {
+    /** Id of the field. */
     id?: string;
+    /** Name of the field. */
     name: string;
+    /** Whether the field should be disabled. */
     disabled?: boolean;
+    /** Function to validate the field. */
     validate?: ValidationFunction<TValue> | ValidationFunction<TValue>[];
+    /** Function to modify the field value without making the form dirty. (e.g. phone number) */
     normalize?: NormalizationFunction<TValue>;
 }
+/** Provides a consistent way to deal with all form fields (non array). */
 export default function useStandardField<TValue>({ id: providedId, name: providedName, disabled, validate, normalize, }: useStandardFieldProps<TValue>): [
     CustomFieldInputProps<TValue>,
     CustomFieldMetaProps<TValue>

package/lib/Field/useStandardField.js

@@ -15,7 +15,7 @@ var react_1 = require("react");
 var formik_1 = require("formik");
 var FieldNameContext_1 = require("./FieldNameContext");
 var ServerErrorContext_1 = require("../Form/ServerErrorContext");
-// provides a consistent way to deal with all form fields (non array)
+/** Provides a consistent way to deal with all form fields (non array). */
 function useStandardField(_a) {
     var providedId = _a.id, providedName = _a.name, disabled = _a.disabled, validate = _a.validate, normalize = _a.normalize;
     // because the formik errors are evaluated all at the same time we need to keep server errors separate
@@ -39,20 +39,19 @@ function useStandardField(_a) {
         disabled: disabled,
         validate: callAllValidators,
     }), formikInput = _c[0], formikMeta = _c[1];
-    var _d = (0, formik_1.useFormikContext)(), setFieldValue = _d.setFieldValue, isSubmitting = _d.isSubmitting;
+    var _d = (0, formik_1.useFormikContext)(), setFieldTouched = _d.setFieldTouched, setFieldValue = _d.setFieldValue, isSubmitting = _d.isSubmitting;
     var touched = formikMeta.touched !== false && formikMeta.touched !== undefined;
     (0, react_1.useEffect)(function () {
         if (!touched && isSubmitting) {
             // because we do not always register all fields up front.
             // e.g. formik expects even a 'create' form to have all fields given, at least, blank values
-            // that seems to be how it touches on submit:
-            // see: https://codesandbox.io/s/formik-example-4n7n8 vs https://codesandbox.io/s/formik-example-kttk5
-            // note in particular the change in line 24
-            // thus, we manually touch all fields here by calling onBlur
-            // there is a "setFieldTouched" from useFormikContext but it doesn't appear to work on field arrays
-            handleBlur();
+            // It looks like this was going to be a thing: https://github.com/jaredpalmer/formik/issues/691
+            // Formik appears to not have an active maintainer: https://github.com/jaredpalmer/formik/discussions/3526
+            // We previously had a different fix in place using handleBlur, but it was causing an infinite update cycle.
+            // This was noted as existing, but there was a note about it not working for FieldArray (this does appear to work in my testing with FieldArray)
+            setFieldTouched(name);
         }
-    });
+    }, [isSubmitting, name, setFieldTouched, touched]);
     // these are the props we expect consumers of this hook to pass directly to the input (or other control)
     var resultInput = {
         name: formikInput.name,

package/lib/FieldArray/FieldArray.d.ts

@@ -1,15 +1,24 @@
 import { ElementType } from 'react';
 import { FieldProps } from '../Field/Field';
 import { ValidationFunction } from '../Validation/ValidationFunction';
-export declare type FieldArrayProps<TForm extends object, TProp extends keyof TForm> = TForm[TProp] extends Array<any> | undefined ? {
+export declare type FieldArrayProps<TForm extends object, TProp extends keyof TForm> = TForm[TProp] extends Array<any> | undefined | null ? {
+    /** Name of the field, used on submission. If using codegen this must be the provided dto. */
     name: TProp;
+    /** Label of the field. */
     label?: string;
+    /** Whether the field should be disabled. */
     disabled?: boolean;
+    /** Function to validate the value. */
     validate?: ValidationFunction<TForm[TProp]> | ValidationFunction<TForm[TProp]>[];
     children: (formBuilder: ArrayFormBuilderProp<TForm[TProp]>) => JSX.Element;
 } : never;
-export declare type ArrayFormBuilderProp<TValue extends Array<any> | undefined> = TValue extends Array<infer TForm> | undefined ? TForm extends object ? {
+export declare type ArrayFormBuilderProp<TValue extends Array<any> | undefined | null> = TValue extends Array<infer TForm> | undefined | null ? TForm extends object ? {
     Field: <TProp extends keyof TForm, TRenderComponent extends ElementType>(props: FieldProps<TForm, TProp, TRenderComponent>) => JSX.Element;
     FieldArray: <TProp extends keyof TForm>(props: FieldArrayProps<TForm, TProp>) => JSX.Element;
 } : never : never;
+/**
+ * An array of fields that allows the user to add multiple instances of the same field.
+ *
+ * Includes "Add Item" and "Remove Item" buttons to allow the user to speicify the number of fields.
+ */
 export default function FieldArray<TForm extends object, TProp extends keyof TForm>({ name, label, validate, disabled, children, ...rest }: FieldArrayProps<TForm, TProp>): JSX.Element;

package/lib/FieldArray/FieldArray.js

@@ -40,14 +40,19 @@ var Field_1 = __importDefault(require("../Field/Field"));
 var FieldNameContext_1 = require("../Field/FieldNameContext");
 var useStandardField_1 = __importDefault(require("../Field/useStandardField"));
 var FormDefaults_1 = require("../FormDefaults");
+/**
+ * An array of fields that allows the user to add multiple instances of the same field.
+ *
+ * Includes "Add Item" and "Remove Item" buttons to allow the user to speicify the number of fields.
+ */
 function FieldArray(_a) {
     var _b;
     var name = _a.name, label = _a.label, validate = _a.validate, disabled = _a.disabled, children = _a.children, rest = __rest(_a, ["name", "label", "validate", "disabled", "children"]);
-    var _c = (0, useStandardField_1.default)({
+    var input = (0, useStandardField_1.default)({
         name: String(name),
         validate: validate,
         disabled: disabled,
-    }), input = _c[0], meta = _c[1];
+    })[0];
     var values = !input.value
         ? []
         : Array.isArray(input.value)

package/lib/File/FileGroup.d.ts

@@ -1,8 +1,10 @@
 import React from 'react';
 import { InjectedFieldProps } from '../Field/InjectedFieldProps';
 import { GroupProps } from '../Group';
-export interface FileGroupProps extends InjectedFieldProps<any | undefined>, Omit<GroupProps, keyof InjectedFieldProps<any> | 'children'>, Omit<React.HTMLProps<HTMLInputElement>, keyof InjectedFieldProps<any> | 'children' | 'className' | 'label'> {
+export interface FileGroupProps extends InjectedFieldProps<any | undefined | null>, Omit<GroupProps, keyof InjectedFieldProps<any> | 'children'>, Omit<React.HTMLProps<HTMLInputElement>, keyof InjectedFieldProps<any> | 'children' | 'className' | 'label'> {
+    /** Allow multiple files to be uploaded. */
     multiple?: boolean | undefined;
 }
+/** File upload input group.  */
 declare const FileGroupWithRef: React.ComponentType<FileGroupProps>;
 export default FileGroupWithRef;

package/lib/File/FileGroup.js

@@ -29,12 +29,12 @@ var jsx_runtime_1 = require("react/jsx-runtime");
 var react_1 = __importDefault(require("react"));
 var classnames_1 = __importDefault(require("classnames"));
 var FileList_1 = __importDefault(require("./FileList"));
-var Group_1 = __importDefault(require("../Group"));
 var FormDefaults_1 = require("../FormDefaults");
+var Group_1 = __importDefault(require("../Group"));
 function FileGroup(_a, ref) {
     var _b;
-    var input = _a.input, meta = _a.meta, label = _a.label, helpText = _a.helpText, className = _a.className, multiple = _a.multiple, rest = __rest(_a, ["input", "meta", "label", "helpText", "className", "multiple"]);
-    return ((0, jsx_runtime_1.jsxs)(Group_1.default, __assign({ input: input, meta: meta, label: label, helpText: helpText, className: (0, classnames_1.default)(className, (_b = {}, _b[FormDefaults_1.FormDefaults.cssClassPrefix + 'multiple'] = multiple, _b), FormDefaults_1.FormDefaults.cssClassPrefix + 'file-group') }, { children: [(0, jsx_runtime_1.jsx)("input", __assign({}, input, rest, { multiple: multiple, onChange: function (e) {
+    var input = _a.input, meta = _a.meta, label = _a.label, helpText = _a.helpText, className = _a.className, required = _a.required, disabled = _a.disabled, multiple = _a.multiple, rest = __rest(_a, ["input", "meta", "label", "helpText", "className", "required", "disabled", "multiple"]);
+    return ((0, jsx_runtime_1.jsxs)(Group_1.default, __assign({ input: input, meta: meta, label: label, helpText: helpText, className: (0, classnames_1.default)(className, (_b = {}, _b[FormDefaults_1.FormDefaults.cssClassPrefix + 'multiple'] = multiple, _b), FormDefaults_1.FormDefaults.cssClassPrefix + 'file-group'), required: required, disabled: disabled }, { children: [(0, jsx_runtime_1.jsx)("input", __assign({}, input, rest, { multiple: multiple, onChange: function (e) {
                     var _a, _b;
                     if (!((_b = (_a = e === null || e === void 0 ? void 0 : e.target) === null || _a === void 0 ? void 0 : _a.files) === null || _b === void 0 ? void 0 : _b.length)) {
                         input.onChange(undefined);
@@ -53,5 +53,6 @@ function FileGroup(_a, ref) {
                     }
                 }, value: undefined, ref: ref, type: "file", className: (0, classnames_1.default)(className, FormDefaults_1.FormDefaults.cssClassPrefix + 'file-group') })), (0, jsx_runtime_1.jsx)(FileList_1.default, { files: input.value })] })));
 }
+/** File upload input group.  */
 var FileGroupWithRef = react_1.default.forwardRef(FileGroup);
 exports.default = FileGroupWithRef;

package/lib/File/FileList.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="react" />
 export interface FileListProps {
-    files?: File | File[] | undefined;
-    rejectedFiles?: File | File[] | undefined;
+    files?: File | File[] | undefined | null;
+    rejectedFiles?: File | File[] | undefined | null;
 }
 export default function FileList({ files, rejectedFiles }: FileListProps): JSX.Element;

package/lib/Form/FocusError.d.ts

@@ -1,5 +1,7 @@
 import { ServerErrorContextProps } from './ServerErrorContext';
 export interface FocusErrorProps {
+    /** Validation errors that have been received from the server. */
     serverErrors: ServerErrorContextProps;
 }
+/** Function to scroll to the field that has an error. */
 export default function FocusError(props: FocusErrorProps): null;

package/lib/Form/FocusError.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 var react_1 = require("react");
 var formik_1 = require("formik");
 var smoothscroll_polyfill_1 = __importDefault(require("smoothscroll-polyfill"));
+/** Function to scroll to the field that has an error. */
 function FocusError(props) {
     var _a = (0, formik_1.useFormikContext)(), errors = _a.errors, isSubmitting = _a.isSubmitting, isValidating = _a.isValidating;
     smoothscroll_polyfill_1.default.polyfill();

package/lib/Form/Form.d.ts

@@ -8,18 +8,24 @@ export declare type FormBuilderProp<TForm extends object> = {
     FieldArray: <TProp extends keyof TForm>(props: FieldArrayProps<TForm, TProp>) => JSX.Element;
 };
 export interface FullFormProps<TForm extends object> {
+    /** The `<Field/>` and `<FieldArray/>` components. */
     children: (formBuilder: FormBuilderProp<TForm>) => JSX.Element;
+    /** Submission handler  */
     onSubmit: (formValues: TForm, formikBag: FormikHelpers<TForm>) => Promise<ValidatedApiResult>;
+    /** Submission handler for forms that use [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData).*/
     onFormDataSubmit: (formValues: FormData, formikBag: FormikHelpers<TForm>) => Promise<ValidatedApiResult>;
     className?: string;
     style?: CSSProperties;
+    /** Prevent the user from leaving the form if they have edited any field. This is presented as a JS `alert()`. */
     ignoreLostChanges?: boolean;
+    /** The intitial values of the form. */
     initialValues?: TForm;
 }
 declare type RequireAtLeastOne<T, Keys extends keyof T = keyof T> = Pick<T, Exclude<keyof T, Keys>> & {
     [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>>;
 }[Keys];
 export declare type FormProps<TForm extends object> = RequireAtLeastOne<FullFormProps<TForm>, 'onSubmit' | 'onFormDataSubmit'>;
+/** Define a form. Uses [formik](https://formik.org/docs/overview). Usually contains many `<Field/>` components. */
 declare function Form<TForm extends object>({ children, className, style, ignoreLostChanges, onSubmit, onFormDataSubmit, initialValues, ...props }: FormProps<TForm>): JSX.Element;
 declare namespace Form {
     var DisplayFormState: () => JSX.Element;

package/lib/Form/Form.js

@@ -37,6 +37,7 @@ var FieldArray_1 = __importDefault(require("../FieldArray/FieldArray"));
 var FormDefaults_1 = require("../FormDefaults");
 var objectContainsNonSerializableProperty_1 = __importDefault(require("../utils/objectContainsNonSerializableProperty"));
 var objectToFormData_1 = __importDefault(require("../utils/objectToFormData"));
+/** Define a form. Uses [formik](https://formik.org/docs/overview). Usually contains many `<Field/>` components. */
 function Form(_a) {
     var children = _a.children, className = _a.className, style = _a.style, ignoreLostChanges = _a.ignoreLostChanges, onSubmit = _a.onSubmit, onFormDataSubmit = _a.onFormDataSubmit, initialValues = _a.initialValues, props = __rest(_a, ["children", "className", "style", "ignoreLostChanges", "onSubmit", "onFormDataSubmit", "initialValues"]);
     // formik resets all error on each blur (with our settings)

package/lib/Form/FormBasedPreventNavigation.d.ts

@@ -1,5 +1,7 @@
+/// <reference types="react" />
 export interface FormBasedPreventNavigationProps {
     ignoreLostChanges?: boolean;
     promptMessage?: string;
 }
-export default function FormBasedPreventNavigation({ ignoreLostChanges, promptMessage, }: FormBasedPreventNavigationProps): null;
+/** Prevent the user from navigating away from a form if there are any changes. */
+export default function FormBasedPreventNavigation({ ignoreLostChanges, promptMessage, }: FormBasedPreventNavigationProps): JSX.Element;