envoc-form 3.1.0 → 4.0.1-0

package/src/Field/Field.tsx

@@ -0,0 +1,90 @@
+import React, { ComponentProps, ElementType, LegacyRef } from 'react';
+import { FieldNameContext } from './FieldNameContext';
+import { InjectedFieldProps } from './InjectedFieldProps';
+import useStandardFormInput from './useStandardField';
+import { NormalizationFunction } from '../Normalization/NormalizationFunction';
+import { ValidationFunction } from '../Validation/ValidationFunction';
+
+// we attempted to support generic components but failed
+// so, we assume the actual TRenderComponent has no generic arguments
+// instead, any concrete TRenderComponent can utilize a TRenderComponent<TValue> as needed
+
+type RenderComponent<TValue, TRenderComponent extends ElementType> = Partial<
+  ComponentProps<TRenderComponent>
+> extends Partial<InjectedFieldProps<TValue>>
+  ? TRenderComponent
+  : never;
+
+type RenderComponentProps<
+  TValue,
+  TRenderComponent extends ElementType
+> = Partial<ComponentProps<TRenderComponent>> extends Partial<
+  InjectedFieldProps<TValue>
+>
+  ? ComponentProps<TRenderComponent>
+  : never;
+
+/** A specific Field instance to be rendered by the given TRenderComponent or by whatever default is reasonable */
+export type FieldProps<
+  TForm extends object,
+  TProp extends keyof TForm,
+  TRenderComponent extends ElementType
+> = {
+  name: TProp; // somewhat duplicated from useStandardFormInputProps but better for autocomplete
+  Component: RenderComponent<TForm[TProp], TRenderComponent>;
+
+  id?: string;
+  disabled?: boolean;
+  validate?:
+    | ValidationFunction<TForm[TProp]>
+    | ValidationFunction<TForm[TProp]>[];
+  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])
+ */
+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>
+) {
+  const [input, meta] = useStandardFormInput<TForm[TProp]>({
+    name: String(name),
+    id: id,
+    normalize: normalize,
+    validate: validate,
+    disabled: disabled,
+  });
+
+  // a bit of a hack so JSX is happy with us
+  const Wrapped = Component as React.ComponentType<
+    InjectedFieldProps<TForm[TProp]>
+  >;
+
+  return (
+    <FieldNameContext.Provider value={input.name}>
+      <Wrapped {...rest} ref={ref} id={id} input={input} meta={meta} />
+    </FieldNameContext.Provider>
+  );
+}
+
+// hack to get forwarded refs to work
+const FieldWithRef = React.forwardRef(Field as any);
+
+export default FieldWithRef as typeof Field;

package/src/Field/FieldErrorScrollTarget.tsx

@@ -0,0 +1,11 @@
+import { useContext } from 'react';
+import { FieldNameContext } from './FieldNameContext';
+
+export default function FieldErrorScrollTarget() {
+  const name = useContext(FieldNameContext);
+  if (!name) {
+    return null;
+  }
+  const divId = `${name.toLowerCase()}-error-scroll-target`;
+  return <div id={divId} style={{ display: 'none' }} />;
+}

package/src/Field/FieldNameContext.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+
+/** provides the full, qualified name of the current field name - including nested fields, path/dot delimited */
+export const FieldNameContext = React.createContext<string | undefined>(
+  undefined
+);

package/src/Field/FieldSection.tsx

@@ -0,0 +1,18 @@
+import React, { useContext } from 'react';
+import { FieldNameContext } from './FieldNameContext';
+
+interface FieldSectionProps {
+  children: React.ReactNode;
+  name: string;
+}
+
+export default function FieldSection({ children, name }: FieldSectionProps) {
+  const parentContext = useContext(FieldNameContext);
+  const effectiveValue = parentContext ? `${parentContext}.${name}` : name;
+
+  return (
+    <FieldNameContext.Provider value={effectiveValue}>
+      {children}
+    </FieldNameContext.Provider>
+  );
+}

package/src/Field/InjectedFieldProps.ts

@@ -0,0 +1,8 @@
+import { CustomFieldInputProps } from './CustomFieldInputProps';
+import { CustomFieldMetaProps } from './CustomFieldMetaProps';
+
+/** Defines what is injected by a Field wrapper of some TRenderComponent */
+export interface InjectedFieldProps<TValue> {
+  input: CustomFieldInputProps<TValue>;
+  meta: CustomFieldMetaProps<TValue>;
+}

package/src/Field/useStandardField.ts

