codeforlife 2.6.6 → 2.6.8

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [2.6.8](https://github.com/ocadotechnology/codeforlife-package-javascript/compare/v2.6.7...v2.6.8) (2025-02-24)
+
+
+### Bug Fixes
+
+* form submission behavior ([#79](https://github.com/ocadotechnology/codeforlife-package-javascript/issues/79)) ([9b1ac2d](https://github.com/ocadotechnology/codeforlife-package-javascript/commit/9b1ac2df0049cf473266798b6d210106045a86ee))
+
+## [2.6.7](https://github.com/ocadotechnology/codeforlife-package-javascript/compare/v2.6.6...v2.6.7) (2025-02-19)
+
+
+### Bug Fixes
+
+* Package javascript 76 ([#77](https://github.com/ocadotechnology/codeforlife-package-javascript/issues/77)) ([73c7113](https://github.com/ocadotechnology/codeforlife-package-javascript/commit/73c7113d50f7e1bff64655cf30da30013f051950))
+
 ## [2.6.6](https://github.com/ocadotechnology/codeforlife-package-javascript/compare/v2.6.5...v2.6.6) (2025-01-27)
 
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "codeforlife",
   "description": "Common frontend code",
   "private": false,
-  "version": "2.6.6",
+  "version": "2.6.8",
   "type": "module",
   "scripts": {
     "dev": "vite",

package/src/components/form/Form.tsx

@@ -1,27 +1,106 @@
+import { FormHelperText, type FormHelperTextProps } from "@mui/material"
 import {
   Formik,
   Form as FormikForm,
   type FormikConfig,
   type FormikErrors,
+  type FormikProps,
 } from "formik"
+import {
+  type ReactNode,
+  type FC,
+  useRef,
+  useEffect,
+  type RefObject,
+} from "react"
 import type { TypedUseMutation } from "@reduxjs/toolkit/query/react"
 
+import { getKeyPaths } from "../../utils/general"
 import {
   submitForm,
   type SubmitFormOptions,
   type FormValues,
 } from "../../utils/form"
 
-const _ = <Values extends FormValues>({
+const SCROLL_INTO_VIEW_OPTIONS: ScrollIntoViewOptions = {
+  behavior: "smooth",
+  block: "start",
+}
+
+type NonFieldErrorsProps = Omit<FormHelperTextProps, "error" | "ref"> & {
+  scrollIntoViewOptions?: ScrollIntoViewOptions
+}
+
+const NonFieldErrors: FC<NonFieldErrorsProps> = ({
+  scrollIntoViewOptions = SCROLL_INTO_VIEW_OPTIONS,
+  ...formHelperTextProps
+}) => {
+  const pRef = useRef<HTMLParagraphElement>(null)
+
+  useEffect(() => {
+    if (pRef.current) pRef.current.scrollIntoView(scrollIntoViewOptions)
+  }, [scrollIntoViewOptions])
+
+  return <FormHelperText ref={pRef} error {...formHelperTextProps} />
+}
+
+export type FormErrors<Values> = FormikErrors<
+  Omit<Values, "non_field_errors"> & { non_field_errors: string }
+>
+
+type _FormikProps<Values> = Omit<FormikProps<Values>, "errors"> & {
+  errors: FormErrors<Values>
+}
+
+type BaseFormProps<Values> = Omit<FormikConfig<Values>, "children"> & {
+  children: ReactNode | ((props: _FormikProps<Values>) => ReactNode)
+  scrollIntoViewOptions?: ScrollIntoViewOptions
+  nonFieldErrorsProps?: Omit<NonFieldErrorsProps, "children">
+  order?: Array<{ name: string; inputRef: RefObject<HTMLInputElement> }>
+}
+
+const BaseForm = <Values extends FormValues>({
   children,
+  scrollIntoViewOptions = SCROLL_INTO_VIEW_OPTIONS,
+  nonFieldErrorsProps,
+  order,
   ...otherFormikProps
-}: FormikConfig<Values>) => (
+}: BaseFormProps<Values>) => (
   <Formik {...otherFormikProps}>
-    {formik => (
-      <FormikForm>
-        {typeof children === "function" ? children(formik) : children}
-      </FormikForm>
-    )}
+    {/* @ts-expect-error */}
+    {(formik: _FormikProps<Values>) => {
+      let nonFieldErrors: undefined | JSX.Element = undefined
+      if (Object.keys(formik.errors).length) {
+        if (typeof formik.errors.non_field_errors === "string") {
+          nonFieldErrors = (
+            <NonFieldErrors {...nonFieldErrorsProps}>
+              {formik.errors.non_field_errors}
+            </NonFieldErrors>
+          )
+        }
+        // If a submission was attempted and refs to the fields were provided.
+        else if (formik.isSubmitting && order && order.length) {
+          const errorNames = getKeyPaths(formik.errors)
+
+          const inputRef = order.find(({ name }) =>
+            errorNames.includes(name),
+          )?.inputRef
+
+          if (inputRef?.current) {
+            inputRef.current.scrollIntoView(scrollIntoViewOptions)
+          }
+        }
+      }
+
+      return (
+        <>
+          {nonFieldErrors}
+          <FormikForm>
+            {typeof children === "function" ? children(formik) : children}
+          </FormikForm>
+        </>
+      )
+    }}
   </Formik>
 )
 
@@ -29,7 +108,7 @@ type SubmitFormProps<
   Values extends FormValues,
   QueryArg extends FormValues,
   ResultType,
-> = Omit<FormikConfig<Values>, "onSubmit"> & {
+> = Omit<BaseFormProps<Values>, "onSubmit"> & {
   useMutation: TypedUseMutation<ResultType, QueryArg, any>
 } & (Values extends QueryArg
     ? { submitOptions?: SubmitFormOptions<Values, QueryArg, ResultType> }
@@ -42,15 +121,16 @@ const SubmitForm = <
 >({
   useMutation,
   submitOptions,
-  ...formikProps
+  ...baseFormProps
 }: SubmitFormProps<Values, QueryArg, ResultType>): JSX.Element => {
   const [trigger] = useMutation()
 
   return (
-    <_
-      {...formikProps}
+    <BaseForm
+      {...baseFormProps}
       onSubmit={submitForm<Values, QueryArg, ResultType>(
         trigger,
+        baseFormProps.initialValues,
         submitOptions as SubmitFormOptions<Values, QueryArg, ResultType>,
       )}
     />
@@ -61,10 +141,10 @@ export type FormProps<
   Values extends FormValues,
   QueryArg extends FormValues,
   ResultType,
-> = FormikConfig<Values> | SubmitFormProps<Values, QueryArg, ResultType>
+> = BaseFormProps<Values> | SubmitFormProps<Values, QueryArg, ResultType>
 
 const Form: {
-  <Values extends FormValues>(props: FormikConfig<Values>): JSX.Element
+  <Values extends FormValues>(props: BaseFormProps<Values>): JSX.Element
   <Values extends FormValues, QueryArg extends FormValues, ResultType>(
     props: SubmitFormProps<Values, QueryArg, ResultType>,
   ): JSX.Element
@@ -75,8 +155,7 @@ const Form: {
 >(
   props: FormProps<Values, QueryArg, ResultType>,
 ): JSX.Element => {
-  return "onSubmit" in props ? <_ {...props} /> : SubmitForm(props)
+  return "onSubmit" in props ? <BaseForm {...props} /> : SubmitForm(props)
 }
 
 export default Form
-export { type FormikErrors as FormErrors }

package/src/components/form/SubmitButton.tsx

@@ -32,7 +32,13 @@ const SubmitButton: FC<SubmitButtonProps> = ({
           type="button"
           onClick={() => {
             form.setTouched(getTouched(form.values), true).then(errors => {
-              if (!errors || !Object.keys(errors).length) form.submitForm()
+              const hasErrors = Boolean(errors && Object.keys(errors).length)
+              // If has errors, set isSubmitting=true so fields in the form are
+              // aware that a submission was attempted. Else, set
+              // isSubmitting=false as it will be set to true when calling
+              // submitForm().
+              form.setSubmitting(hasErrors)
+              if (!hasErrors) form.submitForm()
             })
           }}
           {...otherButtonProps}

package/src/hooks/form.tsx

@@ -0,0 +1,11 @@
+import { useRef } from "react"
+
+/**
+ * Shorthand for a reference to a HTML input element since this is so common for
+ * forms.
+ *
+ * @returns Ref object to a HTML input element.
+ */
+export function useInputRef() {
+  return useRef<HTMLInputElement>(null)
+}

package/src/hooks/index.ts

@@ -1,4 +1,5 @@
 export * from "./api"
 export * from "./auth"
+export * from "./form"
 export * from "./general"
 export * from "./router"

package/src/utils/form.test.ts

@@ -0,0 +1,50 @@
+import { isDirty, getDirty, getCleanNames } from "./form"
+
+const VALUES = {
+  name: { first: "Peter", last: "Parker" },
+}
+const INITIAL_VALUES: typeof VALUES = {
+  name: { first: "Peter", last: "Robbins" },
+}
+
+// isDirty
+
+test("value is dirty", () => {
+  const value = isDirty(VALUES, INITIAL_VALUES, "name.last")
+
+  expect(value).toBe(true)
+})
+
+test("value is clean", () => {
+  const value = isDirty(VALUES, INITIAL_VALUES, "name.first")
+
+  expect(value).toBe(false)
+})
+
+// getDirty
+
+test("get dirty values", () => {
+  const dirty = getDirty(VALUES, INITIAL_VALUES)
+
+  expect(dirty).toMatchObject({ "name.first": false, "name.last": true })
+})
+
+test("get subset of dirty values", () => {
+  const dirty = getDirty(VALUES, INITIAL_VALUES, ["name.first"])
+
+  expect(dirty).toMatchObject({ "name.first": false })
+})
+
+// getCleanNames
+
+test("get clean names", () => {
+  const cleanNames = getCleanNames(VALUES, INITIAL_VALUES)
+
+  expect(cleanNames).toMatchObject(["name.first"])
+})
+
+test("get subset of clean names", () => {
+  const cleanNames = getCleanNames(VALUES, INITIAL_VALUES, ["name.last"])
+
+  expect(cleanNames).toMatchObject([])
+})

package/src/utils/form.ts

@@ -2,7 +2,7 @@ import type { TypedMutationTrigger } from "@reduxjs/toolkit/query/react"
 import type { FieldValidator, FormikHelpers } from "formik"
 import { ValidationError, type Schema, type ValidateOptions } from "yup"
 
-import { excludeKeyPaths } from "./general"
+import { excludeKeyPaths, getNestedProperty, getKeyPaths } from "./general"
 
 export type FormValues = Record<string, any>
 
@@ -40,6 +40,8 @@ export type SubmitFormOptions<
   ResultType,
 > = Partial<{
   exclude: string[]
+  include: string[]
+  onlyDirtyValues: boolean
   then: (
     result: ResultType,
     values: Values,
@@ -67,6 +69,7 @@ export function submitForm<
   ResultType,
 >(
   trigger: TypedMutationTrigger<ResultType, QueryArg, any>,
+  initialValues: Values,
   options?: SubmitFormOptions<Values, QueryArg, ResultType>,
 ): SubmitFormHandler<Values>
 
@@ -76,6 +79,7 @@ export function submitForm<
   ResultType,
 >(
   trigger: TypedMutationTrigger<ResultType, QueryArg, any>,
+  initialValues: Values,
   options: SubmitFormOptions<Values, QueryArg, ResultType>,
 ): SubmitFormHandler<Values>
 
@@ -85,9 +89,17 @@ export function submitForm<
   ResultType,
 >(
   trigger: TypedMutationTrigger<ResultType, QueryArg, any>,
+  initialValues: Values,
   options?: SubmitFormOptions<Values, QueryArg, ResultType>,
 ): SubmitFormHandler<Values> {
-  const { exclude, then, catch: _catch, finally: _finally } = options || {}
+  let {
+    exclude = [],
+    include,
+    onlyDirtyValues = false,
+    then,
+    catch: _catch,
+    finally: _finally,
+  } = options || {}
 
   return (values, helpers) => {
     let arg =
@@ -95,7 +107,18 @@ export function submitForm<
         ? options.clean(values as QueryArg & FormValues)
         : (values as unknown as QueryArg)
 
-    if (exclude) arg = excludeKeyPaths(arg, exclude)
+    if (onlyDirtyValues) {
+      exclude = [
+        ...exclude,
+        ...getCleanNames(values, initialValues).filter(
+          cleanName => !exclude.includes(cleanName),
+        ),
+      ]
+    }
+
+    if (include) exclude = exclude.filter(name => !include.includes(name))
+
+    if (exclude.length) arg = excludeKeyPaths(arg, exclude)
 
     trigger(arg)
       .unwrap()
@@ -131,23 +154,35 @@ export function schemaToFieldValidator(
 
 // Checking if individual fields are dirty is not currently supported.
 // https://github.com/jaredpalmer/formik/issues/1421
-export function getDirty<
-  Values extends FormValues,
-  Names extends Array<keyof Values>,
->(
+export function getDirty<Values extends FormValues>(
   values: Values,
   initialValues: Values,
-  names: Names,
-): Record<Names[number], boolean> {
+  names?: string[],
+): Record<string, boolean> {
+  if (!names) names = getKeyPaths(values)
+
   return Object.fromEntries(
     names.map(name => [name, isDirty(values, initialValues, name)]),
-  ) as Record<Names[number], boolean>
+  )
 }
 
-export function isDirty<Values extends FormValues, Name extends keyof Values>(
+export function isDirty<Values extends FormValues>(
   values: Values,
   initialValues: Values,
-  name: Name,
+  name: string,
 ): boolean {
-  return values[name] !== initialValues[name]
+  const value = getNestedProperty(values, name)
+  const initialValue = getNestedProperty(initialValues, name)
+
+  return value !== initialValue
+}
+
+export function getCleanNames<Values extends FormValues>(
+  values: Values,
+  initialValues: Values,
+  names?: string[],
+): string[] {
+  return Object.entries(getDirty(values, initialValues, names))
+    .filter(([_, isDirty]) => !isDirty)
+    .map(([name]) => name)
 }

package/src/utils/general.test.ts

@@ -1,4 +1,9 @@
-import { excludeKeyPaths, getNestedProperty, withKeyPaths } from "./general"
+import {
+  excludeKeyPaths,
+  getNestedProperty,
+  withKeyPaths,
+  getKeyPaths,
+} from "./general"
 
 // getNestedProperty
 
@@ -24,12 +29,20 @@ test("get a nested property that doesn't exist", () => {
 
 // withKeyPaths
 
-test("get the paths of nested keys", () => {
+test("set the paths of nested keys", () => {
   const obj = withKeyPaths({ a: 1, b: { c: 2, d: { e: 3 } } })
 
   expect(obj).toMatchObject({ a: 1, b: { "b.c": 2, "b.d": { "b.d.e": 3 } } })
 })
 
+// getKeyPaths
+
+test("get the paths of nested keys", () => {
+  const keyPaths = getKeyPaths({ a: 1, b: { c: 2, d: { e: 3 } } })
+
+  expect(keyPaths).toMatchObject(["a", "b", "b.c", "b.d", "b.d.e"])
+})
+
 // excludeKeyPaths
 
 test("exclude nested keys by their path", () => {

package/src/utils/general.ts

@@ -966,7 +966,8 @@ export function withKeyPaths(obj: object, delimiter: string = "."): object {
       Object.entries(obj).map(([key, value]) => {
         const _path = [...path, key]
 
-        if (typeof value === "object") value = _withKeyPaths(value, _path)
+        if (typeof value === "object" && value !== null)
+          value = _withKeyPaths(value, _path)
 
         return [_path.join(delimiter), value]
       }),
@@ -976,6 +977,23 @@ export function withKeyPaths(obj: object, delimiter: string = "."): object {
   return _withKeyPaths(obj, [])
 }
 
+export function getKeyPaths(obj: object, delimiter: string = "."): string[] {
+  function _getKeyPaths(obj: object, path: string[]): string[] {
+    return Object.entries(obj)
+      .map(([key, value]) => {
+        const _path = [...path, key]
+        const keyPath = _path.join(delimiter)
+
+        return typeof value === "object" && value !== null
+          ? [keyPath, ..._getKeyPaths(value, _path)]
+          : [keyPath]
+      })
+      .flat()
+  }
+
+  return _getKeyPaths(obj, [])
+}
+
 export function excludeKeyPaths(
   obj: object,
   exclude: string[],