@chris-c-brine/form-dialog 1.0.6 → 1.1.0

package/README.md

@@ -42,91 +42,55 @@ This package has the following peer dependencies that need to be installed in yo
 
 ```tsx
 // LoginPage.tsx
-import { useCallback, type FC, type PropsWithChildren } from "react";
+import { type FC } from "react";
 import { Container, IconButton } from "@mui/material";
-import { globalErrorAtom, useUser } from "@features";
 import { useDialog } from "@chris-c-brine/form-dialog";
-import { useForm, type SubmitHandler } from "react-hook-form-mui";
+import LoginForm from "./components/forms/LoginForm";
+import { Lock as LockIcon } from "@mui/icons-material";
 import { LoginDialog } from "./LoginDialog";
-import LoginForm from ".//LoginForm";
-import { Lock as LockIcon, Person as PersonIcon } from "@mui/icons-material";
-import { useSetAtom } from "jotai";
 
-const defaultLoginFormValues = { username: "", password: "" };
-type SubmitLogin = SubmitHandler<typeof defaultLoginFormValues>;
 const LoginPage: FC = () => {
-  const { dialogProps, closeDialog, openDialog } = useDialog();
-  const { setUser } = useUser();
-  const setError = useSetAtom(globalErrorAtom);
-
-  const formContext = useForm({ defaultValues: defaultLoginFormValues });
-
-  const onSuccess: SubmitLogin = useCallback(
-    (data, event) => {
-      event?.preventDefault(); // Stop default html form submit
-      formContext.reset(); // Reset form
-      setUser({ name: data.username, isActive: true }); // Update User (and/or other business logic)
-      closeDialog(); // Close Dialog
-      setError({
-        message: <>Hello {data.username}!</>,
-        title: 'Successful Login!',
-        severity: "success",
-        icon: <PersonIcon sx={{fontSize: 35}} />
-      });
-    },
-    [formContext, setUser, closeDialog, setError],
-  );
+  const { dialogProps, openDialog } = useDialog();
 
   return (
-    <LoginFormContainer>
-      <LoginForm onSuccess={onSuccess}>
+    <Container
+      component="main"
+      maxWidth={"xs"}
+      sx={{
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        height: "85vh",
+        overflow: "hidden",
+        animation: "fadeIn 1s ease-in-out",
+        "@keyframes fadeIn": {
+          from: { opacity: 0 },
+          to: { opacity: 1 },
+        },
+      }}
+    >
+      <LoginForm>
         <IconButton color="primary" onClick={openDialog} sx={{ py: 1 }}>
           <LockIcon sx={{ fontSize: 50 }} />
         </IconButton>
       </LoginForm>
-      <LoginDialog
-        dialogProps={{ ...dialogProps }}
-        handleSubmit={onSuccess}
-        onClose={closeDialog}
-      />
-    </LoginFormContainer>
+      <LoginDialog dialogProps={dialogProps} />
+    </Container>
   );
 };
 
 export default LoginPage;
-
-const LoginFormContainer: FC<PropsWithChildren> = ({ children }) => (
-  <Container
-    component="main"
-    maxWidth={"xs"}
-    sx={{
-      display: "flex",
-      alignItems: "center",
-      justifyContent: "center",
-      height: "85vh",
-      overflow: "hidden",
-      animation: "fadeIn 1s ease-in-out",
-      "@keyframes fadeIn": {
-        from: { opacity: 0 },
-        to: { opacity: 1 },
-      },
-    }}
-  >
-    {children}
-  </Container>
-);
 ```
 ```tsx
 // LoginPageConstants.ts
 import type { SubmitHandler } from "react-hook-form";
 
 export const defaultLoginFormValues = { username: "", password: "" };
-export type LoginForm = typeof defaultLoginFormValues;
-export type SubmitLogin = SubmitHandler<LoginForm>;
+export type LoginFormValues = typeof defaultLoginFormValues;
 ```
 ```tsx
 // LoginFormBase.tsx
-import {TextFieldElement, PasswordElement, type PasswordElementProps, useFormContext} from "react-hook-form-mui";
+import { TextFieldElement, PasswordElement, type PasswordElementProps, useFormContext} from "react-hook-form-mui";
 import { memo, useEffect } from "react";
 import { useFormDialog, AutoGrid, type AutoGridProps } from "@chris-c-brine/form-dialog";
 
@@ -177,6 +141,7 @@ const UserName = ({ disabled }: Pick<PasswordElementProps, "disabled">) => (
     }}
   />
 );
+UserName.displayName = "UserName";
 
 const Password = ({ disabled }: Pick<PasswordElementProps, "disabled">) => {
   const { setValue, getValues } = useFormContext();
@@ -184,7 +149,7 @@ const Password = ({ disabled }: Pick<PasswordElementProps, "disabled">) => {
 
   useEffect(() => {
     if (disabled && password !== "") {
-      setValue("passwordDisabled", "");
+      setValue("disabledPassword", "");
     }
   }, [disabled, setValue, password]);
 
@@ -205,26 +170,29 @@ const Password = ({ disabled }: Pick<PasswordElementProps, "disabled">) => {
     />
   );
 };
+
+Password.displayName = "Password";
 ```
 ```tsx
 // LoginForm.tsx
 import { Lock as LockIcon } from "@mui/icons-material";
 import { Box, Typography, type TypographyProps } from "@mui/material";
-import { type SubmitLogin, defaultLoginFormValues } from "./LoginPageConstants";
-import LoginFormBase from "./LoginFormBase";
 import { merge } from "lodash";
-import type { FC, PropsWithChildren } from "react";
+import { FC, PropsWithChildren, useCallback, useMemo } from "react";
 import { FormDialogActions, FormDialogProvider, PaperForm } from "@chris-c-brine/form-dialog";
+import { SubmitHandler, useForm } from "react-hook-form-mui";
+import { defaultLoginFormValues, LoginFormValues } from "./LoginPageConstants";
+import LoginFormBase from "./LoginFormBase";
+import { globalErrorAtom, useUser } from "@features";
+import { useSetAtom } from "jotai/index";
+import {  Person as PersonIcon } from "@mui/icons-material";
 
 const AltIcon = () => <LockIcon sx={{ mr: 1, fontSize: 20 }} />;
 
-interface LoginFormProps extends PropsWithChildren {
-  onSuccess: SubmitLogin;
-}
+export const LoginForm: FC<PropsWithChildren> = ({ children }) => {
 
-const LoginForm: FC<LoginFormProps> = ({ onSuccess, children }) => {
   return (
-    <LoginPaperForm onSuccess={onSuccess}>
+    <LoginPaperForm>
       <Box px={2}>
         {children}
         <SecureLoginText />
@@ -243,8 +211,6 @@ const LoginForm: FC<LoginFormProps> = ({ onSuccess, children }) => {
   );
 };
 
-export default LoginForm;
-
 const SecureLoginText: FC<TypographyProps> = (props) => {
   const typographyProps = merge(
     {
@@ -257,18 +223,38 @@ const SecureLoginText: FC<TypographyProps> = (props) => {
   return <Typography {...typographyProps}>Secure Login</Typography>;
 };
 
-type LoginPaperFormProps = PropsWithChildren & {
-  onSuccess?: SubmitLogin;
-};
+const LoginPaperForm: FC<PropsWithChildren> = ({ children }) => {
+  const formContext = useForm({defaultValues: defaultLoginFormValues});
+  const { setUser } = useUser();
+  const setError = useSetAtom(globalErrorAtom);
+  const reset = useMemo(() => formContext.reset, [formContext?.reset]);
+
+  const onSuccess: SubmitHandler<LoginFormValues> = useCallback(
+    (data, event) => {
+      event?.preventDefault(); // Stop default html form submit
+      event?.stopPropagation(); // STOP!!!!!
+
+      setUser({ name: data.username, isActive: true }); // Update User (and/or other business logic)
+      reset(); // reset form
+      setError({ // Signal Success!
+        message: <>Hello {data.username}!</>,
+        title: "Successful Login!",
+        severity: "success",
+        icon: <PersonIcon sx={{ fontSize: 35 }} />,
+      });
+    }, [setUser, setError, reset]);
 
-const LoginPaperForm: FC<LoginPaperFormProps> = ({ children, onSuccess }) => {
   return (
     <FormDialogProvider>
       <PaperForm
+        persistKey={'login-page-form'}
         formProps={{
-          defaultValues: defaultLoginFormValues,
+          formContext,
           onSuccess,
-          onError: (e) => console.log(e),
+          onError: (errors, event) => {
+            event?.preventDefault();
+            console.log(errors)
+          },
         }}
         elevation={3}
         sx={{
@@ -285,39 +271,63 @@ const LoginPaperForm: FC<LoginPaperFormProps> = ({ children, onSuccess }) => {
 ```
 ```tsx
 // LoginDialog.tsx
-import {useDialog, FormDialog, FormDialogActions, type FormDialogProps,  PersistForm } from "@chris-c-brine/form-dialog";
-import {  type FC } from "react";
-import { useForm } from "react-hook-form-mui";
+import { useDialog, FormDialog, FormDialogActions } from "@chris-c-brine/form-dialog";
+import { memo, useCallback, useMemo } from "react";
 import LoginFormBase from "./LoginFormBase";
-import {
-  defaultLoginFormValues,
-  type LoginForm,
-  type SubmitLogin,
-} from "./LoginPageConstants";
+import { defaultLoginFormValues, LoginFormValues } from "./LoginPageConstants";
+import { SubmitHandler, useForm } from "react-hook-form-mui";
+import { globalErrorAtom, useUser } from "@features";
+import { useSetAtom } from "jotai/index";
+import { Person as PersonIcon } from "@mui/icons-material";
 
 const formKey = "dialog-login-form";
 
-/* Basic Form Dialog Test */
-type LoginDialogProps = Pick<ReturnType<typeof useDialog>, "dialogProps"> &
-  Pick<FormDialogProps<LoginForm>, "onClose"> & {
-    handleSubmit: SubmitLogin;
-  };
+export type LoginDialogProps = {
+  dialogProps: ReturnType<typeof useDialog>["dialogProps"];
+};
 
-export const LoginDialog: FC<LoginDialogProps> = ({ dialogProps, handleSubmit }) => {
+export const LoginDialog = memo(function ({ dialogProps }: LoginDialogProps) {
+  const setError = useSetAtom(globalErrorAtom);
+  const { setUser } = useUser();
   const formContext = useForm({ defaultValues: defaultLoginFormValues });
 
+  const reset = useMemo(() => formContext.reset, [formContext?.reset]);
+
+  const onSuccess: SubmitHandler<LoginFormValues> = useCallback(
+    (data, event) => {
+      event?.preventDefault();
+      event?.stopPropagation();
+
+      console.log(event);
+      setUser({ name: data.username, isActive: true }); // Update User (and/or other business logic)
+      reset(); // reset form
+      setError({
+        // Signal Success!
+        message: <>Hello {data.username}!</>,
+        title: "Successful Login!",
+        severity: "success",
+        icon: <PersonIcon sx={{ fontSize: 35 }} />,
+      });
+      dialogProps?.onClose();
+    },
+    [setUser, setError, dialogProps, reset],
+  );
+
   return (
     <FormDialog
       {...dialogProps}
-      formProps={{ onSuccess: handleSubmit, formContext, onError: (e) => console.log(e) }}
+      persistKey={formKey}
+      formProps={{ onSuccess, formContext }}
       title={"Basic Persist Form Dialog Test"}
       titleProps={{ variant: "h5", textAlign: "center" }}
       actions={<FormDialogActions resetProps={{ formKey }} submitProps={{ maxAttempts: 3 }} />}
     >
-      <PersistForm formName={formKey}>
-        <LoginFormBase name={formKey} columnCount={2} />
-      </PersistForm>
+      <LoginFormBase columnCount={2} />
     </FormDialog>
   );
-};
+});
+
+LoginDialog.displayName = "LoginDialog";
+
+
 ```

