@delightui/components 0.1.104 → 0.1.106

package/docs/components/organisms/SlideOutPanel.md

@@ -0,0 +1,662 @@
+# SlideOutPanel
+
+## Description
+
+A slide-out panel component that provides an overlay interface sliding in from any edge of the screen. SlideOutPanel combines the functionality of a Modal with smooth slide-in animations and form integration capabilities. It's perfect for displaying detailed information, forms, or additional content without leaving the current page context. Can be used with traditional state management or the modern useModal hook for programmatic control.
+
+## Aliases
+
+- SlideOutPanel
+- Slide Panel
+- Side Panel
+- Drawer Panel
+
+## Props Breakdown
+
+**Extends:** `ModalProps` (excluding `size`, `header`, `footer`, `component-variant`) + `FormProviderProps`
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `size` | `'Small' \| 'Medium' \| 'Large'` | `'Medium'` | No | Size of the slide-out panel |
+| `direction` | `'Top' \| 'Left' \| 'Bottom' \| 'Right'` | `'Right'` | No | Direction from which the panel slides in |
+| `isOpen` | `boolean` | `false` | No | Whether the panel is open |
+| `onClose` | `() => void` | - | No | Callback when panel is closed |
+| `children` | `ReactNode` | - | No | Panel content |
+| `className` | `string` | - | No | Additional CSS class names |
+| `onSubmit` | `(data: any, setError: (error: string) => void) => void` | - | No | Form submission handler |
+| `initialValues` | `Record<string, any>` | - | No | Initial form values |
+| `validationSchema` | `any` | - | No | Form validation schema |
+
+Plus all standard HTML div attributes (aria-*, data-*, etc.).
+
+## Examples
+
+### Basic Slide-Out Panel
+
+```tsx
+import { SlideOutPanel, Button, Text, useModal } from '@delightui/components';
+
+const BasicPanel = ({ show, onCancel, content }) => (
+  <SlideOutPanel
+    show={show}
+    onHide={onCancel}
+    direction="Right"
+    size="Medium"
+  >
+    <div style={{ padding: '20px' }}>
+      <Text size="large">Panel Content</Text>
+      <Text>{content}</Text>
+      
+      <Button 
+        onClick={onCancel}
+        style={{ marginTop: '20px' }}
+      >
+        Close Panel
+      </Button>
+    </div>
+  </SlideOutPanel>
+);
+
+function BasicSlideOutExample() {
+  const panel = useModal(BasicPanel);
+
+  return (
+    <Button onClick={() => panel.openModal({
+      content: 'This is a slide-out panel from the right side.'
+    })}>
+      Open Panel
+    </Button>
+  );
+}
+```
+
+### Different Directions
+
+```tsx
+import { SlideOutPanel, Button, Text } from '@delightui/components';
+
+function DirectionsExample() {
+  const [openPanels, setOpenPanels] = useState({
+    top: false,
+    right: false,
+    bottom: false,
+    left: false
+  });
+
+  const openPanel = (direction: keyof typeof openPanels) => {
+    setOpenPanels(prev => ({ ...prev, [direction]: true }));
+  };
+
+  const closePanel = (direction: keyof typeof openPanels) => {
+    setOpenPanels(prev => ({ ...prev, [direction]: false }));
+  };
+
+  return (
+    <div style={{ display: 'flex', gap: '10px', flexWrap: 'wrap' }}>
+      <Button onClick={() => openPanel('top')}>Top Panel</Button>
+      <Button onClick={() => openPanel('right')}>Right Panel</Button>
+      <Button onClick={() => openPanel('bottom')}>Bottom Panel</Button>
+      <Button onClick={() => openPanel('left')}>Left Panel</Button>
+
+      <SlideOutPanel
+        isOpen={openPanels.top}
+        onClose={() => closePanel('top')}
+        direction="Top"
+        size="Small"
+      >
+        <div style={{ padding: '20px', textAlign: 'center' }}>
+          <Text>Panel sliding from the top</Text>
+        </div>
+      </SlideOutPanel>
+
+      <SlideOutPanel
+        isOpen={openPanels.right}
+        onClose={() => closePanel('right')}
+        direction="Right"
+        size="Medium"
+      >
+        <div style={{ padding: '20px' }}>
+          <Text>Panel sliding from the right</Text>
+        </div>
+      </SlideOutPanel>
+
+      <SlideOutPanel
+        isOpen={openPanels.bottom}
+        onClose={() => closePanel('bottom')}
+        direction="Bottom"
+        size="Small"
+      >
+        <div style={{ padding: '20px', textAlign: 'center' }}>
+          <Text>Panel sliding from the bottom</Text>
+        </div>
+      </SlideOutPanel>
+
+      <SlideOutPanel
+        isOpen={openPanels.left}
+        onClose={() => closePanel('left')}
+        direction="Left"
+        size="Medium"
+      >
+        <div style={{ padding: '20px' }}>
+          <Text>Panel sliding from the left</Text>
+        </div>
+      </SlideOutPanel>
+    </div>
+  );
+}
+```
+
+### Different Sizes
+
+```tsx
+import { SlideOutPanel, Button, Text } from '@delightui/components';
+
+function SizesExample() {
+  const [activeSize, setActiveSize] = useState<'Small' | 'Medium' | 'Large' | null>(null);
+
+  return (
+    <div>
+      <div style={{ display: 'flex', gap: '10px' }}>
+        <Button onClick={() => setActiveSize('Small')}>Small Panel</Button>
+        <Button onClick={() => setActiveSize('Medium')}>Medium Panel</Button>
+        <Button onClick={() => setActiveSize('Large')}>Large Panel</Button>
+      </div>
+
+      <SlideOutPanel
+        isOpen={activeSize !== null}
+        onClose={() => setActiveSize(null)}
+        direction="Right"
+        size={activeSize || 'Medium'}
+      >
+        <div style={{ padding: '20px' }}>
+          <Text size="large">{activeSize} Panel</Text>
+          <Text>
+            This is a {activeSize?.toLowerCase()} sized slide-out panel.
+          </Text>
+        </div>
+      </SlideOutPanel>
+    </div>
+  );
+}
+```
+
+### With Form Integration
+
+```tsx
+import { SlideOutPanel, FormField, Input, TextArea, Button, useModal } from '@delightui/components';
+
+const ContactFormPanel = ({ show, onCancel, onSubmit, initialValues }) => {
+  const handleSubmit = (data: any, setError: (error: string) => void) => {
+    // Simulate validation
+    if (!data.email.includes('@')) {
+      setError('Please enter a valid email address');
+      return;
+    }
+
+    onSubmit(data);
+    onCancel(); // Close panel on success
+  };
+
+  return (
+    <SlideOutPanel
+      show={show}
+      onHide={onCancel}
+      direction="Right"
+      size="Medium"
+      onSubmit={handleSubmit}
+      initialValues={initialValues}
+    >
+      <div style={{ padding: '20px' }}>
+        <h2>Contact Us</h2>
+        
+        <FormField name="name" label="Full Name" required>
+          <Input placeholder="Enter your name" />
+        </FormField>
+
+        <FormField name="email" label="Email" required>
+          <Input inputType="Email" placeholder="Enter your email" />
+        </FormField>
+
+        <FormField name="message" label="Message" required>
+          <TextArea 
+            placeholder="Enter your message"
+            rows={4}
+          />
+        </FormField>
+
+        <div style={{ display: 'flex', gap: '10px', marginTop: '20px' }}>
+          <Button actionType="submit">Send Message</Button>
+          <Button 
+            type="Outlined" 
+            onClick={onCancel}
+          >
+            Cancel
+          </Button>
+        </div>
+      </div>
+    </SlideOutPanel>
+  );
+};
+
+function FormIntegrationExample() {
+  const contactPanel = useModal(ContactFormPanel);
+
+  const openContactForm = () => {
+    contactPanel.openModal({
+      initialValues: {
+        name: '',
+        email: '',
+        message: ''
+      },
+      onSubmit: (data) => {
+        console.log('Form submitted:', data);
+        // Handle form submission
+      }
+    });
+  };
+
+  return (
+    <Button onClick={openContactForm}>
+      Open Contact Form
+    </Button>
+  );
+}
+```
+
+### Navigation Panel
+
+```tsx
+import { SlideOutPanel, Button, Nav, NavItem, NavLink } from '@delightui/components';
+
+function NavigationPanelExample() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  const navigationItems = [
+    { label: 'Dashboard', href: '/dashboard' },
+    { label: 'Projects', href: '/projects' },
+    { label: 'Tasks', href: '/tasks' },
+    { label: 'Reports', href: '/reports' },
+    { label: 'Settings', href: '/settings' }
+  ];
+
+  return (
+    <div>
+      <Button onClick={() => setIsOpen(true)}>
+        ☰ Menu
+      </Button>
+
+      <SlideOutPanel
+        isOpen={isOpen}
+        onClose={() => setIsOpen(false)}
+        direction="Left"
+        size="Small"
+      >
+        <div style={{ padding: '20px' }}>
+          <h3>Navigation</h3>
+          
+          <Nav>
+            {navigationItems.map((item, index) => (
+              <NavItem key={index}>
+                <NavLink 
+                  href={item.href}
+                  onClick={() => setIsOpen(false)}
+                >
+                  {item.label}
+                </NavLink>
+              </NavItem>
+            ))}
+          </Nav>
+        </div>
+      </SlideOutPanel>
+    </div>
+  );
+}
+```
+
+### Settings Panel
+
+```tsx
+import { SlideOutPanel, FormField, Toggle, Select, Button } from '@delightui/components';
+
+function SettingsPanelExample() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  const handleSettingsSubmit = (data: any) => {
+    console.log('Settings updated:', data);
+    setIsOpen(false);
+  };
+
+  return (
+    <div>
+      <Button onClick={() => setIsOpen(true)}>
+        Settings
+      </Button>
+
+      <SlideOutPanel
+        isOpen={isOpen}
+        onClose={() => setIsOpen(false)}
+        direction="Right"
+        size="Medium"
+        onSubmit={handleSettingsSubmit}
+        initialValues={{
+          notifications: true,
+          theme: 'light',
+          language: 'en',
+          autoSave: false
+        }}
+      >
+        <div style={{ padding: '20px' }}>
+          <h2>Settings</h2>
+
+          <FormField name="notifications" label="Email Notifications">
+            <Toggle>Enable email notifications</Toggle>
+          </FormField>
+
+          <FormField name="theme" label="Theme">
+            <Select>
+              <option value="light">Light</option>
+              <option value="dark">Dark</option>
+              <option value="auto">Auto</option>
+            </Select>
+          </FormField>
+
+          <FormField name="language" label="Language">
+            <Select>
+              <option value="en">English</option>
+              <option value="es">Spanish</option>
+              <option value="fr">French</option>
+            </Select>
+          </FormField>
+
+          <FormField name="autoSave" label="Auto Save">
+            <Toggle>Automatically save changes</Toggle>
+          </FormField>
+
+          <div style={{ display: 'flex', gap: '10px', marginTop: '30px' }}>
+            <Button actionType="submit">Save Settings</Button>
+            <Button 
+              type="Outlined" 
+              onClick={() => setIsOpen(false)}
+            >
+              Cancel
+            </Button>
+          </div>
+        </div>
+      </SlideOutPanel>
+    </div>
+  );
+}
+```
+
+### Detail View Panel
+
+```tsx
+import { SlideOutPanel, Button, Text, Image, Card } from '@delightui/components';
+
+function DetailViewExample() {
+  const [selectedItem, setSelectedItem] = useState<any>(null);
+
+  const items = [
+    {
+      id: 1,
+      name: 'Product A',
+      description: 'High-quality product with excellent features.',
+      image: '/images/product-a.jpg',
+      price: '$99.99'
+    },
+    {
+      id: 2,
+      name: 'Product B',
+      description: 'Innovative solution for modern needs.',
+      image: '/images/product-b.jpg',
+      price: '$149.99'
+    }
+  ];
+
+  return (
+    <div>
+      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(200px, 1fr))', gap: '20px' }}>
+        {items.map(item => (
+          <Card key={item.id}>
+            <Text size="large">{item.name}</Text>
+            <Text>{item.price}</Text>
+            <Button 
+              onClick={() => setSelectedItem(item)}
+              size="Small"
+            >
+              View Details
+            </Button>
+          </Card>
+        ))}
+      </div>
+
+      <SlideOutPanel
+        isOpen={selectedItem !== null}
+        onClose={() => setSelectedItem(null)}
+        direction="Right"
+        size="Large"
+      >
+        {selectedItem && (
+          <div style={{ padding: '20px' }}>
+            <h2>{selectedItem.name}</h2>
+            
+            <Image 
+              src={selectedItem.image}
+              alt={selectedItem.name}
+              width="100%"
+              height={200}
+              fit="Cover"
+              style={{ marginBottom: '20px', borderRadius: '8px' }}
+            />
+            
+            <Text size="large" style={{ marginBottom: '10px' }}>
+              {selectedItem.price}
+            </Text>
+            
+            <Text style={{ marginBottom: '20px' }}>
+              {selectedItem.description}
+            </Text>
+
+            <div style={{ display: 'flex', gap: '10px' }}>
+              <Button>Add to Cart</Button>
+              <Button type="Outlined">Add to Wishlist</Button>
+            </div>
+          </div>
+        )}
+      </SlideOutPanel>
+    </div>
+  );
+}
+```
+
+### Custom Styling
+
+```tsx
+import { SlideOutPanel, Button, Text } from '@delightui/components';
+
+function CustomStyledExample() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <div>
+      <Button onClick={() => setIsOpen(true)}>
+        Open Styled Panel
+      </Button>
+
+      <SlideOutPanel
+        isOpen={isOpen}
+        onClose={() => setIsOpen(false)}
+        direction="Right"
+        size="Medium"
+        className="custom-slide-panel"
+        style={{
+          '--panel-background': '#f8f9fa',
+          '--panel-border': '1px solid #dee2e6'
+        }}
+      >
+        <div style={{ 
+          padding: '30px',
+          background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
+          color: 'white',
+          minHeight: '100%'
+        }}>
+          <Text size="large" style={{ marginBottom: '20px' }}>
+            Custom Styled Panel
+          </Text>
+          <Text>
+            This panel has custom styling with a gradient background.
+          </Text>
+        </div>
+      </SlideOutPanel>
+    </div>
+  );
+}
+```
+
+## Using with useModal Hook
+
+SlideOutPanel can be used with the `useModal` hook for programmatic control. This approach provides better state management and allows opening panels from anywhere in your application.
+
+### Basic useModal Setup
+
+```tsx
+import { SlideOutPanel, Button, Text, useModal } from '@delightui/components';
+
+const SettingsPanel = ({ show, onCancel, userSettings, onSave }) => (
+  <SlideOutPanel
+    show={show}
+    onHide={onCancel}
+    direction="Right"
+    size="Medium"
+  >
+    <div style={{ padding: '20px' }}>
+      <h2>User Settings</h2>
+      <Text>Configure your preferences here.</Text>
+      
+      <Button 
+        onClick={() => onSave(userSettings)}
+        style={{ marginTop: '20px', marginRight: '10px' }}
+      >
+        Save Settings
+      </Button>
+      <Button 
+        type="Outlined"
+        onClick={onCancel}
+        style={{ marginTop: '20px' }}
+      >
+        Cancel
+      </Button>
+    </div>
+  </SlideOutPanel>
+);
+
+function SettingsPage() {
+  const settingsPanel = useModal(SettingsPanel);
+
+  const openSettings = () => {
+    settingsPanel.openModal({
+      userSettings: { theme: 'dark', notifications: true },
+      onSave: (settings) => {
+        console.log('Settings saved:', settings);
+        settingsPanel.closeModal();
+      }
+    });
+  };
+
+  return (
+    <Button onClick={openSettings}>
+      Open Settings Panel
+    </Button>
+  );
+}
+```
+
+### Multiple Panel Types
+
+```tsx
+import { useModal } from '@delightui/components';
+
+function Dashboard() {
+  const settingsPanel = useModal(SettingsPanel);
+  const helpPanel = useModal(HelpPanel);
+  const profilePanel = useModal(ProfilePanel);
+
+  return (
+    <div>
+      <Button onClick={() => settingsPanel.openModal({})}>
+        Settings
+      </Button>
+      <Button onClick={() => helpPanel.openModal({})}>
+        Help
+      </Button>
+      <Button onClick={() => profilePanel.openModal({})}>
+        Profile
+      </Button>
+    </div>
+  );
+}
+```
+
+### Programmatic Panel Control
+
+```tsx
+const NotificationPanel = ({ show, onCancel, notifications, onMarkAsRead }) => (
+  <SlideOutPanel show={show} onHide={onCancel} direction="Right" size="Medium">
+    <div style={{ padding: '20px' }}>
+      <h2>Notifications</h2>
+      {notifications.map(notification => (
+        <div key={notification.id} style={{ marginBottom: '10px' }}>
+          <Text>{notification.message}</Text>
+          <Button 
+            size="Small"
+            onClick={() => onMarkAsRead(notification.id)}
+          >
+            Mark as Read
+          </Button>
+        </div>
+      ))}
+    </div>
+  </SlideOutPanel>
+);
+
+function NotificationSystem() {
+  const notificationPanel = useModal(NotificationPanel);
+
+  const showNotifications = (notifications) => {
+    notificationPanel.openModal({
+      notifications,
+      onMarkAsRead: (id) => {
+        // Mark notification as read
+        console.log('Marking notification as read:', id);
+      }
+    });
+  };
+
+  // This can be called from anywhere in your app
+  useEffect(() => {
+    // Example: Auto-open notifications panel when new notifications arrive
+    const newNotifications = [
+      { id: 1, message: 'New message received' },
+      { id: 2, message: 'Task completed' }
+    ];
+    
+    if (newNotifications.length > 0) {
+      showNotifications(newNotifications);
+    }
+  }, []);
+
+  return null; // This component doesn't render anything itself
+}
+```
+
+## Requirements
+
+- When using with `useModal`, the SlideOutPanel component must extend `ModalComponentProps`
+- Requires `ModalProvider` to be wrapped around your application
+- The `show` and `onCancel` props are automatically provided by the `useModal` hook
+
+## Related Components
+
+- **[Modal](../molecules/Modal.md)** - Base modal component that SlideOutPanel extends
+- **[useModal](../molecules/useModal.md)** - Hook for programmatic modal management
+- **[ModalProvider](../molecules/ModalProvider.md)** - Context provider for modal state