@app-studio/web 0.9.41 → 0.9.43

package/docs/components/Drawer.mdx

@@ -1,304 +1,465 @@
-# Drawer Component
+# Drawer
 
-A flexible drawer/modal panel component that slides out from any edge of the screen. Useful for displaying additional content, forms, or settings without leaving the current page.
-
-## Features
-
-- **Flexible Placement**: Slide from left, right, top, or bottom
-- **Multiple Sizes**: Choose from xs, sm, md, lg, xl, or full width/height
-- **Compound Component**: Use sub-components for granular control
-- **Customizable Closing**: Prevent closing on overlay click when needed
-- **Smooth Animations**: CSS-based transitions for performance
-- **Accessible**: Built with modal best practices
-
-## Installation
-
-The Drawer component is part of the app-studio library and is already available in your project.
+A slide-out panel component that appears from the edge of the screen, with support for different placements, sizes, and content sections.
 
+### **Import**
 ```tsx
 import { Drawer } from '@app-studio/web';
 ```
 
-## Basic Usage
-
-### Simple Drawer
-
+### **Default**
 ```tsx
-import { useState } from 'react';
+import React, { useState } from 'react';
 import { Drawer } from '@app-studio/web';
-import { Button } from '@app-studio/web';
+import { Button, Text } from 'app-studio';
 
-export function DrawerExample() {
+export const DefaultDrawer = () => {
   const [isOpen, setIsOpen] = useState(false);
-
+  
   return (
     <>
       <Button onClick={() => setIsOpen(true)}>Open Drawer</Button>
-
-      <Drawer isOpen={isOpen} onClose={() => setIsOpen(false)}>
-        <Drawer.Header onClose={() => setIsOpen(false)}>
-          Drawer Title
-        </Drawer.Header>
-        <Drawer.Body>
-          <p>Your content goes here</p>
-        </Drawer.Body>
-        <Drawer.Footer>
-          <Button onClick={() => setIsOpen(false)}>Close</Button>
-        </Drawer.Footer>
+      
+      <Drawer>
+        <Drawer.Overlay isOpen={isOpen} onClose={() => setIsOpen(false)}>
+          <Drawer.Container>
+            <Drawer.Header onClose={() => setIsOpen(false)}>
+              <Text>Drawer Title</Text>
+            </Drawer.Header>
+            <Drawer.Body>
+              <Text>Drawer content goes here</Text>
+            </Drawer.Body>
+            <Drawer.Footer>
+              <Button onClick={() => setIsOpen(false)}>Close</Button>
+            </Drawer.Footer>
+          </Drawer.Container>
+        </Drawer.Overlay>
       </Drawer>
     </>
   );
-}
+};
 ```
 
-### With Different Placements
-
-```tsx
-<Drawer isOpen={isOpen} onClose={onClose} placement="left">
-  {/* Content */}
-</Drawer>
-
-<Drawer isOpen={isOpen} onClose={onClose} placement="right">
-  {/* Content */}
-</Drawer>
-
-<Drawer isOpen={isOpen} onClose={onClose} placement="top">
-  {/* Content */}
-</Drawer>
-
-<Drawer isOpen={isOpen} onClose={onClose} placement="bottom">
-  {/* Content */}
-</Drawer>
-```
+### **isOpen**
+Controls the visibility of the drawer.
 
-### With Different Sizes
+- **Type:** `boolean`
+- **Required:** `true`
 
 ```tsx
-// xs: 320px
-<Drawer isOpen={isOpen} onClose={onClose} size="xs" />
+import React, { useState } from 'react';
+import { Drawer } from '@app-studio/web';
+import { Button, Text } from 'app-studio';
 
-// sm: 380px
-<Drawer isOpen={isOpen} onClose={onClose} size="sm" />
+export const ControlledDrawer = () => {
+  const [isOpen, setIsOpen] = useState(false);
+  
+  return (
+    <>
+      <Button onClick={() => setIsOpen(true)}>Open</Button>
+      <Drawer>
+        <Drawer.Overlay isOpen={isOpen} onClose={() => setIsOpen(false)}>
+          <Drawer.Container>
+            <Drawer.Body>
+              <Text>Controlled Drawer</Text>
+            </Drawer.Body>
+          </Drawer.Container>
+        </Drawer.Overlay>
+      </Drawer>
+    </>
+  );
+};
+```
 
-// md: 480px (default)
-<Drawer isOpen={isOpen} onClose={onClose} size="md" />
+### **onClose**
+Callback function executed when the drawer closes.
 
-// lg: 640px
-<Drawer isOpen={isOpen} onClose={onClose} size="lg" />
+- **Type:** `() => void`
+- **Required:** `true`
 
