@strato-admin/ra-core 0.1.0

package/src/form/groups/useFormGroup.ts

@@ -0,0 +1,181 @@
+import { useEffect, useState } from 'react';
+import get from 'lodash/get.js';
+import isEqual from 'lodash/isEqual.js';
+import { useFormState } from 'react-hook-form';
+import { useFormGroups } from './useFormGroups';
+import { useEvent } from '../../util';
+
+type FieldState = {
+    name: string;
+    error?: any;
+    isDirty: boolean;
+    isTouched: boolean;
+    isValid: boolean;
+    isValidating: boolean;
+};
+
+type FormGroupState = {
+    errors?: object;
+    isDirty: boolean;
+    isTouched: boolean;
+    isValid: boolean;
+    isValidating: boolean;
+};
+
+/**
+ * Retrieve a specific form group data such as its validation status (valid/invalid) or
+ * or whether its inputs have been updated (dirty/pristine)
+ *
+ * @example
+ * import { Edit, SimpleForm, TextInput, FormGroupContextProvider, useFormGroup, minLength } from 'react-admin';
+ * import { Accordion, AccordionDetails, AccordionSummary, Typography } from '@mui/material';
+ * import ExpandMoreIcon from '@mui/icons-material/ExpandMoreIcon';
+ *
+ * const PostEdit = () => (
+ *     <Edit>
+ *         <SimpleForm>
+ *             <TextInput source="title" />
+ *             <FormGroupContextProvider name="options">
+ *                 <Accordion>
+ *                     <AccordionSummary
+ *                         expandIcon={<ExpandMoreIcon />}
+ *                         aria-controls="options-content"
+ *                         id="options-header"
+ *                     >
+ *                         <AccordionSectionTitle name="options">Options</AccordionSectionTitle>
+ *                     </AccordionSummary>
+ *                     <AccordionDetails id="options-content" aria-labelledby="options-header">
+ *                         <TextInput source="teaser" validate={minLength(20)} />
+ *                     </AccordionDetails>
+ *                 </Accordion>
+ *             </FormGroupContextProvider>
+ *         </SimpleForm>
+ *     </Edit>
+ * );
+ *
+ * const AccordionSectionTitle = ({ children, name }) => {
+ *     const formGroupState = useFormGroup(name);
+ *     return (
+ *         <Typography color={!formGroupState.isValid && formGroupState.isDirty ? 'error' : 'inherit'}>
+ *             {children}
+ *         </Typography>
+ *     );
+ * }
+ *
+ * @param {string} name The form group name
+ * @returns {FormGroupState} The form group state
+ */
+export const useFormGroup = (name: string): FormGroupState => {
+    const { dirtyFields, touchedFields, validatingFields, errors } =
+        useFormState();
+
+    // dirtyFields, touchedFields, validatingFields and errors are objects with keys being the field names
+    // Ex: { title: true }
+    // However, they are not correctly serialized when using JSON.stringify
+    // To avoid our effects to not be triggered when they should, we extract the keys and use that as a dependency
+    const dirtyFieldsNames = Object.keys(dirtyFields);
+    const touchedFieldsNames = Object.keys(touchedFields);
+    const validatingFieldsNames = Object.keys(validatingFields);
+    const errorsNames = Object.keys(errors);
+
+    const formGroups = useFormGroups();
+    const [state, setState] = useState<FormGroupState>({
+        errors: undefined,
+        isDirty: false,
+        isTouched: false,
+        isValid: true,
+        isValidating: true,
+    });
+
+    const updateGroupState = useEvent(() => {
+        if (!formGroups) return;
+        const fields = formGroups.getGroupFields(name);
+        const fieldStates = fields
+            .map<FieldState>(field => {
+                return {
+                    name: field,
+                    error: get(errors, field, undefined),
+                    isDirty: get(dirtyFields, field, false) !== false,
+                    isValid: get(errors, field, undefined) == null,
+                    isValidating:
+                        get(validatingFields, field, undefined) == null,
+                    isTouched: get(touchedFields, field, false) !== false,
+                };
+            })
+            .filter(fieldState => fieldState != undefined); // eslint-disable-line
+
+        const newState = getFormGroupState(fieldStates);
+        setState(oldState => {
+            if (!isEqual(oldState, newState)) {
+                return newState;
+            }
+
+            return oldState;
+        });
+    });
+
+    useEffect(() => {
+        updateGroupState();
+    }, [
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        JSON.stringify(dirtyFieldsNames),
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        JSON.stringify(errorsNames),
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        JSON.stringify(touchedFieldsNames),
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        JSON.stringify(validatingFieldsNames),
+        updateGroupState,
+        name,
+        formGroups,
+    ]);
+
+    useEffect(() => {
+        if (!formGroups) return;
+        // Whenever the group content changes (input are added or removed)
+        // we must update its state
+        const unsubscribe = formGroups.subscribe(name, () => {
+            updateGroupState();
+        });
+        return unsubscribe;
+    }, [formGroups, name, updateGroupState]);
+
+    return state;
+};
+
+/**
+ * Get the state of a form group
+ *
+ * @param {FieldState[]} fieldStates A map of field states from react-hook-form where the key is the field name.
+ * @returns {FormGroupState} The state of the group.
+ */
+export const getFormGroupState = (
+    fieldStates: FieldState[]
+): FormGroupState => {
+    return fieldStates.reduce<FormGroupState>(
+        (acc, fieldState) => {
+            const errors = acc.errors || {};
+
+            if (fieldState.error) {
+                errors[fieldState.name] = fieldState.error;
+            }
+
+            const newState = {
+                isDirty: acc.isDirty || fieldState.isDirty,
+                errors,
+                isTouched: acc.isTouched || fieldState.isTouched,
+                isValid: acc.isValid && fieldState.isValid,
+                isValidating: acc.isValidating && fieldState.isValidating,
+            };
+
+            return newState;
+        },
+        {
+            isDirty: false,
+            errors: undefined,
+            isValid: true,
+            isTouched: false,
+            isValidating: false,
+        }
+    );
+};