package/dist/components/buttons/FormSubmitButton.d.ts

@@ -14,7 +14,7 @@ export type FormSubmitButtonProps = Omit<LoadingButtonProps, "onClick"> & {
     maxAttempts?: number;
 };
 /**
- * A submit button for forms with loading state, attempt tracking and form context awareness
+ * A "submit button" for forms with loading state, attempt tracking and form context awareness
  *
  * This component extends the LoadingButton with form-specific features:
  * - Automatically displays loading state during form submission

package/dist/components/dialogs/BaseDialog.d.ts

@@ -9,12 +9,12 @@ export type BaseDialogProps = BlackoutDialogProps & {
     title?: ReactNode;
     /**
      * Props passed to the DialogTitle component
-     * Only applied when title is provided
+     * Only applied when the title is provided
      */
     titleProps?: DialogTitleProps;
     /**
      * Props passed to the DialogContent component
-     * Only applied when children is provided
+     * Only applied when children are provided
      */
     contentProps?: DialogContentProps;
     /**
@@ -24,7 +24,7 @@ export type BaseDialogProps = BlackoutDialogProps & {
     actions?: ReactNode;
     /**
      * Props passed to the DialogActions component
-     * Only applied when actions is provided
+     * Only applied when actions are provided
      */
     actionsProps?: DialogActionsProps;
     /**

package/dist/components/dialogs/FormDialog.d.ts

@@ -1,15 +1,10 @@
 import { type BaseDialogProps } from "./BaseDialog";
-import { type FieldValues, type FormContainerProps } from "react-hook-form-mui";
+import { CommonFormProps } from "../forms/PaperForm";
+import { type FieldValues } from "react-hook-form-mui";
 /**
  * Props for the FormDialog component
  */
