torch-glare 2.1.5 → 2.2.0

package/docs/components/drawer.md

@@ -1,769 +1,628 @@
 ---
 title: Drawer
-description: Bottom sheet drawer component that slides up from the bottom of the screen for mobile-friendly interactions
+description: Gesture-based sliding panel built on Vaul. Anchors to the bottom, left, or right of the screen, supports nested/stacked drawers, and composes with SectionBlock + InputField to build create and edit forms.
 group: Overlays & Dialogs
-keywords: [drawer, bottom-sheet, slide-up, mobile, vaul, sheet]
+keywords: [drawer, sheet, side-panel, bottom-sheet, slide, vaul, form, create, edit, sectionblock, nested, drag-to-dismiss]
 ---
 
 # Drawer
 
-> A bottom sheet drawer component that slides up from the bottom of the screen. Perfect for mobile-friendly actions, forms, and content that doesn't need a full modal. Built with Vaul for smooth, gesture-based interactions.
+> A gesture-based sliding panel built on [Vaul](https://vaul.emilkowal.ski/). It can slide up from the **bottom**, in from the **right**, or in from the **left**. It supports drag-to-dismiss, nested/stacked drawers with an iOS-style scale-back effect, an optional "notch" tab on the top edge, and a dark framed "tray" look. It is the recommended surface for create / edit forms, filter panels, side navigation, action sheets, and full-screen editors.
+
+> [!IMPORTANT]
+> The Drawer is **composed**, not configured. There is no single `direction` style switch on `DrawerContent`. You pick the anchor on the root `<Drawer direction="...">` and then pass layout classes (`wrapperClassName`, `className`, `trayClassName`) plus a few flags (`framed`, `showHandle`, `notch`, `notchSide`) to get the bottom / right / left look. The recipes below give you exact, copy-paste class strings for each direction.
 
 ## Installation
 
 ```bash
-npm install vaul
+npx torch-glare@latest add Drawer
 ```
 
+The Drawer's only third-party dependency is [`vaul`](https://www.npmjs.com/package/vaul), which the CLI installs automatically.
+
+> [!NOTE]
+> **Building create / edit forms?** The Drawer ships on its own. The form examples on this page also use `SectionBlock`, `InputField`, and `Button`. Install them alongside it:
+>
+> ```bash
+> npx torch-glare@latest add Drawer SectionBlock InputField Button
+> ```
+>
+> These are *not* auto-installed by `add Drawer`, because `Drawer.tsx` does not import them — they are only needed for the form composition pattern, not for the Drawer itself.
+
 ## Import
 
-```typescript
+```tsx
 import {
   Drawer,
+  DrawerNested,
   DrawerTrigger,
+  DrawerClose,
   DrawerContent,
   DrawerHeader,
+  DrawerHeaderTitle,
+  DrawerHeaderActions,
+  DrawerBadge,
   DrawerFooter,
   DrawerTitle,
   DrawerDescription,
-  DrawerClose,
-} from '@torch-ui/components'
-```
-
-## Quick Examples
-
-### Basic Usage
-
-```typescript
-import { Drawer, DrawerTrigger, DrawerContent, DrawerHeader, DrawerTitle, DrawerDescription } from '@torch-ui/components'
-import { Button } from '@torch-ui/components'
-
-function Example() {
-  return (
-    <Drawer>
-      <DrawerTrigger asChild>
-        <Button>Open Drawer</Button>
-      </DrawerTrigger>
-      <DrawerContent>
-        <DrawerHeader>
-          <DrawerTitle>Drawer Title</DrawerTitle>
-          <DrawerDescription>
-            This is a drawer that slides up from the bottom.
-          </DrawerDescription>
-        </DrawerHeader>
-      </DrawerContent>
-    </Drawer>
-  )
-}
+  // Notch (the tab that sticks out of the top edge)
+  DrawerNotch,
+  DrawerNotchClose,
+  DrawerNotchPill,
+  DrawerNotchDivider,
+  DrawerNotchApp,
+  // Lower-level primitives (rarely needed directly)
+  DrawerPortal,
+  DrawerOverlay,
+} from "@/components/Drawer";
 ```
 
-### With Form
-
-```typescript
-import { Drawer, DrawerTrigger, DrawerContent, DrawerHeader, DrawerFooter, DrawerTitle, DrawerClose } from '@torch-ui/components'
-import { Button, Input } from '@torch-ui/components'
-
-function FormDrawer() {
-  const handleSubmit = (e: React.FormEvent) => {
-    e.preventDefault()
-    // Handle form submission
-  }
-
-  return (
-    <Drawer>
-      <DrawerTrigger asChild>
-        <Button>Add Comment</Button>
-      </DrawerTrigger>
-      <DrawerContent>
-        <form onSubmit={handleSubmit}>
-          <DrawerHeader>
-            <DrawerTitle>Add a Comment</DrawerTitle>
-            <DrawerDescription>
-              Share your thoughts about this post.
-            </DrawerDescription>
-          </DrawerHeader>
-
-          <div className="p-4 space-y-4">
-            <Input placeholder="Your name" />
-            <textarea
-              placeholder="Your comment"
-              className="w-full p-2 border rounded"
-              rows={4}
-            />
-          </div>
-
-          <DrawerFooter>
-            <Button type="submit">Submit</Button>
-            <DrawerClose asChild>
-              <Button variant="SecondaryStyle">Cancel</Button>
-            </DrawerClose>
-          </DrawerFooter>
-        </form>
-      </DrawerContent>
-    </Drawer>
-  )
-}
-```
-
-### Controlled State
-
-```typescript
-import { Drawer, DrawerContent, DrawerTitle } from '@torch-ui/components'
-import { useState } from 'react'
-
-function ControlledDrawer() {
-  const [open, setOpen] = useState(false)
-
-  return (
-    <>
-      <button onClick={() => setOpen(true)}>Open Drawer</button>
-      <Drawer open={open} onOpenChange={setOpen}>
-        <DrawerContent>
-          <DrawerTitle>Controlled Drawer</DrawerTitle>
-          <button onClick={() => setOpen(false)}>Close</button>
-        </DrawerContent>
-      </Drawer>
-    </>
-  )
-}
+## Anatomy
+
+```tsx
+<Drawer>                      {/* root — owns open state + direction */}
+  <DrawerTrigger />           {/* what opens the drawer (use asChild) */}
+  <DrawerContent>            {/* the panel; controls tray/frame/handle/notch */}
+    <DrawerHeader>
+      <DrawerHeaderTitle>    {/* dark pill holding the title + a badge */}
+        <DrawerBadge />
+        <DrawerTitle />
+      </DrawerHeaderTitle>
+      <DrawerHeaderActions /> {/* dark pill holding header buttons */}
+    </DrawerHeader>
+
+    {/* ...your body content... */}
+
+    <DrawerFooter>
+      <DrawerClose />          {/* anything that should close the drawer */}
+    </DrawerFooter>
+  </DrawerContent>
+</Drawer>
 ```
 