-// xl: 768px
-<Drawer isOpen={isOpen} onClose={onClose} size="xl" />
+```tsx
+import React, { useState } from 'react';
+import { Drawer } from '@app-studio/web';
+import { Button, Text } from 'app-studio';
 
-// full: 100% width/height
-<Drawer isOpen={isOpen} onClose={onClose} size="full" />
+export const CloseCallbackDrawer = () => {
+  const [isOpen, setIsOpen] = useState(false);
+  
+  return (
+    <>
+      <Button onClick={() => setIsOpen(true)}>Open</Button>
+      <Drawer>
+        <Drawer.Overlay 
+          isOpen={isOpen} 
+          onClose={() => {
+            console.log('Drawer closing');
+            setIsOpen(false);
+          }}
+        >
+          <Drawer.Container>
+            <Drawer.Body>
+              <Text>Click outside to close</Text>
+            </Drawer.Body>
+          </Drawer.Container>
+        </Drawer.Overlay>
+      </Drawer>
+    </>
+  );
+};
 ```
 
-## API Reference
+### **placement**
+The placement of the drawer.
 
-### Drawer Props
+- **Type:** `Placement`
+- **Default:** `'right'`
+- **Possible Values:** `'left' | 'right' | 'top' | 'bottom'`
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `isOpen` | `boolean` | Required | Controls whether the drawer is visible |
-| `onClose` | `() => void` | Required | Callback fired when the drawer should close |
-| `placement` | `'left' \| 'right' \| 'top' \| 'bottom'` | `'right'` | Which edge the drawer slides from |
-| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'` | Width (for left/right) or height (for top/bottom) of drawer |
-| `isClosePrevented` | `boolean` | `false` | If true, clicking the overlay won't close the drawer |
-| `children` | `React.ReactNode` | - | Content of the drawer (typically sub-components) |
-
-### Drawer.Overlay Props
+```tsx
+import React, { useState } from 'react';
+import { Drawer } from '@app-studio/web';
+import { Button, Text, Horizontal } from 'app-studio';
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `isOpen` | `boolean` | Required | Controls overlay visibility |
-| `onClose` | `() => void` | Required | Callback when overlay is clicked |
-| `isClosePrevented` | `boolean` | `false` | Prevent closing on overlay click |
-| `blur` | `number` | - | Optional blur amount for backdrop |
-| `children` | `React.ReactNode` | - | Drawer container element |
+export const PlacementDrawers = () => {
+  const [placement, setPlacement] = useState<string | null>(null);
+  
+  return (
+    <>
+      <Horizontal gap={10}>
+        {['left', 'right', 'top', 'bottom'].map((pos) => (
+          <Button key={pos} onClick={() => setPlacement(pos)}>
+            {pos}
+          </Button>
+        ))}
+      </Horizontal>
+      
+      <Drawer>
+        <Drawer.Overlay 
+          isOpen={!!placement} 
+          onClose={() => setPlacement(null)}
+        >
+          <Drawer.Container placement={placement as any}>
+            <Drawer.Header onClose={() => setPlacement(null)}>
+              <Text>Drawer from {placement}</Text>
+            </Drawer.Header>
+            <Drawer.Body>
+              <Text>Content</Text>
+            </Drawer.Body>
+          </Drawer.Container>
+        </Drawer.Overlay>
+      </Drawer>
+    </>
+  );
+};
+```
 
-### Drawer.Container Props
+### **size**
+The size of the drawer.
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `placement` | `'left' \| 'right' \| 'top' \| 'bottom'` | `'right'` | Placement of the drawer |
-| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'` | Size of the drawer |
-| `children` | `React.ReactNode` | - | Drawer content |
+- **Type:** `Size`
+- **Default:** `'md'`
+- **Possible Values:** `'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'full'`
 
-### Drawer.Header Props
+```tsx
+import React, { useState } from 'react';
+import { Drawer } from '@app-studio/web';
+import { Button, Text, Horizontal } from 'app-studio';
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `onClose` | `() => void` | - | Callback for close button |
-| `buttonPosition` | `'left' \| 'right'` | `'right'` | Position of the close button |
-| `children` | `React.ReactNode` | - | Header content (typically title text) |
+export const SizedDrawers = () => {
+  const [size, setSize] = useState<string | null>(null);
+  
+  return (
+    <>
+      <Horizontal gap={10}>
+        {['sm', 'md', 'lg', 'xl', 'full'].map((s) => (
+          <Button key={s} onClick={() => setSize(s)}>
+            {s}
+          </Button>
+        ))}
+      </Horizontal>
+      
+      <Drawer>
+        <Drawer.Overlay isOpen={!!size} onClose={() => setSize(null)}>
+          <Drawer.Container size={size as any}>
+            <Drawer.Header onClose={() => setSize(null)}>
+              <Text>Size: {size}</Text>
+            </Drawer.Header>
+            <Drawer.Body>
+              <Text>Drawer content</Text>
+            </Drawer.Body>
+          </Drawer.Container>
+        </Drawer.Overlay>
+      </Drawer>
+    </>
+  );
+};
+```
 
