@ceed/ads 1.29.1 → 1.30.0-next.1

package/dist/components/navigation/InsetDrawer.md

@@ -2,9 +2,7 @@
 
 ## Introduction
 
-InsetDrawer is a slide-out panel that appears from any edge of the screen, providing a secondary space for navigation, filters, settings, or detailed content without leaving the current page. Unlike a Modal, which overlays the entire viewport, InsetDrawer slides in from a specific edge and pushes or covers only part of the interface.
-
-It is commonly used for mobile navigation menus, filter panels, configuration sidebars, and detail views. The component supports four anchor positions (left, right, top, bottom) and three size presets, making it adaptable to a wide range of layout requirements.
+InsetDrawer is a slide-out panel that appears from any edge of the screen, providing a secondary space for navigation, filters, settings, or detailed content without leaving the current page. Unlike Modal which overlays the entire screen, InsetDrawer slides in from an edge and can optionally allow interaction with the main content behind it. It's commonly used for mobile navigation menus, filter panels, and configuration sidebars.
 
 ```tsx
 <Box sx={{
@@ -140,6 +138,15 @@ Booking options
 | ---------------------------- | ----------- | ------- |
 | Controls resolved at runtime | —           | —       |
 
+> ⚠️ **Usage Warning** ⚠️
+>
+> Consider these factors before using InsetDrawer:
+>
+> - **Mobile-first design**: InsetDrawer works best on mobile; consider persistent sidebars on desktop
+> - **Content hierarchy**: Don't hide critical content in drawers that users need frequently
+> - **Anchor position**: Use `left` for navigation, `right` for details/filters, `bottom` for actions
+> - **Accessibility**: Ensure proper focus management and keyboard navigation
+
 ## Usage
 
 ```tsx