package/src/form/groups/useFormGroupContext.ts

@@ -0,0 +1,10 @@
+import { useContext } from 'react';
+import { FormGroupContext } from './FormGroupContext';
+
+/**
+ * Retrieve the name of the form group the consumer belongs to. May be undefined if the consumer is not inside a form group.
+ */
+export const useFormGroupContext = () => {
+    const context = useContext(FormGroupContext);
+    return context;
+};

package/src/form/groups/useFormGroups.ts

@@ -0,0 +1,10 @@
+import { useContext } from 'react';
+import { FormGroupsContext } from './FormGroupsContext';
+
+/**
+ * Retrieve the form groups management context. Used by inputs to register themselves into a form group.
+ */
+export const useFormGroups = () => {
+    const context = useContext(FormGroupsContext);
+    return context;
+};

package/src/form/index.ts

@@ -0,0 +1,14 @@
+export * from './choices';
+export * from './Form';
+export * from './FormDataConsumer';
+export * from './groups';
+export * from './useApplyInputDefaultValues';
+export * from './useAugmentedForm';
+export * from './useInput';
+export * from './useRecordFromLocation';
+export * from './useSuggestions';
+export * from './useWarnWhenUnsavedChanges';
+export * from './validation';
+export * from './WarnWhenUnsavedChanges';
+export * from './FilterLiveForm';
+export * from './useFormIsDirty';

package/src/form/sanitizeEmptyValues.spec.ts

@@ -0,0 +1,31 @@
+import expect from 'expect';
+
+import { sanitizeEmptyValues } from './sanitizeEmptyValues';
+
+describe('sanitizeEmptyValues', () => {
+    it('does not fail on empty inputs', () => {
+        expect(sanitizeEmptyValues({})).toEqual({});
+    });
+    it('should not change objects with only non-empty values', () => {
+        expect(sanitizeEmptyValues({ foo: 'bar', bar: 0, baz: false })).toEqual(
+            {
+                foo: 'bar',
+                bar: 0,
+                baz: false,
+            }
+        );
+    });
+    it('should remove empty strings from input', () => {
+        expect(sanitizeEmptyValues({ foo: '', bar: 'baz' })).toEqual({
+            bar: 'baz',
+        });
+    });
+    it('should not remove empty strings from input if the record had a value', () => {
+        expect(
+            sanitizeEmptyValues({ foo: '', bar: 'baz' }, { foo: 'foo' })
+        ).toEqual({
+            foo: null,
+            bar: 'baz',
+        });
+    });
+});

package/src/form/sanitizeEmptyValues.ts

@@ -0,0 +1,24 @@
+/**
+ * Remove empty strings from form state
+ *
+ * @example
+ * sanitizeEmptyValues({ foo: '', bar: 'baz' }) // { bar: 'baz' }
+ */
+export const sanitizeEmptyValues = (values: any, record: any = {}): any => {
+    const sanitizedValues = {};
+    Object.keys(values).forEach(key => {
+        if (values[key] == null || values[key] === '') {
+            if (record.hasOwnProperty(key)) {
+                // user has emptied a field, make the value null
+                sanitizedValues[key] = null;
+            } else {
+                // user has emptied a field, but the initial value was undefined
+                // so we don't include it in the sanitized values
+            }
+        } else {
+            // this is a non-empty value, so we include it in the sanitized values
+            sanitizedValues[key] = values[key];
+        }
+    });
+    return sanitizedValues;
+};

