@gradeui/ui 0.9.0 → 0.10.0

package/components/ui/grid.md

@@ -0,0 +1,44 @@
+---
+name: Grid
+import: "@gradeui/ui"
+role: layout
+props:
+  - cols?: "1" | "2" | "3" | "4" | "5" | "6" | "12" (default "3") — desktop column count; each value has a baked-in responsive ladder (e.g. "4" → 1 col mobile, 2 tablet, 4 desktop)
+  - gap?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" (default "md") — gap between grid cells (same scale as Stack/Row)
+  - align?: "start" | "center" | "end" | "stretch" (default "stretch") — cross-axis alignment of cells
+  - asChild?: boolean (default false) — render as the child element via Slot
+  - className?: string
+  - children: React.ReactNode
+when_to_use: 2D layouts where Stack (vertical) and Row (horizontal) don't fit — stat-card grids, feature tiles, pricing columns, photo grids. Reach for Grid over hand-rolled `grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4` so the column count is a prop the settings panel can mutate and the responsive ladder stays consistent across designs.
+composes_with: [Card, Stack (inside each cell), Row, Button, any content component]
+aliases: [grid, tiles, cards grid, stat grid, columns, feature grid]
+notes: |
+  `cols` values and their responsive ladders:
+    "1"  → grid-cols-1 (single column at all breakpoints)
+    "2"  → grid-cols-1 md:grid-cols-2
+    "3"  → grid-cols-1 sm:grid-cols-2 md:grid-cols-3
+    "4"  → grid-cols-1 sm:grid-cols-2 lg:grid-cols-4  (the canonical stat-card grid)
+    "5"  → grid-cols-1 sm:grid-cols-2 lg:grid-cols-5
+    "6"  → grid-cols-2 sm:grid-cols-3 lg:grid-cols-6
+    "12" → grid-cols-4 md:grid-cols-6 lg:grid-cols-12
+  Prefer Grid over bespoke Tailwind grid classes — "gap-md" etc. are NOT real Tailwind classes (the gap scale is numeric: gap-4, gap-6) so hand-rolled grids often end up with zero gap.
+---
+
+```jsx
+// Stat-card grid — the canonical 4-up.
+<Grid cols="4" gap="md">
+  <Card>…</Card>
+  <Card>…</Card>
+  <Card>…</Card>
+  <Card>…</Card>
+</Grid>
+```
+
+```jsx
+// Three-column feature grid with larger gaps.
+<Grid cols="3" gap="lg">
+  <FeatureCard />
+  <FeatureCard />
+  <FeatureCard />
+</Grid>
+```

package/components/ui/hover-card.md

@@ -0,0 +1,35 @@
+---
+name: HoverCard
+import: "@gradeui/ui"
+subcomponents: [HoverCardTrigger, HoverCardContent]
+props:
+  - HoverCard: open?, defaultOpen?, onOpenChange?, openDelay? (default 700), closeDelay? (default 300)
+  - HoverCardTrigger: asChild?: boolean — usually a Link or Button
+  - HoverCardContent: side?, align?, sideOffset?, alignOffset?, className?
+when_to_use: Rich preview content surfaced on hover — user profile mini-cards on @-mentions, link previews, definition popups. Pointer-only by design (no touch-friendly trigger); pair with a click target for touch devices, or fall back to Popover. NEVER use HoverCard for critical info — if the user can't reach it via keyboard or touch, it might as well not exist for accessibility.
+composes_with: [Avatar (user preview), Card (richer content), Link (the trigger)]
+aliases: [hover card, hover preview, mention preview, profile peek, link preview]
+---
+
+```jsx
+// User mention preview — pointer-only enrichment.
+<HoverCard>
+  <HoverCardTrigger asChild>
+    <a href="/u/elena" className="font-medium underline">@elena</a>
+  </HoverCardTrigger>
+  <HoverCardContent className="w-72">
+    <Row gap="sm" align="start">
+      <Avatar>
+        <AvatarImage src="/avatars/elena.png" />
+        <AvatarFallback>EO</AvatarFallback>
+      </Avatar>
+      <Stack gap="xs">
+        <span className="font-semibold">Elena Okafor</span>
+        <span className="text-sm text-muted-foreground">
+          Design lead · Joined Mar 2025
+        </span>
+      </Stack>
+    </Row>
+  </HoverCardContent>
+</HoverCard>
+```

package/components/ui/input.md

@@ -0,0 +1,17 @@
+---
+name: Input
+import: "@gradeui/ui"
+props:
+  - type?: string (text | email | password | number | search | url | tel | date)
+  - All native input HTML attrs (value, onChange, placeholder, disabled, required)
+when_to_use: Any single-line text entry. Always pair with a Label for accessibility.
+composes_with: [Label, Form, Card (in CardContent), Button (form submit)]
+aliases: [text field, textbox, textfield, form field, text input]
+---
+
+```jsx
+<div className="grid gap-1.5">
+  <Label htmlFor="email">Email</Label>
+  <Input id="email" type="email" placeholder="you@example.com" />
+</div>
+```

package/components/ui/label.md

