@chris-c-brine/form-dialog 1.0.1

package/README.md

@@ -0,0 +1,325 @@
+# @chris-c-brine/form-dialog
+
+Easy Form Dialogs with a persistable state!
+
+A React component library that seamlessly integrates Material UI dialogs with React Hook Form, providing persistable form state, context-aware components, and simplified dialog management.
+
+## Installation
+
+This package is currently private and intended for restricted access use.
+
+```bash 
+npm install @chris-c-brine/form-dialog
+```
+
+## Dependencies
+This package has the following peer dependencies that need to be installed in your project:
+- @emotion/react: ^11.14.0
+- @emotion/styled: ^11.14.0
+- @mui/icons-material: ^7.1.0
+- @mui/material: ^7.1.0
+- lodash: ^4.17.21
+- react: ^19.1.0
+- react-dom: ^19.1.0
+- react-hook-form: ^7.56.2
+- react-hook-form-mui: ^7.6.0
+- zustand: ^5.0.4
+
+## Features
+
+- **Integrated Form Dialogs**: Combines Material UI dialogs with React Hook Form
+- **Persistable State**: Store form data across page refreshes using Zustand
+- **Simplified Workflow**: Streamlined API for common form dialog patterns
+- **Context-Aware Components**: Dialog components that share form state
+- **TypeScript Support**: Fully typed for a better developer experience
+- **Customizable UI**: Extends Material UI components
+
+## Known Issues
+- **Max Attempts & Persistence**: PersistForm does not yet support Max attempts
+- **A11Y on Form Dialog Close**: Blocked aria-hidden on an element because its descendant retained focus. The focus must not be hidden from assistive technology users. Avoid using aria-hidden on a focused element or its ancestor. Consider using the inert attribute instead, which will also prevent focus. For more details, see the aria-hidden section of the WAI-ARIA specification at https://w3c.github.io/aria/#aria-hidden.
+  Element with focus...
+- 
+
+```tsx
+// LoginFormBase.tsx
+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";
+
+export type NameProp = {name?: string; };
+export type LoginFormProps = NameProp & Pick<AutoGridProps, "columnCount">;
+
+const LoginFormBase = memo(function ({ name, columnCount = 1 }: LoginFormProps) {
+    const { disabled } = useFormDialog();
+
+    useEffect(() => formNameLog(name), [name]);
+
+    return (
+        <AutoGrid
+            columnCount={columnCount}
+            columnSpacing={2}
+            rowSpacing={1}
+            components={[
+                <UserName key={`${name}-username`} disabled={disabled} />,
+                <Password key={`${name}-password`} disabled={disabled} />,
+            ]}
+        />
+    );
+});
+
+LoginFormBase.displayName = "LoginForm";
+
+export default LoginFormBase;
+
+/**
+ * Inputs
+ */
+const UserName = memo(({ disabled }: Pick<PasswordElementProps, "disabled">) => (
+    <TextFieldElement
+        name="username"
+        label="Username"
+        required
+        autoFocus
+        autoComplete="off"
+        fullWidth
+        margin={"dense"}
+        size={"medium"}
+        disabled={disabled}
+        slotProps={{
+            inputLabel: { shrink: true },
+        }}
+    />
+));
+
+UserName.displayName = "UserName";
+
+const Password = function ({ disabled }: Pick<PasswordElementProps, "disabled">) {
+  const { setValue, getValues } = useFormContext();
+  const password = getValues("password");
+
+  useEffect(() => {
+    if (disabled && password !== "") {
+      setValue("passwordDisabled", "");
+    }
+  }, [disabled, setValue, password]);
+
+  return (
+    <PasswordElement
+      name={"passwordDisabled"}
+      label={"Password"}
+      fullWidth
+      required
+      autoComplete="off"
+      size="medium"
+      margin={"dense"}
+      disabled={disabled}
+      slotProps={{
+        inputLabel: { shrink: true },
+      }}
+      {...(disabled && { renderIcon: () => <></> })}
+    />
+  );
+};
+Password.displayName = "Password";
+```
+```tsx
+// LoginDialog.tsx
+import { FormDialog, FormDialogActions, type FormDialogProps,  PersistForm } from "@chris-c-brine/form-dialog";
+import { useMemo, type FC } from "react";
+import { useForm } from "react-hook-form-mui";
+import LoginFormBase from "../forms/LoginFormBase";
+import {
+    defaultLoginFormValues,
+    type LoginForm,
+    type SubmitLogin,
+} from "@pages/LoginPage/LoginPageConstants";
+import { useDialog } from "@hooks";
+import { devLog } from "@utils";
+
+const formKey = "dialog-login-form";
+
+/* Basic Form Dialog Test */
+type LoginDialogProps = Pick<ReturnType<typeof useDialog>, "dialogProps"> &
+    Pick<FormDialogProps<LoginForm>, "onClose"> & {
+    handleSubmit: SubmitLogin;
+};
+
+const LoginDialog: FC<LoginDialogProps> = ({ dialogProps, handleSubmit }) => {
+    const formContext = useForm({ defaultValues: defaultLoginFormValues });
+    const loginForm = useMemo(() => <LoginFormBase name={formKey} columnCount={2} />, []);
+
+    return (
+        <FormDialog
+            {...dialogProps}
+            formProps={{ onSuccess: handleSubmit, formContext, onError: devLog("Form Errors") }}
+            title={"Basic Form Dialog Test"}
+            titleProps={{ variant: "h5", textAlign: "center" }}
+            actions={<FormDialogActions resetProps={{ formKey }} submitProps={{ maxAttempts: 3 }} />}
+        >
+            <PersistForm formName={formKey}>{loginForm}</PersistForm>
+        </FormDialog>
+    );
+};
+
+LoginDialog.displayName = "LoginDialog";
+
+export default LoginDialog;
+```
+```tsx
+// LoginForm.tsx
+import { Lock as LockIcon } from "@mui/icons-material";
+import { Box, Typography, type TypographyProps } from "@mui/material";
+import { type SubmitLogin, defaultLoginFormValues } from "@pages/LoginPage/LoginPageConstants";
+import { devLog } from "@utils";
+import { merge } from "lodash";
+import type { FC, PropsWithChildren } from "react";
+import LoginFormBase from "./LoginFormBase";
+import { FormDialogActions, FormDialogProvider, PaperForm } from "@chris-c-brine/form-dialog";
+
+const AltIcon = () => <LockIcon sx={{ mr: 1, fontSize: 20 }} />;
+
+interface LoginFormProps extends PropsWithChildren {
+  onSuccess: SubmitLogin;
+}
+
+const LoginForm: FC<LoginFormProps> = ({ onSuccess, children }) => {
+  return (
+    <LoginPaperForm onSuccess={onSuccess}>
+      <Box px={2}>
+        {children}
+        <SecureLoginText />
+        <LoginFormBase name="page-form" columnCount={1} />
+      </Box>
+      <FormDialogActions
+        removeCancelButton={true}
+        gridProps={{ mt:3, mb:1,px:2 }}
+        submitProps={{
+          altIcon: <AltIcon />,
+          children: "Log In",
+          maxAttempts: 5,
+        }}
+      />
+    </LoginPaperForm>
+  );
+};
+
+export default LoginForm;
+
+const SecureLoginText: FC<TypographyProps> = (props) => {
+  const typographyProps = merge(
+    {
+      component: "h1",
+      variant: "h5",
+      sx: { marginBottom: "20px" },
+    },
+    props,
+  );
+  return <Typography {...typographyProps}>Secure Login</Typography>;
+};
+
+type LoginPaperFormProps = PropsWithChildren & {
+  onSuccess?: SubmitLogin;
+};
+
+const LoginPaperForm: FC<LoginPaperFormProps> = ({ children, onSuccess }) => {
+  return (
+    <FormDialogProvider>
+      <PaperForm
+        formProps={{
+          defaultValues: defaultLoginFormValues,
+          onSuccess,
+          onError: devLog("Form Errors"),
+        }}
+        elevation={3}
+        sx={{
+          padding: "20px",
+          marginTop: "50px",
+          textAlign: "center",
+        }}
+      >
+        {children}
+      </PaperForm>
+    </FormDialogProvider>
+  );
+};
+
+```
+```tsx
+// LoginPage.tsx
+import { useCallback, useEffect, useState, type FC, type PropsWithChildren } from "react";
+import { Container, IconButton } from "@mui/material";
+import { useUser } from "@features";
+import { useDialog } from "@chris-c-brine/form-dialog";
+import { useForm, type SubmitHandler } from "react-hook-form-mui";
+import { toast } from "react-toastify";
+import LoginDialog from "./components/dialogs/LoginDialog";
+import LoginForm from "./components/forms/LoginForm";
+import { Lock as LockIcon } from "@mui/icons-material";
+
+const defaultLoginFormValues = { username: "", password: "" };
+type SubmitLogin = SubmitHandler<typeof defaultLoginFormValues>;
+const LoginPage: FC = () => {
+  const { dialogProps, closeDialog, openDialog } = useDialog();
+  const { setUser } = useUser();
+  const [showDialog, setShowDialog] = useState(dialogProps.open);
+
+  useEffect(() => {
+    if (!showDialog && dialogProps.open) {
+      setShowDialog(true);
+    }
+  }, [dialogProps.open, showDialog]);
+
+  const formContext = useForm({ defaultValues: defaultLoginFormValues });
+  const onSuccess: SubmitLogin = useCallback(
+    (data, event) => {
+      event?.preventDefault(); // Stop default form submit
+      formContext.reset(); // Reset form
+      setUser({ name: data.username, isActive: true }); // Update User (and/or other business logic)
+      closeDialog(); // Close Dialog
+      toast.success("Error Dialog Test!"); // Signal success beyond just closing the dialog
+    },
+    [formContext, setUser, closeDialog],
+  );
+
+  return (
+    <LoginFormContainer>
+      <LoginForm onSuccess={onSuccess}>
+        <IconButton color="primary" onClick={openDialog} sx={{ py: 1 }}>
+          <LockIcon sx={{ fontSize: 50 }} />
+        </IconButton>
+      </LoginForm>
+      {showDialog && (
+        <LoginDialog dialogProps={dialogProps} handleSubmit={onSuccess} onClose={undefined} />
+      )}
+    </LoginFormContainer>
+  );
+};
+
+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>
+);
+```

