@undefine-ui/design-system 3.8.7 → 3.9.0

package/README.md

@@ -312,6 +312,82 @@ toast.promise(fetchData(), {
 - **Dark themed:** Consistent dark background with themed icons
 - **Positioned:** Top-right with expandable queue
 
+### File Upload (React Hook Form)
+
+Form-ready file upload component integrated with React Hook Form. Supports single and multiple file uploads with automatic form state management, deduplication, and lifecycle callbacks.
+
+**Usage:**
+
+```tsx
+import { Form, Field } from '@undefine-ui/design-system';
+import { useForm } from 'react-hook-form';
+
+const MyForm = () => {
+  const methods = useForm({
+    defaultValues: {
+      avatar: null,
+      documents: []
+    }
+  });
+
+  return (
+    <Form methods={methods} onSubmit={(data) => console.log(data)}>
+      {/* Single file upload */}
+      <Field.Upload name="avatar" helperText="Upload your profile picture" />
+
+      {/* Multiple files upload */}
+      <Field.Upload name="documents" multiple helperText="Upload multiple documents" />
+
+      {/* With lifecycle callbacks */}
+      <Field.Upload
+        name="photos"
+        multiple
+        onDropComplete={(files) => toast.success(`${files.length} files added`)}
+        onRemoveComplete={(file) => console.log('Removed:', file)}
+        onRemoveAllComplete={() => toast.info('All files cleared')}
+      />
+
+      {/* Custom accept types */}
+      <Field.Upload
+        name="resume"
+        accept={{
+          'application/pdf': ['.pdf'],
+          'application/msword': ['.doc', '.docx']
+        }}
+        helperText="PDF or Word documents only"
+      />
+    </Form>
+  );
+};
+```
+
+**Props:**
+
+- `name` - Form field name for react-hook-form (required)
+- `multiple` - Enable multiple file selection (default: `false`)
+- `helperText` - Helper text displayed below the upload area
+- `accept` - Accepted file types object (e.g., `{ 'image/*': [] }`)
+- `maxSize` - Maximum file size in bytes
+- `maxFiles` - Maximum number of files (for multiple mode)
+- `disabled` - Disable the upload area
+
+**Lifecycle Callbacks:**
+
+These callbacks are called **after** the internal form state is updated, allowing you to add side effects like notifications, analytics, or logging without breaking form integration:
+
+- `onDropComplete` - Called after files are added to form state `(files: File[]) => void`
+- `onDeleteComplete` - Called after a file is deleted from form state (single mode) `() => void`
+- `onRemoveComplete` - Called after a file is removed from form state (multiple mode) `(file: File | string) => void`
+- `onRemoveAllComplete` - Called after all files are removed from form state (multiple mode) `() => void`
+
+**Features:**
+
+- **Form integration:** Automatically syncs with react-hook-form state
+- **Validation:** Displays validation errors from react-hook-form
+- **Deduplication:** Prevents adding duplicate files in multiple mode
+- **Safe callbacks:** Lifecycle callbacks extend (not override) internal form logic
+- **Full control:** Use the base `Upload` component directly if you need to override behavior
+
 ### Date Pickers (React Hook Form)
 
 Form-ready date picker components integrated with React Hook Form. Includes `RHFDatePicker`, `RHFTimePicker`, and `RHFDateTimePicker` for seamless form state management.