Introduce Form Groups

docs/CreateEdit.md

@@ -2019,3 +2019,46 @@ const SaveWithNoteButton = props => {
 ```
 
 The `onSave` value should be a function expecting 2 arguments: the form values to save, and the redirection to perform.
+
+## Grouping Inputs
+
+Sometimes, you may want to group inputs in order to make a form more approachable. You may use a [`<TabbedForm>`](#the-tabbedform-component), an [`<AccordionForm>`](#the-accordionform-component) or you may want to roll your own layout. In this case, you might need to know the state of a group of inputs: whether it's valid or if the user has changed them (dirty/pristine state).
+
+For this, you can use the `<FormGroupContextProvider>`, which accept a group name and will links any inputs inside it to the group. You may then call the `useFormGroup` hook to retrieve the group status. For example:
+
+```jsx
+import { Edit, SimpleForm, TextInput, FormGroupContextProvider, useFormGroup } from 'react-admin';
+import { Accordion, AccordionDetails, AccordionSummary, Typography } from '@material-ui/core';
+
+const PostEdit = (props) => (
+    <Edit {...props}>
+        <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.invalid && formGroupState.dirty ? 'error' : 'inherit'}>
+            {children}
+        </Typography>
+    );
+}
+```

examples/simple/src/posts/PostEdit.js

@@ -29,6 +29,8 @@ import {
     required,
     FormDataConsumer,
 } from 'react-admin'; // eslint-disable-line import/no-unresolved
+import { Box } from '@material-ui/core';
+
 import PostTitle from './PostTitle';
 import TagReferenceInput from './TagReferenceInput';
 
@@ -43,12 +45,25 @@ const EditActions = ({ basePath, data, hasShow }) => (
     </TopToolbar>
 );
 
+const SanitizedBox = ({ fullWidth, basePath, ...props }) => <Box {...props} />;
+
 const PostEdit = ({ permissions, ...props }) => (
     <Edit title={<PostTitle />} actions={<EditActions />} {...props}>
         <TabbedForm initialValues={{ average_note: 0 }} warnWhenUnsavedChanges>
             <FormTab label="post.form.summary">
-                <TextInput disabled source="id" />
-                <TextInput source="title" validate={required()} resettable />
+                <SanitizedBox
+                    display="flex"
+                    width="100%"
+                    justifyContent="space-between"
+                    fullWidth
+                >
+                    <TextInput disabled source="id" />
+                    <TextInput
+                        source="title"
+                        validate={required()}
+                        resettable
+                    />
+                </SanitizedBox>
                 <TextInput
                     multiline={true}
                     fullWidth={true}

packages/ra-core/src/form/FormContext.tsx

@@ -1,10 +1,4 @@
 import { createContext } from 'react';
-import { FormFunctions } from '../types';
+import { FormContextValue } from '../types';
 
-const defaultFormFunctions: FormFunctions = { setOnSave: () => {} };
-
-const FormContext = createContext<FormFunctions>(defaultFormFunctions);
-
-FormContext.displayName = 'FormContext';
-
-export default FormContext;
+export const FormContext = createContext<FormContextValue>(undefined);

packages/ra-core/src/form/FormContextProvider.tsx

@@ -0,0 +1,18 @@
+import * as React from 'react';
+import { ReactNode } from 'react';
+import { FormContextValue } from '../types';
+import { FormContext } from './FormContext';
+
+/**
+ * Provides utilities to Forms children, allowing them to change the default save function or register inputs inside a group.
+ * @param props The component props
+ * @param {ReactNode} props.children The form content
+ * @param {FormContextValue} props.value The form context
+ */
+export const FormContextProvider = ({
+    children,
+    value,
+}: {
+    children: ReactNode;
+    value: FormContextValue;
+}) => <FormContext.Provider value={value}>{children}</FormContext.Provider>;

packages/ra-core/src/form/FormGroupContext.ts

@@ -0,0 +1,5 @@
+import { createContext } from 'react';
+
+export const FormGroupContext = createContext<FormGroupContextValue>(undefined);
+
+export type FormGroupContextValue = string;

packages/ra-core/src/form/FormGroupContextProvider.tsx

@@ -0,0 +1,36 @@
+import * as React from 'react';
+import { ReactNode, useEffect } from 'react';
+import { FormGroupContext } from './FormGroupContext';
+import { useFormContext } from './useFormContext';
+
+/**
+ * This provider allows its input children to know they belong to a specific group.
+ * This enables other components to access groups properties such as its
+ * validation (valid/invalid) or whether its inputs have been updated (dirty/pristine).
+ * @param props The component props
+ * @param {ReactNode} props.children The form group content
+ * @param {String} props.name The form group name
+ */
+export const FormGroupContextProvider = ({
+    children,
+    name,
+}: {
+    children: ReactNode;
+    name: string;
+}) => {
+    const formContext = useFormContext();
+
+    useEffect(() => {
+        formContext.registerGroup(name);
+
+        return () => {
+            formContext.unregisterGroup(name);
+        };
+    }, [formContext, name]);
+
+    return (
+        <FormGroupContext.Provider value={name}>
+            {children}
+        </FormGroupContext.Provider>
+    );
+};

packages/ra-core/src/form/FormWithRedirect.tsx

@@ -11,11 +11,11 @@ import useInitializeFormWithRecord from './useInitializeFormWithRecord';
 import useWarnWhenUnsavedChanges from './useWarnWhenUnsavedChanges';
 import sanitizeEmptyValues from './sanitizeEmptyValues';
 import getFormInitialValues from './getFormInitialValues';
-import FormContext from './FormContext';
-import { Record } from '../types';
+import { FormContextValue, Record } from '../types';
 import { RedirectionSideEffect } from '../sideEffect';
 import { useDispatch } from 'react-redux';
 import { setAutomaticRefresh } from '../actions/uiActions';
+import { FormContextProvider } from './FormContextProvider';
 
 /**
  * Wrapper around react-final-form's Form to handle redirection on submit,
@@ -64,8 +64,9 @@ const FormWithRedirect: FC<FormWithRedirectProps> = ({
     sanitizeEmptyValues: shouldSanitizeEmptyValues = true,
     ...props
 }) => {
-    let redirect = useRef(props.redirect);
-    let onSave = useRef(save);
+    const redirect = useRef(props.redirect);
+    const onSave = useRef(save);
+    const formGroups = useRef<{ [key: string]: string[] }>({});
 
     // We don't use state here for two reasons:
     // 1. There no way to execute code only after the state has been updated
@@ -92,7 +93,38 @@ const FormWithRedirect: FC<FormWithRedirectProps> = ({
         [save]
     );
 
-    const formContextValue = useMemo(() => ({ setOnSave }), [setOnSave]);
+    const formContextValue = useMemo<FormContextValue>(
+        () => ({
+            setOnSave,
+            getGroupFields: name => formGroups.current[name] || [],
+            registerGroup: name => {
+                formGroups.current[name] = formGroups.current[name] || [];
+            },
+            unregisterGroup: name => {
+                delete formGroups[name];
+            },
+            registerField: (source, group) => {
+                if (group) {
+                    formGroups.current[group] = formGroups.current[group] || [];
+                    const fields = new Set(formGroups.current[group]);
+                    fields.add(source);
+                    formGroups.current[group] = Array.from(fields);
+                }
+            },
+            unregisterField: (source, group) => {
+                if (group) {
+                    if (!formGroups.current[group]) {
+                        console.warn(`Invalid form group ${group}`);
+                    } else {
+                        const fields = new Set(formGroups.current[group]);
+                        fields.delete(source);
+                        formGroups.current[group] = Array.from(fields);
+                    }
+                }
+            },
+        }),
+        [setOnSave]
+    );
 
     const finalInitialValues = getFormInitialValues(
         initialValues,
@@ -118,7 +150,7 @@ const FormWithRedirect: FC<FormWithRedirectProps> = ({
     };
 
     return (
-        <FormContext.Provider value={formContextValue}>
+        <FormContextProvider value={formContextValue}>
             <Form
                 key={version} // support for refresh button
                 debug={debug}
@@ -146,7 +178,7 @@ const FormWithRedirect: FC<FormWithRedirectProps> = ({
                     />
                 )}
             />
-        </FormContext.Provider>
+        </FormContextProvider>
     );
 };
 

packages/ra-core/src/form/index.ts

@@ -3,7 +3,6 @@ import FormDataConsumer, {
     FormDataConsumerRender,
     FormDataConsumerRenderParams,
 } from './FormDataConsumer';
-import FormContext from './FormContext';
 import FormField from './FormField';
 import FormWithRedirect, {
     FormWithRedirectProps,
@@ -48,9 +47,15 @@ export {
     useInitializeFormWithRecord,
     useSuggestions,
     ValidationError,
-    FormContext,
     useWarnWhenUnsavedChanges,
 };
 export { isRequired } from './FormField';
 export * from './validate';
 export * from './constants';
+export * from './FormContextProvider';
+export * from './FormContext';
+export * from './useFormContext';
+export * from './FormGroupContext';
+export * from './FormGroupContextProvider';
+export * from './useFormGroup';
+export * from './useFormGroupContext';

packages/ra-core/src/form/useFormContext.ts

@@ -0,0 +1,12 @@
+import { useContext } from 'react';
+import { FormContext } from './FormContext';
+
+/**
+ * Retrieve the form context enabling consumers to alter its save function or to register inputs inside a form group.
+ * @returns {FormContext} The form context.
+ */
+export const useFormContext = () => {
+    const context = useContext(FormContext);
+
+    return context;
+};

packages/ra-core/src/form/useFormGroup.ts

@@ -0,0 +1,79 @@
+import { useState } from 'react';
+import { useForm } from 'react-final-form';
+import isEqual from 'lodash/isEqual';
+import { useFormContext } from './useFormContext';
+
+type FormGroupState = {
+    errors: object;
+    valid: boolean;
+    invalid: boolean;
+    pristine: boolean;
+    dirty: boolean;
+};
+
+/**
+ * Retrieve a specific form group data such as its validation status (valid/invalid) or
+ * or whether its inputs have been updated (dirty/pristine)
+ * @param {string] name The form group name
+ * @returns {FormGroupState} The form group state
+ */
+export const useFormGroup = (name: string): FormGroupState => {
+    const form = useForm();
+    const formContext = useFormContext();
+    const [state, setState] = useState<FormGroupState>({
+        errors: undefined,
+        valid: true,
+        invalid: false,
+        pristine: true,
+        dirty: false,
+    });
+
+    form.subscribe(
+        () => {
+            const fields = formContext.getGroupFields(name);
+            const newState = Array.from(fields).reduce<FormGroupState>(
+                (acc, field) => {
+                    const fieldState = form.getFieldState(field);
+                    let errors = acc.errors;
+
+                    if (fieldState.error) {
+                        if (!errors) {
+                            errors = {};
+                        }
+                        errors[field] = fieldState.error;
+                    }
+
+                    const newState = {
+                        errors,
+                        valid: acc.valid && fieldState.valid,
+                        invalid: acc.invalid || fieldState.invalid,
+                        pristine: acc.pristine && fieldState.pristine,
+                        dirty: acc.dirty || fieldState.dirty,
+                    };
+
+                    return newState;
+                },
+                {
+                    errors: undefined,
+                    valid: true,
+                    invalid: false,
+                    pristine: true,
+                    dirty: false,
+                }
+            );
+
+            if (!isEqual(state, newState)) {
+                setState(newState);
+            }
+        },
+        {
+            errors: true,
+            invalid: true,
+            dirty: true,
+            pristine: true,
+            valid: true,
+        }
+    );
+
+    return state;
+};

packages/ra-core/src/form/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;
+};