@@ -0,0 +1,14 @@
+---
+name: Label
+import: "@gradeui/ui"
+props:
+  - htmlFor?: string — binds to the input's id
+  - All native label HTML attrs
+when_to_use: Every Input / Textarea / Checkbox / Switch / RadioGroup. Always use htmlFor so clicking the label focuses the control.
+composes_with: [Input, Textarea, Checkbox, Switch, RadioGroup, Select]
+---
+
+```jsx
+<Label htmlFor="name">Full name</Label>
+<Input id="name" />
+```

package/components/ui/map.md

@@ -0,0 +1,80 @@
+---
+name: Map
+import: "@gradeui/ui"
+subcomponents: [MapMarker]
+aliases: [map, maps, mapbox, maplibre, google maps, geo, location, latlng, coordinates, marker, pin, airbnb, listings, fleet, real estate, logistics]
+props:
+  - provider — "maplibre" (default, free, no key) | "mapbox" (needs accessToken) | "google" (needs apiKey). Switching is one prop change.
+  - center — `[lng, lat]` tuple. ALWAYS lng first. Required.
+  - zoom — number, 0–22. Required.
+  - bounds — `[[swLng, swLat], [neLng, neLat]]`. When set, takes precedence over center+zoom.
+  - appearance — "light" | "dark" | "satellite" | "auto" (default "auto", follows GradeThemeProvider mode).
+  - hoveredId — controlled string id, pairs with onHoveredIdChange. The matching MapMarker gets `data-gds-state="hovered"` automatically. This is how you build list ↔ map two-way sync.
+  - interactive — false freezes pan/zoom, useful for static cards.
+  - onLoad(handle) / onError(error) — handle exposes flyTo, panTo, fitBounds, getCenter, getZoom, getBounds, instance.
+  - tilerKey (maplibre) — only needed off `gradeui.com`/`localhost`. Default key is referrer-locked.
+  - accessToken (mapbox), apiKey (google) — required for those providers.
+when_to_use: Any layout that needs a real map — listings (real estate, Airbnb-style), fleet/logistics dashboards, store locators, anywhere a user picks a location from a viewport. Reach for the controlled `hoveredId` prop when a sibling list and the map need to highlight each other.
+composes_with: [Card (as marker content), Badge, Avatar, Button, Row, Stack, Skeleton]
+---
+
+Default — zero config, MapLibre + MapTiler demo tiles. Works on `gradeui.com` and `localhost` with no setup:
+
+```jsx
+<Map center={[-122.42, 37.78]} zoom={12}>
+  <MapMarker id="hq" at={[-122.42, 37.78]}>
+    <Badge>HQ</Badge>
+  </MapMarker>
+</Map>
+```
+
+Two-way list ↔ map hover sync — the canonical pattern. ALWAYS use the controlled `hoveredId` prop, do NOT call `mapRef.current.flyTo` on every list-item hover yourself:
+
+```jsx
+const [hoveredId, setHoveredId] = useState(null);
+
+<Row>
+  <Stack>
+    {listings.map(l => (
+      <Card
+        key={l.id}
+        onMouseEnter={() => setHoveredId(l.id)}
+        onMouseLeave={() => setHoveredId(null)}
+      >
+        <CardHeader><CardTitle>{l.title}</CardTitle></CardHeader>
+        <CardContent>${l.price}/night</CardContent>
+      </Card>
+    ))}
+  </Stack>
+
+  <Map
+    center={[-122.42, 37.78]}
+    zoom={12}
+    hoveredId={hoveredId}
+    onHoveredIdChange={setHoveredId}
+  >
+    {listings.map(l => (
+      <MapMarker key={l.id} id={l.id} at={l.coords}>
+        <Badge>${l.price}</Badge>
+      </MapMarker>
+    ))}
+  </Map>
+</Row>
+```
+
+Provider swap — one line:
+
+```jsx
+<Map provider="mapbox" accessToken={env.MAPBOX_TOKEN} center={[-0.1, 51.5]} zoom={11} />
+<Map provider="google" apiKey={env.GOOGLE_MAPS_KEY} center={[-0.1, 51.5]} zoom={11} />
+```
+
+ANTI-PATTERNS — don't do these:
+
+- DO NOT pass `{ lat, lng }` objects. Coordinates are ALWAYS `[lng, lat]` tuples. Google's adapter handles the object conversion internally.
+- DO NOT hand-roll an iframe with a Google Maps embed URL. Use `<Map provider="google" apiKey={...}>`.
+- DO NOT use `useRef` + `mapRef.current.flyTo(id)` on list-hover when `hoveredId` already does it controlled.
+- DO NOT call `setStyle` or reach for `mapboxgl.Marker` directly — use `appearance` and `<MapMarker>`. The escape hatch (`mapRef.current.instance`) is for things the wrapper genuinely doesn't expose (3D extrusions, drawing tools, heatmaps).
+- DO NOT render >500 markers without clustering. The component warns in dev. For larger datasets, drop to `.instance` and use the provider's clustering layer.
+
+Markers are DOM — children inherit `--rds-*` tokens. Drop a `<Card>`, `<Badge>`, `<Avatar>`, or anything else inside `<MapMarker>` and it themes correctly.