package/src/form/useApplyInputDefaultValues.ts

@@ -0,0 +1,107 @@
+import { useEffect, useRef } from 'react';
+import {
+    FieldValues,
+    UseFieldArrayReturn,
+    useFormContext,
+} from 'react-hook-form';
+import get from 'lodash/get.js';
+import { useRecordContext } from '../controller';
+import { InputProps } from './useInput';
+import { useWrappedSource } from '../core';
+
+interface StandardInput {
+    inputProps: Partial<InputProps> & { source: string };
+    isArrayInput?: undefined;
+    fieldArrayInputControl?: undefined;
+}
+
+interface ArrayInput {
+    inputProps: Partial<InputProps> & { source: string };
+    isArrayInput: true;
+    fieldArrayInputControl: UseFieldArrayReturn<FieldValues, string, 'id'>;
+}
+
+type Props = StandardInput | ArrayInput;
+
+/*
+ * This hook updates the input with the default value if default value is present
+ * and field input is not already populated or dirty
+ */
+export const useApplyInputDefaultValues = ({
+    inputProps,
+    isArrayInput,
+    fieldArrayInputControl,
+}: Props) => {
+    const { defaultValue, source, disabled } = inputProps;
+    const finalSource = useWrappedSource(source);
+
+    const record = useRecordContext(inputProps);
+    const { getValues, resetField, reset, subscribe } = useFormContext();
+    const recordValue = get(record, finalSource);
+    const formValue = get(getValues(), finalSource);
+    const isDirty = useRef<boolean | undefined>(undefined);
+
+    useEffect(() => {
+        return subscribe({
+            // Even though we only need dirtyFields, we subscribe to values as well to
+            // ensure we properly receive dirtyFields updates for newly added items in an ArrayInput
+            formState: { values: true, dirtyFields: true },
+            callback: ({ dirtyFields }) => {
+                isDirty.current = get(dirtyFields ?? {}, finalSource, false);
+            },
+        });
+    }, [finalSource, subscribe]);
+    useEffect(() => {
+        if (
+            defaultValue == null ||
+            formValue != null ||
+            // When the input is disabled, its value may always be undefined, no matter the default value.
+            // This prevents from trying to reset the value indefinitely.
+            disabled ||
+            // We check strictly for undefined to avoid setting default value
+            // when the field is null
+            recordValue !== undefined ||
+            isDirty.current === true
+        ) {
+            return;
+        }
+
+        // Side note: For Array Input but checked for all to avoid possible regression
+        // Since we use get(record, source), if source is like foo.23.bar,
+        // this effect will run. However we only want to set the default value
+        // for the subfield bar if the record actually has a value for foo.23
+        const pathContainsIndex = finalSource
+            .split('.')
+            .some(pathPart => numericRegex.test(pathPart));
+        if (pathContainsIndex) {
+            const parentPath = finalSource.split('.').slice(0, -1).join('.');
+            const parentValue = get(getValues(), parentPath);
+            if (parentValue == null) {
+                // the parent is undefined, so we don't want to set the default value
+                return;
+            }
+        }
+
+        if (isArrayInput) {
+            if (!fieldArrayInputControl) {
+                throw new Error(
+                    'useApplyInputDefaultValues: No fieldArrayInputControl passed in props for array input usage'
+                );
+            }
+
+            // We need to update inputs nested in array using react hook forms
+            // own array controller rather then the generic reset to prevent control losing
+            // context of the nested inputs
+            fieldArrayInputControl.replace(defaultValue);
+            // resets the form so that control no longer sees the form as dirty after
+            // defaults applied
+            reset({}, { keepValues: true });
+
+            return;
+        }
+
+        resetField(finalSource, { defaultValue });
+    });
+};
+
+const numericRegex = /^\d+$/;

package/src/form/useAugmentedForm.ts

