envoc-form 4.0.1-9 → 5.0.1

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}
+      />
+    );
+  }
 }

package/src/Form/LegacyFormBasedPreventNavigation.tsx

@@ -0,0 +1,77 @@
+import type { History, Blocker, Transition } from 'history';
+import { useEffect } from 'react';
+// see: https://gist.github.com/rmorse/426ffcc579922a82749934826fa9f743
+import { Navigator as BaseNavigator } from 'react-router-dom';
+
+interface Navigator extends BaseNavigator {
+  block?: History['block'];
+}
+
+export interface FormBasedPreventNavigationProps {
+  promptMessage?: string;
+  preventNavigate: boolean;
+  navigator: Navigator;
+}
+/** Only use this if the project uses `<BrowserRouter/>` or any router that does not support the new
+ * [react-router Data API](https://reactrouter.com/en/main/routers/picking-a-router#using-v64-data-apis)
+ *
+ * Legacy function to prevent the user from navigating away from a form if there are any changes.
+ */
+export default function LegacyFormBasedPreventNavigation({
+  promptMessage = 'Changes you made may not be saved.',
+  preventNavigate,
+  navigator,
+}: FormBasedPreventNavigationProps) {
+  useEffect(() => {
+    if (!preventNavigate) {
+      return;
+    }
+    let unblock = () => {};
+    const push = navigator.push;
+
+    // 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
+    if (navigator.block) {
+      const blocker: Blocker = (tx) => {
+        if (window.confirm(promptMessage)) {
+          tx.retry();
+        }
+      };
+      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);
+      });
+    } else {
+      //https://gist.github.com/MarksCode/64e438c82b0b2a1161e01c88ca0d0355
+      navigator.push = (...args: Parameters<typeof push>) => {
+        if (window.confirm(promptMessage)) {
+          push(...args);
+        }
+      };
+    }
+
+    window.addEventListener('beforeunload', beforeUnload);
+    return () => {
+      unblock();
+      navigator.push = push;
+      window.removeEventListener('beforeunload', beforeUnload);
+    };
+
+    function beforeUnload(e: BeforeUnloadEvent) {
+      e.preventDefault();
+      e.returnValue = promptMessage;
+    }
+  }, [preventNavigate, promptMessage, navigator]);
+
+  return null;
+}

package/src/Form/NewFormBasedPreventNavigation.tsx

@@ -0,0 +1,59 @@
+import type { History, Blocker, Transition } from 'history';
+import { useEffect } from 'react';
+import {
+  Navigator as BaseNavigator,
+  unstable_usePrompt as usePrompt,
+} from 'react-router-dom';
+
+interface Navigator extends BaseNavigator {
+  block?: History['block'];
+  location: Location;
+}
+
+interface FormBasedPreventNavigationProps {
+  promptMessage?: string;
+  preventNavigate: boolean;
+  navigator: Navigator;
+}
+
+/** Temporary function to allow backwards compatibility with routers that do not use the new Data API */
+export default function NewFormBasedPreventNavigation({
+  promptMessage = 'Changes you made may not be saved.',
+  preventNavigate,
+  navigator,
+}: FormBasedPreventNavigationProps) {
+  usePrompt({
+    when: preventNavigate,
+    message: promptMessage,
+  });
+
+  // TODO: Once react-router fully supports usePrompt and when we do not want to support routers
+  // that do not support the react-router Data API we can remove this.
+  useEffect(() => {
+    if (!preventNavigate) {
+      return;
+    }
+    let unblock = () => {};
+    const push = navigator.push;
+
+    navigator.push = (...args: Parameters<typeof push>) => {
+      if (window.confirm(promptMessage)) {
+        push(...args);
+      }
+    };
+
+    window.addEventListener('beforeunload', beforeUnload);
+    return () => {
+      unblock();
+      navigator.push = push;
+      window.removeEventListener('beforeunload', beforeUnload);
+    };
+
+    function beforeUnload(e: BeforeUnloadEvent) {
+      e.preventDefault();
+      e.returnValue = promptMessage;
+    }
+  }, [preventNavigate, promptMessage, navigator]);
+
+  return null;
+}

