envoc-form 4.0.1-9 → 4.2.0

package/src/DateTimePicker/__snapshots__/DateTimePicker.test.tsx.snap

@@ -0,0 +1,216 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`StringDateTimePickerGroup has matching snapshot 1`] = `
+<DocumentFragment>
+  <form
+    action="#"
+    class="envoc-form-form"
+  >
+    <div
+      class="envoc-form-date-time-picker envoc-form-group"
+    >
+      <div
+        id="createddatetime-error-scroll-target"
+        style="display: none;"
+      />
+      <label
+        for="createdDateTime"
+      >
+        Created Date Time
+      </label>
+      <div
+        class="react-datetime-picker react-datetime-picker--closed react-datetime-picker--enabled envoc-form-date-time-picker"
+        id="createdDateTime"
+      >
+        <div
+          class="react-datetime-picker__wrapper"
+        >
+          <div
+            class="react-datetime-picker__inputGroup"
+          >
+            <input
+              hidden=""
+              max="2023-09-23T00:00"
+              min="2022-06-22T00:00"
+              name="datetime"
+              step="60"
+              style="visibility: hidden; position: absolute; z-index: -999;"
+              type="datetime-local"
+              value=""
+            />
+            <input
+              autocomplete="off"
+              class="react-datetime-picker__inputGroup__input react-datetime-picker__inputGroup__month"
+              data-input="true"
+              inputmode="numeric"
+              max="12"
+              min="1"
+              name="month"
+              placeholder="mm"
+              type="number"
+              value=""
+            />
+            <span
+              class="react-datetime-picker__inputGroup__divider"
+            >
+              /
+            </span>
+            <input
+              autocomplete="off"
+              class="react-datetime-picker__inputGroup__input react-datetime-picker__inputGroup__day"
+              data-input="true"
+              inputmode="numeric"
+              max="31"
+              min="1"
+              name="day"
+              placeholder="dd"
+              type="number"
+              value=""
+            />
+            <span
+              class="react-datetime-picker__inputGroup__divider"
+            >
+              /
+            </span>
+            <input
+              autocomplete="off"
+              class="react-datetime-picker__inputGroup__input react-datetime-picker__inputGroup__year"
+              data-input="true"
+              inputmode="numeric"
+              max="2023"
+              min="2022"
+              name="year"
+              placeholder="yyyy"
+              step="1"
+              type="number"
+              value=""
+            />
+            <span
+              class="react-datetime-picker__inputGroup__divider"
+            >
+               
+            </span>
+            <input
+              autocomplete="off"
+              class="react-datetime-picker__inputGroup__input react-datetime-picker__inputGroup__hour"
+              data-input="true"
+              inputmode="numeric"
+              max="12"
+              min="1"
+              name="hour12"
+              placeholder="--"
+              type="number"
+              value=""
+            />
+            <span
+              class="react-datetime-picker__inputGroup__divider"
+            >
+              :
+            </span>
+            <input
+              autocomplete="off"
+              class="react-datetime-picker__inputGroup__input react-datetime-picker__inputGroup__minute"
+              data-input="true"
+              inputmode="numeric"
+              max="59"
+              min="0"
+              name="minute"
+              placeholder="--"
+              type="number"
+              value=""
+            />
+            <span
+              class="react-datetime-picker__inputGroup__divider"
+            >
+               
+            </span>
+            <select
+              class="react-datetime-picker__inputGroup__input react-datetime-picker__inputGroup__amPm"
+              data-input="true"
+              data-select="true"
+              name="amPm"
+            >
+              <option
+                value=""
+              >
+                --
+              </option>
+              <option
+                value="am"
+              >
+                AM
+              </option>
+              <option
+                value="pm"
+              >
+                PM
+              </option>
+            </select>
+          </div>
+          <button
+            class="react-datetime-picker__clear-button react-datetime-picker__button"
+            type="button"
+          >
+            <svg
+              class="react-datetime-picker__clear-button__icon react-datetime-picker__button__icon"
+              height="19"
+              stroke="black"
+              stroke-width="2"
+              viewBox="0 0 19 19"
+              width="19"
+              xmlns="http://www.w3.org/2000/svg"
+            >
+              <line
+                x1="4"
+                x2="15"
+                y1="4"
+                y2="15"
+              />
+              <line
+                x1="15"
+                x2="4"
+                y1="4"
+                y2="15"
+              />
+            </svg>
+          </button>
+          <button
+            class="react-datetime-picker__calendar-button react-datetime-picker__button"
+            type="button"
+          >
+            <svg
+              class="react-datetime-picker__calendar-button__icon react-datetime-picker__button__icon"
+              height="19"
+              stroke="black"
+              stroke-width="2"
+              viewBox="0 0 19 19"
+              width="19"
+              xmlns="http://www.w3.org/2000/svg"
+            >
+              <rect
+                fill="none"
+                height="15"
+                width="15"
+                x="2"
+                y="2"
+              />
+              <line
+                x1="6"
+                x2="6"
+                y1="0"
+                y2="4"
+              />
+              <line
+                x1="13"
+                x2="13"
+                y1="0"
+                y2="4"
+              />
+            </svg>
+          </button>
+        </div>
+      </div>
+    </div>
+  </form>
+</DocumentFragment>
+`;

