doc: write documentation for useUnsavedFormChanges

pages/hooks/_meta.json

@@ -11,5 +11,6 @@
   "use-persistent-state": "usePersistentState",
   "use-query-params": "useQueryParams",
   "use-timeout": "useTimeout",
+  "use-unsaved-form-changes": "useUnsavedFormChanges",
   "use-url": "useUrl"
 }

pages/hooks/use-unsaved-form-changes.mdx

@@ -0,0 +1,85 @@
+# useUnsavedFormChanges
+
+<h3 className="mt-4 text-xl font-normal text-gray-400">A custom hook to manage unsaved form changes and warn users before leaving the page.</h3>
+
+## Add hook
+
+Create a file `use-unsaved-form-changes.ts` and copy & paste the code from [useUnsavedFormChanges](/hooks/use-unsaved-form-changes#hook).
+
+## Usage
+
+```tsx {3,6}
+
+import React from 'react';
+import { useUnsavedFormChanges } from './hooks/use-unsaved-form-changes';
+
+function App() {
+    const { isFormChanged, setFormChanged } = useUnsavedFormChanges();
+
+    const handleChange = () => {
+        setFormChanged(true);
+    };
+
+    const handleSave = () => {
+        setFormChanged(false);
+    };
+
+    return (
+        <div>
+            <h1>useUnsavedFormChanges Example</h1>
+            <form>
+                <input type="text" onChange={handleChange} />
+                <button type="button" onClick={handleSave}>Save</button>
+            </form>
+            {isFormChanged && <p>You have unsaved changes!</p>}
+        </div>
+    );
+}
+
+export default App;
+
+```
+
+## Hook
+
+```tsx
+
+import { useEffect, useState } from 'react';
+
+export function useUnsavedFormChanges() {
+    const [isFormChanged, setIsFormChanged] = useState(false);
+
+    const setFormChanged = (value: boolean) => {
+        setIsFormChanged(value);
+    };
+
+    useEffect(() => {
+        const handleBeforeUnload = (event: { returnValue: string }) => {
+            if (isFormChanged) {
+                const confirmationMessage = 'You have unsaved changes. Are you sure you want to leave?';
+                event.returnValue = confirmationMessage;
+                return confirmationMessage;
+            }
+        };
+
+        window.addEventListener('beforeunload', handleBeforeUnload);
+
+        return () => {
+            window.removeEventListener('beforeunload', handleBeforeUnload);
+        };
+    }, [isFormChanged]);
+
+    return { isFormChanged, setFormChanged };
+}
+
+```
+
+## API
+
+<h1 className='text-xl font-medium mt-6'>Returns</h1>
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| `isFormChanged` | `boolean` | Indicates whether the form has unsaved changes. |
+| `setFormChanged` | `(value: boolean) => void` | A function to set the `isFormChanged` state. |
+

theme.config.jsx

@@ -76,6 +76,7 @@ const config = {
             title === "useUrl" ||
             title === "useEnv" ||
             title === "useMouse" ||
+            title === "useUnsavedFormChanges" ||
             title === "useCookie") && (
             <Badge className=" absolute -right-[0.5em] bg-transparent border-lime-400 text-lime-500 px-[0.5em] hover:bg-transparent">
               New