# Modal

## Description

A modal dialog component that displays content in a layer above the main application interface. Provides flexible sizing options, customizable header and footer areas, backdrop controls, and accessibility features for creating overlay dialogs, confirmations, and forms.

## Aliases

- Modal
- Dialog
- Popup
- Overlay
- Lightbox

## Props Breakdown

**Extends:** Standalone interface (no HTML element inheritance)

| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `children` | `ReactNode` | - | Yes | The content rendered inside the modal |
| `size` | `'Small' \| 'Medium' \| 'Large'` | `'Medium'` | No | Size of the modal |
| `onHide` | `() => void` | - | No | Callback function invoked when modal is hidden |
| `show` | `boolean` | `false` | No | Controls modal visibility |
| `header` | `ReactNode` | - | No | Content rendered in the modal header |
| `footer` | `ReactNode` | - | No | Content rendered in the modal footer |
| `renderBackdrop` | `ReactNode` | - | No | Custom backdrop element |
| `backdrop` | `boolean` | `true` | No | Whether to display backdrop behind modal |
| `disableBackdropDismiss` | `boolean` | `false` | No | Disables dismissing modal by clicking backdrop |
| `component-variant` | `string` | - | No | Override styling variant |
| `className` | `string` | - | No | Additional CSS class names |

## Examples

### Basic Usage
```tsx
import { Modal, Button, Text, useModal } from '@delightui/components';

const SimpleModal = ({ show, onCancel, title, message }) => (
  <Modal show={show} onHide={onCancel}>
    <Text type="Heading4">{title}</Text>
    <Text>{message}</Text>
  </Modal>
);

function BasicExample() {
  const modal = useModal(SimpleModal);

  return (
    <Button onClick={() => modal.openModal({
      title: 'Welcome!',
      message: 'This is a simple modal with basic content.'
    })}>
      Open Modal
    </Button>
  );
}
```

### Modal Sizes
```tsx
import { Modal, Button, Text, useModal } from '@delightui/components';

const SizedModal = ({ show, onCancel, size, title, message }) => (
  <Modal show={show} onHide={onCancel} size={size}>
    <Text type={size === 'Small' ? 'Heading5' : size === 'Medium' ? 'Heading4' : 'Heading3'}>
      {title}
    </Text>
    <Text>{message}</Text>
  </Modal>
);

function SizesExample() {
  const smallModal = useModal(SizedModal);
  const mediumModal = useModal(SizedModal);
  const largeModal = useModal(SizedModal);

  return (
    <div className="modal-sizes">
      <Button onClick={() => smallModal.openModal({
        size: 'Small',
        title: 'Small Modal',
        message: 'This is a small modal for quick messages.'
      })}>
        Small Modal
      </Button>
      
      <Button onClick={() => mediumModal.openModal({
        size: 'Medium',
        title: 'Medium Modal',
        message: 'This is a medium modal with more content space.'
      })}>
        Medium Modal
      </Button>
      
      <Button onClick={() => largeModal.openModal({
        size: 'Large',
        title: 'Large Modal',
        message: 'This is a large modal for complex content and forms.'
      })}>
        Large Modal
      </Button>
    </div>
  );
}
```

### Modal with Header and Footer
```tsx
import { Modal, Button, Text, Icon, useModal } from '@delightui/components';

const ConfirmModal = ({ show, onCancel, onConfirm }) => {
  const header = (
    <div className="modal-header">
      <Text type="Heading4">Confirm Action</Text>
      <Button 
        type="Ghost" 
        onClick={onCancel}
        aria-label="Close modal"
      >
        <Icon icon="Close" />
      </Button>
    </div>
  );

  const footer = (
    <div className="modal-footer">
      <Button 
        type="Outlined" 
        onClick={onCancel}
      >
        Cancel
      </Button>
      <Button 
        style="Destructive"
        onClick={onConfirm}
      >
        Delete
      </Button>
    </div>
  );

  return (
    <Modal 
      show={show}
      onHide={onCancel}
      header={header}
      footer={footer}
    >
      <Text>
        Are you sure you want to delete this item? 
        This action cannot be undone.
      </Text>
    </Modal>
  );
};

function HeaderFooterExample() {
  const confirmModal = useModal(ConfirmModal);

  return (
    <Button onClick={() => confirmModal.openModal({
      onConfirm: () => {
        // Handle confirmation
        console.log('Item deleted');
        confirmModal.closeModal();
      }
    })}>
      Delete Item
    </Button>
  );
}
```

### Form Modal
```tsx
import { Modal, Form, FormField, Input, TextArea, Button, Text, useModal } from '@delightui/components';

const ProjectFormModal = ({ show, onCancel }) => {
  const handleSubmit = (values, setError) => {
    console.log('Form submitted:', values);
    onCancel();
  };

  const header = (
    <Text type="Heading4">Create New Project</Text>
  );

  return (
    <Modal 
      show={show}
      onHide={onCancel}
      size="Medium"
      header={header}
    >
      <Form onSubmit={handleSubmit}>
        <FormField name="projectName" label="Project Name" required>
          <Input placeholder="Enter project name" />
        </FormField>
        
        <FormField name="description" label="Description">
          <TextArea 
            placeholder="Project description..." 
            rows={3}
          />
        </FormField>
        
        <FormField name="category" label="Category" required>
          <Select>
            <Option value="web">Web Development</Option>
            <Option value="mobile">Mobile App</Option>
            <Option value="design">Design</Option>
          </Select>
        </FormField>
        
        <div className="modal-form-actions">
          <Button 
            type="Outlined" 
            onClick={onCancel}
          >
            Cancel
          </Button>
          <Button actionType="submit">
            Create Project
          </Button>
        </div>
      </Form>
    </Modal>
  );
};

function FormModalExample() {
  const projectModal = useModal(ProjectFormModal);

  return (
    <Button onClick={() => projectModal.openModal({})}>
      New Project
    </Button>
  );
}
```