package/components/ui/media-surface.md

@@ -0,0 +1,18 @@
+---
+name: MediaSurface
+import: "@gradeui/ui"
+props:
+  - aspect?: "video" | "square" | "portrait" | "wide" | "auto" (default "video")
+  - radius?: "none" | "sm" | "md" | "lg" | "xl" (default "lg") — driven by `--rds-media-radius` CSS var
+  - className?: string
+  - children: React.ReactNode
+when_to_use: Low-level shell primitive that wraps a media canvas (video, Rive runtime, WebGL canvas) in an aspect-ratio surface with shared border-radius and pause-on-offscreen behaviour. Prefer VideoPlayer / RivePlayer / ThreeScene, which wrap this. Reach for MediaSurface directly only if you're building a bespoke media component and want consistent chrome.
+composes_with: [VideoPlayer, RivePlayer, ThreeScene — all use this internally]
+aliases: [media, canvas wrapper, media shell]
+---
+
+```jsx
+<MediaSurface aspect="video" radius="lg">
+  <canvas ref={canvasRef} className="w-full h-full" />
+</MediaSurface>
+```

package/components/ui/popover.md

@@ -0,0 +1,36 @@
+---
+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]
+---
+
+```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>
+```

package/components/ui/progress.md

@@ -0,0 +1,14 @@
+---
+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)]
+---
+
+```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]
+---
+
+```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]
+---
+
+```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]
+---
+
+```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]
+---
+
+```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]
+---
+
+```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]
+---
+
+```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,46 @@
+---
+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]
+---
+
+```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>
+```

package/components/ui/side-menu.md

@@ -0,0 +1,40 @@
+---
+name: SideMenu
+import: "@gradeui/ui"
+props:
+  - sections: SideMenuSection[] — top-level groups; each section has `{ title?, items }`
+  - sections[].title?: string — optional group heading
+  - sections[].items: SideMenuItem[] — `{ label, href?, icon?, active?, badge?, onClick? }`
+  - activeHref?: string — auto-derives `active` on matching items; falls back to per-item `active`
+  - onItemClick?: (item) => void — fires for client-side routing; complements per-item onClick
+  - className?: string
+when_to_use: The primary navigation rail inside an AppShell — Admin/Settings/Billing, Inbox/Sent/Archive, file-tree-ish sidebars. Always sits inside <AppShellNav placement="side">. For top horizontal nav, compose Row + Button/Link directly — Side Menu is vertical-stack-of-items by design. For palette-style jump-to, use Command.
+composes_with: [AppShellNav, AppShell, Avatar (header above the menu), Badge (item counts)]
+aliases: [side menu, sidebar nav, side nav, vertical nav, sidebar items, rail, side bar]
+---
+
+```jsx
+// Inbox/Sent/Archive rail inside AppShellNav.
+<AppShellNav placement="side">
+  <SideMenu
+    activeHref="/inbox"
+    sections={[
+      {
+        title: "Mail",
+        items: [
+          { label: "Inbox", href: "/inbox", icon: <Inbox />, badge: "12" },
+          { label: "Sent", href: "/sent", icon: <Send /> },
+          { label: "Archive", href: "/archive", icon: <Archive /> },
+        ],
+      },
+      {
+        title: "Labels",
+        items: [
+          { label: "Work", href: "/label/work", icon: <Tag /> },
+          { label: "Personal", href: "/label/personal", icon: <Tag /> },
+        ],
+      },
+    ]}
+  />
+</AppShellNav>
+```

package/components/ui/simple-tabs.md

@@ -0,0 +1,27 @@
+---
+name: SimpleTabs
+import: "@gradeui/ui"
+subcomponents: [SimpleTabsList, SimpleTabsTrigger, SimpleTabsContent, SimpleTabsRoot, SimpleTabsPanel]
+props:
+  - SimpleTabs: tabs: { value: string; label: string; content: React.ReactNode }[] — fully-data-driven tab strip
+  - SimpleTabs: defaultValue?: string — initial selected tab value
+  - SimpleTabs: value?: string — controlled selected tab
+  - SimpleTabs: onValueChange?: (value: string) => void
+  - SimpleTabs: className?: string — wrapper class
+  - SimpleTabsPanel / SimpleTabsRoot / SimpleTabsList / SimpleTabsTrigger / SimpleTabsContent: composition primitives for when the data-driven prop isn't flexible enough
+when_to_use: A quick tab strip you can declare from data — config-driven settings tabs, model output where the LLM passes an array. For richer composition (icons, tooltips, per-trigger props) reach for the canonical Tabs component instead.
+composes_with: [Card, Dialog]
+aliases: [simple tabs, data tabs, config tabs]
+---
+
+```jsx
+// Data-driven — pass an array of { value, label, content }.
+<SimpleTabs
+  defaultValue="profile"
+  tabs={[
+    { value: "profile", label: "Profile", content: <ProfilePanel /> },
+    { value: "team", label: "Team", content: <TeamPanel /> },
+    { value: "billing", label: "Billing", content: <BillingPanel /> },
+  ]}
+/>
+```