-### Action Sheet
-
-```typescript
-import { Drawer, DrawerTrigger, DrawerContent, DrawerHeader, DrawerTitle, DrawerClose } from '@torch-ui/components'
-import { Button } from '@torch-ui/components'
-
-function ActionSheet() {
-  const handleShare = (platform: string) => {
-    console.log('Sharing to', platform)
-  }
+## Quick Examples
 
-  return (
-    <Drawer>
-      <DrawerTrigger asChild>
-        <Button>Share</Button>
-      </DrawerTrigger>
-      <DrawerContent>
-        <DrawerHeader>
-          <DrawerTitle>Share this post</DrawerTitle>
-        </DrawerHeader>
-        <div className="p-4 space-y-2">
-          <DrawerClose asChild>
-            <button
-              onClick={() => handleShare('twitter')}
-              className="w-full p-3 text-left hover:bg-gray-100 rounded"
-            >
-              <i className="ri-twitter-line mr-2" />
-              Share on Twitter
-            </button>
-          </DrawerClose>
-          <DrawerClose asChild>
-            <button
-              onClick={() => handleShare('facebook')}
-              className="w-full p-3 text-left hover:bg-gray-100 rounded"
-            >
-              <i className="ri-facebook-line mr-2" />
-              Share on Facebook
-            </button>
-          </DrawerClose>
-          <DrawerClose asChild>
-            <button
-              onClick={() => handleShare('copy')}
-              className="w-full p-3 text-left hover:bg-gray-100 rounded"
-            >
-              <i className="ri-link mr-2" />
-              Copy Link
-            </button>
-          </DrawerClose>
-        </div>
-      </DrawerContent>
-    </Drawer>
-  )
-}
+### Basic (bottom sheet)
+
+The default. Slides up from the bottom with a drag handle. Use `framed={false}` for the clean sheet look (no dark tray border).
+
+```tsx
+<Drawer>
+  <DrawerTrigger asChild>
+    <Button variant="PrimeStyle">Open drawer</Button>
+  </DrawerTrigger>
+  <DrawerContent framed={false}>
+    <DrawerHeader>
+      <DrawerTitle>Basic drawer</DrawerTitle>
+      <DrawerDescription>
+        Drag the handle down or press Escape to close.
+      </DrawerDescription>
+    </DrawerHeader>
+
+    <div className="px-4 pb-4">
+      <p className="typography-body-small-regular text-content-presentation-action-light-secondary">
+        Put any content here — forms, lists, settings.
+      </p>
+    </div>
+
+    <DrawerFooter>
+      <DrawerClose asChild>
+        <Button variant="PrimeStyle">Done</Button>
+      </DrawerClose>
+      <DrawerClose asChild>
+        <Button variant="BorderStyle">Cancel</Button>
+      </DrawerClose>
+    </DrawerFooter>
+  </DrawerContent>
+</Drawer>
 ```
 
-### Product Details Drawer
-
-```typescript
-import { Drawer, DrawerTrigger, DrawerContent, DrawerHeader, DrawerTitle, DrawerDescription, DrawerFooter, DrawerClose } from '@torch-ui/components'
-import { Button, Badge } from '@torch-ui/components'
-
-function ProductDrawer({ product }: { product: Product }) {
-  return (
-    <Drawer>
-      <DrawerTrigger asChild>
-        <button className="w-full text-left p-4 border rounded hover:bg-gray-50">
-          <h3>{product.name}</h3>
-          <p>${product.price}</p>
-        </button>
-      </DrawerTrigger>
-      <DrawerContent>
-        <DrawerHeader>
-          <DrawerTitle>{product.name}</DrawerTitle>
-          <DrawerDescription>
-            <Badge variant="green" label={product.stock > 0 ? 'In Stock' : 'Out of Stock'} />
-          </DrawerDescription>
-        </DrawerHeader>
+### Create / Edit form (Drawer + SectionBlock)
 
-        <div className="p-4">
-          <img src={product.image} alt={product.name} className="w-full rounded-lg mb-4" />
-          <p className="text-2xl font-bold mb-2">${product.price}</p>
-          <p className="text-gray-600">{product.description}</p>
-        </div>
+This is the headline pattern: a **right-anchored** drawer that holds a form, grouped into `SectionBlock`s, with the inputs laid out as label-on-left / field-on-right rows. The same layout works for both **"New item"** (empty fields) and **"Edit item"** (pass `defaultValue` to each field and swap the badge/title).
 
-        <DrawerFooter>
-          <Button className="w-full">Add to Cart</Button>
-          <DrawerClose asChild>
-            <Button variant="SecondaryStyle" className="w-full">
-              Continue Shopping
-            </Button>
-          </DrawerClose>
-        </DrawerFooter>
-      </DrawerContent>
-    </Drawer>
-  )
-}
-```
-
-### Filter Drawer
-
-```typescript
-import { Drawer, DrawerTrigger, DrawerContent, DrawerHeader, DrawerTitle, DrawerFooter, DrawerClose } from '@torch-ui/components'
-import { Button, Checkbox } from '@torch-ui/components'
-import { useState } from 'react'
+```tsx
+import {
+  Drawer,
+  DrawerTrigger,
+  DrawerContent,
+  DrawerHeader,
+  DrawerHeaderTitle,
+  DrawerHeaderActions,
+  DrawerBadge,
+  DrawerTitle,
+  DrawerClose,
+  DrawerNotch,
+  DrawerNotchClose,
+  DrawerNotchPill,
+} from "@/components/Drawer";
+import { Button } from "@/components/Button";
+import { SectionBlock } from "@/components/SectionBlock";
+import { InputField } from "@/components/InputField";
 
-function FilterDrawer() {
-  const [filters, setFilters] = useState({
-    inStock: false,
-    onSale: false,
-    freeShipping: false,
-  })
+function ContactDrawer({ mode = "create", contact }) {
+  const isEdit = mode === "edit";
 
   return (
-    <Drawer>
+    <Drawer direction="right">
       <DrawerTrigger asChild>
-        <Button>
-          <i className="ri-filter-line mr-2" />
-          Filters
+        <Button variant="PrimeStyle">
+          {isEdit ? "Edit contact" : "New contact"}
         </Button>
       </DrawerTrigger>
-      <DrawerContent>
+
+      <DrawerContent
+        showHandle={false}
+        /* The top-edge notch: close button + "Open in new tab" pill. */
+        notch={
+          <DrawerNotch>
+            <DrawerClose asChild>
+              <DrawerNotchClose />
+            </DrawerClose>
+            <DrawerNotchPill color="Yellow">
+              Open in new tab
+              <i className="ri-arrow-right-up-line text-[12px]" />
+            </DrawerNotchPill>
+          </DrawerNotch>
+        }
+        wrapperClassName="top-2 right-2 bottom-2 left-auto mt-0 h-auto w-[1046px] max-w-[calc(100vw-16px)]"
+        /* With a notch, round all corners EXCEPT the top one the notch sits on. */
+        className="rounded-tr-[16px] rounded-b-[16px]"
+      >
+        {/* Header: badge flips New / Edit, actions live in their own dark pill */}
         <DrawerHeader>
-          <DrawerTitle>Filter Products</DrawerTitle>
+          <DrawerHeaderTitle>
+            <DrawerBadge color={isEdit ? "Yellow" : "Blue"}>
+              {isEdit ? "Edit" : "New"}
+            </DrawerBadge>
+            <DrawerTitle>Individual Contact</DrawerTitle>
+          </DrawerHeaderTitle>
+          <div className="flex items-center">
+            <Button variant="PrimeStyle" size="L">Save Draft</Button>
+          </div>
         </DrawerHeader>
 
-        <div className="p-4 space-y-4">
-          <label className="flex items-center gap-2">
-            <Checkbox
-              checked={filters.inStock}
-              onCheckedChange={(checked) =>
-                setFilters({ ...filters, inStock: !!checked })
+        {/* Scrollable body holds the grouped form sections */}
+        <div className="flex-1 overflow-y-auto px-12 py-6 space-y-3">
+          <SectionBlock
+            color="Blue"
+            containerClassName="w-full"
+            title={
+              <span className="flex items-center gap-[6px]">
+                <i className="ri-draft-fill" />
+                Identity
+              </span>
+            }
+          >
+            <FieldRow
+              label="Name"
+              required
+              right={
+                <div className="flex flex-1 min-w-0 items-center gap-3">
+                  <InputField
+                    placeholder="First Name*"
+                    defaultValue={contact?.firstName}
+                    className="flex-1 min-w-0"
+                  />
+                  <InputField
+                    placeholder="Last Name*"
+                    defaultValue={contact?.lastName}
+                    className="flex-1 min-w-0"
+                  />
+                </div>
               }
             />
-            <span>In Stock Only</span>
-          </label>
-          <label className="flex items-center gap-2">
-            <Checkbox
-              checked={filters.onSale}
-              onCheckedChange={(checked) =>
-                setFilters({ ...filters, onSale: !!checked })
+            <RowDivider />
+            <FieldRow
+              label="Email"
+              required
+              right={
+                <InputField
+                  type="email"
+                  placeholder="name@example.com"
+                  defaultValue={contact?.email}
+                  className="flex-1"
+                />
               }
             />
-            <span>On Sale</span>
-          </label>
-          <label className="flex items-center gap-2">
-            <Checkbox
-              checked={filters.freeShipping}
-              onCheckedChange={(checked) =>
-                setFilters({ ...filters, freeShipping: !!checked })
+            <RowDivider />
+            <FieldRow
+              label="Phone"
+              right={
+                <InputField
+                  placeholder="+1 555 0000"
+                  defaultValue={contact?.phone}
+                  className="flex-1"
+                />
               }
             />
-            <span>Free Shipping</span>
-          </label>
-        </div>
-
-        <DrawerFooter>
-          <Button>Apply Filters</Button>
-          <DrawerClose asChild>
-            <Button variant="SecondaryStyle">Reset</Button>
-          </DrawerClose>
-        </DrawerFooter>
-      </DrawerContent>
-    </Drawer>
-  )
-}
-```
-
-### Settings Drawer
-
-```typescript
-import { Drawer, DrawerTrigger, DrawerContent, DrawerHeader, DrawerTitle, DrawerDescription } from '@torch-ui/components'
-import { Switch } from '@torch-ui/components'
-import { useState } from 'react'
-
-function SettingsDrawer() {
-  const [settings, setSettings] = useState({
-    notifications: true,
-    darkMode: false,
-    autoPlay: true,
-  })
-
-  return (
-    <Drawer>
-      <DrawerTrigger asChild>
-        <button>
-          <i className="ri-settings-line text-2xl" />
-        </button>
-      </DrawerTrigger>
-      <DrawerContent>
-        <DrawerHeader>
-          <DrawerTitle>Settings</DrawerTitle>
-          <DrawerDescription>
-            Manage your preferences
-          </DrawerDescription>
-        </DrawerHeader>
-
-        <div className="p-4 space-y-4">
-          <div className="flex items-center justify-between">
-            <span>Notifications</span>
-            <Switch
-              checked={settings.notifications}
-              onCheckedChange={(checked) =>
-                setSettings({ ...settings, notifications: checked })
-              }
+          </SectionBlock>
+
+          <SectionBlock
+            color="Purple"
+            containerClassName="w-full"
+            title={
+              <span className="flex items-center gap-[6px]">
+                <i className="ri-map-pin-line" />
+                Address
+              </span>
+            }
+          >
+            <FieldRow
+              label="Street"
+              right={<InputField placeholder="123 Main St" className="flex-1" />}
             />
-          </div>
-          <div className="flex items-center justify-between">
-            <span>Dark Mode</span>
-            <Switch
-              checked={settings.darkMode}
-              onCheckedChange={(checked) =>
-                setSettings({ ...settings, darkMode: checked })
-              }
-            />
-          </div>
-          <div className="flex items-center justify-between">
-            <span>Auto-play Videos</span>
-            <Switch
-              checked={settings.autoPlay}
-              onCheckedChange={(checked) =>
-                setSettings({ ...settings, autoPlay: checked })
-              }
+            <RowDivider />
+            <FieldRow
+              label="City"
+              right={<InputField placeholder="San Francisco" className="flex-1" />}
             />
-          </div>
+          </SectionBlock>
         </div>
       </DrawerContent>
     </Drawer>
-  )
+  );
 }
-```
-
-### Confirmation Drawer
 