@@ -165,9 +172,145 @@ function FilterDrawer() {
 }
 ```
 
-## Anchor Positions
+## Examples
+
+### Playground
+
+Interactive example with controls for anchor position and size.
+
+```tsx
+<Box sx={{
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 2
+}}>
+<Button variant="outlined" color="neutral" startDecorator={<FilterListIcon />} onClick={() => setOpen(true)}>
+  Open Drawer
+</Button>
+
+<InsetDrawer {...args} open={open} onClose={() => setOpen(false)}>
+  <Sheet sx={{
+    borderRadius: 'md',
+    p: 2,
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 2,
+    height: '100%',
+    overflow: 'auto'
+  }}>
+  <DialogTitle>Filters</DialogTitle>
+  <ModalClose />
+  <Divider sx={{
+    mt: 'auto'
+  }} />
+  <DialogContent>
+    <FormControl>
+      <FormLabel sx={{
+        typography: 'title-md',
+        fontWeight: 'bold'
+      }}>Property type</FormLabel>
+      <RadioGroup>
+        <Box sx={{
+          display: 'grid',
+          gridTemplateColumns: 'repeat(auto-fill, minmax(140px, 1fr))',
+          gap: 1.5
+        }}>
+        {[{
+          name: 'House',
+          icon: <HomeRoundedIcon />
+        }, {
+          name: 'Apartment',
+          icon: <ApartmentRoundedIcon />
+        }, {
+          name: 'Guesthouse',
+          icon: <MeetingRoomRoundedIcon />
+        }, {
+          name: 'Hotel',
+          icon: <HotelRoundedIcon />
+        }].map(item => <Card key={item.name} sx={{
+          boxShadow: 'none',
+          '&:hover': {
+            bgcolor: 'background.level1'
+          }
+        }}>
+        <CardContent>
+          {item.icon}
+          <Typography level="title-md">{item.name}</Typography>
+        </CardContent>
+        <Radio disableIcon overlay variant="outlined" color="neutral" value={item.name} sx={{
+          mt: -2
+        }} slotProps={{
+          action: {
+            sx: {
+              '&:hover': {
+                bgcolor: 'transparent'
+              }
+            }
+          }
+        }} />
+      </Card>)}
+    </Box>
+  </RadioGroup>
+</FormControl>
+
+<Typography level="title-md" fontWeight="bold" sx={{
+  mt: 2
+}}>
+Booking options
+</Typography>
+<FormControl orientation="horizontal">
+  <Box sx={{
+    flex: 1,
+    pr: 1
+  }}>
+  <FormLabel sx={{
+    typography: 'title-sm'
+  }}>Instant booking</FormLabel>
+  <FormHelperText sx={{
+    typography: 'body-sm'
+  }}>
+  Listings that you can book without waiting for host approval.
+</FormHelperText>
+</Box>
+<Switch />
+</FormControl>
+
+<FormControl orientation="horizontal">
+  <Box sx={{
+    flex: 1,
+    mt: 1,
+    mr: 1
+  }}>
+  <FormLabel sx={{
+    typography: 'title-sm'
+  }}>Self check-in</FormLabel>
+  <FormHelperText sx={{
+    typography: 'body-sm'
+  }}>
+  Easy access to the property when you arrive.
+</FormHelperText>
+</Box>
+<Switch />
+</FormControl>
+</DialogContent>
+
+<Divider sx={{
+  mt: 'auto'
+}} />
+<Stack direction="row" justifyContent="space-between" useFlexGap spacing={1}>
+  <Button variant="outlined" color="neutral">
+    Clear
+  </Button>
+  <Button onClick={() => setOpen(false)}>Show 165 properties</Button>
+</Stack>
+</Sheet>
+</InsetDrawer>
+</Box>
+```
+
+### Anchors
 
-InsetDrawer supports four anchor positions. Use `left` for navigation, `right` for details or filters, `top` for search bars, and `bottom` for mobile action sheets.
+Different anchor positions: left, right, top, bottom.
 
 ```tsx
 <Box sx={{
@@ -214,9 +357,9 @@ InsetDrawer supports four anchor positions. Use `left` for navigation, `right` f
 </Box>
 ```
 
-## Sizes
+### Sizes
 
-Three size presets are available: `sm`, `md`, and `lg`. The size controls width for left/right anchors and height for top/bottom anchors.
+Available size options: small, medium, large.
 
 ```tsx
 <Box sx={{
@@ -260,9 +403,9 @@ Three size presets are available: `sm`, `md`, and `lg`. The size controls width
 </Box>
 ```
 
-## Navigation Menu
+### Navigation Menu
 
-A typical mobile navigation menu pattern using InsetDrawer anchored to the left with a compact size.
+A mobile navigation menu using InsetDrawer.
 
 ```tsx
 <Box>
@@ -294,9 +437,9 @@ A typical mobile navigation menu pattern using InsetDrawer anchored to the left
 </Box>
 ```
 
-## Filter Panel
+### Filter Panel
 
-A filter panel that slides in from the right, containing form controls for refining search results.
+A filter panel with form controls sliding from the right.
 
 ```tsx
 <Box>
@@ -435,8 +578,235 @@ Booking options
 </Box>
 ```
 
+## When to Use
+
+### ✅ Good Use Cases
+
+- **Mobile navigation**: Hamburger menu that slides in from the left
+- **Filter panels**: Complex filters that would clutter the main UI
+- **Detail views**: Additional information without navigating away
+- **Settings panels**: Quick access to preferences or configurations
+- **Shopping cart**: E-commerce cart preview on the side
+- **Help/Support**: Context-sensitive help or chat interfaces
+
+### ❌ When Not to Use
+
+- **Critical actions**: Don't hide essential features in drawers
+- **Primary navigation on desktop**: Consider a persistent sidebar instead
+- **Simple choices**: Use Select or Dropdown for simple selections
+- **Confirmations**: Use Dialog for confirmation messages
+- **Notifications**: Use Toast or Alert for feedback messages
+- **Large forms**: Complex forms should have their own page
+
 ## Common Use Cases
 
+### Mobile Navigation Drawer
+
+```tsx
+function NavigationDrawer({ open, onClose, currentPath }) {
+  const navItems = [
+    { label: 'Dashboard', path: '/dashboard', icon: <DashboardIcon /> },
+    { label: 'Users', path: '/users', icon: <PeopleIcon /> },
+    { label: 'Settings', path: '/settings', icon: <SettingsIcon /> },
+  ];
+
+  return (
+    <InsetDrawer open={open} onClose={onClose} anchor="left">
+      <Sheet sx={{ width: 280, height: '100%', p: 2 }}>
+        <Stack gap={1}>
+          <Box sx={{ display: 'flex', alignItems: 'center', mb: 2 }}>
+            <Avatar src="/logo.png" />
+            <Typography level="title-lg" sx={{ ml: 1 }}>My App</Typography>
+          </Box>
+          <Divider />
+          <List>
+            {navItems.map((item) => (
+              <ListItem key={item.path}>
+                <ListItemButton
+                  selected={currentPath === item.path}
+                  onClick={() => {
+                    navigate(item.path);
+                    onClose();
+                  }}
+                >
+                  <ListItemDecorator>{item.icon}</ListItemDecorator>
+                  {item.label}
+                </ListItemButton>
+              </ListItem>
+            ))}
+          </List>
+        </Stack>
+      </Sheet>
+    </InsetDrawer>
+  );
+}
+```
+
+### Filter Panel
+
+```tsx
+function ProductFilters({ open, onClose, filters, onApply }) {
+  const [localFilters, setLocalFilters] = useState(filters);
+
+  const handleApply = () => {
+    onApply(localFilters);
+    onClose();
+  };
+
+  const handleClear = () => {
+    setLocalFilters({});
+  };
+
+  return (
+    <InsetDrawer open={open} onClose={onClose} anchor="right" size="md">
+      <Sheet sx={{ height: '100%', display: 'flex', flexDirection: 'column' }}>
+        <Box sx={{ p: 2, borderBottom: '1px solid', borderColor: 'divider' }}>
+          <DialogTitle>Filters</DialogTitle>
+          <ModalClose />
+        </Box>
+
+        <DialogContent sx={{ flex: 1, overflow: 'auto', p: 2 }}>
+          <Stack gap={3}>
+            <FormControl>
+              <FormLabel>Category</FormLabel>
+              <Select
+                value={localFilters.category || ''}
+                onChange={(_, value) =>
+                  setLocalFilters({ ...localFilters, category: value })
+                }
+              >
+                <Option value="electronics">Electronics</Option>
+                <Option value="clothing">Clothing</Option>
+                <Option value="books">Books</Option>
+              </Select>
+            </FormControl>
+
+            <FormControl>
+              <FormLabel>Price Range</FormLabel>
+              <Stack direction="row" gap={1}>
+                <Input
+                  type="number"
+                  placeholder="Min"
+                  value={localFilters.minPrice || ''}
+                  onChange={(e) =>
+                    setLocalFilters({ ...localFilters, minPrice: e.target.value })
+                  }
+                />
+                <Input
+                  type="number"
+                  placeholder="Max"
+                  value={localFilters.maxPrice || ''}
+                  onChange={(e) =>
+                    setLocalFilters({ ...localFilters, maxPrice: e.target.value })
+                  }
+                />
+              </Stack>
+            </FormControl>
+
+            <FormControl>
+              <FormLabel>Rating</FormLabel>
+              <RadioGroup
+                value={localFilters.rating || ''}
+                onChange={(e) =>
+                  setLocalFilters({ ...localFilters, rating: e.target.value })
+                }
+              >
+                {[4, 3, 2, 1].map((rating) => (
+                  <Radio
+                    key={rating}
+                    value={String(rating)}
+                    label={`${rating}+ stars`}
+                  />
+                ))}
+              </RadioGroup>
+            </FormControl>
+          </Stack>
+        </DialogContent>
+
+        <Box sx={{ p: 2, borderTop: '1px solid', borderColor: 'divider' }}>
+          <Stack direction="row" gap={1} justifyContent="space-between">
+            <Button variant="outlined" color="neutral" onClick={handleClear}>
+              Clear All
+            </Button>
+            <Button onClick={handleApply}>Apply Filters</Button>
+          </Stack>
+        </Box>
+      </Sheet>
+    </InsetDrawer>
+  );
+}
+```
+
+### Shopping Cart Drawer
+
+```tsx
+function CartDrawer({ open, onClose, items, onCheckout }) {
+  const total = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
+
+  return (
+    <InsetDrawer open={open} onClose={onClose} anchor="right" size="lg">
+      <Sheet sx={{ height: '100%', display: 'flex', flexDirection: 'column' }}>
+        <Box sx={{ p: 2, borderBottom: '1px solid', borderColor: 'divider' }}>
+          <DialogTitle>Shopping Cart ({items.length})</DialogTitle>
+          <ModalClose />
+        </Box>
+
+        <DialogContent sx={{ flex: 1, overflow: 'auto', p: 0 }}>
+          {items.length === 0 ? (
+            <Box sx={{ p: 4, textAlign: 'center' }}>
+              <ShoppingCartIcon sx={{ fontSize: 48, color: 'neutral.400' }} />
+              <Typography level="body-lg" sx={{ mt: 2 }}>
+                Your cart is empty
+              </Typography>
+            </Box>
+          ) : (
+            <List>
+              {items.map((item) => (
+                <ListItem key={item.id}>
+                  <ListItemDecorator>
+                    <img
+                      src={item.image}
+                      alt={item.name}
+                      style={{ width: 60, height: 60, objectFit: 'cover' }}
+                    />
+                  </ListItemDecorator>
+                  <ListItemContent>
+                    <Typography level="title-sm">{item.name}</Typography>
+                    <Typography level="body-sm">
+                      ${item.price} x {item.quantity}
+                    </Typography>
+                  </ListItemContent>
+                  <IconButton size="sm" color="danger">
+                    <DeleteIcon />
+                  </IconButton>
+                </ListItem>
+              ))}
+            </List>
+          )}
+        </DialogContent>
+
+        {items.length > 0 && (
+          <Box sx={{ p: 2, borderTop: '1px solid', borderColor: 'divider' }}>
+            <Stack gap={2}>
+              <Box sx={{ display: 'flex', justifyContent: 'space-between' }}>
+                <Typography level="title-md">Total</Typography>
+                <Typography level="title-md">${total.toFixed(2)}</Typography>
+              </Box>
+              <Button fullWidth onClick={onCheckout}>
+                Proceed to Checkout
+              </Button>
+              <Button variant="outlined" fullWidth onClick={onClose}>
+                Continue Shopping
+              </Button>
+            </Stack>
+          </Box>
+        )}
+      </Sheet>
+    </InsetDrawer>
+  );
+}
+```
+
 ### Settings Drawer
 
 ```tsx
@@ -453,6 +823,7 @@ function SettingsDrawer({ open, onClose }) {
         <DialogTitle>Settings</DialogTitle>
         <ModalClose />
         <Divider sx={{ my: 2 }} />
+
         <DialogContent>
           <Stack gap={3}>
             <FormControl orientation="horizontal">
@@ -467,6 +838,7 @@ function SettingsDrawer({ open, onClose }) {
                 }
               />
             </FormControl>
+
             <FormControl orientation="horizontal">
               <Box sx={{ flex: 1 }}>
                 <FormLabel>Dark Mode</FormLabel>
@@ -479,35 +851,21 @@ function SettingsDrawer({ open, onClose }) {
                 }
               />
             </FormControl>
-          </Stack>
-        </DialogContent>
-      </Sheet>
-    </InsetDrawer>
-  );
-}
-```
-
-### Detail View Drawer
-
-```tsx
-function DetailDrawer({ open, onClose, itemId }) {
-  const [data, setData] = useState(null);
-
-  useEffect(() => {
-    if (open && itemId) {
-      fetchItemDetails(itemId).then(setData);
-    }
-  }, [open, itemId]);
 
-  return (
-    <InsetDrawer open={open} onClose={onClose} anchor="right" size="lg">
-      <Sheet sx={{ height: '100%', display: 'flex', flexDirection: 'column' }}>
-        <Box sx={{ p: 2, borderBottom: '1px solid', borderColor: 'divider' }}>
-          <DialogTitle>Item Details</DialogTitle>
-          <ModalClose />
-        </Box>
-        <DialogContent sx={{ flex: 1, overflow: 'auto', p: 2 }}>
-          {data ? <ItemDetails data={data} /> : <Skeleton variant="text" />}
+            <FormControl>
+              <FormLabel>Language</FormLabel>
+              <Select
+                value={settings.language}
+                onChange={(_, value) =>
+                  setSettings({ ...settings, language: value || 'en' })
+                }
+              >
+                <Option value="en">English</Option>
+                <Option value="ko">한국어</Option>
+                <Option value="ja">日本語</Option>
+              </Select>
+            </FormControl>
+          </Stack>
         </DialogContent>
       </Sheet>
     </InsetDrawer>
@@ -522,18 +880,32 @@ function ActionSheet({ open, onClose, onAction }) {
   const actions = [
     { id: 'edit', label: 'Edit', icon: <EditIcon /> },
     { id: 'share', label: 'Share', icon: <ShareIcon /> },
+    { id: 'duplicate', label: 'Duplicate', icon: <ContentCopyIcon /> },
     { id: 'delete', label: 'Delete', icon: <DeleteIcon />, color: 'danger' },
   ];
 
   return (
     <InsetDrawer open={open} onClose={onClose} anchor="bottom">
       <Sheet sx={{ borderRadius: 'lg lg 0 0', p: 2 }}>
+        <Box
+          sx={{
+            width: 40,
+            height: 4,
+            bgcolor: 'neutral.300',
+            borderRadius: 'xl',
+            mx: 'auto',
+            mb: 2,
+          }}
+        />
         <List>
           {actions.map((action) => (
             <ListItem key={action.id}>
               <ListItemButton
                 color={action.color}
-                onClick={() => { onAction(action.id); onClose(); }}
+                onClick={() => {
+                  onAction(action.id);
+                  onClose();
+                }}
               >
                 <ListItemDecorator>{action.icon}</ListItemDecorator>
                 {action.label}
@@ -541,7 +913,13 @@ function ActionSheet({ open, onClose, onAction }) {
             </ListItem>
           ))}
         </List>
-        <Button variant="soft" color="neutral" fullWidth sx={{ mt: 1 }} onClick={onClose}>
+        <Button
+          variant="soft"
+          color="neutral"
+          fullWidth
+          sx={{ mt: 1 }}
+          onClick={onClose}
+        >
           Cancel
         </Button>
       </Sheet>
@@ -550,61 +928,353 @@ function ActionSheet({ open, onClose, onAction }) {
 }
 ```
 
+### Help/Support Panel
+
+```tsx
+function HelpDrawer({ open, onClose }) {
+  const [searchQuery, setSearchQuery] = useState('');
+
+  const faqItems = [
+    { question: 'How do I reset my password?', answer: '...' },
+    { question: 'How do I change my email?', answer: '...' },
+    { question: 'How do I delete my account?', answer: '...' },
+  ];
+
+  return (
+    <InsetDrawer open={open} onClose={onClose} anchor="right" size="lg">
+      <Sheet sx={{ height: '100%', display: 'flex', flexDirection: 'column' }}>
+        <Box sx={{ p: 2, borderBottom: '1px solid', borderColor: 'divider' }}>
+          <DialogTitle>Help Center</DialogTitle>
+          <ModalClose />
+          <Input
+            placeholder="Search for help..."
+            startDecorator={<SearchIcon />}
+            value={searchQuery}
+            onChange={(e) => setSearchQuery(e.target.value)}
+            sx={{ mt: 2 }}
+          />
+        </Box>
+
+        <DialogContent sx={{ flex: 1, overflow: 'auto', p: 2 }}>
+          <Typography level="title-md" sx={{ mb: 2 }}>
+            Frequently Asked Questions
+          </Typography>
+          <Accordion>
+            {faqItems
+              .filter((item) =>
+                item.question.toLowerCase().includes(searchQuery.toLowerCase())
+              )
+              .map((item, index) => (
+                <AccordionItem key={index}>
+                  <AccordionSummary>{item.question}</AccordionSummary>
+                  <AccordionDetails>{item.answer}</AccordionDetails>
+                </AccordionItem>
+              ))}
+          </Accordion>
+        </DialogContent>
+
+        <Box sx={{ p: 2, borderTop: '1px solid', borderColor: 'divider' }}>
+          <Typography level="body-sm" sx={{ mb: 1 }}>
+            Can't find what you're looking for?
+          </Typography>
+          <Button fullWidth startDecorator={<ChatIcon />}>
+            Contact Support
+          </Button>
+        </Box>
+      </Sheet>
+    </InsetDrawer>
+  );
+}
+```
+
+## Props and Customization
+
+### Key Props
+
+| Prop       | Type                                     | Default  | Description                                      |
+| ---------- | ---------------------------------------- | -------- | ------------------------------------------------ |
+| `open`     | `boolean`                                | `false`  | Controls whether the drawer is visible           |
+| `onClose`  | `() => void`                             | -        | Callback fired when the drawer requests to close |
+| `anchor`   | `'left' \| 'right' \| 'top' \| 'bottom'` | `'left'` | Edge from which the drawer slides in             |
+| `size`     | `'sm' \| 'md' \| 'lg'`                   | `'md'`   | Size of the drawer                               |
+| `children` | `ReactNode`                              | -        | Content to render inside the drawer              |
+
+### Anchor Positions
+
+```tsx
+// Left drawer (navigation menus)
+<InsetDrawer anchor="left" open={open}>
+  <Sheet sx={{ width: 280 }}>Navigation</Sheet>
+</InsetDrawer>
+
+// Right drawer (details, filters)
+<InsetDrawer anchor="right" open={open}>
+  <Sheet sx={{ width: 400 }}>Details</Sheet>
+</InsetDrawer>
+
+// Top drawer (search, notifications)
+<InsetDrawer anchor="top" open={open}>
+  <Sheet sx={{ height: 200 }}>Search</Sheet>
+</InsetDrawer>
+
+// Bottom drawer (mobile actions)
+<InsetDrawer anchor="bottom" open={open}>
+  <Sheet sx={{ maxHeight: '80vh' }}>Actions</Sheet>
+</InsetDrawer>
+```
+
+### Size Options
+
+The `size` prop controls the width (for left/right anchors) or height (for top/bottom anchors):
+
+```tsx
+// Small drawer (~280px)
+<InsetDrawer size="sm" anchor="right" />
+
+// Medium drawer (~400px) - default
+<InsetDrawer size="md" anchor="right" />
+
+// Large drawer (~600px)
+<InsetDrawer size="lg" anchor="right" />
+```
+
+### Custom Sizing
+
+For more control, use `Sheet` with custom styles:
+
+```tsx
+<InsetDrawer open={open} anchor="right">
+  <Sheet sx={{ width: { xs: '100vw', sm: 450 }, height: '100%' }}>
+    Content
+  </Sheet>
+</InsetDrawer>
+```
+
+### Drawer Content Structure
+
+Use these components for consistent drawer layout:
+
+```tsx
+<InsetDrawer open={open}>
+  <Sheet sx={{ height: '100%', display: 'flex', flexDirection: 'column' }}>
+    {/* Header */}
+    <Box sx={{ p: 2, borderBottom: '1px solid', borderColor: 'divider' }}>
+      <DialogTitle>Drawer Title</DialogTitle>
+      <ModalClose />
+    </Box>
+
+    {/* Scrollable Content */}
+    <DialogContent sx={{ flex: 1, overflow: 'auto', p: 2 }}>
+      {/* Main content */}
+    </DialogContent>
+
+    {/* Footer */}
+    <Box sx={{ p: 2, borderTop: '1px solid', borderColor: 'divider' }}>
+      <Stack direction="row" gap={1}>
+        <Button variant="outlined">Cancel</Button>
+        <Button>Save</Button>
+      </Stack>
+    </Box>
+  </Sheet>
+</InsetDrawer>
+```
+
+## Accessibility
+
+InsetDrawer includes built-in accessibility features:
+
+### ARIA Attributes
+
+- Drawer container has appropriate `role="dialog"` or `role="presentation"`
+- Focus is trapped within the drawer when open
+- Proper `aria-modal` attribute when modal
+
+### Keyboard Navigation
+
+- **Escape**: Close the drawer
+- **Tab**: Navigate between focusable elements within drawer
+- **Shift + Tab**: Navigate backwards
+
+### Focus Management
+
+```tsx
+// Focus automatically moves to drawer content when opened
+<InsetDrawer
+  open={open}
+  onClose={onClose}
+  // Focus is trapped within drawer
+>
+  <Sheet>
+    {/* First focusable element receives focus */}
+    <Input autoFocus placeholder="Search..." />
+  </Sheet>
+</InsetDrawer>
+```
+
+### Screen Reader Support
+
+```tsx
+// Provide descriptive title for screen readers
+<InsetDrawer open={open}>
+  <Sheet role="dialog" aria-labelledby="drawer-title">
+    <DialogTitle id="drawer-title">Filters</DialogTitle>
+    {/* Content */}
+  </Sheet>
+</InsetDrawer>
+```
+
 ## Best Practices
 
-1. **Use appropriate anchor positions**: Match the drawer position to the content type for intuitive UX.
+### ✅ Do
+
+1. **Use appropriate anchor positions**: Match drawer position to content type
 
 ```tsx
-// ✅ Good: Navigation on the left, details on the right
-<InsetDrawer anchor="left">  {/* Navigation menu */}
-<InsetDrawer anchor="right"> {/* Detail panel or filters */}
-<InsetDrawer anchor="bottom">{/* Mobile action sheet */}
+// ✅ Good: Navigation on left, details on right
+<InsetDrawer anchor="left">  {/* Navigation */}
+<InsetDrawer anchor="right"> {/* Details/filters */}
+<InsetDrawer anchor="bottom">{/* Mobile actions */}
 ```
 
-2. **Provide clear close affordances**: Always give users multiple ways to close the drawer -- a close button, a cancel button, and backdrop click.
+2. **Provide clear close affordances**: Include close button and backdrop click
 
 ```tsx
-// ✅ Good: Multiple close methods
+// ✅ Good: Multiple ways to close
 <InsetDrawer open={open} onClose={handleClose}>
   <Sheet>
-    <ModalClose />
-    <Button onClick={handleClose}>Cancel</Button>
+    <ModalClose /> {/* X button */}
+    <Button onClick={handleClose}>Cancel</Button> {/* Cancel button */}
   </Sheet>
 </InsetDrawer>
 ```
 
-3. **Structure content consistently**: Use a header/body/footer layout with clear dividers so users can quickly scan the drawer's content.
+3. **Use consistent header/footer patterns**: Structure content predictably
 
 ```tsx
-// ✅ Good: Clear header/body/footer structure
-<Sheet sx={{ height: '100%', display: 'flex', flexDirection: 'column' }}>
-  <Box sx={{ p: 2, borderBottom: '1px solid', borderColor: 'divider' }}>
+// ✅ Good: Clear structure
+<Sheet>
+  <Box sx={{ borderBottom: '1px solid', borderColor: 'divider' }}>
     <DialogTitle>Title</DialogTitle>
     <ModalClose />
   </Box>
-  <DialogContent sx={{ flex: 1, overflow: 'auto', p: 2 }}>
-    {/* Scrollable content */}
-  </DialogContent>
-  <Box sx={{ p: 2, borderTop: '1px solid', borderColor: 'divider' }}>
-    <Button>Save</Button>
+  <DialogContent>{/* Scrollable content */}</DialogContent>
+  <Box sx={{ borderTop: '1px solid', borderColor: 'divider' }}>
+    {/* Action buttons */}
   </Box>
 </Sheet>
 ```
 
-4. **Do not nest drawers**: Opening a drawer inside another drawer creates a confusing experience.
+4. **Handle mobile responsiveness**: Full width on small screens
 
 ```tsx
-// ❌ Bad: Nested drawers
+// ✅ Good: Responsive width
+<Sheet sx={{ width: { xs: '100vw', sm: 400 } }}>
+```
+
+### ❌ Don't
+
+1. **Don't hide critical content**: Keep essential features accessible
+
+```tsx
+// ❌ Bad: Primary action hidden in drawer
 <InsetDrawer>
-  <InsetDrawer>{/* Avoid this pattern */}</InsetDrawer>
+  <Button>Complete Purchase</Button> {/* Should be on main page */}
 </InsetDrawer>
 ```
 
-5. **Do not use for confirmations**: Use Dialog or Modal for simple confirmation prompts. InsetDrawer is designed for rich, scrollable content.
+2. **Don't nest drawers**: Leads to confusing UX
 
-## Accessibility
+```tsx
+// ❌ Bad: Drawer within drawer
+<InsetDrawer>
+  <Button onClick={() => setNestedOpen(true)}>Open Another</Button>
+  <InsetDrawer open={nestedOpen}>{/* Nested drawer */}</InsetDrawer>
+</InsetDrawer>
+```
+
+3. **Don't use for confirmations**: Use Dialog instead
+
+```tsx
+// ❌ Bad: Drawer for confirmation
+<InsetDrawer>
+  <Typography>Are you sure?</Typography>
+  <Button>Confirm</Button>
+</InsetDrawer>
+
+// ✅ Good: Use Dialog
+<Dialog>
+  <Typography>Are you sure?</Typography>
+  <Button>Confirm</Button>
+</Dialog>
+```
+
+4. **Don't forget about keyboard users**: Ensure proper focus management
+
+## Performance Considerations
+
+### Lazy Loading Content
+
+For drawers with heavy content, load data when drawer opens:
+
+```tsx
+function DetailDrawer({ open, itemId }) {
+  const [data, setData] = useState(null);
+
+  useEffect(() => {
+    if (open && itemId) {
+      fetchItemDetails(itemId).then(setData);
+    }
+  }, [open, itemId]);
+
+  return (
+    <InsetDrawer open={open}>
+      <Sheet>
+        {data ? <ItemDetails data={data} /> : <Skeleton />}
+      </Sheet>
+    </InsetDrawer>
+  );
+}
+```
+
+### Memoize Handlers
+
+```tsx
+const handleClose = useCallback(() => {
+  setOpen(false);
+}, []);
+
+const handleApply = useCallback((filters) => {
+  applyFilters(filters);
+  setOpen(false);
+}, [applyFilters]);
+
+<InsetDrawer open={open} onClose={handleClose}>
+  <FilterPanel onApply={handleApply} />
+</InsetDrawer>
+```
+
+### Unmount When Closed
+
+For memory-intensive content, conditionally render:
+
+```tsx
+{open && (
+  <InsetDrawer open={open} onClose={handleClose}>
+    <HeavyContentComponent />
+  </InsetDrawer>
+)}
+```
+
+### Avoid Layout Shifts
+
+Use fixed dimensions to prevent content shifts:
+
+```tsx
+<Sheet sx={{
+  width: 400,
+  height: '100%',
+  // Content won't cause width changes
+}}>
+```
 
-- InsetDrawer traps focus within the drawer when open, ensuring keyboard users cannot accidentally interact with content behind it.
-- Pressing **Escape** closes the drawer, and **Tab** / **Shift+Tab** cycles through focusable elements inside.
-- Use `DialogTitle` with a matching `id` and `aria-labelledby` on the Sheet to provide a descriptive label for screen readers.
-- When the drawer closes, focus returns to the element that triggered it, maintaining a predictable navigation flow.
+InsetDrawer provides flexible secondary content areas that slide in from screen edges. Use it for navigation menus, filter panels, and detail views while keeping primary actions visible on the main screen. Always consider the user's workflow and ensure drawers enhance rather than hinder the experience.