# 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