-```typescript
-import { Drawer, DrawerTrigger, DrawerContent, DrawerHeader, DrawerTitle, DrawerDescription, DrawerFooter, DrawerClose } from '@torch-ui/components'
-import { Button } from '@torch-ui/components'
-
-function ConfirmationDrawer({ onConfirm }: { onConfirm: () => void }) {
+/* Reusable label-on-left / field-on-right row. */
+function FieldRow({ label, required, right }) {
   return (
-    <Drawer>
-      <DrawerTrigger asChild>
-        <Button variant="DestructiveStyle">Delete Item</Button>
-      </DrawerTrigger>
-      <DrawerContent>
-        <DrawerHeader>
-          <DrawerTitle>Confirm Deletion</DrawerTitle>
-          <DrawerDescription>
-            This action cannot be undone. This will permanently delete the item.
-          </DrawerDescription>
-        </DrawerHeader>
-
-        <DrawerFooter>
-          <DrawerClose asChild>
-            <Button variant="DestructiveStyle" onClick={onConfirm}>
-              Yes, Delete
-            </Button>
-          </DrawerClose>
-          <DrawerClose asChild>
-            <Button variant="SecondaryStyle">Cancel</Button>
-          </DrawerClose>
-        </DrawerFooter>
-      </DrawerContent>
-    </Drawer>
-  )
+    <div className="flex items-center gap-6 py-[18px]">
+      <div className="flex w-[180px] shrink-0 items-center gap-[6px]">
+        <span className="typography-body-medium-regular text-content-presentation-action-light-primary">
+          {label}
+        </span>
+        {required && (
+          <span className="typography-body-small-medium text-content-presentation-state-negative">
+            (Required)
+          </span>
+        )}
+      </div>
+      <div className="flex flex-1 min-w-0 items-center">{right}</div>
+    </div>
+  );
 }
-```
-
-### Scrollable Content
 