-### Drawer.Body Props
+### **isClosePrevented**
+Prevents the drawer from closing when clicking the overlay.
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `children` | `React.ReactNode` | - | Main content of the drawer |
+- **Type:** `boolean`
+- **Default:** `false`
 
-### Drawer.Footer Props
+```tsx
+import React, { useState } from 'react';
+import { Drawer } from '@app-studio/web';
+import { Button, Text } from 'app-studio';
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `children` | `React.ReactNode` | - | Footer content (typically action buttons) |
+export const PreventCloseDrawer = () => {
+  const [isOpen, setIsOpen] = useState(false);
+  
+  return (
+    <>
+      <Button onClick={() => setIsOpen(true)}>Open</Button>
+      <Drawer>
+        <Drawer.Overlay 
+          isOpen={isOpen} 
+          onClose={() => setIsOpen(false)}
+          isClosePrevented
+        >
+          <Drawer.Container>
+            <Drawer.Header onClose={() => setIsOpen(false)}>
+              <Text>Must use close button</Text>
+            </Drawer.Header>
+            <Drawer.Body>
+              <Text>Click outside won't close this drawer</Text>
+            </Drawer.Body>
+          </Drawer.Container>
+        </Drawer.Overlay>
+      </Drawer>
+    </>
+  );
+};
+```
 
-## Compound Components
+### **blur**
+The degree of blurriness applied to the overlay.
 
-The Drawer uses a compound component pattern for flexible composition:
+- **Type:** `number`
 
 ```tsx
-<Drawer isOpen={isOpen} onClose={onClose}>
-  <Drawer.Overlay>
-    <Drawer.Container>
-      <Drawer.Header onClose={onClose}>Title</Drawer.Header>
-      <Drawer.Body>Content</Drawer.Body>
-      <Drawer.Footer>Actions</Drawer.Footer>
-    </Drawer.Container>
-  </Drawer.Overlay>
-</Drawer>
-```
+import React, { useState } from 'react';
+import { Drawer } from '@app-studio/web';
+import { Button, Text } from 'app-studio';
 
-However, you typically use the simpler form where the main Drawer component wraps the sub-components directly.
+export const BlurredDrawer = () => {
+  const [isOpen, setIsOpen] = useState(false);
+  
+  return (
+    <>
+      <Button onClick={() => setIsOpen(true)}>Open Blurred Drawer</Button>
+      <Drawer>
+        <Drawer.Overlay 
+          isOpen={isOpen} 
+          onClose={() => setIsOpen(false)}
+          blur={10}
+        >
+          <Drawer.Container>
+            <Drawer.Body>
+              <Text>Background is blurred</Text>
+            </Drawer.Body>
+          </Drawer.Container>
+        </Drawer.Overlay>
+      </Drawer>
+    </>
+  );
+};
+```
 
-## Common Patterns
+### **buttonPosition**
+Position of the close button in the header.
 
-### Form in a Drawer
+- **Type:** `CloseButtonPosition`
+- **Possible Values:** `'left' | 'right' | 'none'`
 
 ```tsx