package/src/Form/ServerErrorContext.ts

@@ -8,6 +8,7 @@ export interface ServerErrorContextProps {
   getError: (path: string) => string | undefined;
   setError: (path: string, errorMessage: string | undefined) => void;
 }
+/** Context to store the API errors from the server for the form. */
 export const ServerErrorContext = React.createContext<ServerErrorContextProps>({
   errors: {},
   getError: (path: string) => {

package/src/FormActions.tsx

@@ -3,10 +3,17 @@ import { useFormikContext } from 'formik';
 import SubmitFormButton from './SubmitFormButton';
 
 export interface FormActionsProps {
+  /** Allow the form to be submitted without any changes. By default this is not allowed. */
   allowPristineSubmit?: boolean;
+  /** The cancel button's `onClick`.
+   * @defaultValue `window.history.back()`
+   */
   handleCancel?: () => void;
+  /** Whether both buttons should be disabled. */
   disabled?: boolean;
 }
+
+/** Standard cancel and submit buttons. */
 export default function FormActions({
   allowPristineSubmit,
   handleCancel,

package/src/FormDefaults.ts

@@ -1 +1,2 @@
+/** `envoc-form-` CSS class prefix */
 export const FormDefaults = { cssClassPrefix: 'envoc-form-' };

package/src/Group.tsx

@@ -4,20 +4,24 @@ import FieldErrorScrollTarget from './Field/FieldErrorScrollTarget';
 import { InjectedFieldProps } from './Field/InjectedFieldProps';
 
 export interface GroupProps extends InjectedFieldProps<any> {
+  /** Extra class names to apply. */
   className?: string;
 
   children: React.ReactNode;
 
-  /** simple text label before the input */
+  /** Simple text label before the input. */
   label?: string;
 
-  /** simple helper text after the input*/
+  /** Simple helper text after the input. */
   helpText?: string | React.ReactNode;
 
+  /** Whether the field should be disabled. */
   disabled?: boolean;
+
+  required?: boolean;
 }
 
-/** contains standard field bits like a label, helper text, error scroll target, validation message container, etc */
+/** Contains standard field bits like a label, helper text, error scroll target, validation message container, etc. */
 export default function Group({
   className,
   children,
@@ -26,12 +30,14 @@ export default function Group({
   meta,
   input,
   disabled,
+  required,
 }: GroupProps) {
   return (
     <div
       className={classNames(className, FormDefaults.cssClassPrefix + 'group', {
         [FormDefaults.cssClassPrefix + 'invalid']: meta.error,
         [FormDefaults.cssClassPrefix + 'disabled']: disabled,
+        [FormDefaults.cssClassPrefix + 'required']: required,
       })}>
       <FieldErrorScrollTarget />
       {meta.warning && (
@@ -42,7 +48,9 @@ export default function Group({
       <label htmlFor={input.id}>{label}</label>
       {children}
       {meta.error && (
-        <div className={FormDefaults.cssClassPrefix + 'error'}>
+        <div
+          id={`${input.id}-error`}
+          className={FormDefaults.cssClassPrefix + 'error'}>
           {meta.error}
         </div>
       )}

package/src/Input/IconInputGroup.tsx

@@ -7,11 +7,13 @@ import { FormDefaults } from '../FormDefaults';
 // or should we just give a div a className and let each project decide? (this seems to be the patern)
 export interface IconInputGroupProps
   extends Omit<
-    InputGroupProps<string | undefined>,
+    InputGroupProps<string | undefined | null>,
     'onChange' | 'type' | 'value'
   > {
   type?: 'color' | 'email' | 'search' | 'tel' | 'text' | 'url';
+  /** Icon to display on the input group. */
   icon: React.ReactNode;
+  /** Text to display after the input group to give more information to the user. */
   helpText?: string;
 }
 
@@ -30,7 +32,7 @@ function IconInputGroup(
           className,
           FormDefaults.cssClassPrefix + 'icon-input-group'
         )}
-        value={input.value || ''}
+        value={input.value ?? ''}
         onChange={(e) => {
           if (!e.target.value) {
             input.onChange(undefined);
@@ -44,6 +46,7 @@ function IconInputGroup(
   );
 }
 
+/** Input group with an icon. */
 const IconInputGroupWithRef = React.forwardRef(
   IconInputGroup
 ) as React.ComponentType<IconInputGroupProps>;

package/src/Input/InputGroup.tsx

@@ -1,22 +1,25 @@
 import React, { ChangeEventHandler, LegacyRef } from 'react';
 import classNames from 'classnames';
 import { InjectedFieldProps } from '../Field/InjectedFieldProps';
-import Group, { GroupProps } from '../Group';
 import { FormDefaults } from '../FormDefaults';
+import Group, { GroupProps } from '../Group';
 
 export interface InputGroupProps<TValue>
   extends InjectedFieldProps<TValue>,
     Omit<
       React.HTMLProps<HTMLInputElement>,
-      keyof InjectedFieldProps<any> | 'children' | 'className' | 'label'
+      | keyof InjectedFieldProps<any>
+      | 'children'
+      | 'className'
+      | 'label'
+      | 'value'
     >,
     Omit<GroupProps, keyof InjectedFieldProps<any> | 'children'> {
   onChange: ChangeEventHandler<HTMLInputElement>;
-  value: string | number;
+  value: string | number | null | undefined;
   icon?: React.ReactNode;
 }
 
-/** generic controlled <input/> wrapped by a Group */
 function InputGroup<TValue>(
   {
     input,
@@ -24,6 +27,7 @@ function InputGroup<TValue>(
     label,
     helpText,
     className,
+    required,
     disabled,
     onChange,
     value,
@@ -36,6 +40,7 @@ function InputGroup<TValue>(
     <Group
       input={input}
       meta={meta}
+      required={required}
       disabled={disabled}
       label={label}
       helpText={helpText}
@@ -47,7 +52,9 @@ function InputGroup<TValue>(
       <input
         {...input}
         {...rest}
-        value={value}
+        aria-invalid={!!meta.error}
+        aria-errormessage={!!meta.error ? `${input.name}-error` : undefined}
+        value={value ?? ''}
         onChange={onChange}
         ref={ref}
         className={classNames(
@@ -59,6 +66,7 @@ function InputGroup<TValue>(
   );
 }
 
+/** Generic controlled `<input/>` wrapped by a `<Group/>` */
 const InputGroupWithRef = React.forwardRef(InputGroup) as typeof InputGroup;
 
 export default InputGroupWithRef;

package/src/Input/MoneyInputGroup.tsx

@@ -5,9 +5,10 @@ import { FormDefaults } from '../FormDefaults';
 
 export interface MoneyInputGroupProps
   extends Omit<
-    InputGroupProps<number | undefined>,
+    InputGroupProps<number | undefined | null>,
     'onChange' | 'type' | 'value'
   > {
+  /** Custom parsing function when the value changes. */
   parseFunc?: typeof parseInt | typeof parseFloat;
 }
 
@@ -41,6 +42,7 @@ function MoneyInputGroup(
   );
 }
 
+/** Input group for inputting money. */
 const MoneyInputGroupWithRef = React.forwardRef(
   MoneyInputGroup
 ) as React.FunctionComponent<MoneyInputGroupProps>;

package/src/Input/NumberInputGroup.tsx

@@ -5,9 +5,10 @@ import { FormDefaults } from '../FormDefaults';
 
 export interface NumberInputGroupProps
   extends Omit<
-    InputGroupProps<number | undefined>,
+    InputGroupProps<number | undefined | null>,
     'onChange' | 'type' | 'value'
   > {
+  /** Custom parsing function when the value changes. */
   parseFunc?: typeof parseInt | typeof parseFloat;
 }
 
@@ -39,6 +40,7 @@ function NumberInputGroup(
   );
 }
 
+/** Standard number input group. By default allows for float values. */
 const NumberInputGroupWithRef = React.forwardRef(
   NumberInputGroup
 ) as React.ComponentType<NumberInputGroupProps>;

package/src/Input/StringInputGroup.tsx

@@ -5,7 +5,7 @@ import { FormDefaults } from '../FormDefaults';
 
 export interface StringInputGroupProps
   extends Omit<
-    InputGroupProps<string | undefined>,
+    InputGroupProps<string | undefined | null>,
     'onChange' | 'type' | 'value'
   > {
   type?:
@@ -33,7 +33,7 @@ function StringInputGroup(
         className,
         FormDefaults.cssClassPrefix + 'string-group'
       )}
-      value={input.value || ''}
+      value={input.value ?? ''}
       onChange={(e) => {
         if (!e.target.value) {
           input.onChange(undefined);
@@ -45,6 +45,7 @@ function StringInputGroup(
   );
 }
 
+/** Standard string input group. */
 const StringInputGroupWithRef = React.forwardRef(
   StringInputGroup
 ) as React.ComponentType<StringInputGroupProps>;

package/src/Input/__Tests__/__snapshots__/IconInputGroup.test.tsx.snap

@@ -20,6 +20,7 @@ exports[`IconInputGroup has matching snapshot 1`] = `
         Pretend this is an icon
       </span>
       <input
+        aria-invalid="false"
         class="envoc-form-icon-input-group envoc-form-input-group"
         id="nameWithIcon"
         name="nameWithIcon"

package/src/Input/__Tests__/__snapshots__/MoneyInputGroup.test.tsx.snap

@@ -19,6 +19,7 @@ exports[`MoneyInputGroup has matching snapshot 1`] = `
         Salary
       </label>
       <input
+        aria-invalid="false"
         class="something-here envoc-form-money-group envoc-form-input-group"
         id="yearlySalaryUSD"
         min="0"

package/src/Input/__Tests__/__snapshots__/NumberInputGroup.test.tsx.snap

@@ -19,6 +19,7 @@ exports[`NumberInputGroup has matching snapshot 1`] = `
         Arm Count
       </label>
       <input
+        aria-invalid="false"
         class="envoc-form-number-group envoc-form-input-group"
         id="numberOfArms"
         name="numberOfArms"

package/src/Input/__Tests__/__snapshots__/StringInputGroup.test.tsx.snap

@@ -19,6 +19,7 @@ exports[`StringInputGroup has matching snapshot 1`] = `
         Name
       </label>
       <input
+        aria-invalid="false"
         class="envoc-form-string-group envoc-form-input-group"
         id="name"
         name="name"

package/src/Normalization/normalizers.ts

@@ -1,4 +1,5 @@
-export const phoneNumber = (value: string | undefined) => {
+/** Normalizer for converting a string into a valid phone number. */
+export const phoneNumber = (value: string | undefined | null) => {
   if (!value) {
     return undefined;
   }
@@ -30,7 +31,8 @@ export const phoneNumber = (value: string | undefined) => {
   return onlyNums;
 };
 
-export const zipCode = (value: string | undefined) => {
+/** Normalizer for converting a string into a valid zip code. Allows for XXXXX and XXXXX-XXXX format. */
+export const zipCode = (value: string | undefined | null) => {
   if (!value) {
     return undefined;
   }

package/src/Select/BooleanSelectGroup.tsx

@@ -13,9 +13,10 @@ const booleanOptions: SelectOption<boolean>[] = [
 ];
 
 export interface BooleanSelectGroupProps
-  extends Omit<SelectGroupPropsHelper<boolean>, 'options'> {
+  extends Omit<SelectGroupPropsHelper<boolean | undefined | null>, 'options'> {
   options?: SelectOption<boolean>[];
 }
+/** A `<SelectGroup/>` dropdown with two options. Default options are 'Yes' and 'No' with values of `true` and `false`. */
 export function BooleanSelectGroup(props: BooleanSelectGroupProps) {
   return (
     <SelectGroup

package/src/Select/NumberSelectGroup.tsx

@@ -2,13 +2,15 @@ import SelectGroup from './SelectGroup';
 import { SelectGroupPropsHelper } from './SelectGroupPropsHelper';
 
 export interface MultiNumberSelectGroupProps
-  extends SelectGroupPropsHelper<number[]> {}
+  extends SelectGroupPropsHelper<number[] | undefined | null> {}
+/** A `<SelectGroup/>` dropdown with values as numbers. Many options can be selected at a time. */
 export function MultiNumberSelectGroup(props: MultiNumberSelectGroupProps) {
   return <SelectGroup multiple={true} {...props} />;
 }
 
 export interface SingleNumberSelectGroupProps
-  extends SelectGroupPropsHelper<number> {}
+  extends SelectGroupPropsHelper<number | undefined | null> {}
+/** A `<SelectGroup/>` dropdown with values as numbers. Only one option can be selected at a time. */
 export function SingleNumberSelectGroup(props: SingleNumberSelectGroupProps) {
   return <SelectGroup multiple={false} {...props} />;
 }

package/src/Select/SelectGroup.tsx

@@ -1,11 +1,13 @@
 import { default as ReactSelect } from 'react-select';
 import classNames from 'classnames';
 import { InjectedFieldProps } from '../Field/InjectedFieldProps';
-import Group, { GroupProps } from '../Group';
 import { FormDefaults } from '../FormDefaults';
+import Group, { GroupProps } from '../Group';
 
 export interface SelectOption<TValue> {
+  /** Value for the select. This will be sent to the API. */
   value: (TValue extends Array<infer P> ? P : TValue) | undefined;
+  /** Label for the select. This is displayed to the user. */
   label: string;
 }
 
@@ -23,21 +25,27 @@ interface OptionsUseServiceResult<TValue> {
 }
 
 export interface SelectGroupProps<TValue>
-  extends InjectedFieldProps<TValue | undefined>,
+  extends InjectedFieldProps<TValue | undefined | null>,
     Omit<GroupProps, 'input' | 'meta' | 'children'> {
   // allows for "useService" or other handles to control the data - including cache
   // TODO: do we still want a version of select that has a "url" or maybe a promise func or something?
   // eventually we can just add the shape of, say, useQuery (TanStack) to the union type
+  /** Options for the dropdown. Includes the label and value. */
   options: SelectOption<TValue>[] | OptionsUseServiceResult<TValue>;
+  /** Whether the user should be able to have multiple values selected. */
   multiple: TValue extends Array<any> ? true : false;
+  /** Text diplayed when no value is selected. */
   placeholder?: string;
 }
 
 // TODO: we could also name this "ReactSelectGroup" or similar but the types are strongly defined now so kept the names consistent
+/** Generic select dropdown. Uses [react-select](https://react-select.com/home). */
 export default function SelectGroup<TValue>({
   input,
   meta,
   className,
+  required,
+  disabled,
   options,
   multiple,
   placeholder,
@@ -64,6 +72,8 @@ export default function SelectGroup<TValue>({
       {...rest}
       input={input}
       meta={meta}
+      required={required}
+      disabled={disabled}
       className={classNames(
         className,
         {
@@ -78,6 +88,7 @@ export default function SelectGroup<TValue>({
       >
         inputId={input.id}
         isMulti={multiple}
+        isDisabled={disabled}
         options={effectiveOptions}
         onBlur={input.onBlur}
         value={getValue()}

package/src/Select/StringSelectGroup.tsx

@@ -3,12 +3,14 @@ import { SelectGroupPropsHelper } from './SelectGroupPropsHelper';
 
 export interface MultiStringSelectGroupProps
   extends SelectGroupPropsHelper<string[]> {}
+/** A `<SelectGroup/>` dropdown with values as strings. Multiple options can be selected at a time. */
 export function MultiStringSelectGroup(props: MultiStringSelectGroupProps) {
   return <SelectGroup multiple={true} {...props} />;
 }
 
 export interface SingleStringSelectGroupProps
   extends SelectGroupPropsHelper<string> {}
+/** A `<SelectGroup/>` dropdown with the value as a string. Only one option can be selected at a time. */
 export function SingleStringSelectGroup(props: SingleStringSelectGroupProps) {
   return <SelectGroup multiple={false} {...props} />;
 }