@@ -0,0 +1,169 @@
+import {
+    BaseSyntheticEvent,
+    useCallback,
+    useEffect,
+    useMemo,
+    useRef,
+} from 'react';
+import {
+    FieldValues,
+    SubmitHandler,
+    useForm,
+    UseFormProps,
+} from 'react-hook-form';
+import merge from 'lodash/merge.js';
+import { RaRecord } from '../types';
+import { SaveHandler, useRecordContext, useSaveContext } from '../controller';
+import getFormInitialValues from './getFormInitialValues';
+import {
+    getSimpleValidationResolver,
+    ValidateForm,
+} from './validation/getSimpleValidationResolver';
+import { setSubmissionErrors } from './validation/setSubmissionErrors';
+import { useNotifyIsFormInvalid } from './validation/useNotifyIsFormInvalid';
+import { sanitizeEmptyValues as sanitizeValues } from './sanitizeEmptyValues';
+import { useRecordFromLocation } from './useRecordFromLocation';
+
+/**
+ * Wrapper around react-hook-form's useForm
+ *
+ * This hook adds the following features to react-hook-form's useForm:
+ *
+ * - form initialization based on RecordContext
+ * - validation based on a validate function
+ * - sanitization of empty values
+ * - notification on invalid form
+ * - stop form submission event propagation
+ */
+export const useAugmentedForm = <RecordType = any>(
+    props: UseAugmentedFormProps<RecordType>
+) => {
+    const {
+        criteriaMode = 'firstError',
+        defaultValues,
+        formRootPathname,
+        resolver,
+        resetOptions,
+        reValidateMode = 'onChange',
+        onSubmit,
+        sanitizeEmptyValues,
+        validate,
+        disableInvalidFormNotification,
+        ...rest
+    } = props;
+    const saveContext = useSaveContext();
+    const record = useRecordContext(props);
+
+    const defaultValuesIncludingRecord = useMemo(
+        () => getFormInitialValues(defaultValues, record),
+        // eslint-disable-next-line
+        [
+            // eslint-disable-next-line
+            JSON.stringify({
+                defaultValues:
+                    typeof defaultValues === 'function'
+                        ? 'function'
+                        : defaultValues,
+                record,
+            }),
+        ]
+    );
+
+    const finalResolver = resolver
+        ? resolver
+        : validate
+          ? getSimpleValidationResolver(validate)
+          : undefined;
+
+    const form = useForm({
+        criteriaMode,
+        defaultValues: defaultValuesIncludingRecord,
+        reValidateMode,
+        resolver: finalResolver,
+        ...rest,
+    });
+
+    const formRef = useRef(form);
+    const { reset, formState } = form;
+    const { isReady } = formState;
+
+    const previousRecordId = useRef(record?.id);
+
+    useEffect(() => {
+        const recordIdChanged = record?.id !== previousRecordId.current;
+        previousRecordId.current = record?.id;
+
+        reset(
+            defaultValuesIncludingRecord,
+            recordIdChanged ? undefined : resetOptions
+        );
+    }, [defaultValuesIncludingRecord, reset, resetOptions, record?.id]);
+
+    // notify on invalid form
+    useNotifyIsFormInvalid(form.control, !disableInvalidFormNotification);
+
+    const recordFromLocation = useRecordFromLocation();
+    const recordFromLocationApplied = useRef(false);
+    useEffect(() => {
+        if (!isReady) return;
+        if (recordFromLocation && !recordFromLocationApplied.current) {
+            reset(merge({}, defaultValuesIncludingRecord, recordFromLocation), {
+                keepDefaultValues: true,
+            });
+            recordFromLocationApplied.current = true;
+        }
+    }, [defaultValuesIncludingRecord, recordFromLocation, reset, isReady]);
+
+    // submit callbacks
+    const handleSubmit = useCallback(
+        async (values, event) => {
+            let errors;
+            const finalValues = sanitizeEmptyValues
+                ? sanitizeValues(values, record)
+                : values;
+            if (onSubmit) {
+                errors = await onSubmit(finalValues, event);
+            }
+            if (onSubmit == null && saveContext?.save) {
+                errors = await saveContext.save(finalValues, event);
+            }
+            if (errors != null) {
+                setSubmissionErrors(errors, formRef.current.setError);
+            }
+        },
+        [onSubmit, saveContext, sanitizeEmptyValues, record]
+    );
+
+    const formHandleSubmit = useCallback(
+        (event: BaseSyntheticEvent) => {
+            if (!event.defaultPrevented) {
+                // Prevent outer forms to receive the event
+                event.stopPropagation();
+                form.handleSubmit(handleSubmit)(event);
+            }
+            return;
+        },
+        [form, handleSubmit]
+    );
+
+    return {
+        form,
+        handleSubmit,
+        formHandleSubmit,
+    };
+};
+
+export type UseAugmentedFormProps<RecordType = any> =
+    UseFormOwnProps<RecordType> &
+        Omit<UseFormProps, 'onSubmit'> & {
+            validate?: ValidateForm;
+        };
+
+export interface UseFormOwnProps<RecordType = any> {
+    defaultValues?: any;
+    formRootPathname?: string;
+    record?: Partial<RaRecord>;
+    onSubmit?: SubmitHandler<FieldValues> | SaveHandler<RecordType>;
+    sanitizeEmptyValues?: boolean;
+    disableInvalidFormNotification?: boolean;
+}