package/dist/components/AutoGrid.d.ts

@@ -0,0 +1,12 @@
+import { type GridProps } from "@mui/material";
+import { type FC, type ReactNode } from "react";
+export type AutoGridProps = Omit<GridProps, "container" | "children"> & {
+    components?: ReactNode[];
+    columnCount?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+};
+/**
+ * Dev Note:
+ *  Be careful of transferring keys of children to the wrapper, Grid.
+ *  If not done correctly, it will cause React to discard the old tree and remount children components
+ */
+export declare const AutoGrid: FC<AutoGridProps>;

package/dist/components/BaseDialog.d.ts

@@ -0,0 +1,13 @@
+import type { FC, ReactNode } from "react";
+import { type BlackoutDialogProps } from "./BlackoutDialog";
+import type { DialogContentProps, DialogTitleProps, DialogActionsProps } from "@mui/material";
+export type BaseDialogProps = Omit<BlackoutDialogProps, "children" | "title" | "content"> & {
+    title?: ReactNode;
+    titleProps?: DialogTitleProps;
+    children?: ReactNode;
+    contentProps?: DialogContentProps;
+    actions?: ReactNode;
+    actionsProps?: DialogActionsProps;
+    closeButton?: ReactNode;
+};
+export declare const BaseDialog: FC<BaseDialogProps>;