-```typescript
-import { Drawer, DrawerTrigger, DrawerContent, DrawerHeader, DrawerTitle, DrawerFooter } from '@torch-ui/components'
-import { Button, ScrollArea } from '@torch-ui/components'
-
-function ScrollableDrawer() {
-  const items = Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`)
-
-  return (
-    <Drawer>
-      <DrawerTrigger asChild>
-        <Button>View List</Button>
-      </DrawerTrigger>
-      <DrawerContent>
-        <DrawerHeader>
-          <DrawerTitle>Long List</DrawerTitle>
-        </DrawerHeader>
-
-        <ScrollArea className="h-96">
-          <div className="p-4 space-y-2">
-            {items.map((item) => (
-              <div key={item} className="p-2 border-b">
-                {item}
-              </div>
-            ))}
-          </div>
-        </ScrollArea>
-
-        <DrawerFooter>
-          <Button>Done</Button>
-        </DrawerFooter>
-      </DrawerContent>
-    </Drawer>
-  )
+/* Thin separator between rows inside a SectionBlock. */
+function RowDivider() {
+  return <div className="h-px w-full bg-border-presentation-global-primary" />;
 }
 ```
 
-### Without Background Scale
-
-```typescript
-import { Drawer, DrawerTrigger, DrawerContent, DrawerTitle } from '@torch-ui/components'
-
-function NoScaleDrawer() {
-  return (
-    <Drawer shouldScaleBackground={false}>
-      <DrawerTrigger asChild>
-        <button>Open (No Scale)</button>
-      </DrawerTrigger>
-      <DrawerContent>
-        <DrawerTitle>Drawer without background scaling</DrawerTitle>
-        <p className="p-4">The background won't scale when this opens.</p>
-      </DrawerContent>
-    </Drawer>
-  )
-}
+> **Create vs. Edit in one component.** Keep a single drawer and branch on a `mode` prop:
+> - **Badge / title** — `<DrawerBadge color={isEdit ? "Yellow" : "Blue"}>{isEdit ? "Edit" : "New"}</DrawerBadge>`.
+> - **Fields** — spread the existing record into each input's `defaultValue` (or `value` if controlled). Empty in create mode, pre-filled in edit mode.
+> - **Footer / actions** — keep "Save Draft" / "Save" identical; only the submit handler changes (POST vs. PATCH).
+
+### Nested drawers (multi-step)
+
+`DrawerNested` must live **inside** an already-open `DrawerContent`. The parent scales down and slides back; the child slides in on top. Great for `cart → shipping → payment` style flows or drill-down settings.
+
+```tsx
+<Drawer>
+  <DrawerTrigger asChild>
+    <Button variant="PrimeStyle">Checkout</Button>
+  </DrawerTrigger>
+  <DrawerContent framed={false}>
+    <DrawerHeader>
+      <DrawerTitle>Your cart</DrawerTitle>
+      <DrawerDescription>1 item — $129.00</DrawerDescription>
+    </DrawerHeader>
+
+    <DrawerFooter>
+      <DrawerNested>
+        <DrawerTrigger asChild>
+          <Button variant="PrimeStyle">Continue to shipping</Button>
+        </DrawerTrigger>
+        <DrawerContent framed={false}>
+          <DrawerHeader>
+            <DrawerTitle>Shipping</DrawerTitle>
+          </DrawerHeader>
+          {/* ...another DrawerNested inside here for payment... */}
+        </DrawerContent>
+      </DrawerNested>
+    </DrawerFooter>
+  </DrawerContent>
+</Drawer>
 ```
 