-export function FormDrawer() {
-  const [isOpen, setIsOpen] = useState(false);
-  const [formData, setFormData] = useState({ name: '', email: '' });
-
-  const handleSubmit = () => {
-    console.log('Form submitted:', formData);
-    setIsOpen(false);
-  };
+import React, { useState } from 'react';
+import { Drawer } from '@app-studio/web';
+import { Button, Text } from 'app-studio';
 
+export const ButtonPositionDrawer = () => {
+  const [isOpen, setIsOpen] = useState(false);
+  
   return (
     <>
-      <Button onClick={() => setIsOpen(true)}>Open Form</Button>
-
-      <Drawer isOpen={isOpen} onClose={() => setIsOpen(false)}>
-        <Drawer.Header onClose={() => setIsOpen(false)}>
-          Create New Item
-        </Drawer.Header>
-        <Drawer.Body>
-          <input
-            placeholder="Name"
-            value={formData.name}
-            onChange={(e) => setFormData({ ...formData, name: e.target.value })}
-          />
-          <input
-            placeholder="Email"
-            value={formData.email}
-            onChange={(e) => setFormData({ ...formData, email: e.target.value })}
-          />
-        </Drawer.Body>
-        <Drawer.Footer>
-          <Button variant="secondary" onClick={() => setIsOpen(false)}>
-            Cancel
-          </Button>
-          <Button onClick={handleSubmit}>Submit</Button>
-        </Drawer.Footer>
+      <Button onClick={() => setIsOpen(true)}>Open</Button>
+      <Drawer>
+        <Drawer.Overlay isOpen={isOpen} onClose={() => setIsOpen(false)}>
+          <Drawer.Container>
+            <Drawer.Header 
+              onClose={() => setIsOpen(false)}
+              buttonPosition="left"
+            >
+              <Text>Close button on left</Text>
+            </Drawer.Header>
+            <Drawer.Body>
+              <Text>Drawer content</Text>
+            </Drawer.Body>
+          </Drawer.Container>
+        </Drawer.Overlay>
       </Drawer>
     </>
   );
-}
+};
 ```
 
-### Prevent Closing on Overlay Click
+### **Navigation Drawer**
+A common use case for navigation menus.
 
 ```tsx
-<Drawer
-  isOpen={isOpen}
-  onClose={onClose}
-  isClosePrevented={true}
->
-  <Drawer.Header onClose={onClose}>
-    Important Action
-  </Drawer.Header>
-  <Drawer.Body>
-    This drawer can only be closed by clicking the close button
-  </Drawer.Body>
-</Drawer>
+import React, { useState } from 'react';
+import { Drawer } from '@app-studio/web';
+import { Button, Text, Vertical } from 'app-studio';
+
+export const NavigationDrawer = () => {
+  const [isOpen, setIsOpen] = useState(false);
+  
+  const menuItems = [
+    'Dashboard',
+    'Profile',
+    'Settings',
+    'Analytics',
+    'Help',
+  ];
+  
+  return (
+    <>
+      <Button onClick={() => setIsOpen(true)}>☰ Menu</Button>
+      <Drawer>
+        <Drawer.Overlay isOpen={isOpen} onClose={() => setIsOpen(false)}>
+          <Drawer.Container placement="left" size="sm">
+            <Drawer.Header onClose={() => setIsOpen(false)}>
+              <Text fontSize={20} fontWeight="bold">Menu</Text>
+            </Drawer.Header>
+            <Drawer.Body>
+              <Vertical gap={0}>
+                {menuItems.map((item) => (
+                  <Button
+                    key={item}
+                    variant="ghost"
+                    onClick={() => {
+                      console.log('Navigate to:', item);
+                      setIsOpen(false);
+                    }}
+                  >
+                    {item}
+                  </Button>
+                ))}
+              </Vertical>
+            </Drawer.Body>
+          </Drawer.Container>
+        </Drawer.Overlay>
+      </Drawer>
+    </>
+  );
+};
 ```
 
-### Nested Drawers
+### **Form Drawer**
+Using drawer for forms and data entry.
 
 ```tsx