package/dist/components/BlackoutDialog.d.ts

@@ -0,0 +1,23 @@
+import { type DialogProps } from "@mui/material";
+import { type FC, type PropsWithChildren } from "react";
+export type BlackoutDialogProps = DialogProps & Partial<PropsWithChildren> & {
+    /**
+     * An optional unique string identifier
+     * @default 'blackout-dialog'
+     */
+    id?: string;
+    /**
+     * Whether the dialog is currently visible.
+     * @default false
+     */
+    open: boolean;
+    /**
+     * Whether to apply a black overlay behind the dialog.
+     * @default false
+     */
+    blackout?: boolean;
+};
+/**
+ * A component for rendering a modal dialog with an optional blackout effect.
+ */
+export declare const BlackoutDialog: FC<BlackoutDialogProps>;

package/dist/components/FormDialog.d.ts

@@ -0,0 +1,11 @@
+import { type BaseDialogProps } from "./BaseDialog";
+import { type FieldValues, type FormContainerProps } from "react-hook-form-mui";
+/**
+ * Props for the FormDialog component. Inherits from BaseDialogProps and adds formProps.
+ * @param formProps - Props for the FormContainer component from react-hook-form-mui.
+ * @returns The FormDialog component.
+ */
+export type FormDialogProps<T extends FieldValues> = Omit<BaseDialogProps, "PaperComponent"> & {
+    formProps: FormContainerProps<T>;
+};
+export declare const FormDialog: <T extends FieldValues>({ formProps, children, open, onClose, ...dialogProps }: FormDialogProps<T>) => import("react/jsx-runtime").JSX.Element;