@@ -0,0 +1,121 @@
+import { useContext, useEffect } from 'react';
+import { useField, useFormikContext } from 'formik';
+import { CustomFieldInputProps } from './CustomFieldInputProps';
+import { CustomFieldMetaProps } from './CustomFieldMetaProps';
+import { FieldNameContext } from './FieldNameContext';
+import { ServerErrorContext } from '../Form/ServerErrorContext';
+import { NormalizationFunction } from '../Normalization/NormalizationFunction';
+import { ValidationFunction } from '../Validation/ValidationFunction';
+
+export interface useStandardFieldProps<TValue> {
+  id?: string;
+  name: string;
+  disabled?: boolean;
+  validate?: ValidationFunction<TValue> | ValidationFunction<TValue>[];
+  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>
+] {
+  // because the formik errors are evaluated all at the same time we need to keep server errors separate
+  const { getError: getServerError, setError: setServerError } =
+    useContext(ServerErrorContext);
+
+  // ensure that form section values are obeyed, e.g. homeAddress.zipCode
+  const fieldNameContextValue = useContext(FieldNameContext);
+  const name = fieldNameContextValue
+    ? `${fieldNameContextValue}.${providedName}`
+    : providedName;
+
+  // ensure that nested contexts don't have duplicate id issues when an id is specified
+  const id = providedId
+    ? fieldNameContextValue
+      ? `${fieldNameContextValue}.${providedId}`
+      : providedId
+    : name;
+
+  // ensure that our custom validation rules are handled
+  // e.g. we allow arrays of validators
+  const [formikInput, formikMeta] = useField<TValue>({
+    name,
+    id: id ? id : name,
+    disabled: disabled,
+    validate: callAllValidators,
+  });
+  const { setFieldValue, isSubmitting } = useFormikContext();
+
+  const touched =
+    formikMeta.touched !== false && formikMeta.touched !== undefined;
+  useEffect(() => {
+    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();
+    }
+  });
+
+  // these are the props we expect consumers of this hook to pass directly to the input (or other control)
+  const resultInput: CustomFieldInputProps<TValue> = {
+    name: formikInput.name,
+    // pass any direct from server props through normalize without making the form dirty (e.g. phone number)
+    value: normalize ? normalize(formikInput.value) : formikInput.value,
+    onChange: handleChange,
+    onBlur: handleBlur,
+    // extensions to formik
+    id: id,
+  };
+
+  const resultMeta: CustomFieldMetaProps<TValue> = {
+    ...formikMeta,
+    error: getServerError(name) || (touched ? formikMeta.error : undefined),
+    // extensions to formik
+    warning: undefined, // TODO - did this never work?
+    touched: touched,
+  };
+
+  return [resultInput, resultMeta];
+
+  function handleBlur() {
+    formikInput.onBlur({ target: { name: name } });
+  }
+
+  function handleChange(value: TValue) {
+    if (disabled) {
+      return;
+    }
+    const normalized = normalize ? normalize(value) : value;
+    setFieldValue(name, normalized);
+    setServerError(name, undefined);
+  }
+
+  function callAllValidators(value: TValue) {
+    if (disabled || !validate) {
+      return;
+    }
+
+    if (!Array.isArray(validate)) {
+      return validate(value);
+    }
+
+    for (let i = 0; i < validate.length; i++) {
+      const result = validate[i](value);
+      if (result) {
+        return result;
+      }
+    }
+  }
+}

package/src/FieldArray/FieldArray.tsx

