@gradeui/ui 1.0.0 → 1.1.0

package/components/ui/sheet.md

@@ -6,16 +6,24 @@ props:
   - Sheet: open?, defaultOpen?, onOpenChange?, modal? (default true)
   - SheetTrigger: asChild?: boolean
   - SheetContent: side? "top" | "right" | "bottom" | "left" (default "right")
+  - SheetContent: surface? (solid | translucent | glass | glass-strong) — what the sheet panel is *made of*. `solid` is the default opaque `bg-background`. Reach for `glass` whenever the canvas behind the sheet (a layout in progress, a media gallery, a dashboard) should remain visible.
   - SheetContent: className?: string — usually set a width (right/left) or height (top/bottom)
   - SheetTitle / SheetDescription: identify the sheet to screen readers; required for accessibility even if visually styled differently
   - SheetClose: asChild? — usually wraps a Button labelled Cancel or Done
-when_to_use: A panel that slides in from a screen edge — mobile nav drawers, side panels for editing a single record without leaving the list, filter trays on small viewports. For a centered focus modal use Dialog. For a transient announcement use Toast (Sonner). For inline reveals use Collapsible.
-composes_with: [Form controls (an inline edit sheet), Button (trigger + close), AppShellNav (mobile-only swap)]
-aliases: [sheet, drawer, side panel, slide-in, nav drawer, mobile drawer, slide-over, action sheet, modal sheet, bottom sheet, side sheet, react native modal sheet, bottom-sheet, ios action sheet]
+when_to_use: A panel that slides in from a screen edge — mobile nav drawers, side panels for editing a single record without leaving the list, filter trays on small viewports, Studio-style inspector panels. For a centered focus modal use Dialog. For a transient announcement use Toast (Sonner). For inline reveals use Collapsible.
+composes_with: [Form controls (an inline edit sheet), Button (trigger + close), AppShellNav (mobile-only swap), Code (changelog drawers), MediaSurface (image-detail sheets)]
+aliases: [sheet, drawer, side panel, slide-in, nav drawer, mobile drawer, slide-over, action sheet, modal sheet, bottom sheet, side sheet, react native modal sheet, bottom-sheet, ios action sheet, inspector panel, glass sheet, frosted drawer]
 ---
 
+SheetContent sits at elevation-5. The `surface` axis controls material independently of `side` (which controls layout direction) — every combination is valid.
+
+---
+
+### Scenario 1 — Edit-record drawer (default opaque)
+
+A right-edge drawer that lets a user edit one record without losing their place in a list. The list is the user's context — the drawer doesn't need to blur it; it just needs to be visibly distinct.
+
 ```jsx
-// Edit-record drawer from the right edge.
 <Sheet>
   <SheetTrigger asChild>
     <Button variant="outline">Edit user</Button>
@@ -45,8 +53,92 @@ aliases: [sheet, drawer, side panel, slide-in, nav drawer, mobile drawer, slide-
 </Sheet>
 ```
 
-SheetContent ships at elevation-5. Opt into a frosted glass sheet when the canvas behind it should remain visible:
+`solid` is the right default for editing workflows. Form fields need maximum legibility; blur behind them works against that.
+
+---
+
+### Scenario 2 — Glass inspector panel (creative tool aesthetic)
+
+You're building a creative tool. The canvas is the work — a Studio layout, an image being annotated, a presentation slide. The inspector panel needs to live alongside the work without obscuring it. Glass is the canonical "I am chrome, not content" signal.
+
+```jsx
+<Sheet open={hasSelection} modal={false}>
+  <SheetContent
+    side="right"
+    surface="glass"
+    className="w-96 shadow-elevation-5"
+  >
+    <SheetHeader>
+      <SheetTitle>Selection</SheetTitle>
+      <SheetDescription>Button — Toolbar &gt; trailing</SheetDescription>
+    </SheetHeader>
+
+    <Stack gap="md" className="py-4">
+      <Stack gap="xs">
+        <Label>Variant</Label>
+        <Select defaultValue="raised">{/* … */}</Select>
+      </Stack>
+      <Stack gap="xs">
+        <Label>Size</Label>
+        <ToggleGroup type="single" defaultValue="md">
+          <ToggleGroupItem value="sm">sm</ToggleGroupItem>
+          <ToggleGroupItem value="md">md</ToggleGroupItem>
+          <ToggleGroupItem value="lg">lg</ToggleGroupItem>
+        </ToggleGroup>
+      </Stack>
+    </Stack>
+  </SheetContent>
+</Sheet>
+```
+
+Three things to notice: `modal={false}` so the user keeps interacting with the canvas while the inspector is open; `surface="glass"` so the canvas reads through; `shadow-elevation-5` to lift the panel cleanly off the canvas. This is the Studio inspector pattern.
+
+---
+
+### Scenario 3 — Bottom action sheet (mobile, glass for iOS feel)
+
+The iOS-native action sheet has glass behind it. Matching that material on mobile flows is "feels like a native app" by default.
+
+```jsx
+<Sheet open={pickerOpen} onOpenChange={setPickerOpen}>
+  <SheetContent
+    side="bottom"
+    surface="glass"
+    className="rounded-t-2xl"
+  >
+    <SheetHeader className="text-center">
+      <SheetTitle>Share screen</SheetTitle>
+    </SheetHeader>
+    <Stack gap="xs" className="py-4">
+      <Button variant="ghost" className="justify-start"><Mail /> Email</Button>
+      <Button variant="ghost" className="justify-start"><MessageCircle /> Message</Button>
+      <Button variant="ghost" className="justify-start"><Copy /> Copy link</Button>
+    </Stack>
+    <SheetClose asChild>
+      <Button variant="outline" className="w-full">Cancel</Button>
+    </SheetClose>
+  </SheetContent>
+</Sheet>
+```
+
+`side="bottom"` + `surface="glass"` + `rounded-t-2xl` is the iOS action-sheet recipe. The rounded top corners signal "this can be dismissed by dragging down" even before any gesture handler is wired up.
+
+---
+
+### Anti-patterns
+
+**DO NOT roll glass by hand on SheetContent.**
 
 ```jsx
-<SheetContent className="gds-surface-glass">…</SheetContent>
+{/* ❌ Tailwind soup — no edge highlight, blur isn't theme-tuned. */}
+<SheetContent className="bg-background/60 backdrop-blur-md">
+
+{/* ✅ */}
+<SheetContent surface="glass">
 ```
+
+**DO NOT use `surface="glass"` for a modal sheet that contains a long form.** Form legibility wins over aesthetic. If the user is going to spend 30 seconds in this sheet, give them an opaque background.
+
+**DO NOT pair `surface="glass"` with `modal={true}` and the default scrim.** The scrim already dims the canvas — adding glass on top of a dimmed canvas reads as "two competing layers of de-emphasis". Either turn off the scrim (`modal={false}`), or use `surface="solid"`.
+
+**DO NOT skip SheetTitle.** Screen readers announce it on open. If the design has no visible title, wrap a `sr-only` one.