-## API Reference
-
-### Drawer (Root)
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `open` | `boolean` | - | Controlled open state |
-| `onOpenChange` | `(open: boolean) => void` | - | Callback when open state changes |
-| `defaultOpen` | `boolean` | `false` | Uncontrolled default open state |
-| `shouldScaleBackground` | `boolean` | `true` | Whether to scale and blur background |
-| `modal` | `boolean` | `true` | Whether to render as modal |
-
-### DrawerTrigger
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `asChild` | `boolean` | `false` | Render trigger as child element |
+### Notch (top-edge tab)
+
+The notch is an optional tab that sticks out of the top edge of the drawer — used for a close button plus an "Open in new tab" / "Open in the app" affordance. Pass it to `DrawerContent` via the `notch` prop. When a notch is present, hide the drag handle (`showHandle={false}`) and use the asymmetric corner rounding (`className="rounded-tr-[16px] rounded-b-[16px]"` for a right drawer) so the panel tucks under the notch.
+
+**Simple notch** — close button + "Open in new tab" pill. This is the most common form, used on the create/edit drawer above:
+
+```tsx
+<DrawerContent
+  showHandle={false}
+  className="rounded-tr-[16px] rounded-b-[16px]"
+  notch={
+    <DrawerNotch>
+      <DrawerClose asChild>
+        <DrawerNotchClose />
+      </DrawerClose>
+      <DrawerNotchPill color="Yellow">
+        Open in new tab
+        <i className="ri-arrow-right-up-line text-[12px]" />
+      </DrawerNotchPill>
+    </DrawerNotch>
+  }
+>
+  {/* ... */}
+</DrawerContent>
+```
 
-### DrawerContent
+**App notch** — adds an app icon + name and a colored "Open in the app" pill, separated by a divider:
+
+```tsx
+<DrawerContent
+  showHandle={false}
+  className="rounded-tr-[16px] rounded-b-[16px]"
+  notch={
+    <DrawerNotch>
+      <DrawerClose asChild>
+        <DrawerNotchClose />
+      </DrawerClose>
+      <DrawerNotchDivider />
+      <DrawerNotchApp
+        icon={<i className="ri-customer-service-2-fill text-white text-[14px]" />}
+        name="Sales & Services App"
+      />
+      <DrawerNotchPill color="Blue">
+        Open in the app
+        <i className="ri-arrow-right-up-line text-[12px]" />
+      </DrawerNotchPill>
+    </DrawerNotch>
+  }
+>
+  {/* ... */}
+</DrawerContent>
+```
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `className` | `string` | - | Additional CSS classes |
-| `onPointerDownOutside` | `(event) => void` | - | Callback when clicking outside |
-| `onEscapeKeyDown` | `(event) => void` | - | Callback when Escape is pressed |
+#### What "Open in new tab" does
 
-### DrawerHeader, DrawerFooter
+> [!IMPORTANT]
+> **`DrawerNotchPill` has no built-in navigation — it is a styled `<button>`.** The "Open in new tab" interaction is a pattern *you* wire up. The intended behavior is:
+>
+> **Clicking "Open in new tab" opens the *same content* the drawer is showing, but as a standalone full page (its own route) in a new browser tab — not as a drawer.**
+>
+> The drawer is the *quick/inline* way to view or edit a record; the full page is the *expanded* view of the exact same thing (same form, same data), just rendered at full width instead of in the side panel. So a "New contact" drawer opens a full-page "New contact" form; an "Edit contact #42" drawer opens the full-page edit route for contact 42.
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `className` | `string` | - | Additional CSS classes |
+**How to wire it.** Point the pill at the route that renders the same section as a page, and open it in a new tab. `DrawerNotchPill` forwards all button props, so use `onClick`:
 
-### DrawerTitle
+```tsx
+// `href` is the full-page route that renders the SAME section/form as the drawer.
+// For an edit drawer, include the record id so the page opens pre-filled:
+//   const href = isEdit ? `/contacts/${contact.id}/edit` : "/contacts/new";
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `className` | `string` | - | Additional CSS classes |
-
-### DrawerDescription
+<DrawerNotchPill
+  color="Yellow"
+  onClick={() => window.open(href, "_blank", "noopener")}
+>
+  Open in new tab
+  <i className="ri-arrow-right-up-line text-[12px]" />
+</DrawerNotchPill>
+```
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `className` | `string` | - | Additional CSS classes |
+Or, if you prefer a real anchor (better for middle-click / "copy link"), wrap a styled link instead of the pill — the pill is just a button, so for true link semantics render your own `<a target="_blank">` with the same classes, or in Next.js:
 
-### DrawerClose
+```tsx
+import Link from "next/link";
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `asChild` | `boolean` | `false` | Render close trigger as child |
+<Link href={href} target="_blank" rel="noopener" className="contents">
+  <DrawerNotchPill color="Yellow" tabIndex={-1}>
+    Open in new tab
+    <i className="ri-arrow-right-up-line text-[12px]" />
+  </DrawerNotchPill>
+</Link>
+```
 
-## TypeScript
+**The contract:** the drawer and the full page must render the **same section component** with the **same data**. Build the form body (the `SectionBlock` groups + fields) as a shared component, drop it into the `DrawerContent` for the inline view and into a normal page route for the full-page view. That guarantees "open in new tab" shows an identical form — just full-page instead of in the drawer.
 
-### Full Type Definitions
+> The **"Open in the app"** pill (App notch) follows the same idea but targets a different surface — e.g. a deep link into a separate application — rather than a full-page route in the same app.
 