package/src/Field/Field.tsx

@@ -4,6 +4,7 @@ import { InjectedFieldProps } from './InjectedFieldProps';
 import useStandardFormInput from './useStandardField';
 import { NormalizationFunction } from '../Normalization/NormalizationFunction';
 import { ValidationFunction } from '../Validation/ValidationFunction';
+import { required as requiredValidator } from '../Validation/validators';
 
 // we attempted to support generic components but failed
 // so, we assume the actual TRenderComponent has no generic arguments
@@ -13,7 +14,7 @@ export type RenderComponent<
   TValue,
   TRenderComponent extends ElementType
 > = Partial<ComponentProps<TRenderComponent>> extends Partial<
-  InjectedFieldProps<TValue | undefined>
+  InjectedFieldProps<TValue | undefined | null>
 >
   ? TRenderComponent
   : never;
@@ -22,7 +23,7 @@ export type RenderComponentProps<
   TValue,
   TRenderComponent extends ElementType
 > = Partial<ComponentProps<TRenderComponent>> extends Partial<
-  InjectedFieldProps<TValue | undefined>
+  InjectedFieldProps<TValue | undefined | null>
 >
   ? ComponentProps<TRenderComponent>
   : never;
@@ -33,14 +34,19 @@ export type FieldProps<
   TProp extends keyof TForm,
   TRenderComponent extends ElementType
 > = {
+  /** Name of the field. Used on submission. */
   name: TProp; // somewhat duplicated from useStandardFormInputProps but better for autocomplete
+  /** 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>,
@@ -60,9 +66,9 @@ function Field<
     name,
     Component,
     id,
-    normalize,
-    validate,
     disabled,
+    validate,
+    normalize,
     ...rest
   }: FieldProps<TForm, TProp, TRenderComponent>,
   ref: LegacyRef<any>
@@ -70,11 +76,17 @@ function Field<
   const [input, meta] = useStandardFormInput<TForm[TProp]>({
     name: String(name),
     id: id,
-    normalize: normalize,
-    validate: validate,
     disabled: disabled,
+    validate: validate,
+    normalize: normalize,
   });
 
+  const isRequired =
+    rest?.required !== undefined
+      ? rest.required
+      : validate === requiredValidator ||
+        (Array.isArray(validate) && validate.includes(requiredValidator));
+
   // a bit of a hack so JSX is happy with us
   const Wrapped = Component as React.ComponentType<
     InjectedFieldProps<TForm[TProp]>
@@ -88,6 +100,7 @@ function Field<
         id={input.id}
         input={input}
         meta={meta}
+        required={isRequired}
         disabled={disabled}
       />
     </FieldNameContext.Provider>

package/src/Field/FieldErrorScrollTarget.tsx

@@ -1,6 +1,7 @@
 import { useContext } from 'react';
 import { FieldNameContext } from './FieldNameContext';
 
+/** Hidden `<div/>` that acts as an anchor to scroll to when a form error occurs. */
 export default function FieldErrorScrollTarget() {
   const name = useContext(FieldNameContext);
   if (!name) {

package/src/Field/StandAloneInput.tsx

@@ -9,8 +9,11 @@ export 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>,
@@ -21,6 +24,7 @@ export type StandAloneInputProps<
   | '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>
 ) {

package/src/Field/useStandardField.ts

@@ -8,14 +8,19 @@ 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)
+/** Provides a consistent way to deal with all form fields (non array). */
 export default function useStandardField<TValue>({
   id: providedId,
   name: providedName,
@@ -51,7 +56,7 @@ export default function useStandardField<TValue>({
     disabled: disabled,
     validate: callAllValidators,
   });
-  const { setFieldValue, isSubmitting } = useFormikContext();
+  const { setFieldTouched, setFieldValue, isSubmitting } = useFormikContext();
 
   const touched =
     formikMeta.touched !== false && formikMeta.touched !== undefined;
@@ -59,14 +64,13 @@ export default function useStandardField<TValue>({
     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)
   const resultInput: CustomFieldInputProps<TValue> = {

package/src/FieldArray/FieldArray.tsx

@@ -3,17 +3,21 @@ import classNames from 'classnames';
 import Field, { FieldProps } from '../Field/Field';
 import { FieldNameContext } from '../Field/FieldNameContext';
 import useStandardFormInput from '../Field/useStandardField';
-import { ValidationFunction } from '../Validation/ValidationFunction';
 import { FormDefaults } from '../FormDefaults';
+import { ValidationFunction } from '../Validation/ValidationFunction';
 
 export type FieldArrayProps<
   TForm extends object,
   TProp extends keyof TForm
-> = TForm[TProp] extends Array<any> | undefined
+> = 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]>[];
@@ -23,8 +27,8 @@ export type FieldArrayProps<
     }
   : never;
 
-export type ArrayFormBuilderProp<TValue extends Array<any> | undefined> =
-  TValue extends Array<infer TForm> | undefined
+export type ArrayFormBuilderProp<TValue extends Array<any> | undefined | null> =
+  TValue extends Array<infer TForm> | undefined | null
     ? TForm extends object
       ? {
           Field: <
@@ -41,6 +45,11 @@ export type ArrayFormBuilderProp<TValue extends Array<any> | undefined> =
       : 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
@@ -52,7 +61,7 @@ export default function FieldArray<
   children,
   ...rest
 }: FieldArrayProps<TForm, TProp>) {
-  const [input, meta] = useStandardFormInput<TForm[TProp]>({
+  const [input] = useStandardFormInput<TForm[TProp]>({
     name: String(name),
     validate: validate,
     disabled: disabled,

package/src/File/FileGroup.tsx

@@ -2,17 +2,18 @@ import React, { ComponentType, LegacyRef } from 'react';
 import classNames from 'classnames';
 import FileList from './FileList';
 import { InjectedFieldProps } from '../Field/InjectedFieldProps';
-import Group, { GroupProps } from '../Group';
 import { FormDefaults } from '../FormDefaults';
+import Group, { GroupProps } from '../Group';
 
 export interface FileGroupProps
   // note: file props are of type "any" with the current type generation
-  extends InjectedFieldProps<any | undefined>,
+  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;
 }
 
@@ -23,6 +24,8 @@ function FileGroup(
     label,
     helpText,
     className,
+    required,
+    disabled,
     multiple,
     ...rest
   }: FileGroupProps,
@@ -38,7 +41,9 @@ function FileGroup(
         className,
         { [FormDefaults.cssClassPrefix + 'multiple']: multiple },
         FormDefaults.cssClassPrefix + 'file-group'
-      )}>
+      )}
+      required={required}
+      disabled={disabled}>
       <input
         {...input}
         {...rest}
@@ -72,6 +77,7 @@ function FileGroup(
   );
 }
 
+/** File upload input group.  */
 const FileGroupWithRef = React.forwardRef(
   FileGroup
 ) as ComponentType<FileGroupProps>;

package/src/File/FileList.tsx

@@ -1,8 +1,8 @@
 import { FormDefaults } from '../FormDefaults';
 
 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) {
   return (

package/src/Form/FocusError.tsx

@@ -4,8 +4,11 @@ import smoothscroll from 'smoothscroll-polyfill';
 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) {
   const { errors, isSubmitting, isValidating } = useFormikContext();
   smoothscroll.polyfill();

package/src/Form/Form.tsx

@@ -41,18 +41,23 @@ export type FormBuilderProp<TForm extends object> = {
 };
 
 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;
 }
 
@@ -69,6 +74,7 @@ export type FormProps<TForm extends object> = RequireAtLeastOne<
   'onSubmit' | 'onFormDataSubmit'
 >;
 
+/** Define a form. Uses [formik](https://formik.org/docs/overview). Usually contains many `<Field/>` components. */
 export default function Form<TForm extends object>({
   children,
   className,

package/src/Form/FormBasedPreventNavigation.tsx

@@ -1,16 +1,18 @@
-import type { History, Blocker, Transition } from 'history';
-import { ContextType, useContext, useEffect } from 'react';
-// see: https://gist.github.com/rmorse/426ffcc579922a82749934826fa9f743
+import type { History } from 'history';
+import { ContextType, useContext } from 'react';
 import {
   Navigator as BaseNavigator,
   UNSAFE_NavigationContext as NavigationContext,
 } from 'react-router-dom';
 import { useFormikContext } from 'formik';
+import LegacyFormBasedPreventNavigation from './LegacyFormBasedPreventNavigation';
+import NewFormBasedPreventNavigation from './NewFormBasedPreventNavigation';
 
 interface Navigator extends BaseNavigator {
-  block: History['block'];
+  block?: History['block'];
+  location: Location;
 }
-// see: https://github.com/remix-run/react-router/issues/8139#issuecomment-1023105785
+
 type NavigationContextWithBlock = ContextType<typeof NavigationContext> & {
   navigator: Navigator;
 };
@@ -19,6 +21,8 @@ export interface FormBasedPreventNavigationProps {
   ignoreLostChanges?: boolean;
   promptMessage?: string;
 }
+
+/** Prevent the user from navigating away from a form if there are any changes. */
 export default function FormBasedPreventNavigation({
   ignoreLostChanges,
   promptMessage = 'Changes you made may not be saved.',
@@ -30,45 +34,23 @@ export default function FormBasedPreventNavigation({
     NavigationContext
   ) as NavigationContextWithBlock;
 
-  useEffect(() => {
-    if (!preventNavigate) {
-      return;
-    }
-
-    // TODO: https://reactrouter.com/docs/en/v6/upgrading/v5#prompt-is-not-currently-supported
-    // this is a workaround until we get native support for prompt on navigate
-
-    const blocker: Blocker = (tx) => {
-      if (window.confirm(promptMessage)) {
-        tx.retry();
-      }
-    };
-    const unblock = navigator.block((tx: Transition) => {
-      const autoUnblockingTx = {
-        ...tx,
-        retry() {
-          // Automatically unblock the transition so it can play all the way
-          // through before retrying it. TODO: Figure out how to re-enable
-          // this block if the transition is cancelled for some reason.
-          unblock();
-          tx.retry();
-        },
-      };
-
-      blocker(autoUnblockingTx);
-    });
-
-    window.addEventListener('beforeunload', beforeUnload);
-    return () => {
-      unblock();
-      window.removeEventListener('beforeunload', beforeUnload);
-    };
-
-    function beforeUnload(e: BeforeUnloadEvent) {
-      e.preventDefault();
-      e.returnValue = promptMessage;
-    }
-  }, [preventNavigate, promptMessage, navigator]);
-
-  return null;
+  const isUsingDataRouter = navigator.location === undefined;
+
+  if (isUsingDataRouter) {
+    return (
+      <NewFormBasedPreventNavigation
+        promptMessage={promptMessage}
+        preventNavigate={preventNavigate}
+        navigator={navigator}
+      />
+    );
+  } else {
+    return (
+      <LegacyFormBasedPreventNavigation
+        promptMessage={promptMessage}
+        preventNavigate={preventNavigate}
+        navigator={navigator}
+      />
+    );
+  }
 }