-export type FormDialogProps<T extends FieldValues> = Omit<BaseDialogProps, "PaperComponent"> & {
-    /**
-     * Form methods from useForm hook
-     * Establish the form context for child components
-     */
-    formProps: FormContainerProps<T>;
-};
+export type FormDialogProps<T extends FieldValues> = Omit<BaseDialogProps, "PaperComponent"> & CommonFormProps<T>;
 /**
  * A dialog component specialized for forms with integrated context providers
  *
@@ -31,4 +26,7 @@ export type FormDialogProps<T extends FieldValues> = Omit<BaseDialogProps, "Pape
  * - useFormDialog() - Access dialog controls and state
  *
  */
-export declare const FormDialog: <T extends FieldValues>({ formProps, children, open, onClose, ...dialogProps }: FormDialogProps<T>) => import("react/jsx-runtime").JSX.Element;
+export declare const FormDialog: {
+    <T extends FieldValues>({ formProps, children, open, onClose, persistKey, ...dialogProps }: FormDialogProps<T>): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/components/dialogs/FormDialogActions.d.ts

@@ -16,7 +16,7 @@ export type FormDialogActionsProps = Partial<PropsWithChildren> & {
      */
     resetProps?: FormResetButtonProps;
     /**
-     * Props to customize the submit button
+     * Props to customize the "submit button"
      */
     submitProps?: FormSubmitButtonProps;
     /**

package/dist/components/forms/PaperForm.d.ts

@@ -1,15 +1,23 @@
 import { type PaperProps } from "@mui/material";
 import { type FieldValues, type FormContainerProps } from "react-hook-form-mui";
-/**
- * Props for the PaperForm component
- */
-export type PaperFormProps<T extends FieldValues> = PaperProps & {
+export type CommonFormProps<T extends FieldValues> = {
     /**
      * Props to configure the form container
-     * Includes settings for form state, validation, and submission handling
+     * This includes settings for form state, validation, and submission handling
      */
     formProps: FormContainerProps<T>;
+    /**
+     * Optional key to use for form state persistence
+     * When provided, the form state will be persisted in
+     * session storage with a fallback to local storage (TODO: make configurable)
+     * and restored on form reload/mount.
+     */
+    persistKey?: string;
 };
+/**
+ * Props for the PaperForm component
+ */
+export type PaperFormProps<T extends FieldValues> = PaperProps & CommonFormProps<T>;
 /**
  * A component that combines a Material UI Paper with a form container
  *
@@ -56,4 +64,4 @@ export type PaperFormProps<T extends FieldValues> = PaperProps & {
  *
  * @template T - The type of form values being handled
  */
-export declare const PaperForm: <T extends FieldValues>({ children, formProps, ...paperProps }: PaperFormProps<T>) => import("react/jsx-runtime").JSX.Element;
+export declare const PaperForm: <T extends FieldValues>({ children, persistKey, formProps, ...paperProps }: PaperFormProps<T>) => import("react/jsx-runtime").JSX.Element;

package/dist/components/forms/PersistForm.d.ts

@@ -1,4 +1,4 @@
-import type { FC, PropsWithChildren } from "react";
+import { type PropsWithChildren } from "react";
 /**
  * Props for the PersistForm component
  */
@@ -50,4 +50,4 @@ export interface PersistFormProps extends PropsWithChildren {
  *   </PersistForm>
  * </FormDialog>
  */
-export declare const PersistForm: FC<PersistFormProps>;
+export declare const PersistForm: import("react").NamedExoticComponent<PersistFormProps>;

package/dist/hooks/index.d.ts

@@ -1,5 +1,5 @@
 export * from "./useFormDialog";
 export * from "./useMaxAttempts";
-export * from "./usePersistedForm";
+export * from "./usePersistForm";
 export * from "./useOnMount";
 export * from "./useDialog";

package/dist/hooks/useDialog.d.ts

@@ -1,19 +1,20 @@
-import { DialogProps } from "@mui/material";
+import { MouseEvent } from "react";
 export interface UseDialogProps {
     /** Initial open state of the dialog */
     open?: boolean;
-    /** Additional props to spread onto the dialog component */
-    dialogProps?: Omit<DialogProps, "open" | "onClose">;
+    /** Always keep the children in the DOM. */
+    keepMounted?: boolean;
 }
-export interface UseDialogReturn extends Omit<DialogProps, "open" | "onClose"> {
+export interface UseDialogReturn {
     /** Function to close the dialog */
     closeDialog: () => void;
     /** Function to open the dialog */
-    openDialog: () => void;
+    openDialog: (e?: MouseEvent) => void;
     /** Props to spread onto the dialog component */
-    dialogProps: DialogProps & {
+    dialogProps: {
         open: boolean;
         onClose: () => void;
+        keepMounted: boolean;
     };
 }
 /**
@@ -23,6 +24,8 @@ export interface UseDialogReturn extends Omit<DialogProps, "open" | "onClose"> {
  * functions to open and close the dialog, along with props that can be
  * spread onto a Material-UI Dialog component.
  *
+ * Restores focus to the opening element, but only after the dialog has fully closed.
+ *
  * @example
  * // Basic usage
  * const { openDialog, closeDialog, dialogProps } = useDialog();
@@ -35,7 +38,6 @@ export interface UseDialogReturn extends Omit<DialogProps, "open" | "onClose"> {
  * // With initial configuration
  * const { dialogProps } = useDialog({ keepMounted: true});
  *
- *
  * @param props - Optional configuration options
  */
 export declare const useDialog: (props?: UseDialogProps) => UseDialogReturn;

package/dist/hooks/useFormDialog.d.ts

@@ -2,7 +2,7 @@
  * Hook for accessing the FormDialog context values and functions
  *
  * This hook provides access to the form dialog state and controls managed by
- * the FormDialogProvider. It allows components to interact with dialog state,
+ * the FormDialogProvider. It allows components to interact with the dialog state,
  * including open/close status and form-wide disabled state.
  *
  * The context provides:

package/dist/hooks/usePersistForm.d.ts

@@ -0,0 +1,29 @@
+import { FieldValues, UseFormReturn } from "react-hook-form-mui";
+export type PersistedFormProviderProps<T extends FieldValues> = {
+    /**
+     * A unique key for the form
+     */
+    formName: string | undefined;
+    /**
+     * Represents the context of a form, which is used to manage the state and actions of the form.
+     * The context is typically provided by a form management library and used to handle form inputs,
+     * validation, and submission.
+     */
+    formContext: UseFormReturn<T, any, T> | UseFormReturn<T> | undefined;
+};
+/**
+ * Hook that enables form state persistence across sessions
+ *
+ * This hook connects a form to persistent storage (e.g., sessionStorage)
+ * allowing form values to be preserved when navigating away and returning.
+ * It works by watching form changes and syncing with a zustand store.
+ *
+ * Key features:
+ * - Persists form values during navigation or page reloads
+ * - Automatically restores saved values when form is rendered
+ * - Debounced updates to avoid excessive storage operations
+ * - Only saves changed fields, not the entire form state
+ * - Automatically clears storage when form values match defaults
+ *
+ */
+export declare const usePersistForm: <T extends FieldValues>({ formName, formContext }: PersistedFormProviderProps<T>) => void;

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export * from "./components";
-export { usePersistedForm, useFormDialog, useDialog } from "./hooks";
+export { usePersistForm, useFormDialog, useDialog } from "./hooks";
 export { FormDialogProvider } from "./state/FormDialogProvider";