-```typescript
-import { Drawer as DrawerPrimitive } from 'vaul'
+## Direction — how bottom, right, and left differ
 
-// Root component
-interface DrawerProps extends React.ComponentProps<typeof DrawerPrimitive.Root> {
-  shouldScaleBackground?: boolean
-  open?: boolean
-  onOpenChange?: (open: boolean) => void
-  defaultOpen?: boolean
-  modal?: boolean
-  children: React.ReactNode
-}
+There is **no automatic per-direction styling**. The anchor is set on the root with `direction`, and the *look* (where it sits, which corners round, whether there's a drag handle or a frame) comes from props you pass to `DrawerContent`. Here is exactly what changes per direction and the copy-paste recipe for each.
 
-export const Drawer: React.FC<DrawerProps>
+| Aspect | Bottom (default) | Right | Left |
+|---|---|---|---|
+| Root prop | _(none)_ | `direction="right"` | `direction="left"` |
+| Sits at | full width, pinned to bottom | floating panel on the right | floating panel on the left |
+| Drag handle | **shown** (`showHandle` default `true`) | hidden (`showHandle={false}`) | hidden (`showHandle={false}`) |
+| Frame / tray | usually off (`framed={false}`) for clean sheet | on (default) for the dark tray | on (default) |
+| Rounded corners | top corners only | all/left corners | top-left + bottom corners |
+| Notch side | top-left (`notchSide="left"`) | top-left | mirror to `notchSide="right"` |
+| Best for | mobile sheets, action sheets, comments | create/edit forms, filters, detail panels | RTL panels, side navigation |
 
-// Compound components
-export const DrawerTrigger: React.ForwardRefExoticComponent<
-  React.ComponentPropsWithoutRef<typeof DrawerPrimitive.Trigger>
->
+### Bottom (default)
 
-export const DrawerContent: React.ForwardRefExoticComponent<
-  React.ComponentPropsWithoutRef<typeof DrawerPrimitive.Content>
->
+No `direction` prop. Keep the drag handle; drop the frame for a clean sheet.
 
-export const DrawerHeader: React.FC<React.HTMLAttributes<HTMLDivElement>>
-export const DrawerFooter: React.FC<React.HTMLAttributes<HTMLDivElement>>
-export const DrawerTitle: React.ForwardRefExoticComponent<
-  React.ComponentPropsWithoutRef<typeof DrawerPrimitive.Title>
->
-export const DrawerDescription: React.ForwardRefExoticComponent<
-  React.ComponentPropsWithoutRef<typeof DrawerPrimitive.Description>
->
-export const DrawerClose: React.ForwardRefExoticComponent<
-  React.ComponentPropsWithoutRef<typeof DrawerPrimitive.Close>
->
+```tsx
+<Drawer>
+  <DrawerTrigger asChild>
+    <Button variant="PrimeStyle">Open bottom sheet</Button>
+  </DrawerTrigger>
+  <DrawerContent framed={false}>
+    {/* drag handle appears automatically */}
+    <DrawerHeader>
+      <DrawerTitle>Comments</DrawerTitle>
+    </DrawerHeader>
+    {/* ... */}
+  </DrawerContent>
+</Drawer>
 ```
 
-## Common Patterns
-
-### useDrawer Hook
-
-```typescript
-import { useState } from 'react'
-
-function useDrawer() {
-  const [open, setOpen] = useState(false)
+**Half-screen / snap points** — the bottom drawer can open to half height then snap to full. Drive it with Vaul's `snapPoints` on the root:
 
-  const openDrawer = () => setOpen(true)
-  const closeDrawer = () => setOpen(false)
-  const toggleDrawer = () => setOpen(!open)
-
-  return {
-    open,
-    setOpen,
-    openDrawer,
-    closeDrawer,
-    toggleDrawer,
-  }
-}
-
-// Usage
-function App() {
-  const drawer = useDrawer()
-
-  return (
-    <>
-      <button onClick={drawer.openDrawer}>Open</button>
-      <Drawer open={drawer.open} onOpenChange={drawer.setOpen}>
-        <DrawerContent>Content</DrawerContent>
-      </Drawer>
-    </>
-  )
-}
+```tsx
+<Drawer snapPoints={[0.5, 1]} fadeFromIndex={1}>
+  <DrawerTrigger asChild>
+    <Button variant="PrimeStyle">Open half-screen</Button>
+  </DrawerTrigger>
+  <DrawerContent framed={false} wrapperClassName="h-full max-h-[97vh]">
+    {/* ... */}
+  </DrawerContent>
+</Drawer>
 ```
 
-## Gesture Features
+### Right
+
+A floating panel anchored to the right edge — the canonical home for create/edit forms and filter panels. Hide the handle, anchor with `wrapperClassName`, round the corners.
+
+```tsx
+<Drawer direction="right">
+  <DrawerTrigger asChild>
+    <Button variant="PrimeStyle">Open right drawer</Button>
+  </DrawerTrigger>
+  <DrawerContent
+    showHandle={false}
+    wrapperClassName="top-2 right-2 bottom-2 left-auto mt-0 h-auto w-[420px] max-w-[calc(100vw-16px)]"
+    trayClassName="rounded-[16px]"
+    className="rounded-[10px]"
+  >
+    <DrawerHeader>
+      <DrawerTitle>Filters</DrawerTitle>
+      <DrawerDescription>Status, owner, tags, priority…</DrawerDescription>
+    </DrawerHeader>
+    <div className="px-4 pb-4 space-y-3 flex-1 overflow-y-auto">
+      {/* ...filter rows... */}
+    </div>
+    <DrawerFooter>
+      <DrawerClose asChild>
+        <Button variant="PrimeStyle">Apply</Button>
+      </DrawerClose>
+      <DrawerClose asChild>
+        <Button variant="BorderStyle">Reset</Button>
+      </DrawerClose>
+    </DrawerFooter>
+  </DrawerContent>
+</Drawer>
+```
 
