@delightui/components 0.1.105 → 0.1.107

package/docs/components/molecules/Modal.md

@@ -0,0 +1,470 @@
+# 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>
+    </>
+  );
+}
+```