package/dist/components/FormDialogActions.d.ts

@@ -0,0 +1,15 @@
+import { GridProps } from "@mui/material";
+import type { FC, PropsWithChildren } from "react";
+import { type FormCancelButtonProps } from "./buttons/FormCancelButton";
+import { type FormResetButtonProps } from "./buttons/FormResetButton";
+import { FormSubmitButtonProps } from "./buttons/FormSubmitButton";
+export type FormDialogActionsProps = PropsWithChildren & {
+    cancelProps?: FormCancelButtonProps;
+    resetProps?: FormResetButtonProps;
+    submitProps?: FormSubmitButtonProps;
+    variant?: "icon" | "text" | "iconText";
+    removeCancelButton?: boolean;
+    removeResetButton?: boolean;
+    gridProps?: GridProps;
+};
+export declare const FormDialogActions: FC<FormDialogActionsProps>;

package/dist/components/GridSpacer.d.ts

@@ -0,0 +1,2 @@
+import type { FC } from "react";
+export declare const GridSpacer: FC;

package/dist/components/PaperForm.d.ts

@@ -0,0 +1,6 @@
+import { type PaperProps } from "@mui/material";
+import { type FieldValues, type FormContainerProps } from "react-hook-form-mui";
+export type PaperFormProps<T extends FieldValues> = PaperProps & {
+    formProps: FormContainerProps<T>;
+};
+export declare const PaperForm: <T extends FieldValues>({ children, formProps, ...paperProps }: PaperFormProps<T>) => import("react/jsx-runtime").JSX.Element;

package/dist/components/PersistForm.d.ts

@@ -0,0 +1,5 @@
+import type { FC, PropsWithChildren } from "react";
+export interface PersistFormProps extends PropsWithChildren {
+    formName: string;
+}
+export declare const PersistForm: FC<PersistFormProps>;

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

@@ -0,0 +1,5 @@
+import { type ButtonProps } from "@mui/material";
+export type FormCancelButtonProps = Omit<ButtonProps, "onClick"> & {
+    keepCount?: boolean;
+};
+export declare const FormCancelButton: import("react").NamedExoticComponent<object>;

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

@@ -0,0 +1,6 @@
+import { type ButtonProps } from "@mui/material";
+export type FormResetButtonProps = Omit<ButtonProps, "onClick"> & {
+    keepCount?: boolean;
+    formKey?: string;
+};
+export declare const FormResetButton: import("react").NamedExoticComponent<object>;

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

@@ -0,0 +1,9 @@
+import { type LoadingButtonProps } from "./LoadingButton";
+export type FormSubmitButtonProps = Omit<LoadingButtonProps, "onClick"> & {
+    showAttempts?: boolean;
+    maxAttempts?: number;
+};
+/**
+ * Form Submit Button
+ */
+export declare const FormSubmitButton: import("react").NamedExoticComponent<FormSubmitButtonProps>;

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