-### Drag to Close
-- Users can drag the drawer down to close it
-- Smooth spring animation follows finger/pointer
-- Automatic threshold detection for close vs. snap-back
+> Widen `w-[420px]` to `w-[1046px]` (as in the form example) for a roomy two-column form. Always pair a fixed width with `max-w-[calc(100vw-16px)]` so it never overflows on small screens.
+
+### Left (RTL / navigation)
+
+Mirror of the right recipe: `direction="left"`, anchor to the left edge, and if you use a notch, set `notchSide="right"` so the tab mirrors correctly.
+
+```tsx
+<Drawer direction="left">
+  <DrawerTrigger asChild>
+    <Button variant="PrimeStyle">Open left drawer</Button>
+  </DrawerTrigger>
+  <DrawerContent
+    showHandle={false}
+    notchSide="right"
+    wrapperClassName="top-2 left-2 bottom-2 right-auto mt-0 h-auto w-[420px] max-w-[calc(100vw-16px)]"
+    className="rounded-tl-[16px] rounded-b-[16px]"
+    notch={
+      <DrawerNotch>
+        <DrawerClose asChild>
+          <DrawerNotchClose />
+        </DrawerClose>
+        <DrawerNotchPill color="Yellow">
+          Open in new tab
+          <i className="ri-arrow-right-up-line text-[12px]" />
+        </DrawerNotchPill>
+      </DrawerNotch>
+    }
+  >
+    <DrawerHeader>
+      <DrawerHeaderTitle>
+        <DrawerBadge color="Purple">Menu</DrawerBadge>
+        <DrawerTitle>Navigation</DrawerTitle>
+      </DrawerHeaderTitle>
+    </DrawerHeader>
+    {/* ...nav items... */}
+  </DrawerContent>
+</Drawer>
+```
 
-### Snap Points (Advanced)
-```typescript
-// Vaul supports snap points for partial drawer heights
-<Drawer snapPoints={[0.5, 1]} activeSnapPoint={1}>
-  <DrawerContent>Content</DrawerContent>
+### Full-screen
+
+Anchor a bottom drawer to every edge via `wrapperClassName`.
+
+```tsx
+<Drawer>
+  <DrawerTrigger asChild>
+    <Button variant="PrimeStyle">Open full-screen</Button>
+  </DrawerTrigger>
+  <DrawerContent
+    framed={false}
+    wrapperClassName="inset-x-0 top-0 bottom-0 m-0 h-screen w-screen max-w-none"
+  >
+    {/* immersive editor / media viewer */}
+  </DrawerContent>
 </Drawer>
 ```
 
-## Testing
+## API Reference
 
-### Unit Test Example
+### `Drawer` (root)
 
-```typescript
-import { render, screen, fireEvent } from '@testing-library/react'
-import { Drawer, DrawerTrigger, DrawerContent, DrawerTitle } from '@torch-ui/components'
+Wraps Vaul's `Drawer.Root` and defaults `shouldScaleBackground` to `true`. Accepts all [Vaul Root props](https://vaul.emilkowal.ski/api).
 
-describe('Drawer', () => {
-  it('opens when trigger is clicked', () => {
-    render(
-      <Drawer>
-        <DrawerTrigger>Open</DrawerTrigger>
-        <DrawerContent>
-          <DrawerTitle>Test Drawer</DrawerTitle>
-        </DrawerContent>
-      </Drawer>
-    )
-
-    fireEvent.click(screen.getByText('Open'))
-    expect(screen.getByText('Test Drawer')).toBeInTheDocument()
-  })
-
-  it('closes on close button click', () => {
-    render(
-      <Drawer defaultOpen>
-        <DrawerContent>
-          <DrawerTitle>Test</DrawerTitle>
-          <DrawerClose>Close</DrawerClose>
-        </DrawerContent>
-      </Drawer>
-    )
-
-    fireEvent.click(screen.getByText('Close'))
-    expect(screen.queryByText('Test')).not.toBeInTheDocument()
-  })
-
-  it('handles controlled state', () => {
-    const handleChange = jest.fn()
-
-    render(
-      <Drawer onOpenChange={handleChange}>
-        <DrawerTrigger>Open</DrawerTrigger>
-        <DrawerContent>Content</DrawerContent>
-      </Drawer>
-    )
-
-    fireEvent.click(screen.getByText('Open'))
-    expect(handleChange).toHaveBeenCalledWith(true)
-  })
-})
-```
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `direction` | `"bottom" \| "top" \| "left" \| "right"` | `"bottom"` | Edge the drawer slides in from. |
+| `shouldScaleBackground` | `boolean` | `true` | Scales/pushes the page back when open (the iOS sheet effect). |
+| `open` | `boolean` | — | Controlled open state. |
+| `onOpenChange` | `(open: boolean) => void` | — | Fires when open state changes. |
+| `snapPoints` | `(number \| string)[]` | — | Snap stops, e.g. `[0.5, 1]` for half then full. |
+| `fadeFromIndex` | `number` | — | Snap index from which the overlay starts to fade. |
+| `nested` | `boolean` | — | Prefer the `DrawerNested` component instead. |
 
-## Accessibility
-
-- **Keyboard Support**:
-  - Escape: Close drawer
-  - Tab: Navigate focusable elements
-  - Shift+Tab: Navigate backwards
-- **ARIA Attributes**:
-  - `role="dialog"` automatically applied
-  - `aria-labelledby` links to title
-  - `aria-describedby` links to description
-- **Focus Management**:
-  - Focus trapped within drawer when open
-  - Focus returned to trigger on close
-- **Touch/Pointer**: Gesture-based closing with drag down
-
-### Accessibility Best Practices
-
-```typescript
-// Always provide a title
-<DrawerContent>
-  <DrawerTitle>Drawer Title</DrawerTitle> {/* Required */}
-  <DrawerDescription>Description</DrawerDescription>
-</DrawerContent>
+### `DrawerContent`
 
