@gradeui/ui 0.9.0 → 1.0.0

package/components/ui/media-surface.md

@@ -0,0 +1,61 @@
+---
+name: MediaSurface
+import: "@gradeui/ui"
+props:
+  - aspect?: "video" | "square" | "portrait" | "wide" | "auto" — when omitted, derived from `hint` (album/product/food → square, portrait/poster → portrait, landscape → wide, video/audio/embed/generic → video)
+  - radius?: "none" | "sm" | "md" | "lg" | "xl" (default "lg") — driven by `--gds-media-radius` CSS var
+  - border?: boolean (default false)
+  - loading?: boolean — renders the muted skeleton overlay
+  - hint?: "album" | "portrait" | "landscape" | "poster" | "product" | "food" | "video" | "audio" | "embed" | "3d" | "generic" (default "generic") — picks the placeholder glyph + the default aspect + the future generation provider
+  - alt?: string — becomes the eventual `<img alt>`; also drives the placeholder caption and small-tier initials
+  - source?: { kind, …per-kind fields } — structured metadata for the generation pipeline. Shapes per kind — album: { artist, title, year? } · poster: { title, year? } · portrait: { name?, role? } · landscape: { location?, mood? } · product: { name?, brand? } · food: { dish?, cuisine? } · generic: { prompt } · video/audio/embed/3d: no fields
+  - src?: string — when set, renders an `<img>` filling the slot via object-cover; the wrapper keeps its chrome
+  - glyph?: ReactNode — per-instance override of the hint-derived placeholder glyph (escape hatch for unusual slots)
+  - overlay?: ReactNode — decorative layer rendered ABOVE the media/placeholder (play buttons, hover gradients, corner badges, progress bars). Does NOT suppress the placeholder — use this for decoration, use `children` for replacement
+  - emptyState?: "auto" | "icon" | "none" | ReactNode — "auto" (default) renders the size-tiered placeholder; "icon" is a legacy alias; "none" disables; a node fully overrides
+  - className?: string
+  - children?: ReactNode — escape hatch for putting a custom `<video>`, `<canvas>`, Rive runtime, etc. inside. When supplied, the placeholder is suppressed
+when_to_use: The canonical media slot for ALL non-person imagery — album art, posters, hero images, landscape photos, video and 3D containers. Pass `hint` + `alt` + (optionally) `source` so the empty-state placeholder is meaningful and the generation pipeline can later fill the slot with a real image. Use directly for declarative slots; the higher-level VideoPlayer / RivePlayer / ThreeScene wrap this for runtime-heavy media.
+composes_with: [Card (as the image slot), CardBlock, MediaBlock, VideoPlayer, RivePlayer, ThreeScene]
+aliases: [media, image slot, media slot, image placeholder, cover, thumbnail, poster slot, image, image view, image well, imagebackground, asyncimage, react native image, fastimage]
+notes: |
+  Anti-patterns to avoid:
+
+  - DO NOT wrap <Avatar> inside <MediaSurface> to get a 2-letter initials
+    fallback. That conflates two primitives. Set `alt` + `hint` on
+    MediaSurface directly — the placeholder already renders initials at
+    small sizes derived from `alt`.
+  - DO NOT use <Avatar> for album art, posters, products, food, landscapes,
+    etc. Avatar is for PEOPLE only (circular, social context). Use
+    MediaSurface with the appropriate `hint`.
+  - DO NOT inline manual gradient backgrounds (`bg-gradient-to-br …`) on
+    MediaSurface as a "placeholder vibe" — the empty-state placeholder is
+    already styled via `--gds-media-placeholder-bg/-fg` and themes with
+    the rest of the design system.
+
+  When you have a real image URL, pass it as `src=`. The wrapper keeps its
+  aspect/radius/border chrome and fills with object-cover.
+---
+
+```jsx
+{/* Empty placeholder — model emits this before generation has filled the slot */}
+<MediaSurface
+  hint="album"
+  alt="Travelling Without Moving — Jamiroquai"
+  source={{ kind: "album", artist: "Jamiroquai", title: "Travelling Without Moving" }}
+  radius="md"
+/>
+
+{/* Filled — same component, now with a src */}
+<MediaSurface
+  hint="album"
+  alt="Travelling Without Moving — Jamiroquai"
+  src="https://coverartarchive.org/release/.../front-500.jpg"
+  radius="md"
+/>
+
+{/* Video container — children escape hatch */}
+<MediaSurface aspect="video" radius="lg">
+  <video src="/intro.mp4" controls className="absolute inset-0 h-full w-full" />
+</MediaSurface>
+```