@@ -0,0 +1,133 @@
+import { ElementType } from 'react';
+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';
+
+export type FieldArrayProps<
+  TForm extends object,
+  TProp extends keyof TForm
+> = TForm[TProp] extends Array<any> | undefined
+  ? {
+      name: TProp;
+      label?: string;
+      disabled?: boolean;
+      validate?:
+        | ValidationFunction<TForm[TProp]>
+        | ValidationFunction<TForm[TProp]>[];
+      children: (
+        formBuilder: ArrayFormBuilderProp<TForm[TProp]>
+      ) => JSX.Element;
+    }
+  : never;
+
+export type ArrayFormBuilderProp<TValue extends Array<any> | undefined> =
+  TValue extends Array<infer TForm> | undefined
+    ? TForm extends object
+      ? {
+          Field: <
+            TProp extends keyof TForm,
+            TRenderComponent extends ElementType
+          >(
+            props: FieldProps<TForm, TProp, TRenderComponent>
+          ) => JSX.Element; // assumes this is never null - thought he final component may not render
+
+          FieldArray: <TProp extends keyof TForm>(
+            props: FieldArrayProps<TForm, TProp>
+          ) => JSX.Element;
+        }
+      : never
+    : never;
+
+export default function FieldArray<
+  TForm extends object,
+  TProp extends keyof TForm
+>({
+  name,
+  label,
+  validate,
+  disabled,
+  children,
+  ...rest
+}: FieldArrayProps<TForm, TProp>) {
+  const [input, meta] = useStandardFormInput<TForm[TProp]>({
+    name: String(name),
+    validate: validate,
+    disabled: disabled,
+  });
+
+  const values: any[] = !input.value
+    ? []
+    : Array.isArray(input.value)
+    ? input.value
+    : [];
+
+  return (
+    <div className="field-array">
+      <div className="field-array-header">
+        <div className="field-array-title">{label}</div>
+        <button
+          className={classNames('add-array-item-button', { disabled })}
+          title="Add Item"
+          type="button"
+          onClick={addItem}>
+          +
+        </button>
+      </div>
+      <div className="field-array-body">
+        {values.map((value, index) => {
+          const itemName = `${input.name}[${index}]`;
+          return (
+            <div
+              key={
+                (value && value['form-input-array-key']) ||
+                (value && value['id']) ||
+                itemName
+              }
+              className={classNames('field-array-item', {
+                removed: value.isDeleted,
+              })}
+              role="listitem">
+              <FieldNameContext.Provider value={itemName}>
+                {children({
+                  Field: Field,
+                  FieldArray: FieldArray,
+                } as any)}
+              </FieldNameContext.Provider>
+              <button
+                className={classNames('remove-array-item-button', { disabled })}
+                type="button"
+                title="Remove Item"
+                onClick={() => removeItem(value)}>
+                -
+              </button>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+
+  function addItem() {
+    if (disabled) {
+      return;
+    }
+    input.onChange([...values, {}] as any);
+  }
+
+  function removeItem(item: any) {
+    if (disabled) {
+      return;
+    }
+    // assumes anything from the server has an 'id' value sent
+    if (!item.id) {
+      input.onChange(values.filter((x) => x !== item) as any);
+      return;
+    }
+    const mapped = values.map((x) =>
+      x !== item ? x : Object.assign({}, x, { isDeleted: true })
+    );
+    input.onChange(mapped as any);
+  }
+}

package/src/File/FileGroup.test.tsx

@@ -0,0 +1,35 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+import { FileGroup } from '../';
+import FormTestBase from '../__Tests__/FormTestBase';
+
+describe('FileGroup', () => {
+  it('renders without crashing', () => {
+    render(
+      <FormTestBase>
+        {({ Field }) => (
+          <Field
+            name="profileImage"
+            Component={FileGroup}
+            label="Profile Image"
+          />
+        )}
+      </FormTestBase>
+    );
+  });
+
+  it('has matching snapshot', () => {
+    const renderResult = render(
+      <FormTestBase>
+        {({ Field }) => (
+          <Field
+            name="profileImage"
+            Component={FileGroup}
+            label="Profile Image"
+          />
+        )}
+      </FormTestBase>
+    );
+    expect(renderResult.asFragment()).toMatchSnapshot();
+  });
+});

package/src/File/FileGroup.tsx

@@ -0,0 +1,71 @@
+import React, { ComponentType, LegacyRef } from 'react';
+import classNames from 'classnames';
+import FileList from './FileList';
+import { InjectedFieldProps } from '../Field/InjectedFieldProps';
+import Group, { GroupProps } from '../Group';
+
+export interface FileGroupProps
+  // note: file props are of type "any" with the current type generation
+  extends InjectedFieldProps<any | undefined>,
+    Omit<GroupProps, keyof InjectedFieldProps<any> | 'children'>,
+    Omit<
+      React.HTMLProps<HTMLInputElement>,
+      keyof InjectedFieldProps<any> | 'children' | 'className' | 'label'
+    > {
+  multiple?: boolean | undefined;
+}
+
+function FileGroup(
+  {
+    input,
+    meta,
+    label,
+    helpText,
+    className,
+    multiple,
+    ...rest
+  }: FileGroupProps,
+  ref: LegacyRef<HTMLInputElement>
+) {
+  return (
+    <Group
+      input={input}
+      meta={meta}
+      label={label}
+      helpText={helpText}
+      className={classNames(className, { multiple }, 'file-group')}>
+      <input
+        {...input}
+        {...rest}
+        multiple={multiple}
+        onChange={(e) => {
+          if (!e?.target?.files?.length) {
+            input.onChange(undefined);
+          } else {
+            const files: File[] = [];
+            for (let i = 0; i < e.target.files.length; i++) {
+              files.push(e.target.files[i]);
+            }
+            if (!multiple) {
+              input.onChange(files[0]);
+            } else {
+              input.onChange(files);
+            }
+          }
+        }}
+        value={undefined}
+        ref={ref}
+        type="file"
+        className={classNames(className, 'file-group')}
+      />
+      {/* Note: because input.value is any - due to how files are currently handled - type safeness isn't great here */}
+      <FileList files={input.value} />
+    </Group>
+  );
+}
+
+const FileGroupWithRef = React.forwardRef(
+  FileGroup
+) as ComponentType<FileGroupProps>;
+
+export default FileGroupWithRef;

package/src/File/FileList.tsx

@@ -0,0 +1,19 @@
+export interface FileListProps {
+  files?: File | File[] | undefined;
+  rejectedFiles?: File | File[] | undefined;
+}
+export default function FileList({ files, rejectedFiles }: FileListProps) {
+  return (
+    <div className="file-list">
+      {!files ? null : Array.isArray(files) ? (
+        files.map((x, i) => <File file={x} key={i} />)
+      ) : (
+        <File file={files} />
+      )}
+    </div>
+  );
+}
+
+function File({ file }: { file: File }) {
+  return null;
+}

package/src/File/__snapshots__/FileGroup.test.tsx.snap

@@ -0,0 +1,32 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`FileGroup has matching snapshot 1`] = `
+<DocumentFragment>
+  <form
+    action="#"
+  >
+    <div
+      class="file-group group"
+    >
+      <div
+        id="profileimage-error-scroll-target"
+        style="display: none;"
+      />
+      <label
+        for="profileImage"
+      >
+        Profile Image
+      </label>
+      <input
+        class="file-group"
+        name="profileImage"
+        type="file"
+        value=""
+      />
+      <div
+        class="file-list"
+      />
+    </div>
+  </form>
+</DocumentFragment>
+`;

package/src/File/humanFileSize.ts

@@ -0,0 +1,8 @@
+export function humanFileSize(size: number) {
+  const i = Math.floor(Math.log(size) / Math.log(1024));
+  return (
+    (size / Math.pow(1024, i)).toFixed(2) +
+    ' ' +
+    ['B', 'KB', 'MB', 'GB', 'TB'][i]
+  );
+}

package/src/Form/{FocusError.js → FocusError.tsx}

@@ -1,8 +1,12 @@
 import { useEffect } from 'react';
 import { useFormikContext } from 'formik';
 import smoothscroll from 'smoothscroll-polyfill';
+import { ServerErrorContextProps } from './ServerErrorContext';
 
-export default function FocusError(props) {
+export interface FocusErrorProps {
+  serverErrors: ServerErrorContextProps;
+}
+export default function FocusError(props: FocusErrorProps) {
   const { errors, isSubmitting, isValidating } = useFormikContext();
   smoothscroll.polyfill();
   useEffect(() => {
@@ -28,14 +32,14 @@ export default function FocusError(props) {
   return null;
 }
 
-const scrollToErrorElement = (keys) => {
-  let firstErrorElement = document.getElementById(
+const scrollToErrorElement = (keys: string[]) => {
+  let firstErrorElement: HTMLElement | null = document.getElementById(
     `${keys[0].toLowerCase()}-error-scroll-target`
   );
-  if (firstErrorElement == null || firstErrorElement.parentNode == null) {
+  if (!firstErrorElement || !firstErrorElement.parentNode) {
     return;
   }
-  firstErrorElement = firstErrorElement.parentNode;
+  firstErrorElement = firstErrorElement.parentNode as HTMLElement;
   const headerOffset = -110;
   const y =
     firstErrorElement.getBoundingClientRect().top +
@@ -43,6 +47,6 @@ const scrollToErrorElement = (keys) => {
     headerOffset;
   window.scrollTo({ top: y, behavior: 'smooth' });
   setTimeout(() => {
-    firstErrorElement.focus();
+    firstErrorElement?.focus();
   }, 500);
 };

package/src/Form/Form.test.tsx

@@ -0,0 +1,14 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+import FormTestBase from '../__Tests__/FormTestBase';
+
+describe('FormTestBase', () => {
+  it('renders without crashing', () => {
+    render(<FormTestBase>{() => <></>}</FormTestBase>);
+  });
+
+  it('has matching snapshot', () => {
+    const renderResult = render(<FormTestBase>{() => <></>}</FormTestBase>);
+    expect(renderResult.asFragment()).toMatchSnapshot();
+  });
+});