-// Ensure close affordance
-<DrawerClose asChild>
-  <Button aria-label="Close drawer">Close</Button>
-</DrawerClose>
-```
+The panel. This is where direction-specific styling is applied.
 
-## Performance
-
-| Metric | Value |
-|--------|-------|
-| Bundle size (minified) | ~6kb |
-| Bundle size (gzipped) | ~2.5kb |
-| Dependencies | vaul (~8kb) |
-| Animation | Hardware accelerated |
-| Gesture latency | <16ms (60fps) |
-| Tree-shakeable | ✅ |
-
-### Performance Tips
-
-1. **Lazy load content**: Render content only when open
-   ```typescript
-   {open && <DrawerContent>{/* Heavy content */}</DrawerContent>}
-   ```
-
-2. **Use CSS transforms**: Already optimized by Vaul
-3. **Avoid heavy renders**: Memoize drawer content
-   ```typescript
-   const DrawerBody = useMemo(() => <HeavyComponent />, [deps])
-   ```
-
-## Migration from Dialog
-
-```diff
-- import { Dialog, DialogTrigger, DialogContent } from '@torch-ui/components'
-+ import { Drawer, DrawerTrigger, DrawerContent } from '@torch-ui/components'
-
-- <Dialog>
--   <DialogTrigger>Open</DialogTrigger>
--   <DialogContent>Content</DialogContent>
-- </Dialog>
-
-+ <Drawer>
-+   <DrawerTrigger>Open</DrawerTrigger>
-+   <DrawerContent>Content</DrawerContent>
-+ </Drawer>
-```
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `framed` | `boolean` | `true` | Show the dark "tray" frame (border + inset shadow) around the panel. Set `false` for clean bottom sheets. |
+| `showHandle` | `boolean` | `true` | Show the centered drag handle. Auto-hidden when a `notch` is present. Set `false` for side drawers. |
+| `notch` | `ReactNode` | — | A `DrawerNotch` tab rendered on the top edge. |
+| `notchSide` | `"left" \| "right"` | `"left"` | Which side the notch attaches to (and which corner stays square). Use `"right"` for left-anchored drawers. |
+| `wrapperClassName` | `string` | — | Classes on the outer positioned element — this is how you anchor/size the panel per direction. |
+| `trayClassName` | `string` | — | Classes on the dark tray frame (e.g. corner rounding). |
+| `className` | `string` | — | Classes on the inner light content surface. |
+| `...props` | Vaul `Content` props | — | Forwarded to `Drawer.Content`. |
+
+### Sub-components
+
+| Component | Description |
+|---|---|
+| `DrawerTrigger` | Opens the drawer. Use `asChild` to wrap your own button. |
+| `DrawerClose` | Closes the drawer. Use `asChild` to wrap any element. |
+| `DrawerNested` | A nested/stacked drawer. Must be rendered inside an open `DrawerContent`. |
+| `DrawerHeader` | Header row (space-between layout) holding title + actions. |
+| `DrawerHeaderTitle` | Dark rounded pill that groups a `DrawerBadge` + `DrawerTitle`. |
+| `DrawerHeaderActions` | Dark rounded pill (right-aligned) for header buttons. |
+| `DrawerTitle` | Accessible title (maps to Vaul `Drawer.Title`). |
+| `DrawerDescription` | Muted supporting text (maps to Vaul `Drawer.Description`). |
+| `DrawerBadge` | Small uppercase status pill. `color`: `Blue \| Green \| Red \| Yellow \| Purple \| Gray` (default `Blue`). |
+| `DrawerFooter` | Bottom action area (`mt-auto`, stacked). |
+| `DrawerNotch` | The top-edge tab container. `side`: `"left" \| "right"`. |
+| `DrawerNotchClose` | Round close button for inside a notch. |
+| `DrawerNotchPill` | Pill button for inside a notch. `color`: `Yellow \| Blue \| Gray` (default `Yellow`). Styled `<button>` only — wire navigation yourself via `onClick` (see ["What 'Open in new tab' does"](#what-open-in-new-tab-does)). |
+| `DrawerNotchDivider` | Thin vertical divider between notch items. |
+| `DrawerNotchApp` | App identity block (icon + name) for inside a notch. Props: `icon?`, `name`. |
+| `DrawerPortal` / `DrawerOverlay` | Lower-level primitives; rarely used directly. |
 
 ## Best Practices
 
-1. **Use on mobile/tablet**: Drawer is better than dialog on touch devices
-   ```typescript
-   const isMobile = useMediaQuery('(max-width: 768px)')
-   return isMobile ? <Drawer /> : <Dialog />
-   ```
-
-2. **Keep height reasonable**: Don't make drawers full-screen height
-   ```typescript
-   <DrawerContent className="max-h-[80vh]">
-   ```
-
-3. **Provide visual drag handle**: Built-in drag indicator included
-   ```typescript
-   // Automatic drag handle bar rendered at top
-   ```
-
-4. **Use for actions and forms**: Perfect for quick interactions
-   ```typescript
-   // Good: Share sheet, filters, settings
-   // Avoid: Long articles, complex wizards
-   ```
-
-5. **Handle background scroll**: Automatically prevents scroll
-   ```typescript
-   // Background scroll blocked when drawer is open
-   ```
-
-6. **Test gesture interactions**: Ensure drag-to-close works smoothly
-   ```typescript
-   // Test on actual touch devices
-   ```
-
-7. **Provide close button**: Don't rely solely on gesture
-   ```typescript
-   <DrawerClose asChild>
-     <Button>Done</Button>
-   </DrawerClose>
-   ```
+- **Pick the anchor by job.** Bottom for mobile sheets / action sheets / comments; right for create-edit forms and filter/detail panels; left for RTL panels and side navigation.
+- **Side drawers: hide the handle.** Always pass `showHandle={false}` on left/right drawers — the drag handle only makes sense on a bottom sheet.
+- **Always cap the width.** Pair any fixed `w-[…]` with `max-w-[calc(100vw-16px)]` so the panel never overflows narrow viewports.
+- **One drawer for create *and* edit.** Branch on a `mode` prop for the badge/title and feed `defaultValue`/`value` from the record. Don't build two near-identical drawers.
+- **Group form fields with `SectionBlock`.** Use a colored `SectionBlock` per logical group (Identity, Address, …) and the `FieldRow` / `RowDivider` helpers for consistent label/field rows.
+- **Make the body scroll, not the panel.** Put `flex-1 overflow-y-auto` on the body wrapper so the header/footer stay pinned while content scrolls.
+- **`DrawerNested` only inside an open drawer.** It will not work as a standalone trigger.
 
 ## Related Components
 
-- [Dialog](./dialog.md) - Desktop-oriented modal alternative
-- [AlertDialog](./alert-dialog.md) - For confirmations
-- [Popover](./popover.md) - Smaller contextual overlays
+- **[Dialog](./dialog.md)** — centered modal for short confirmations and compact forms.
+- **[AlertDialog](./alert-dialog.md)** — blocking confirmation for destructive actions.
+- **[SectionBlock](./section-block.md)** — the grouping container used for the form body above.
+- **[InputField](./input-field.md)** — the input used in the form rows.