@@ -0,0 +1,8 @@
+import { type ButtonProps } from "@mui/material";
+import type { ReactNode } from "react";
+export type LoadingButtonProps = ButtonProps & {
+    loading?: boolean;
+    /** The icon displayed when not loading */
+    altIcon?: ReactNode;
+};
+export declare const LoadingButton: ({ children, loading, altIcon, ...props }: LoadingButtonProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,13 @@
+import type { FC, ReactNode } from "react";
+import { type BlackoutDialogProps } from "./BlackoutDialog";
+import type { DialogContentProps, DialogTitleProps, DialogActionsProps } from "@mui/material";
+export type BaseDialogProps = Omit<BlackoutDialogProps, "children" | "title" | "content"> & {
+    title?: ReactNode;
+    titleProps?: DialogTitleProps;
+    children?: ReactNode;
+    contentProps?: DialogContentProps;
+    actions?: ReactNode;
+    actionsProps?: DialogActionsProps;
+    closeButton?: ReactNode;
+};
+export declare const BaseDialog: FC<BaseDialogProps>;

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

@@ -0,0 +1,23 @@
+import { type DialogProps } from "@mui/material";
+import { type FC, type PropsWithChildren } from "react";
+export type BlackoutDialogProps = DialogProps & Partial<PropsWithChildren> & {
+    /**
+     * An optional unique string identifier
+     * @default 'blackout-dialog'
+     */
+    id?: string;
+    /**
+     * Whether the dialog is currently visible.
+     * @default false
+     */
+    open: boolean;
+    /**
+     * Whether to apply a black overlay behind the dialog.
+     * @default false
+     */
+    blackout?: boolean;
+};
+/**
+ * A component for rendering a modal dialog with an optional blackout effect.
+ */
+export declare const BlackoutDialog: FC<BlackoutDialogProps>;

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

@@ -0,0 +1,11 @@
+import { type BaseDialogProps } from "./BaseDialog";
+import { type FieldValues, type FormContainerProps } from "react-hook-form-mui";
+/**
+ * Props for the FormDialog component. Inherits from BaseDialogProps and adds formProps.
+ * @param formProps - Props for the FormContainer component from react-hook-form-mui.
+ * @returns The FormDialog component.
+ */
+export type FormDialogProps<T extends FieldValues> = Omit<BaseDialogProps, "PaperComponent"> & {
+    formProps: FormContainerProps<T>;
+};
+export declare const FormDialog: <T extends FieldValues>({ formProps, children, open, onClose, ...dialogProps }: FormDialogProps<T>) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,15 @@
+import { GridProps } from "@mui/material";
+import type { FC, PropsWithChildren } from "react";
+import { type FormCancelButtonProps } from "../buttons/FormCancelButton";
+import { type FormResetButtonProps } from "../buttons/FormResetButton";
+import { FormSubmitButtonProps } from "../buttons/FormSubmitButton";
+export type FormDialogActionsProps = PropsWithChildren & {
+    cancelProps?: FormCancelButtonProps;
+    resetProps?: FormResetButtonProps;
+    submitProps?: FormSubmitButtonProps;
+    variant?: "icon" | "text" | "iconText";
+    removeCancelButton?: boolean;
+    removeResetButton?: boolean;
+    gridProps?: GridProps;
+};
+export declare const FormDialogActions: FC<FormDialogActionsProps>;

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

@@ -0,0 +1,6 @@
+import { type PaperProps } from "@mui/material";
+import { type FieldValues, type FormContainerProps } from "react-hook-form-mui";
+export type PaperFormProps<T extends FieldValues> = PaperProps & {
+    formProps: FormContainerProps<T>;
+};
+export declare const PaperForm: <T extends FieldValues>({ children, formProps, ...paperProps }: PaperFormProps<T>) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,5 @@
+import type { FC, PropsWithChildren } from "react";
+export interface PersistFormProps extends PropsWithChildren {
+    formName: string;
+}
+export declare const PersistForm: FC<PersistFormProps>;

package/dist/components/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./dialogs/FormDialog";
+export * from "./dialogs/BaseDialog";
+export * from "./dialogs/BlackoutDialog";
+export * from "./forms/PaperForm";
+export * from "./forms/PersistForm";
+export * from "./buttons/FormCancelButton";
+export * from "./buttons/FormSubmitButton";
+export * from "./buttons/FormResetButton";
+export * from "./dialogs/FormDialogActions";
+export * from "./AutoGrid";

package/dist/hooks/index.d.ts

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

package/dist/hooks/useDialog.d.ts

@@ -0,0 +1,12 @@
+export interface UseDialogProps {
+    defaultOpen: boolean;
+}
+export declare const useDialog: (props?: UseDialogProps) => {
+    closeDialog: () => void;
+    openDialog: () => void;
+    dialogProps: {
+        open: boolean;
+        onClose: () => void;
+        keepMounted: boolean;
+    };
+};

package/dist/hooks/useFormDialog.d.ts

@@ -0,0 +1 @@
+export declare const useFormDialog: () => import("../state/FormDialogContext").FormDialogContextType;

package/dist/hooks/useMaxAttempts.d.ts

@@ -0,0 +1,5 @@
+type UseMaxAttemptProps = {
+    maxAttempts?: number;
+};
+export declare const useMaxAttempts: ({ maxAttempts }: UseMaxAttemptProps) => void;
+export {};

package/dist/hooks/useOnMount.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Runs a provided callback function once on the first component mount.
+ *
+ * @param callback - The function to run on first mount.
+ */
+export declare function useOnMount(callback: () => void): void;

package/dist/hooks/usePersistedForm.d.ts

@@ -0,0 +1,7 @@
+export interface PersistedFormProviderProps {
+    /**
+     * A unique key for the form
+     */
+    formName: string | undefined;
+}
+export declare const usePersistedForm: ({ formName }: PersistedFormProviderProps) => void;

package/dist/index.d.ts

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