package/src/form/useFormIsDirty.spec.ts

@@ -0,0 +1,136 @@
+import { checkHasDirtyFields } from './useFormIsDirty';
+
+describe('useFormIsDirty', () => {
+    describe('checkHasDirtyFields', () => {
+        it('should return true if any field is dirty on simple forms', () => {
+            const dirtyFields = { name: true, age: false };
+            expect(checkHasDirtyFields(dirtyFields)).toBe(true);
+        });
+
+        it('should return false if no field is dirty on simple forms', () => {
+            const dirtyFields = { name: false, age: false };
+            expect(checkHasDirtyFields(dirtyFields)).toBe(false);
+        });
+
+        it('should return true if any field is dirty on forms with nested fields', () => {
+            const dirtyFields = {
+                name: false,
+                age: false,
+                address: { street: true, city: false },
+            };
+            expect(checkHasDirtyFields(dirtyFields)).toBe(true);
+        });
+
+        it('should return false if no field is dirty on forms with nested fields', () => {
+            const dirtyFields = {
+                name: false,
+                age: false,
+                address: { street: false, city: false },
+            };
+            expect(checkHasDirtyFields(dirtyFields)).toBe(false);
+        });
+
+        it('should return true if any field is dirty on forms with array of scalar fields', () => {
+            const dirtyFields = {
+                name: false,
+                age: false,
+                hobbies: [true, false],
+            };
+            expect(checkHasDirtyFields(dirtyFields)).toBe(true);
+        });
+
+        it('should return false if no field is dirty on forms with array of scalar fields', () => {
+            const dirtyFields = {
+                name: false,
+                age: false,
+                hobbies: [false, false],
+            };
+            expect(checkHasDirtyFields(dirtyFields)).toBe(false);
+        });
+
+        it('should return true if any field is dirty on forms with array of objects', () => {
+            const dirtyFields = {
+                name: false,
+                age: false,
+                hobbies: [{ name: true }, { name: false }],
+            };
+            expect(checkHasDirtyFields(dirtyFields)).toBe(true);
+        });
+
+        it('should return false if no field is dirty on forms with array of objects', () => {
+            const dirtyFields = {
+                name: false,
+                age: false,
+                hobbies: [{ name: false }, { name: false }],
+            };
+            expect(checkHasDirtyFields(dirtyFields)).toBe(false);
+        });
+
+        it('should return true if any field is dirty on forms with nested array of objects', () => {
+            const dirtyFields = {
+                name: false,
+                age: false,
+                address: {
+                    street: false,
+                    city: [{ name: true }, { name: false }],
+                },
+            };
+            expect(checkHasDirtyFields(dirtyFields)).toBe(true);
+        });
+
+        it('should return false if no field is dirty on forms with nested array of objects', () => {
+            const dirtyFields = {
+                name: false,
+                age: false,
+                address: {
+                    street: false,
+                    city: [{ name: false }, { name: false }],
+                },
+            };
+            expect(checkHasDirtyFields(dirtyFields)).toBe(false);
+        });
+
+        // nested array of scalar values
+        it('should return true if any field is dirty on forms with nested array of scalar values', () => {
+            const dirtyFields = {
+                name: false,
+                age: false,
+                hobbies: [
+                    { name: false, tags: [true, true] },
+                    { name: false, tags: [false, false] },
+                ],
+            };
+            expect(checkHasDirtyFields(dirtyFields)).toBe(true);
+        });
+
+        it('should return false if no field is dirty on forms with nested array of scalar values', () => {
+            const dirtyFields = {
+                name: false,
+                age: false,
+                hobbies: [
+                    { name: false, tags: [false, false] },
+                    { name: false, tags: [false, false] },
+                ],
+            };
+            expect(checkHasDirtyFields(dirtyFields)).toBe(false);
+        });
+
+        it('should return true when an array contains an empty object (new item)', () => {
+            const dirtyFields = {
+                name: false,
+                age: false,
+                hobbies: [{}], // empty object should be considered dirty
+            };
+            expect(checkHasDirtyFields(dirtyFields)).toBe(true);
+        });
+
+        it('should return true when an array contains undefined entries (new item)', () => {
+            const dirtyFields = {
+                name: false,
+                age: false,
+                hobbies: [undefined], // undefined should be considered dirty
+            } as any;
+            expect(checkHasDirtyFields(dirtyFields)).toBe(true);
+        });
+    });
+});