package/components/ui/multi-select.md

@@ -0,0 +1,114 @@
+---
+name: MultiSelect
+import: "@gradeui/ui"
+props:
+  - options: { value: string; label: string; icon?: ComponentType; disabled?: boolean }[]
+  - value?: string[] — controlled selection
+  - defaultValue?: string[] — uncontrolled initial selection
+  - onValueChange?: (next: string[]) => void
+  - placeholder?: string (default "Select…")
+  - searchPlaceholder?: string (default "Search…")
+  - emptyMessage?: string (default "Nothing matches.")
+  - maxCount?: number (default 3) — badges shown on the trigger before collapsing to "+N more"
+  - searchable?: boolean (default true) — hide for short option lists
+  - badgeDismissible?: boolean (default true) — show × on each selected badge
+  - disabled?: boolean
+  - modalPopover?: boolean (default false) — Popover modal mode
+  - className?: string
+when_to_use: |
+  Picking multiple items from a finite list — tag selectors, filter chips,
+  "share with N people", multi-region settings.
+
+  **This is the answer for ANY "removable-chips-inside-an-input" pattern.**
+  MultiSelect's trigger renders the current selection as Badges with X
+  icons (the "chip-in-trigger" / "chip-in-input" shape), opens a Popover
+  with a searchable Command list, and supports "+N more" collapse past
+  `maxCount`. Reach for it for:
+    - Linear-style filter bars (assignee, label, project chips inside one trigger)
+    - Slack channel pickers (selected channels as removable chips)
+    - Notion relation properties (related-page chips)
+    - GitHub label / assignee pickers
+    - tag / category / mention pickers anywhere
+  Don't invent a `<ChipInput>` or `<TagInput>` for these — MultiSelect
+  already covers the trigger-with-badges shape.
+
+  Use `<Select>` instead for SINGLE selection. Use `<Command>` directly
+  (no MultiSelect wrapper) when the option set is unbounded or async
+  (users to @-mention, email recipients, search-as-you-type API results).
+composes_with: [Popover, Command, Badge, Checkbox-style row indicator, Separator]
+aliases: [
+  multi select, multiselect, multi-select, tag picker, chips input,
+  chip input, chipinput, tag input, taginput, chip picker, badge picker,
+  multi picker, multi-pick combobox, multipicker, tag select,
+  react native multi select, multi-select combobox,
+  filter chips, filter bar chips, removable chips, removable pills,
+  channel picker, label picker, recipient picker, relation picker,
+  picker with chips, selected items as chips, badges in input,
+  badges in trigger, pills in input, multi-select with badges
+]
+---
+
+```jsx
+const frameworks = [
+  { value: "next", label: "Next.js" },
+  { value: "remix", label: "Remix" },
+  { value: "astro", label: "Astro" },
+  { value: "nuxt", label: "Nuxt" },
+];
+
+<MultiSelect
+  options={frameworks}
+  defaultValue={["next", "remix"]}
+  onValueChange={setSelected}
+  placeholder="Pick frameworks"
+  maxCount={2}
+/>
+```
+
+```jsx
+// With per-option icons — the icon renders both in the dropdown row
+// and on the selected badge.
+import { Code2, Server, Cloud } from "lucide-react";
+const services = [
+  { value: "edge", label: "Edge runtime", icon: Cloud },
+  { value: "node", label: "Node runtime", icon: Server },
+  { value: "browser", label: "Browser only", icon: Code2 },
+];
+
+<MultiSelect options={services} placeholder="Select runtimes" />
+```
+
+```jsx
+// Filter-bar chip picker (Linear / Jira style). Selected status chips
+// render INSIDE the trigger with X icons; click the trigger to open the
+// Popover and toggle more. Pair with a search Input to the left for the
+// "search + scoped filters" composition (e.g. Reddit / Linear / GitHub
+// header search). Don't reach for a custom ChipInput — this IS it.
+const statuses = [
+  { value: "todo", label: "Todo" },
+  { value: "doing", label: "In Progress" },
+  { value: "done", label: "Done" },
+];
+
+<Row gap="sm" align="center">
+  <Input placeholder="Search issues…" className="flex-1" />
+  <MultiSelect
+    options={statuses}
+    placeholder="Status"
+    maxCount={2}
+    badgeDismissible
+  />
+</Row>
+```
+
+### Anti-patterns
+
+DO NOT use MultiSelect for single-pick — that's `<Select>`. The visual semantics differ (badges vs single value) and screen-reader announcements differ ("combobox, 2 selected" vs "combobox, Apple").
+
+DO NOT pass `value` without `onValueChange` — the component becomes a read-only display of the controlled state and selections inside the popover silently no-op. Either go fully uncontrolled (`defaultValue`) or wire both.
+
+DO NOT inline `options` as `[{value, label}, ...]` from scratch on every render — memoise it. The component memoises its internal lookup, but a fresh array reference on every parent render still forces React to reconcile every row.
+
+DO NOT reach for MultiSelect when the list is unbounded or async (users to mention, email recipients, search-as-you-type API results). Use `<Command>` directly with custom rendering — MultiSelect's `options` model expects the full set up front.
+
+DO NOT hand-roll a "chip input" / "tag input" / "search with removable filter chips" composition with raw Badge + Input + state. MultiSelect already covers the trigger-with-removable-Badges pattern (the chip-in-trigger shape). If your screenshot has selected items rendered as removable pills, MultiSelect is the answer — even if the source visual integrates the chips with a search field. (Genuine gap: the *typed-text-immediately-next-to-chips* search composition where the input is freeform and the chips are scopes — that's a Row of `<Input>` + `<MultiSelect>`, not a new primitive.)

package/components/ui/popover.md

@@ -0,0 +1,43 @@
+---
+name: Popover
+import: "@gradeui/ui"
+subcomponents: [PopoverTrigger, PopoverContent, PopoverAnchor]
+props:
+  - Popover: open?, defaultOpen?, onOpenChange?, modal? (default false)
+  - PopoverTrigger: asChild?: boolean — usually a Button
+  - PopoverContent: side? "top" | "right" | "bottom" | "left"; align? "start" | "center" | "end"; sideOffset?, alignOffset?, collisionPadding?, className?
+  - PopoverAnchor: asChild?: boolean — pin the popover to a different element than the trigger
+when_to_use: A floating panel anchored to a trigger that contains interactive content — date pickers, color pickers, filter pickers, "more info" panels, inline forms. Differs from Tooltip (hover-only, no focusable content) and Dialog (modal, blocks the page). DatePicker, DateRangePicker, and the Combobox pattern all compose Popover internally.
+composes_with: [Button (as trigger), Calendar (date picker), Command (combobox), Form controls (inline edit popover)]
+aliases: [popover, dropdown panel, floating panel, inline editor, attached panel, filter pop, popover view, popoverpresentation, attached popover]
+---
+
+```jsx
+// Filter popover anchored to a Button trigger.
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="outline" size="sm">
+      <Filter /> Filters
+    </Button>
+  </PopoverTrigger>
+  <PopoverContent className="w-72" align="end">
+    <Stack gap="md">
+      <Stack gap="xs">
+        <Label>Plan</Label>
+        <Select>{/* … */}</Select>
+      </Stack>
+      <Stack gap="xs">
+        <Label>Status</Label>
+        <Select>{/* … */}</Select>
+      </Stack>
+    </Stack>
+  </PopoverContent>
+</Popover>
+```
+
+PopoverContent ships at elevation-4. Opt into glass for a frosted look, or layer in aura when the popover is AI-driven:
+
+```jsx
+<PopoverContent className="gds-surface-glass">…</PopoverContent>
+<PopoverContent className="gds-aura-ring">Studio suggestion</PopoverContent>
+```

package/components/ui/progress.md

@@ -0,0 +1,15 @@
+---
+name: Progress
+import: "@gradeui/ui"
+props:
+  - value?: number (0–100) — percent complete
+  - max?: number (default 100)
+  - className?: string
+when_to_use: Determinate progress — file uploads, multi-step forms, quota meters. Indeterminate state → use Skeleton or animated Loader icon.
+composes_with: [Card (as a section), Badge (showing % next to it), Label (describing what's loading)]
+aliases: [progress, progress view, progress indicator, progress bar, determinate progress, loading bar, completion bar]
+---
+
+```jsx
+<Progress value={42} />
+```

package/components/ui/radio-group.md

@@ -0,0 +1,37 @@
+---
+name: RadioGroup
+import: "@gradeui/ui"
+subcomponents: [RadioGroupItem]
+props:
+  - RadioGroup: value?: string — controlled selection
+  - RadioGroup: defaultValue?: string — uncontrolled initial
+  - RadioGroup: onValueChange?: (value: string) => void
+  - RadioGroup: disabled?: boolean
+  - RadioGroup: orientation? "horizontal" | "vertical" (default "vertical")
+  - RadioGroup: name?: string — form name when posting natively
+  - RadioGroupItem: value: string — what the group emits when this item is picked
+  - RadioGroupItem: id?: string — pair with a <Label htmlFor> for click-on-label
+  - RadioGroupItem: disabled?: boolean
+when_to_use: A small set of mutually-exclusive options where the user needs to SEE all of them at once — pricing tiers (3-4 options), shipping speed, payment method radio cards. For 5+ options use Select. For a segmented control as part of a toolbar use ToggleGroup. For yes/no use Switch.
+composes_with: [Label (paired with each item via htmlFor), Stack (vertical list), Card (radio card pattern)]
+aliases: [radio group, radio buttons, single-choice, pricing options, payment method, radio buttons, radio control, single-select]
+---
+
+```jsx
+<RadioGroup defaultValue="pro" name="plan">
+  <Stack gap="sm">
+    <Row gap="sm" align="center">
+      <RadioGroupItem id="plan-free" value="free" />
+      <Label htmlFor="plan-free">Free</Label>
+    </Row>
+    <Row gap="sm" align="center">
+      <RadioGroupItem id="plan-pro" value="pro" />
+      <Label htmlFor="plan-pro">Pro — $12/mo</Label>
+    </Row>
+    <Row gap="sm" align="center">
+      <RadioGroupItem id="plan-team" value="team" />
+      <Label htmlFor="plan-team">Team — $48/mo</Label>
+    </Row>
+  </Stack>
+</RadioGroup>
+```

package/components/ui/resizable.md

@@ -0,0 +1,30 @@
+---
+name: Resizable
+import: "@gradeui/ui"
+subcomponents: [ResizablePanelGroup, ResizablePanel, ResizableHandle]
+props:
+  - ResizablePanelGroup: direction: "horizontal" | "vertical" — required; sets the axis the user drags along
+  - ResizablePanelGroup: autoSaveId?: string — persists user-adjusted sizes to localStorage under this id
+  - ResizablePanelGroup: onLayout?: (sizes: number[]) => void
+  - ResizablePanel: defaultSize?: number — percent of group (0-100); siblings should sum to ~100
+  - ResizablePanel: minSize?, maxSize?: number — percent bounds
+  - ResizablePanel: collapsible?: boolean — allow this panel to collapse to zero
+  - ResizablePanel: collapsedSize?, onCollapse?, onExpand? — collapse behaviour controls
+  - ResizableHandle: withHandle?: boolean — show a visible drag affordance (default just a hit-zone)
+when_to_use: A multi-pane layout where the user wants to drag the divider — Slack/Mail-style list+detail, IDE editor+terminal, side-by-side compare view. Static layouts shouldn't use this — reach for AppShell with nav="three-pane" (fixed widths) or Grid (responsive ladder). Built on react-resizable-panels under the hood.
+composes_with: [AppShellMain (host the splitter inside main), ScrollArea (each panel's content), Card]
+aliases: [resizable, splitter, split pane, drag divider, adjustable panels, resizer, split view, draggable divider, split pane resizer, ns split view]
+---
+
+```jsx
+// List + detail with a draggable divider, saved between sessions.
+<ResizablePanelGroup direction="horizontal" autoSaveId="inbox">
+  <ResizablePanel defaultSize={30} minSize={20}>
+    <InboxList />
+  </ResizablePanel>
+  <ResizableHandle withHandle />
+  <ResizablePanel defaultSize={70}>
+    <ConversationView />
+  </ResizablePanel>
+</ResizablePanelGroup>
+```

package/components/ui/rive-player.md

@@ -0,0 +1,38 @@
+---
+name: RivePlayer
+import: "@gradeui/ui"
+props:
+  - src: string — URL or path to the .riv file
+  - stateMachines?: string | string[] — state machine(s) to run
+  - artboard?: string — artboard name; omit to use default
+  - controls?: boolean (default false) — viewer mode by default; set true for play/pause overlay
+  - autoPlay?: boolean (default true) — respects reduced-motion
+  - loop?: boolean (default true)
+  - pauseOffscreen?: boolean (default true)
+  - fit?: "contain" | "cover" | "fill" | "fitWidth" | "fitHeight" | "none" (default "contain")
+  - stateMachineInputs?: Record<string, number | boolean | string>
+  - aspect?: "video" | "square" | "portrait" | "wide" | "auto" (default "square")
+  - radius?: "none" | "sm" | "md" | "lg" | "xl" (default "lg")
+  - poster?: string — image shown while the runtime loads
+when_to_use: Rive runtime wrapped in the shared media surface. Reach for Rive when you need interactive state-machine animations driven by scroll/hover/input. For non-interactive looping video, use VideoPlayer; for shader-driven backgrounds, use ThreeScene.
+composes_with: [MediaSurface (internal), Card, any container]
+aliases: [rive, riv, animation, animated, lottie]
+notes: The Rive runtime (`@rive-app/react-canvas`) is an optional dependency of `@gradeui/ui` — lazy-imported at mount. Consumers who don't use Rive can install with `--no-optional` and the dep is skipped; RivePlayer renders a friendly error if the runtime is missing. When no `src` is given RivePlayer renders an empty surface — ALWAYS pass `src`. If you don't have a specific file, use the public Rive CDN sample "https://cdn.rive.app/animations/vehicles.riv" with `stateMachines="bumpy"` — a known-working demo.
+---
+
+```jsx
+// Known-working public sample — use this when you don't have a specific .riv
+<RivePlayer
+  src="https://cdn.rive.app/animations/vehicles.riv"
+  stateMachines="bumpy"
+  aspect="square"
+/>
+
+// Player mode with state-machine inputs
+<RivePlayer
+  src="/button.riv"
+  stateMachines="Hover"
+  stateMachineInputs={{ isHovered: true }}
+  controls
+/>
+```

package/components/ui/row.md

@@ -0,0 +1,32 @@
+---
+name: Row
+import: "@gradeui/ui"
+role: layout
+props:
+  - gap?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" (default "md") — gap between children
+  - align?: "start" | "center" | "end" | "stretch" | "baseline" (default "center") — cross-axis (vertical) alignment
+  - justify?: "start" | "center" | "end" | "between" | "around" | "evenly" (default "start") — main-axis distribution
+  - wrap?: boolean (default false) — allow children to wrap onto additional lines when they overflow
+  - asChild?: boolean (default false) — render as the child element via Slot
+  - className?: string
+  - children: React.ReactNode
+when_to_use: Horizontal composition — button groups, inline form rows, logo + nav rows, anything on one line. Reach for Row instead of `flex items-center gap-*` so the alignment and spacing are editable through the settings panel. For two-pane layouts with an explicit ratio (sidebar + content, 1/3 + 2/3) use Split instead — Row evenly flows whatever children it holds.
+composes_with: [Button, Input, NavItem, Stack (can wrap a Row), any content component]
+aliases: [row, hstack, horizontal, inline, horizontal layout, hstack, h-stack, horizontal stack, lazyhstack]
+---
+
+```jsx
+// Button group — justify="end" pushes the group to the right.
+<Row gap="sm" justify="end">
+  <Button variant="ghost">Cancel</Button>
+  <Button>Save</Button>
+</Row>
+```
+
+```jsx
+// Spread apart — logo left, action right.
+<Row justify="between" align="center">
+  <Logo />
+  <Button>Sign in</Button>
+</Row>
+```

package/components/ui/scroll-area.md

@@ -0,0 +1,27 @@
+---
+name: ScrollArea
+import: "@gradeui/ui"
+subcomponents: [ScrollBar]
+props:
+  - ScrollArea: type? "auto" | "always" | "scroll" | "hover" — when the scrollbar shows
+  - ScrollArea: scrollHideDelay?: number — ms before "scroll"/"hover" scrollbars fade
+  - ScrollArea: dir? "ltr" | "rtl"
+  - ScrollArea: className?: string — set a height/max-height here, otherwise nothing scrolls
+  - ScrollBar: orientation? "vertical" | "horizontal" (default vertical)
+when_to_use: Bounded content that needs custom scroll chrome — sidebars with long item lists, chat transcripts, table panels inside a dashboard, anywhere the OS scrollbar would feel out of place against the design tokens. The wrapping element has to have a height constraint (`h-`, `max-h-`, or grid row sizing) or nothing scrolls — scroll-area can't infer a bound on its own. For body-level scrolling, leave the document to the browser.
+composes_with: [Card (long card body), AppShellNav (long sidebar), Sheet (long modal body), Table (sticky-header scrolling list)]
+aliases: [scroll area, scroll container, custom scrollbar, sidebar scroll, panel scroll, scroll view, scrollview, react native scrollview]
+---
+
+```jsx
+// Sidebar with a long item list — fixed height so scroll engages.
+<ScrollArea className="h-96 w-56 rounded-md border">
+  <Stack gap="xs" className="p-3">
+    {items.map((item) => (
+      <button key={item.id} className="text-left px-2 py-1 rounded hover:bg-muted">
+        {item.name}
+      </button>
+    ))}
+  </Stack>
+</ScrollArea>
+```

package/components/ui/select.md

@@ -0,0 +1,24 @@
+---
+name: Select
+import: "@gradeui/ui"
+subcomponents: [SelectTrigger, SelectValue, SelectContent, SelectItem, SelectGroup, SelectLabel, SelectSeparator]
+props:
+  - Select: value?, onValueChange?, defaultValue?, disabled? — Radix root
+  - SelectTrigger: wraps the clickable control; nest SelectValue inside
+  - SelectValue: placeholder?: string — text when nothing is selected
+  - SelectContent: accepts items via children
+  - SelectItem: value: string — required; content is the label
+when_to_use: Single-choice from 3+ known options. Fewer than 3 → RadioGroup. Huge list with search → use a Combobox (not in DS yet). Multi-select → not supported by this primitive.
+composes_with: [Label (above SelectTrigger), Form, Card]
+aliases: [dropdown, combobox, picker, select, pop-up button, popup button, popup picker, picker view, rnpickerselect, react native picker, native picker]
+---
+
+```jsx
+<Select defaultValue="apple">
+  <SelectTrigger><SelectValue placeholder="Pick a fruit" /></SelectTrigger>
+  <SelectContent>
+    <SelectItem value="apple">Apple</SelectItem>
+    <SelectItem value="banana">Banana</SelectItem>
+  </SelectContent>
+</Select>
+```

package/components/ui/separator.md

@@ -0,0 +1,16 @@
+---
+name: Separator
+import: "@gradeui/ui"
+props:
+  - orientation? ("horizontal" | "vertical") — default "horizontal"
+  - decorative?: boolean (default true) — hide from a11y tree
+  - className?: string
+when_to_use: Light divider between sibling blocks in a Card, list, or header. For section-level partition use extra spacing instead.
+composes_with: [Card (between CardHeader/Content/Footer), navigation menus, any vertical stacks]
+aliases: [divider, rule, hr, line, horizontal rule]
+---
+
+```jsx
+<Separator />
+<Separator orientation="vertical" className="h-6" />
+```

package/components/ui/shader-preset-picker.md

@@ -0,0 +1,26 @@
+---
+name: ShaderPresetPicker
+import: "@gradeui/ui"
+props:
+  - value?: string — currently selected preset id (controlled)
+  - onChange?: (id: string) => void — called when the user clicks a preset card
+  - filterTags?: string[] — only show presets matching at least one tag ("space" | "retro" | "motion" | "hero" | "background" …)
+  - live?: "never" | "hover" | "always" (default "hover") — thumbnail render mode
+  - postPreset?: string — shared post-FX preset applied to every thumbnail
+  - palette?: Partial<Palette> — shared palette applied to every thumbnail
+  - columns?: 2 | 3 | 4 (default 3) — grid columns at md+ breakpoint
+when_to_use: Runtime gallery of shader presets — click to select. Use with ThreeScene as a controlled input so the user can pick a background shader. For a single preview card, use ShaderPresetPreview directly.
+composes_with: [ShaderPresetPreview (internal), ThreeScene (the typical downstream consumer)]
+aliases: [shader picker, preset picker, shader gallery, preset gallery]
+notes: Powered by the same preset registry that drives `<ThreeScene preset="…" />` — adding a preset to the registry makes it appear here automatically. At time of writing only "space" is registered, so the picker renders a single card until more presets ship.
+---
+
+```jsx
+const [preset, setPreset] = useState("space");
+
+<ShaderPresetPicker value={preset} onChange={setPreset} />
+<ThreeScene preset={preset} postPreset="vhs" aspect="wide" />
+
+// Filter to a subset
+<ShaderPresetPicker filterTags={["hero"]} columns={3} />
+```

package/components/ui/shader-preset-preview.md

@@ -0,0 +1,24 @@
+---
+name: ShaderPresetPreview
+import: "@gradeui/ui"
+props:
+  - preset: string — shader preset id from the registry
+  - live?: "never" | "hover" | "always" (default "hover") — when to run the live WebGL render
+  - postPreset?: string — override the preset's default post-FX
+  - palette?: Partial<Palette> — palette overrides for the preview
+  - aspect?: "video" | "square" | "portrait" | "wide" (default "video")
+  - hideLabel?: boolean (default false) — hide the label strip under the preview
+  - onClick?: () => void
+when_to_use: Thumbnail-sized preview card for a shader preset. Defaults to a cheap static placeholder until hovered, at which point the live WebGL render kicks in. Use directly when you want a single preset card; use ShaderPresetPicker for a filterable grid.
+composes_with: [ThreeScene (internal), ShaderPresetPicker (wraps this)]
+aliases: [shader preview, preset preview, shader card]
+notes: Prefer `live="hover"` in galleries — Safari caps concurrent WebGL contexts at ~8. `live="always"` is fine for one or two cards; past that you'll run out of contexts. VALID `preset` ids come from the shader registry — at time of writing the only shipped preset is "space". Unknown ids render a placeholder card with the raw id as a label (no error). Do NOT pass invented ids like "neon-grid" — it will render as the literal string "neon-grid".
+---
+
+```jsx
+// Hover-to-live (default)
+<ShaderPresetPreview preset="space" />
+
+// Always-live — use sparingly
+<ShaderPresetPreview preset="space" live="always" />
+```

package/components/ui/sheet.md

@@ -0,0 +1,52 @@
+---
+name: Sheet
+import: "@gradeui/ui"
+subcomponents: [SheetTrigger, SheetContent, SheetHeader, SheetTitle, SheetDescription, SheetFooter, SheetClose]
+props:
+  - Sheet: open?, defaultOpen?, onOpenChange?, modal? (default true)
+  - SheetTrigger: asChild?: boolean
+  - SheetContent: side? "top" | "right" | "bottom" | "left" (default "right")
+  - 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]
+---
+
+```jsx
+// Edit-record drawer from the right edge.
+<Sheet>
+  <SheetTrigger asChild>
+    <Button variant="outline">Edit user</Button>
+  </SheetTrigger>
+  <SheetContent className="w-full sm:max-w-md">
+    <SheetHeader>
+      <SheetTitle>Edit user</SheetTitle>
+      <SheetDescription>Update Elena's profile and role.</SheetDescription>
+    </SheetHeader>
+    <Stack gap="md" className="py-4">
+      <Stack gap="xs">
+        <Label htmlFor="name">Name</Label>
+        <Input id="name" defaultValue="Elena Okafor" />
+      </Stack>
+      <Stack gap="xs">
+        <Label htmlFor="role">Role</Label>
+        <Select>{/* … */}</Select>
+      </Stack>
+    </Stack>
+    <SheetFooter>
+      <SheetClose asChild>
+        <Button variant="ghost">Cancel</Button>
+      </SheetClose>
+      <Button>Save changes</Button>
+    </SheetFooter>
+  </SheetContent>
+</Sheet>
+```
+
+SheetContent ships at elevation-5. Opt into a frosted glass sheet when the canvas behind it should remain visible:
+
+```jsx
+<SheetContent className="gds-surface-glass">…</SheetContent>
+```