### Confirmation Modal
```tsx
function ConfirmationModalExample() {
  const [showModal, setShowModal] = useState(false);
  const [loading, setLoading] = useState(false);

  const handleConfirm = async () => {
    setLoading(true);
    // Simulate API call
    await new Promise(resolve => setTimeout(resolve, 2000));
    setLoading(false);
    setShowModal(false);
  };

  return (
    <>
      <Button style="Destructive" onClick={() => setShowModal(true)}>
        Delete Account
      </Button>
      
      <Modal 
        show={showModal}
        onHide={() => setShowModal(false)}
        size="Small"
        disableBackdropDismiss={loading}
      >
        <div className="confirmation-modal">
          <Icon icon="Warning" className="warning-icon" />
          
          <Text type="Heading5">Delete Account</Text>
          
          <Text>
            This will permanently delete your account and all associated data. 
            This action cannot be undone.
          </Text>
          
          <div className="confirmation-actions">
            <Button 
              type="Outlined" 
              onClick={() => setShowModal(false)}
              disabled={loading}
            >
              Cancel
            </Button>
            <Button 
              style="Destructive"
              loading={loading}
              onClick={handleConfirm}
            >
              Delete Account
            </Button>
          </div>
        </div>
      </Modal>
    </>
  );
}
```

### Image Gallery Modal
```tsx
function ImageGalleryModalExample() {
  const [selectedImage, setSelectedImage] = useState(null);
  
  const images = [
    { src: '/image1.jpg', alt: 'Gallery Image 1' },
    { src: '/image2.jpg', alt: 'Gallery Image 2' },
    { src: '/image3.jpg', alt: 'Gallery Image 3' }
  ];

  return (
    <div className="image-gallery">
      {images.map((image, index) => (
        <Image 
          key={index}
          src={image.src}
          alt={image.alt}
          className="gallery-thumbnail"
          onClick={() => setSelectedImage(image)}
        />
      ))}
      
      <Modal 
        show={!!selectedImage}
        onHide={() => setSelectedImage(null)}
        size="Large"
        className="image-modal"
      >
        {selectedImage && (
          <>
            <div className="image-modal-header">
              <Button 
                type="Ghost"
                onClick={() => setSelectedImage(null)}
              >
                <Icon icon="Close" />
              </Button>
            </div>
            
            <div className="image-modal-content">
              <Image 
                src={selectedImage.src}
                alt={selectedImage.alt}
                fit="Fit"
              />
            </div>
          </>
        )}
      </Modal>
    </div>
  );
}
```

### Multi-step Modal
```tsx
function MultiStepModalExample() {
  const [showModal, setShowModal] = useState(false);
  const [currentStep, setCurrentStep] = useState(1);
  const totalSteps = 3;

  const nextStep = () => setCurrentStep(prev => Math.min(prev + 1, totalSteps));
  const prevStep = () => setCurrentStep(prev => Math.max(prev - 1, 1));
  
  const closeModal = () => {
    setShowModal(false);
    setCurrentStep(1);
  };

  const header = (
    <div className="multi-step-header">
      <Text type="Heading4">Setup Wizard</Text>
      <Text type="BodySmall">Step {currentStep} of {totalSteps}</Text>
    </div>
  );

  const footer = (
    <div className="multi-step-footer">
      <Button 
        type="Outlined"
        onClick={currentStep === 1 ? closeModal : prevStep}
      >
        {currentStep === 1 ? 'Cancel' : 'Previous'}
      </Button>
      
      <Button 
        onClick={currentStep === totalSteps ? closeModal : nextStep}
      >
        {currentStep === totalSteps ? 'Finish' : 'Next'}
      </Button>
    </div>
  );

  return (
    <>
      <Button onClick={() => setShowModal(true)}>
        Start Setup
      </Button>
      
      <Modal 
        show={showModal}
        onHide={closeModal}
        size="Medium"
        header={header}
        footer={footer}
        disableBackdropDismiss
      >
        <div className="step-content">
          {currentStep === 1 && (
            <div>
              <Text type="Heading5">Welcome</Text>
              <Text>Let's get you started with your account setup.</Text>
            </div>
          )}
          
          {currentStep === 2 && (
            <div>
              <Text type="Heading5">Profile Information</Text>
              <FormField name="name" label="Full Name">
                <Input placeholder="Your name" />
              </FormField>
            </div>
          )}
          
          {currentStep === 3 && (
            <div>
              <Text type="Heading5">Complete</Text>
              <Text>Your account has been set up successfully!</Text>
            </div>
          )}
        </div>
      </Modal>
    </>
  );
}
```

### Custom Backdrop Modal
```tsx
function CustomBackdropExample() {
  const [showModal, setShowModal] = useState(false);

  const customBackdrop = (
    <div className="custom-backdrop">
      <div className="backdrop-pattern" />
    </div>
  );

  return (
    <>
      <Button onClick={() => setShowModal(true)}>
        Custom Backdrop
      </Button>
      
      <Modal 
        show={showModal}
        onHide={() => setShowModal(false)}
        renderBackdrop={customBackdrop}
      >
        <Text type="Heading4">Custom Styled Modal</Text>
        <Text>
          This modal uses a custom backdrop with special styling.
        </Text>
      </Modal>
    </>
  );
}
```