@availity/mui-controlled-form 0.2.5 → 0.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@availity/mui-controlled-form",
-  "version": "0.2.5",
-  "description": "Availity MUI ControlledForm Component - part of the @availity/element design system",
+  "version": "0.3.0",
+  "description": "Availity MUI/react-hook-form controlled form components - part of the @availity/element design system",
   "keywords": [
     "react",
     "typescript",

package/src/index.ts

@@ -10,3 +10,50 @@ export * from './lib/ProviderAutocomplete';
 export * from './lib/RadioGroup';
 export * from './lib/Select';
 export * from './lib/TextField';
+
+export {
+  FormProvider,
+  /** Custom react-hook-form hook to manage the entire form.
+   *
+   * ```tsx
+   * function App() {
+   *    const { handleSubmit, methods, formState: { isSubmitting } } = useForm();
+   *    const schema = yup.object({
+   *      textField: yup
+   *        .string(),
+   *      requiredTextField: yup
+   *        .string()
+   *        .required('This field is required.'),
+   *    });
+   *
+   *    type FormInputsType = yup.InferType<typeof schema>;
+   *
+   *    const onSubmit: SubmitHandler<FormInputsType> = (data) => console.log(data)
+   *
+   *    const defaultValues = {
+   *      textField: "",
+   *      requiredTextField: ""
+   *    }
+   *
+   *   return (
+   *      <FormProvider {...methods}>
+   *        <form onSubmit={methods.handleSubmit(onSubmit)}>
+   *          <TextField name="textField" />
+   *          <TextField name="requiredTextField" />
+   *          <LoadingButton loading={isSubmitting}>Submit</LoadingButton>
+   *        </form>
+   *      </FormProvider>
+   *    );
+   *  }
+   *  ```
+   */
+  useForm,
+  useFormContext
+} from 'react-hook-form';
+
+export type {
+  SubmitHandler,
+  /** react-hook-form `useForm` options, like `defaultValues` and validation `mode`. For more information see the [react-hook-form useForm docs](https://react-hook-form.com/docs/useform) */
+  UseFormProps,
+  UseFormReturn,
+} from 'react-hook-form';

package/src/lib/AsyncAutocomplete.stories.tsx

@@ -1,20 +1,19 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import { ControlledAsyncAutocomplete } from './AsyncAutocomplete';
-import { ControlledForm } from './ControlledForm';
 import { Button } from '@availity/mui-button';
-import { useFormContext } from 'react-hook-form';
+import { FormProvider, useForm } from 'react-hook-form';
 import { Paper } from '@availity/mui-paper';
 import { Typography } from '@availity/mui-typography';
 import { Grid } from '@availity/mui-layout';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import AvApi, { ApiConfig } from '@availity/api-axios';
-import { missingRHFprops } from '../../docs/propDefinitions';
+import { AllControllerPropertiesCategorized, AsyncAutocompletePropsCategorized } from './Types';
 
 const meta: Meta<typeof ControlledAsyncAutocomplete> = {
   title: 'Form Components/Controlled Form/Autocomplete/ControlledAsyncAutocomplete',
   component: ControlledAsyncAutocomplete,
   tags: ['autodocs'],
-  argTypes: missingRHFprops,
+  argTypes: {...AllControllerPropertiesCategorized, ...AsyncAutocompletePropsCategorized}
 };
 
 export default meta;
@@ -65,49 +64,35 @@ const client = new QueryClient({
 
 export const _ControlledAsyncAutoComplete: StoryObj<typeof ControlledAsyncAutocomplete> = {
   render: (args) => {
-    const SubmittedValues = () => {
-      const {
-        getValues,
-        formState: { isSubmitSuccessful },
-      } = useFormContext();
+    const methods = useForm();
 
-      return isSubmitSuccessful ? (
-        <Paper sx={{ padding: '1.5rem', marginTop: '1.5rem' }}>
-          <Typography variant="h2">Submitted Values</Typography>
-          <pre>{JSON.stringify(getValues(), null, 2)}</pre>
-        </Paper>
-      ) : null;
-    };
-
-    const Actions = () => {
-      const {
-        reset,
-        formState: { isSubmitSuccessful },
-      } = useFormContext();
-      return (
-        <Grid container direction="row" justifyContent="space-between" marginTop={1}>
-          <Button disabled={!isSubmitSuccessful} children="Reset" color="secondary" onClick={() => reset()} />
-          <Button type="submit" disabled={isSubmitSuccessful} children="Submit" />
-        </Grid>
-      );
-    };
     return (
       <QueryClientProvider client={client}>
-        <ControlledForm values={{ controlledAutocomplete: undefined }} onSubmit={(data) => data}>
-          <ControlledAsyncAutocomplete {...args} />
-          <Actions />
-          <SubmittedValues />
-        </ControlledForm>
+        <FormProvider {...methods}>
+          <form onSubmit={methods.handleSubmit((data) => data)}>
+            <ControlledAsyncAutocomplete {...args} />
+            <Grid container direction="row" justifyContent="space-between" marginTop={1}>
+              <Button disabled={!methods?.formState?.isSubmitSuccessful} children="Reset" color="secondary" onClick={() => methods.reset()} />
+              <Button type="submit" disabled={methods?.formState?.isSubmitSuccessful} children="Submit" />
+            </Grid>
+            { methods?.formState?.isSubmitSuccessful ? (
+              <Paper sx={{ padding: '1.5rem', marginTop: '1.5rem' }}>
+                <Typography variant="h2">Submitted Values</Typography>
+                <pre data-testid="result">{JSON.stringify(methods.getValues(), null, 2)}</pre>
+              </Paper>
+            ) : null }
+          </form>
+        </FormProvider>
       </QueryClientProvider>
     );
   },
   args: {
     name: 'controlledAsyncAutocomplete',
-    FieldProps: { label: 'Async Select', helperText: 'Helper Text', fullWidth: false },
+    FieldProps: { label: 'Async Select', helperText: 'Helper Text', fullWidth: false, required: true },
     getOptionLabel: (val: Option) => val.label,
     loadOptions,
     limit: 10,
     queryKey: 'example',
-    required: 'This is required.',
+    rules: { required:'This is required.' },
   },
 };

package/src/lib/AsyncAutocomplete.test.tsx

@@ -1,15 +1,10 @@
 import { fireEvent, render, waitFor } from '@testing-library/react';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { Paper } from '@availity/mui-paper';
-import { Typography } from '@availity/mui-typography';
-import { useFormContext } from 'react-hook-form';
-import { Grid } from '@availity/mui-layout';
-import { Button } from '@availity/mui-button';
 import AvApi, { ApiConfig } from '@availity/api-axios';
 // eslint-disable-next-line @nx/enforce-module-boundaries
 import { server } from '@availity/mock/src/lib/server';
-import { ControlledForm } from './ControlledForm';
 import { ControlledAsyncAutocomplete } from './AsyncAutocomplete';
+import { TestForm } from './UtilComponents';
 
 const api = new AvApi({ name: 'example' } as ApiConfig);
 
@@ -47,33 +42,6 @@ const loadOptions = async (offset: number, limit: number) => {
   };
 };
 
-const SubmittedValues = () => {
-  const {
-    getValues,
-    formState: { isSubmitSuccessful },
-  } = useFormContext();
-
-  return isSubmitSuccessful ? (
-    <Paper sx={{ padding: '1.5rem', marginTop: '1.5rem' }}>
-      <Typography variant="h2">Submitted Values</Typography>
-      <pre data-testid="result">{JSON.stringify(getValues(), null, 2)}</pre>
-    </Paper>
-  ) : null;
-};
-
-const Actions = () => {
-  const {
-    reset,
-    formState: { isSubmitSuccessful },
-  } = useFormContext();
-  return (
-    <Grid container direction="row" justifyContent="space-between">
-      <Button disabled={!isSubmitSuccessful} children="Reset" color="secondary" onClick={() => reset()} />
-      <Button type="submit" disabled={isSubmitSuccessful} children="Submit" />
-    </Grid>
-  );
-};
-
 const onSubmit = jest.fn();
 
 describe('ControlledAsyncAutocomplete', () => {
@@ -98,20 +66,18 @@ describe('ControlledAsyncAutocomplete', () => {
   });
 
   test('should loadOptions successfully', async () => {
-    const screen = render(
-      <QueryClientProvider client={client}>
-        <ControlledForm values={{ controlledAutocomplete: undefined }} onSubmit={(data) => data}>
-          <ControlledAsyncAutocomplete
-            name="controlledAsyncAutocomplete"
-            FieldProps={{ label: 'Async Select', helperText: 'Helper Text', fullWidth: false }}
-            getOptionLabel={(val: Option) => val.label}
-            loadOptions={loadOptions}
-            limit={10}
-            queryKey="example"
-          />
-          <Actions />
-          <SubmittedValues />
-        </ControlledForm>
+      const screen = render(
+        <QueryClientProvider client={client}>
+          <TestForm UseFormOptions={{values: { controlledAutocomplete: undefined }}} onSubmit={onSubmit}>
+            <ControlledAsyncAutocomplete
+              name="controlledAsyncAutocomplete"
+              FieldProps={{ label: 'Async Select', helperText: 'Helper Text', fullWidth: false }}
+              getOptionLabel={(val: Option) => val.label}
+              loadOptions={loadOptions}
+              limit={10}
+              queryKey="example"
+            />
+        </TestForm>
       </QueryClientProvider>
     );
 
@@ -125,7 +91,7 @@ describe('ControlledAsyncAutocomplete', () => {
   test('should set the value and submit the form data', async () => {
     const screen = render(
       <QueryClientProvider client={client}>
-        <ControlledForm values={{ controlledAutocomplete: undefined }} onSubmit={onSubmit}>
+        <TestForm UseFormOptions={{values: { controlledAutocomplete: undefined }}} onSubmit={onSubmit}>
           <ControlledAsyncAutocomplete
             name="controlledAsyncAutocomplete"
             FieldProps={{ label: 'Async Select', helperText: 'Helper Text', fullWidth: false }}
@@ -134,11 +100,9 @@ describe('ControlledAsyncAutocomplete', () => {
             limit={10}
             queryKey="example"
           />
-          <Actions />
-          <SubmittedValues />
-        </ControlledForm>
-      </QueryClientProvider>
-    );
+      </TestForm>
+    </QueryClientProvider>
+  );
 
     const dropdown = screen.getByRole('combobox');
     fireEvent.click(dropdown);

package/src/lib/AsyncAutocomplete.tsx

@@ -1,6 +1,7 @@
 import { AsyncAutocomplete, AsyncAutocompleteProps } from '@availity/mui-autocomplete';
-import { useFormContext, RegisterOptions, FieldValues, Controller, ControllerProps } from 'react-hook-form';
+import { RegisterOptions, FieldValues, Controller } from 'react-hook-form';
 import { ChipTypeMap } from '@mui/material/Chip';
+import { ControllerProps, DeprecatedRulesProps } from './Types';
 
 export type ControlledAsyncAutocompleteProps<
   Option,
@@ -8,9 +9,13 @@ export type ControlledAsyncAutocompleteProps<
   DisableClearable extends boolean | undefined,
   FreeSolo extends boolean | undefined,
   ChipComponent extends React.ElementType = ChipTypeMap['defaultComponent'],
-> = Omit<AsyncAutocompleteProps<Option, Multiple, DisableClearable, FreeSolo, ChipComponent>, 'name'> &
-  Omit<RegisterOptions<FieldValues, string>, 'disabled' | 'valueAsNumber' | 'valueAsDate' | 'setValueAs'> &
-  Pick<ControllerProps, 'defaultValue' | 'shouldUnregister' | 'name'>;
+> = Omit<AsyncAutocompleteProps<Option, Multiple, DisableClearable, FreeSolo, ChipComponent>,
+'onBlur' | 'onChange' | 'value' | 'name'
+> & Pick<RegisterOptions<FieldValues, string>,
+'onBlur' | 'onChange' | 'value'
+> & ControllerProps
+//TODO v1 - remove deprecated props
+& DeprecatedRulesProps;
 
 export const ControlledAsyncAutocomplete = <
   Option,
@@ -29,18 +34,16 @@ export const ControlledAsyncAutocomplete = <
   onChange,
   pattern,
   required,
+  rules = {},
   shouldUnregister,
   validate,
   value,
   FieldProps,
   ...rest
 }: ControlledAsyncAutocompleteProps<Option, Multiple, DisableClearable, FreeSolo, ChipComponent>) => {
-  const { control, getFieldState } = useFormContext();
-  const errorMessage = getFieldState(name).error?.message;
   return (
     <Controller
       name={name}
-      control={control}
       defaultValue={rest.defaultValue}
       rules={{
         deps,
@@ -55,25 +58,25 @@ export const ControlledAsyncAutocomplete = <
         shouldUnregister,
         validate,
         value,
+        ...rules,
       }}
       shouldUnregister={shouldUnregister}
-      render={({ field: { onChange, value, onBlur } }) => (
+      render={({ field: { onChange, value, onBlur, ref }, fieldState: { error } }) => (
         <AsyncAutocomplete
           {...rest}
           FieldProps={{
             ...FieldProps,
-            required: typeof required === 'object' ? required.value : !!required,
-            error: !!errorMessage,
-            helperText:
-              errorMessage && typeof errorMessage === 'string' ? (
-                <>
-                  {errorMessage}
-                  <br />
-                  {FieldProps?.helperText}
-                </>
-              ) : (
-                FieldProps?.helperText
-              ),
+            error: !!error,
+            helperText: error?.message ? (
+              <>
+                {error.message}
+                <br />
+                {FieldProps?.helperText}
+              </>
+            ) : (
+              FieldProps?.helperText
+            ),
+            inputRef:ref
           }}
           onChange={(event, value, reason) => {
             if (reason === 'clear') {

package/src/lib/Autocomplete.stories.tsx

@@ -1,60 +1,47 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import { ControlledAutocomplete } from './Autocomplete';
-import { ControlledForm } from './ControlledForm';
 import { Button } from '@availity/mui-button';
-import { useFormContext } from 'react-hook-form';
+import { FormProvider, useForm } from '..';
 import { Paper } from '@availity/mui-paper';
 import { Typography } from '@availity/mui-typography';
 import { Grid } from '@availity/mui-layout';
+import { AllControllerPropertiesCategorized, AutocompletePropsCategorized } from './Types';
 
 const meta: Meta<typeof ControlledAutocomplete> = {
   title: 'Form Components/Controlled Form/Autocomplete/ControlledAutocomplete',
   component: ControlledAutocomplete,
   tags: ['autodocs'],
+  argTypes: {...AllControllerPropertiesCategorized, ...AutocompletePropsCategorized}
 };
 
 export default meta;
 
 export const _ControlledAutoComplete: StoryObj<typeof ControlledAutocomplete> = {
   render: (args) => {
-    const SubmittedValues = () => {
-      const {
-        getValues,
-        formState: { isSubmitSuccessful },
-      } = useFormContext();
+    const methods = useForm();
 
-      return isSubmitSuccessful ? (
-        <Paper sx={{ padding: '1.5rem', marginTop: '1.5rem' }}>
-          <Typography variant="h2">Submitted Values</Typography>
-          <pre>{JSON.stringify(getValues(), null, 2)}</pre>
-        </Paper>
-      ) : null;
-    };
-
-    const Actions = () => {
-      const {
-        reset,
-        formState: { isSubmitSuccessful },
-      } = useFormContext();
-      return (
-        <Grid container direction="row" justifyContent="space-between" marginTop={1}>
-          <Button disabled={!isSubmitSuccessful} children="Reset" color="secondary" onClick={() => reset()} />
-          <Button type="submit" disabled={isSubmitSuccessful} children="Submit" />
-        </Grid>
-      );
-    };
     return (
-      <ControlledForm values={{ controlledAutocomplete: undefined }} onSubmit={(data) => data}>
-        <ControlledAutocomplete {...args} />
-        <Actions />
-        <SubmittedValues />
-      </ControlledForm>
+      <FormProvider {...methods}>
+        <form onSubmit={methods.handleSubmit((data) => data)}>
+          <ControlledAutocomplete {...args} />
+          <Grid container direction="row" justifyContent="space-between" marginTop={1}>
+            <Button disabled={!methods?.formState?.isSubmitSuccessful} children="Reset" color="secondary" onClick={() => methods.reset()} />
+            <Button type="submit" disabled={methods?.formState?.isSubmitSuccessful} children="Submit" />
+          </Grid>
+          { methods?.formState?.isSubmitSuccessful ? (
+            <Paper sx={{ padding: '1.5rem', marginTop: '1.5rem' }}>
+              <Typography variant="h2">Submitted Values</Typography>
+              <pre data-testid="result">{JSON.stringify(methods.getValues(), null, 2)}</pre>
+            </Paper>
+          ) : null }
+        </form>
+      </FormProvider>
     );
   },
   args: {
     name: 'controlledAutocomplete',
     options: ['Option 1', 'Option 2'],
-    required: 'This is required.',
+    rules: { required: 'This is required.' },
     FieldProps: { label: 'Autocomplete Label' },
   },
 };

package/src/lib/Autocomplete.test.tsx

@@ -1,11 +1,6 @@
 import { fireEvent, render, waitFor } from '@testing-library/react';
-import { useFormContext } from 'react-hook-form';
-import { Paper } from '@availity/mui-paper';
-import { Typography } from '@availity/mui-typography';
-import { Grid } from '@availity/mui-layout';
-import { Button } from '@availity/mui-button';
-import { ControlledForm } from './ControlledForm';
 import { ControlledAutocomplete } from './Autocomplete';
+import { TestForm } from './UtilComponents';
 
 const onSubmit = jest.fn();
 
@@ -17,38 +12,13 @@ describe('ControlledAsyncAutocomplete', () => {
   });
 
   test('should set the value and submit the form', async () => {
-    const SubmittedValues = () => {
-      const {
-        getValues,
-        formState: { isSubmitSuccessful },
-      } = useFormContext();
-
-      return isSubmitSuccessful ? (
-        <Paper sx={{ padding: '1.5rem', marginTop: '1.5rem' }}>
-          <Typography variant="h2">Submitted Values</Typography>
-          <pre data-testid="result">{JSON.stringify(getValues(), null, 2)}</pre>
-        </Paper>
-      ) : null;
-    };
-
-    const Actions = () => {
-      const {
-        reset,
-        formState: { isSubmitSuccessful },
-      } = useFormContext();
-      return (
-        <Grid container direction="row" justifyContent="space-between">
-          <Button disabled={!isSubmitSuccessful} children="Reset" color="secondary" onClick={() => reset()} />
-          <Button type="submit" disabled={isSubmitSuccessful} children="Submit" />
-        </Grid>
-      );
-    };
     const screen = render(
-      <ControlledForm values={{ controlledAutocomplete: undefined }} onSubmit={onSubmit}>
-        <ControlledAutocomplete name="controlledAutocomplete" options={['Option 1', 'Option 2']} />
-        <Actions />
-        <SubmittedValues />
-      </ControlledForm>
+      <TestForm UseFormOptions={{values: { controlledAutocomplete: null}}} onSubmit={onSubmit}>
+        <ControlledAutocomplete
+          name="controlledAutocomplete"
+          options={['Option 1', 'Option 2']}
+        />
+      </TestForm>
     );
 
     const dropdown = screen.getByRole('combobox');

package/src/lib/Autocomplete.tsx

@@ -1,6 +1,7 @@
 import { Autocomplete, AutocompleteProps } from '@availity/mui-autocomplete';
-import { useFormContext, RegisterOptions, FieldValues, Controller, ControllerProps } from 'react-hook-form';
+import { RegisterOptions, FieldValues, Controller } from 'react-hook-form';
 import { ChipTypeMap } from '@mui/material/Chip';
+import { ControllerProps, DeprecatedRulesProps } from './Types';
 
 export type ControlledAutocompleteProps<
   T,
@@ -9,11 +10,13 @@ export type ControlledAutocompleteProps<
   FreeSolo extends boolean | undefined,
   ChipComponent extends React.ElementType = ChipTypeMap['defaultComponent'],
 > = Omit<
-  AutocompleteProps<T, Multiple, DisableClearable, FreeSolo, ChipComponent>,
-  'onChange' | 'onBlur' | 'value' | 'name'
-> &
-  Omit<RegisterOptions<FieldValues, string>, 'disabled' | 'valueAsNumber' | 'valueAsDate' | 'setValueAs'> &
-  Pick<ControllerProps, 'defaultValue' | 'shouldUnregister' | 'name'>;
+AutocompleteProps<T, Multiple, DisableClearable, FreeSolo, ChipComponent>,
+'onBlur' | 'onChange' | 'value' | 'name'
+> & Pick<RegisterOptions<FieldValues, string>,
+'onBlur' | 'onChange' | 'value'
+> & ControllerProps
+//TODO v1 - remove deprecated props
+& DeprecatedRulesProps;
 
 export const ControlledAutocomplete = <
   T,
@@ -25,6 +28,7 @@ export const ControlledAutocomplete = <
   name,
   FieldProps,
   defaultValue,
+  rules = {},
   deps,
   max,
   maxLength,
@@ -39,11 +43,8 @@ export const ControlledAutocomplete = <
   value,
   ...rest
 }: ControlledAutocompleteProps<T, Multiple, DisableClearable, FreeSolo, ChipComponent>) => {
-  const { control, getFieldState } = useFormContext();
-  const errorMessage = getFieldState(name).error?.message;
   return (
     <Controller
-      control={control}
       name={name}
       defaultValue={defaultValue}
       rules={{
@@ -59,25 +60,25 @@ export const ControlledAutocomplete = <
         shouldUnregister,
         validate,
         value,
+        ...rules,
       }}
       shouldUnregister={shouldUnregister}
-      render={({ field: { onChange, value, onBlur } }) => (
+      render={({ field: { onChange, value, onBlur, ref }, fieldState: { error } }) => (
         <Autocomplete
           {...rest}
           FieldProps={{
             ...FieldProps,
-            required: typeof required === 'object' ? required.value : !!required,
-            error: !!errorMessage,
-            helperText:
-              errorMessage && typeof errorMessage === 'string' ? (
+            error: !!error,
+            helperText: error?.message ? (
                 <>
-                  {errorMessage}
+                  {error.message}
                   <br />
                   {FieldProps?.helperText}
                 </>
               ) : (
                 FieldProps?.helperText
               ),
+            inputRef: ref
           }}
           onChange={(event, value, reason) => {
             if (reason === 'clear') {