-export function NestedDrawers() {
-  const [drawer1Open, setDrawer1Open] = useState(false);
-  const [drawer2Open, setDrawer2Open] = useState(false);
+import React, { useState } from 'react';
+import { Drawer } from '@app-studio/web';
+import { Button, Text, Vertical } from 'app-studio';
+import { TextField } from '@app-studio/web';
 
+export const FormDrawer = () => {
+  const [isOpen, setIsOpen] = useState(false);
+  
   return (
     <>
-      <Button onClick={() => setDrawer1Open(true)}>Open First Drawer</Button>
-
-      <Drawer isOpen={drawer1Open} onClose={() => setDrawer1Open(false)} placement="left">
-        <Drawer.Header onClose={() => setDrawer1Open(false)}>
-          First Drawer
-        </Drawer.Header>
-        <Drawer.Body>
-          <Button onClick={() => setDrawer2Open(true)}>Open Second Drawer</Button>
-        </Drawer.Body>
-      </Drawer>
-
-      <Drawer isOpen={drawer2Open} onClose={() => setDrawer2Open(false)} placement="right">
-        <Drawer.Header onClose={() => setDrawer2Open(false)}>
-          Second Drawer
-        </Drawer.Header>
-        <Drawer.Body>Content for second drawer</Drawer.Body>
+      <Button onClick={() => setIsOpen(true)}>Add User</Button>
+      <Drawer>
+        <Drawer.Overlay isOpen={isOpen} onClose={() => setIsOpen(false)}>
+          <Drawer.Container placement="right" size="md">
+            <Drawer.Header onClose={() => setIsOpen(false)}>
+              <Text fontSize={18} fontWeight="bold">Add New User</Text>
+            </Drawer.Header>
+            <Drawer.Body>
+              <Vertical gap={15}>
+                <TextField label="Name" placeholder="Enter name" />
+                <TextField label="Email" placeholder="Enter email" />
+                <TextField label="Role" placeholder="Enter role" />
+              </Vertical>
+            </Drawer.Body>
+            <Drawer.Footer>
+              <Horizontal gap={10} justifyContent="flex-end">
+                <Button 
+                  variant="outline" 
+                  onClick={() => setIsOpen(false)}
+                >
+                  Cancel
+                </Button>
+                <Button 
+                  variant="filled"
+                  onClick={() => {
+                    console.log('Save user');
+                    setIsOpen(false);
+                  }}
+                >
+                  Save
+                </Button>
+              </Horizontal>
+            </Drawer.Footer>
+          </Drawer.Container>
+        </Drawer.Overlay>
       </Drawer>
     </>
   );
-}
+};
 ```
 
-## Styling & Customization
-
-The Drawer component respects the `app-studio` theme. You can customize appearance using:
-
-1. **CSS Classes** - Override via CSS
-2. **ViewProps** - Pass style props to adjust appearance
-3. **Placement and Size** - Primary customization levers
-
-## Size Reference
-
-| Size | Width/Height |
-|------|-------------|
-| `xs` | 320px |
-| `sm` | 380px |
-| `md` | 480px (default) |
-| `lg` | 640px |
-| `xl` | 768px |
-| `full` | 100% |
-
-## Best Practices
-
-1. **Always provide onClose**: Ensure users can exit the drawer
-2. **Clear call-to-action**: Make it obvious what the drawer is for
-3. **Concise content**: Drawers work best for focused, task-specific content
-4. **Footer buttons**: Use Footer component for action buttons
-5. **Prevent accidental closes**: Use `isClosePrevented` for critical operations
-6. **Keyboard support**: Ensure proper focus management with your content
-7. **Mobile consideration**: Test drawer sizes on mobile - consider using `full` size on small screens
+### **Details Drawer**
+Showing detailed information in a drawer.
 
-## Examples
-
-Check out the example implementations:
-- Default Drawer: `src/components/Drawer/Examples/DefaultDrawer.tsx`
-- Placements: `src/components/Drawer/Examples/DrawerPlacements.tsx`
-- Sizes: `src/components/Drawer/Examples/DrawerSizes.tsx`
-
-## Accessibility
-
-- Drawer automatically manages focus when opening/closing
-- Overlay click triggers `onClose` callback (unless `isClosePrevented`)
-- Close button in Header provides clear exit path
-- Built-in animations respect `prefers-reduced-motion` preferences
+```tsx
+import React, { useState } from 'react';
+import { Drawer } from '@app-studio/web';
+import { Button, Text, Vertical, Horizontal } from 'app-studio';
 
-## Browser Support
+export const DetailsDrawer = () => {
+  const [isOpen, setIsOpen] = useState(false);
+  
+  return (
+    <>
+      <Button onClick={() => setIsOpen(true)}>View Details</Button>
+      <Drawer>
+        <Drawer.Overlay isOpen={isOpen} onClose={() => setIsOpen(false)}>
+          <Drawer.Container placement="right" size="lg">
+            <Drawer.Header onClose={() => setIsOpen(false)}>
+              <Text fontSize={20} fontWeight="bold">Product Details</Text>
+            </Drawer.Header>
+            <Drawer.Body>
+              <Vertical gap={20}>
+                <div>
+                  <Text fontSize={14} color="#6b7280">Name</Text>
+                  <Text fontSize={16}>Premium Widget</Text>
+                </div>
+                <div>
+                  <Text fontSize={14} color="#6b7280">Price</Text>
+                  <Text fontSize={16}>$99.99</Text>
+                </div>
+                <div>
+                  <Text fontSize={14} color="#6b7280">Description</Text>
+                  <Text fontSize={16}>
+                    A high-quality widget with advanced features
+                    and premium materials.
+                  </Text>
+                </div>
+              </Vertical>
+            </Drawer.Body>
+            <Drawer.Footer>
+              <Button onClick={() => setIsOpen(false)}>
+                Add to Cart
+              </Button>
+            </Drawer.Footer>
+          </Drawer.Container>
+        </Drawer.Overlay>
+      </Drawer>
+    </>
+  );
+};
+```
 
-Works in all modern browsers that support CSS transforms and transitions.