@delightui/components 0.1.105 → 0.1.107

package/docs/components/molecules/useModal.md

@@ -0,0 +1,379 @@
+# useModal
+
+## Description
+
+A React hook that provides programmatic modal management with automatic ID generation and simplified modal state handling. The useModal hook takes a modal component as a parameter and returns functions to open and close that specific modal, along with automatic unique identifier generation for each modal instance.
+
+## Aliases
+
+- useModal
+- Modal Hook
+- Modal Manager
+
+## Hook Signature
+
+```tsx
+function useModal<T extends ModalComponentProps>(
+  Component: React.ComponentType<T>
+): UseModalReturn<T>
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `Component` | `React.ComponentType<T>` | Yes | Modal component that extends ModalComponentProps |
+
+## Return Value
+
+Returns an object with the following properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `openModal` | `(props: T) => void` | Function to open the modal with specified props |
+| `closeModal` | `() => void` | Function to close the modal instance |
+| `modalId` | `string` | Unique identifier for this modal instance |
+
+## Requirements
+
+### ModalComponentProps Interface
+
+Modal components used with `useModal` must extend the `ModalComponentProps` interface:
+
+```tsx
+interface ModalComponentProps {
+  show?: boolean;
+  onCancel?: () => void;
+}
+```
+
+The hook automatically provides these props:
+- `show`: Set to `true` when modal is opened
+- `onCancel`: Function that closes the modal and calls the original `onCancel` if provided
+
+## Examples
+
+### Basic Usage
+
+```tsx
+import React from 'react';
+import { Modal, Button, Text, useModal } from '@delightui/components';
+
+// Define your modal component
+const AlertModal = ({ show, onCancel, title, message }) => (
+  <Modal show={show} onHide={onCancel}>
+    <Text type="Heading4">{title}</Text>
+    <Text>{message}</Text>
+  </Modal>
+);
+
+function MyComponent() {
+  const alertModal = useModal(AlertModal);
+
+  const showAlert = () => {
+    alertModal.openModal({
+      title: 'Success!',
+      message: 'Your action was completed successfully.'
+    });
+  };
+
+  return (
+    <Button onClick={showAlert}>
+      Show Alert
+    </Button>
+  );
+}
+```
+
+### Confirmation Modal
+
+```tsx
+import { Modal, Button, Text, useModal } from '@delightui/components';
+
+const ConfirmationModal = ({ show, onCancel, title, message, onConfirm }) => (
+  <Modal 
+    show={show} 
+    onHide={onCancel}
+    footer={
+      <div style={{ display: 'flex', gap: '8px' }}>
+        <Button type="Outlined" onClick={onCancel}>Cancel</Button>
+        <Button style="Primary" onClick={onConfirm}>Confirm</Button>
+      </div>
+    }
+  >
+    <Text type="Heading4">{title}</Text>
+    <Text>{message}</Text>
+  </Modal>
+);
+
+function DeleteButton() {
+  const confirmModal = useModal(ConfirmationModal);
+
+  const handleDelete = () => {
+    confirmModal.openModal({
+      title: 'Delete Item',
+      message: 'Are you sure you want to delete this item? This action cannot be undone.',
+      onConfirm: () => {
+        // Perform delete action
+        console.log('Item deleted');
+        confirmModal.closeModal();
+      }
+    });
+  };
+
+  return (
+    <Button style="Destructive" onClick={handleDelete}>
+      Delete Item
+    </Button>
+  );
+}
+```
+
+### Form Modal
+
+```tsx
+import { Modal, Form, FormField, Input, Button, useModal } from '@delightui/components';
+
+const UserFormModal = ({ show, onCancel, onSubmit, initialData }) => {
+  const handleSubmit = (formData) => {
+    onSubmit(formData);
+    onCancel(); // Close modal after submission
+  };
+
+  return (
+    <Modal
+      show={show}
+      onHide={onCancel}
+      size="Medium"
+      header={<Text type="Heading4">Edit User</Text>}
+    >
+      <Form onSubmit={handleSubmit} initialValues={initialData}>
+        <FormField name="name" label="Name" required>
+          <Input placeholder="Enter name" />
+        </FormField>
+        
+        <FormField name="email" label="Email" required>
+          <Input type="email" placeholder="Enter email" />
+        </FormField>
+        
+        <div style={{ display: 'flex', gap: '8px', marginTop: '16px' }}>
+          <Button type="Outlined" onClick={onCancel}>
+            Cancel
+          </Button>
+          <Button actionType="submit">
+            Save Changes
+          </Button>
+        </div>
+      </Form>
+    </Modal>
+  );
+};
+
+function UserList() {
+  const userModal = useModal(UserFormModal);
+
+  const editUser = (user) => {
+    userModal.openModal({
+      initialData: user,
+      onSubmit: (formData) => {
+        console.log('User updated:', formData);
+        // Handle form submission
+      }
+    });
+  };
+
+  return (
+    <Button onClick={() => editUser({ name: 'John', email: 'john@example.com' })}>
+      Edit User
+    </Button>
+  );
+}
+```
+
+### Multiple Modal Types
+
+```tsx
+import { useModal } from '@delightui/components';
+
+function Dashboard() {
+  const alertModal = useModal(AlertModal);
+  const confirmModal = useModal(ConfirmationModal);
+  const formModal = useModal(UserFormModal);
+
+  return (
+    <div>
+      <Button onClick={() => alertModal.openModal({
+        title: 'Info',
+        message: 'This is an information message.'
+      })}>
+        Show Info
+      </Button>
+      
+      <Button onClick={() => confirmModal.openModal({
+        title: 'Confirm Action',
+        message: 'Are you sure?',
+        onConfirm: () => console.log('Confirmed')
+      })}>
+        Confirm Action
+      </Button>
+      
+      <Button onClick={() => formModal.openModal({
+        onSubmit: (data) => console.log('Form data:', data)
+      })}>
+        Open Form
+      </Button>
+    </div>
+  );
+}
+```
+
+### Custom Modal with Complex State
+
+```tsx
+const SettingsModal = ({ show, onCancel, settings, onSave }) => {
+  const [localSettings, setLocalSettings] = useState(settings);
+
+  useEffect(() => {
+    setLocalSettings(settings);
+  }, [settings]);
+
+  const handleSave = () => {
+    onSave(localSettings);
+    onCancel();
+  };
+
+  return (
+    <Modal
+      show={show}
+      onHide={onCancel}
+      size="Large"
+      header={<Text type="Heading3">Settings</Text>}
+      footer={
+        <div>
+          <Button type="Outlined" onClick={onCancel}>Cancel</Button>
+          <Button onClick={handleSave}>Save Settings</Button>
+        </div>
+      }
+    >
+      {/* Settings form content */}
+      <div>
+        <h4>Notification Settings</h4>
+        <label>
+          <input 
+            type="checkbox" 
+            checked={localSettings.notifications}
+            onChange={(e) => setLocalSettings(prev => ({
+              ...prev,
+              notifications: e.target.checked
+            }))}
+          />
+          Enable notifications
+        </label>
+      </div>
+    </Modal>
+  );
+};
+
+function SettingsPage() {
+  const settingsModal = useModal(SettingsModal);
+  const [userSettings, setUserSettings] = useState({
+    notifications: true,
+    theme: 'light'
+  });
+
+  const openSettings = () => {
+    settingsModal.openModal({
+      settings: userSettings,
+      onSave: (newSettings) => {
+        setUserSettings(newSettings);
+        console.log('Settings saved:', newSettings);
+      }
+    });
+  };
+
+  return (
+    <Button onClick={openSettings}>
+      Open Settings
+    </Button>
+  );
+}
+```
+
+## TypeScript Support
+
+The hook is fully typed and provides excellent TypeScript support:
+
+```tsx
+interface MyModalProps extends ModalComponentProps {
+  title: string;
+  count: number;
+  onAction: (value: string) => void;
+}
+
+const MyModal: React.FC<MyModalProps> = ({ show, onCancel, title, count, onAction }) => {
+  // Modal implementation
+};
+
+function MyComponent() {
+  const modal = useModal(MyModal);
+  
+  // TypeScript will enforce correct prop types
+  modal.openModal({
+    title: "Required string",     // ✅ Required
+    count: 42,                   // ✅ Required number
+    onAction: (val) => {...}     // ✅ Required function
+    // Missing any required prop will cause TypeScript error
+  });
+}
+```
+
+## Best Practices
+
+1. **Create reusable modal components** that extend `ModalComponentProps`
+2. **Use one hook per modal type** for better organization
+3. **Handle async operations** within modal components or callbacks
+4. **Always provide meaningful prop types** for better TypeScript support
+5. **Keep modal logic separate** from business logic for better testability
+
+## Common Patterns
+
+### Loading States
+
+```tsx
+const LoadingModal = ({ show, onCancel, isLoading, message }) => (
+  <Modal show={show} onHide={!isLoading ? onCancel : undefined}>
+    {isLoading ? (
+      <div>
+        <Spinner />
+        <Text>Loading...</Text>
+      </div>
+    ) : (
+      <Text>{message}</Text>
+    )}
+  </Modal>
+);
+```
+
+### Conditional Modal Content
+
+```tsx
+const DynamicModal = ({ show, onCancel, mode, data }) => (
+  <Modal show={show} onHide={onCancel}>
+    {mode === 'view' && <ViewContent data={data} />}
+    {mode === 'edit' && <EditContent data={data} />}
+    {mode === 'delete' && <DeleteConfirmation data={data} />}
+  </Modal>
+);
+```
+
+## Requirements
+
+- Must be used within a `ModalProvider`
+- Modal components must extend `ModalComponentProps`
+- Requires React 18+ for `useId` hook support
+
+## Related
+
+- **[ModalProvider](./ModalProvider.md)** - Context provider for modal state
+- **[Modal](./Modal.md)** - Base modal component
+- **[ModalComponentProps](./Modal.md#modalcomponentprops)** - Required interface for modal components

package/docs/components/organisms/Dropzone.md

@@ -0,0 +1,346 @@
+# Dropzone
+
+## Description
+
+A comprehensive file upload component with drag-and-drop functionality. The Dropzone component provides an intuitive interface for users to upload files either by dragging and dropping them onto the designated area or by clicking to open a file dialog. It supports file type restrictions, size limits, and multiple file uploads with customizable states for empty, loading, and uploaded scenarios.
+
+## Aliases
+
+- Dropzone
+- File Upload
+- File Drop
+- Upload Area
+
+## Props Breakdown
+
+**Extends:** `ControlledFormComponentProps<File[]>`
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `empty` | `ReactNode` | - | No | Content to display when the dropzone is empty |
+| `loading` | `ReactNode` | - | No | Content to display during file upload/processing |
+| `uploaded` | `ReactNode` | - | No | Content to display when files are uploaded |
+| `accept` | `{ [key: string]: readonly string[] }` | - | No | Accepted file types based on mime type |
+| `maxSize` | `number` | - | No | Maximum file size in bytes |
+| `maxFiles` | `number` | `1` | No | Maximum number of files to upload |
+| `onFilesReset` | `() => void` | - | No | Callback when files are reset |
+| `className` | `string` | - | No | Additional CSS class names |
+| `initialValue` | `File[]` | - | No | Initial files value |
+| `value` | `File[]` | - | No | Current files value |
+| `onValueChange` | `(files: File[]) => void` | - | No | Callback when files change |
+| `disabled` | `boolean` | `false` | No | Whether the dropzone is disabled |
+| `required` | `boolean` | `false` | No | Whether file selection is required |
+| `invalid` | `boolean` | `false` | No | Whether the current state is invalid |
+| `id` | `string` | - | No | ID for the dropzone |
+
+Plus all standard HTML div attributes (aria-*, data-*, etc.).
+
+## Examples
+
+### Basic Dropzone
+
+```tsx
+import { Dropzone } from '@delightui/components';
+
+function BasicDropzoneExample() {
+  const [files, setFiles] = useState<File[]>([]);
+
+  return (
+    <Dropzone
+      value={files}
+      onValueChange={setFiles}
+      maxFiles={1}
+      accept={{
+        'image/*': ['.jpg', '.jpeg', '.png', '.gif']
+      }}
+    />
+  );
+}
+```
+
+### Custom States
+
+```tsx
+import { Dropzone, Text, Spinner, Button } from '@delightui/components';
+
+function CustomStatesExample() {
+  const [files, setFiles] = useState<File[]>([]);
+  const [isUploading, setIsUploading] = useState(false);
+
+  const handleUpload = async () => {
+    setIsUploading(true);
+    // Simulate upload
+    await new Promise(resolve => setTimeout(resolve, 2000));
+    setIsUploading(false);
+  };
+
+  return (
+    <Dropzone
+      value={files}
+      onValueChange={setFiles}
+      empty={
+        <div style={{ textAlign: 'center', padding: '40px' }}>
+          <Text size="large">Drop files here or click to upload</Text>
+          <Text size="small" color="secondary">
+            Supports JPG, PNG, GIF up to 10MB
+          </Text>
+        </div>
+      }
+      loading={
+        <div style={{ textAlign: 'center', padding: '40px' }}>
+          <Spinner />
+          <Text>Uploading files...</Text>
+        </div>
+      }
+      uploaded={
+        <div style={{ textAlign: 'center', padding: '40px' }}>
+          <Text color="success">✓ Files uploaded successfully</Text>
+          <Button onClick={() => setFiles([])}>Upload More</Button>
+        </div>
+      }
+      accept={{
+        'image/*': ['.jpg', '.jpeg', '.png', '.gif']
+      }}
+      maxSize={10 * 1024 * 1024} // 10MB
+      maxFiles={5}
+    />
+  );
+}
+```
+
+### Multiple File Upload
+
+```tsx
+import { Dropzone, Text } from '@delightui/components';
+
+function MultipleFileExample() {
+  const [files, setFiles] = useState<File[]>([]);
+
+  const handleFilesReset = () => {
+    setFiles([]);
+    console.log('Files reset');
+  };
+
+  return (
+    <div>
+      <Dropzone
+        value={files}
+        onValueChange={setFiles}
+        onFilesReset={handleFilesReset}
+        maxFiles={10}
+        accept={{
+          'image/*': ['.jpg', '.jpeg', '.png'],
+          'application/pdf': ['.pdf'],
+          'text/*': ['.txt', '.csv']
+        }}
+        maxSize={5 * 1024 * 1024} // 5MB per file
+      />
+      
+      {files.length > 0 && (
+        <div style={{ marginTop: '16px' }}>
+          <Text>Selected files: {files.length}</Text>
+          {files.map((file, index) => (
+            <Text key={index} size="small">
+              {file.name} ({(file.size / 1024).toFixed(1)} KB)
+            </Text>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### Form Integration
+
+```tsx
+import { Form, FormField, Dropzone, Button } from '@delightui/components';
+
+function FormDropzoneExample() {
+  const handleSubmit = (data: any) => {
+    console.log('Form submitted with files:', data.documents);
+  };
+
+  return (
+    <Form onSubmit={handleSubmit}>
+      <FormField
+        name="documents"
+        label="Upload Documents"
+        required
+        message="Please upload at least one document"
+      >
+        <Dropzone
+          accept={{
+            'application/pdf': ['.pdf'],
+            'application/msword': ['.doc'],
+            'application/vnd.openxmlformats-officedocument.wordprocessingml.document': ['.docx']
+          }}
+          maxSize={20 * 1024 * 1024} // 20MB
+          maxFiles={3}
+        />
+      </FormField>
+
+      <Button actionType="submit">Submit Documents</Button>
+    </Form>
+  );
+}
+```
+
+### Image Upload with Preview
+
+```tsx
+import { Dropzone, Text, Image } from '@delightui/components';
+
+function ImageUploadExample() {
+  const [files, setFiles] = useState<File[]>([]);
+  const [previews, setPreviews] = useState<string[]>([]);
+
+  useEffect(() => {
+    // Create preview URLs for images
+    const urls = files.map(file => {
+      if (file.type.startsWith('image/')) {
+        return URL.createObjectURL(file);
+      }
+      return null;
+    }).filter(Boolean) as string[];
+
+    setPreviews(urls);
+
+    // Cleanup URLs on unmount
+    return () => {
+      urls.forEach(url => URL.revokeObjectURL(url));
+    };
+  }, [files]);
+
+  return (
+    <div>
+      <Dropzone
+        value={files}
+        onValueChange={setFiles}
+        accept={{
+          'image/*': ['.jpg', '.jpeg', '.png', '.gif', '.webp']
+        }}
+        maxSize={5 * 1024 * 1024}
+        maxFiles={1}
+        uploaded={
+          previews.length > 0 ? (
+            <div style={{ textAlign: 'center', padding: '20px' }}>
+              <Image
+                src={previews[0]}
+                alt="Preview"
+                width={200}
+                height={200}
+                fit="Crop"
+                style={{ borderRadius: '8px' }}
+              />
+              <Text>Image uploaded successfully</Text>
+            </div>
+          ) : undefined
+        }
+      />
+    </div>
+  );
+}
+```
+
+### Disabled State
+
+```tsx
+import { Dropzone, Text } from '@delightui/components';
+
+function DisabledDropzoneExample() {
+  return (
+    <Dropzone
+      disabled
+      empty={
+        <div style={{ textAlign: 'center', padding: '40px' }}>
+          <Text color="disabled">File upload is currently disabled</Text>
+        </div>
+      }
+    />
+  );
+}
+```
+
+### Custom Styling
+
+```tsx
+import { Dropzone, Text } from '@delightui/components';
+
+function CustomStyledDropzoneExample() {
+  const [files, setFiles] = useState<File[]>([]);
+
+  return (
+    <Dropzone
+      value={files}
+      onValueChange={setFiles}
+      className="custom-dropzone"
+      style={{
+        border: '2px dashed #007bff',
+        borderRadius: '12px',
+        backgroundColor: '#f8f9fa'
+      }}
+      empty={
+        <div style={{ 
+          textAlign: 'center', 
+          padding: '60px 20px',
+          color: '#007bff'
+        }}>
+          <Text size="large">📁 Drop your files here</Text>
+          <Text size="small">or click to browse</Text>
+        </div>
+      }
+    />
+  );
+}
+```
+
+### Error Handling
+
+```tsx
+import { Dropzone, Text } from '@delightui/components';
+
+function ErrorHandlingExample() {
+  const [files, setFiles] = useState<File[]>([]);
+  const [error, setError] = useState<string>('');
+
+  const handleFileChange = (newFiles: File[]) => {
+    setError('');
+    
+    // Validate files
+    const invalidFiles = newFiles.filter(file => {
+      if (file.size > 10 * 1024 * 1024) {
+        setError(`File "${file.name}" is too large. Maximum size is 10MB.`);
+        return true;
+      }
+      return false;
+    });
+
+    if (invalidFiles.length === 0) {
+      setFiles(newFiles);
+    }
+  };
+
+  return (
+    <div>
+      <Dropzone
+        value={files}
+        onValueChange={handleFileChange}
+        invalid={!!error}
+        accept={{
+          'image/*': ['.jpg', '.jpeg', '.png'],
+          'application/pdf': ['.pdf']
+        }}
+        maxSize={10 * 1024 * 1024}
+        maxFiles={3}
+      />
+      
+      {error && (
+        <Text color="error" size="small" style={{ marginTop: '8px' }}>
+          {error}
+        </Text>
+      )}
+    </div>
+  );
+}
+```