@gradeui/ui 0.8.2 → 0.10.0

package/components/ui/accordion.md

@@ -0,0 +1,30 @@
+---
+name: Accordion
+import: "@gradeui/ui"
+subcomponents: [AccordionItem, AccordionTrigger, AccordionContent]
+props:
+  - Accordion: type: "single" | "multiple" — single keeps one open at a time, multiple lets several be open at once
+  - Accordion: collapsible?: boolean — only valid with type="single"; allows the open item to be toggled shut
+  - Accordion: defaultValue?: string | string[] — initial open item(s)
+  - Accordion: value?: string | string[] — controlled
+  - Accordion: onValueChange?: (value: string | string[]) => void
+  - AccordionItem: value: string — id used by the open-state machinery
+  - AccordionTrigger: children: React.ReactNode — the row label users click to expand
+  - AccordionContent: children: React.ReactNode — the body that animates in
+when_to_use: Long-form content that would overwhelm if shown all at once — FAQs, settings groups, "what's included" sections, nested help. For tab-style peer views with one always visible, reach for Tabs. For a single show/hide reveal use Collapsible.
+composes_with: [Card (as a faq inside a card body), Section primitives]
+aliases: [accordion, faq, expand, collapse list, disclosure list]
+---
+
+```jsx
+<Accordion type="single" collapsible defaultValue="one">
+  <AccordionItem value="one">
+    <AccordionTrigger>What's included?</AccordionTrigger>
+    <AccordionContent>Everything in the design system, plus Studio.</AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="two">
+    <AccordionTrigger>Can I bring my own theme?</AccordionTrigger>
+    <AccordionContent>Yes — three hues in, full theme out.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```

package/components/ui/ai-chat.md

@@ -0,0 +1,35 @@
+---
+name: AIChat
+import: "@gradeui/ui"
+props:
+  - messages?: ChatMessage[] — `{ id, role: "user" | "assistant", content, timestamp }`; defaults to empty
+  - onSendMessage?: (message: string) => void — fires when the user submits a query
+  - isLoading?: boolean — shows a typing indicator on the last assistant turn
+  - placeholder?: string — input placeholder text
+  - suggestedPrompts?: { icon?: React.ReactNode; text: string }[] — empty-state quick prompts
+  - className?: string
+when_to_use: A pre-built chat block — paste it in to get a working LLM chat surface without composing the message list, autoscroll, suggested prompts, and submit input yourself. Reach for it as the "AI panel" in an admin/support tool, or to demo an LLM-driven feature inside a marketing page. For Studio-grade chat with file refs and streaming structured output, you'll outgrow this and want a custom composition built on Textarea + Card + ScrollArea.
+composes_with: [Card (host in a sidebar panel), Sheet (mobile drawer), Stack (place above other content)]
+aliases: [ai chat, chat panel, chat block, llm chat, assistant panel, copilot chat]
+---
+
+```jsx
+const [messages, setMessages] = useState([]);
+const [loading, setLoading] = useState(false);
+
+<AIChat
+  messages={messages}
+  isLoading={loading}
+  onSendMessage={async (text) => {
+    setMessages((m) => [...m, { id: uid(), role: "user", content: text, timestamp: new Date() }]);
+    setLoading(true);
+    const reply = await fetchAssistant(text);
+    setMessages((m) => [...m, { id: uid(), role: "assistant", content: reply, timestamp: new Date() }]);
+    setLoading(false);
+  }}
+  suggestedPrompts={[
+    { icon: <Sparkles />, text: "Summarise this page" },
+    { icon: <Lightbulb />, text: "Suggest next steps" },
+  ]}
+/>
+```

package/components/ui/alert.md

@@ -0,0 +1,21 @@
+---
+name: Alert
+import: "@gradeui/ui"
+subcomponents: [AlertTitle, AlertDescription]
+variants: [default, destructive, success, warning, info, highlight]
+props:
+  - variant? (default | destructive | success | warning | info | highlight)
+  - All native div HTML attrs
+when_to_use: Inline status/feedback that sits inside the layout flow. NOT a toast (use Sonner for transient). NOT a modal (use Dialog). Put an icon as first child — it will be auto-positioned; AlertTitle + AlertDescription follow.
+composes_with: [lucide-react icons as first child, Button (inside AlertDescription), Card (as a section callout)]
+---
+
+Variant tokens come from theme (`--destructive-soft`, `--success-deep`, etc.) so they restyle with the active Grade theme.
+
+```jsx
+<Alert variant="warning">
+  <AlertTriangle />
+  <AlertTitle>Low disk space</AlertTitle>
+  <AlertDescription>2GB remaining on /dev/sda1.</AlertDescription>
+</Alert>
+```

package/components/ui/app-shell.md

@@ -0,0 +1,61 @@
+---
+name: AppShell
+import: "@gradeui/ui"
+role: layout
+subcomponents: [AppShellNav, AppShellMain]
+props:
+  - nav?: "none" | "top" | "side" (default "none") — layout structure. "top" puts the nav above main, "side" to the left, "none" hides it
+  - asChild?: boolean (default false) — render as the child element via Slot
+  - className?: string
+  - children: React.ReactNode
+when_to_use: The top-level page scaffold for app-like layouts — any screen that needs a nav region plus a content region. Reach for AppShell instead of hand-rolled `grid grid-cols-[auto_1fr]` so the layout shape (top vs side nav, constrained vs full-width main) is a prop the settings panel can mutate. Drop a Stack of nav items into AppShellNav for the nav region; drop a Stack into AppShellMain for the page's vertical rhythm.
+composes_with: [Stack, Row, Card, Button, Separator, any page content]
+aliases: [app shell, page shell, layout, app layout, dashboard shell, scaffold]
+notes: |
+  Three parts:
+    AppShell        — <div> by default; sets the grid (nav=none|top|side)
+    AppShellNav     — <nav> by default; props: placement ("top"|"side"|"none", match AppShell.nav), sticky (boolean, default true)
+    AppShellMain    — <main> by default; props: maxWidth ("full"|"container", default "full")
+  All three support asChild and emit data-gds-part ("app-shell", "app-shell-nav", "app-shell-main").
+  Pure structure — no collapse state, no context. Server-renders cleanly.
+  For nav placement="side" + sticky=true the nav gets h-screen + self-scroll, so long nav lists don't push main down.
+---
+
+```jsx
+// Side nav + full-width main — the classic dashboard shape.
+<AppShell nav="side">
+  <AppShellNav placement="side">
+    {/* nav items — Stack of Buttons, a SideMenu, etc. */}
+  </AppShellNav>
+  <AppShellMain>
+    <Stack gap="lg" className="p-6">
+      {/* page content */}
+    </Stack>
+  </AppShellMain>
+</AppShell>
+```
+
+```jsx
+// Top nav + constrained content — marketing / docs / settings pages.
+<AppShell nav="top">
+  <AppShellNav placement="top">
+    <Row justify="between" align="center" className="px-6 py-3">
+      {/* logo + nav buttons */}
+    </Row>
+  </AppShellNav>
+  <AppShellMain maxWidth="container">
+    <Stack gap="lg" className="py-8">
+      {/* page content */}
+    </Stack>
+  </AppShellMain>
+</AppShell>
+```
+
+```jsx
+// No nav — just a shell for a single-screen prototype.
+<AppShell nav="none">
+  <AppShellMain maxWidth="container">
+    {/* page content */}
+  </AppShellMain>
+</AppShell>
+```

package/components/ui/avatar.md

@@ -0,0 +1,18 @@
+---
+name: Avatar
+import: "@gradeui/ui"
+subcomponents: [AvatarImage, AvatarFallback]
+props:
+  - Avatar: className? — set size via utilities (default h-10 w-10)
+  - AvatarImage: src, alt
+  - AvatarFallback: initials/icon rendered when image fails or loads
+when_to_use: User/entity identity in lists, cards, headers. Always include AvatarFallback so load failure doesn't leave a gap.
+composes_with: [Card (in CardHeader), Table cells, Badge (placed next to for status), Skeleton (loading state)]
+---
+
+```jsx
+<Avatar>
+  <AvatarImage src="/ada.jpg" alt="Ada Lovelace" />
+  <AvatarFallback>AL</AvatarFallback>
+</Avatar>
+```

package/components/ui/badge.md

@@ -0,0 +1,18 @@
+---
+name: Badge
+import: "@gradeui/ui"
+variants: [default, secondary, destructive, outline, highlight, success, warning, info, success-soft, warning-soft, destructive-soft, info-soft, highlight-soft, success-outline, warning-outline, destructive-outline, info-outline]
+props:
+  - variant? (see list above)
+  - rounded? (default | full) — "full" gives a pill shape
+  - All native div HTML attrs
+when_to_use: Compact status chips, counts, tags, pills. For higher-signal inline status → use Alert. For solid CTAs → Button. Soft/outline variants are quieter; solid variants are loud.
+composes_with: [Card, Table (inside a cell), Avatar (next to it), anywhere inline]
+aliases: [chip, tag, pill, label chip]
+---
+
+```jsx
+<Badge>New</Badge>
+<Badge variant="success-soft" rounded="full">Active</Badge>
+<Badge variant="destructive-outline">Blocked</Badge>
+```

package/components/ui/breadcrumb.md

@@ -0,0 +1,54 @@
+---
+name: Breadcrumb
+import: "@gradeui/ui"
+subcomponents: [BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator, BreadcrumbEllipsis]
+props:
+  - Breadcrumb: aria-label? (defaults to "breadcrumb") — passed to the underlying <nav>
+  - BreadcrumbList: className? — the <ol> wrapper; usually no overrides needed
+  - BreadcrumbItem: className? — wraps a single crumb (link or page)
+  - BreadcrumbLink: href? — renders as <a> when set, <button> when not; asChild? wraps a custom element
+  - BreadcrumbPage: className? — the current page; rendered as a non-interactive <span> with aria-current="page"
+  - BreadcrumbSeparator: children? (defaults to a chevron) — the visual separator between crumbs
+  - BreadcrumbEllipsis: className? — collapsed middle crumbs marker, use between BreadcrumbItems
+when_to_use: Reach for Breadcrumb whenever a screen sits inside a hierarchy and you want the path back to the top to be visible. Common spots: above page titles in admin/CMS screens, top of Settings detail pages, after a router redirect when the URL implies depth. Use the current page as a <BreadcrumbPage> (non-clickable) and prior levels as <BreadcrumbLink>. For a horizontal "top nav" of peer destinations use Side Menu or Tabs instead — Breadcrumb is strictly for hierarchical path.
+composes_with: [AppShellMain, Card (in CardHeader), Dialog]
+aliases: [breadcrumb, breadcrumbs, crumbs, path, page hierarchy]
+---
+
+```jsx
+// Two-level path — Dashboard → current page.
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/">Dashboard</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>Settings</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```
+
+```jsx
+// Deep path with collapsed middle — useful when the path is long.
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/">Home</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbEllipsis />
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/projects/acme">Acme</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>Billing</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```

package/components/ui/button.md

@@ -0,0 +1,31 @@
+---
+name: Button
+import: "@gradeui/ui"
+variants: [default, destructive, outline, secondary, ghost, link]
+sizes: [sm, md, lg, icon]
+props:
+  - variant? (default | destructive | outline | secondary | ghost | link)
+  - size? (sm | md | lg | icon) — t-shirt scale aligned with Tabs/ToggleGroup heights (sm=h-7, md=h-8, lg=h-10). `default` still works as an alias for `md`.
+  - asChild?: boolean — renders as the child element (use to wrap <a>/<Link>)
+  - disabled?: boolean
+  - All native button HTML attrs (onClick, type, etc.)
+when_to_use: Any clickable action. Use size="icon" for square icon-only buttons, variant="link" for inline links that should look like Button. A Button placed next to a TabsList of the same size lines up edge-to-edge without per-call overrides.
+composes_with: [Dialog, DropdownMenu, Tooltip, Card (in CardFooter), Row, Form controls]
+---
+
+```jsx
+<Button>Save</Button>
+<Button variant="outline" size="sm">Cancel</Button>
+<Button size="icon" variant="ghost"><Mail /></Button>
+```
+
+```jsx
+// Lined up next to a TabsList — same size = same height.
+<Row gap="sm" align="center">
+  <TabsList size="sm">
+    <TabsTrigger value="all">All</TabsTrigger>
+    <TabsTrigger value="open">Open</TabsTrigger>
+  </TabsList>
+  <Button size="sm">New issue</Button>
+</Row>
+```

package/components/ui/calendar.md

@@ -0,0 +1,39 @@
+---
+name: Calendar
+import: "@gradeui/ui"
+subcomponents: [CalendarDayButton]
+props:
+  - mode?: "single" | "multiple" | "range" — picks one date, several dates, or a [from, to] range
+  - selected?: Date | Date[] | { from: Date; to?: Date } — controlled selection; shape matches `mode`
+  - onSelect?: (value) => void — fires with the new selection
+  - month?: Date — controlled displayed month
+  - defaultMonth?: Date — uncontrolled initial month
+  - onMonthChange?: (date: Date) => void
+  - numberOfMonths?: number (default 1) — render multiple months side by side, useful for range pickers
+  - disabled?: Date | Date[] | { before?: Date; after?: Date } | (date: Date) => boolean
+  - captionLayout?: "label" | "dropdown" | "dropdown-months" | "dropdown-years"
+  - className?: string
+when_to_use: An inline date grid — date-of-birth pickers in profile forms, scheduling screens with a month view, range selection in reporting filters. For a compact trigger-and-popover input, use DatePicker / DateRangePicker (which wrap Calendar internally). For one-off relative dates ("yesterday", "last week") use a Select instead.
+composes_with: [Popover (DatePicker composes them), Card (inline scheduling card), Dialog (full-screen mobile date pick)]
+aliases: [calendar, date grid, month view, scheduler grid]
+---
+
+```jsx
+// Single-date inline calendar.
+<Calendar
+  mode="single"
+  selected={date}
+  onSelect={setDate}
+  captionLayout="dropdown"
+/>
+```
+
+```jsx
+// Two-month range picker — typical reporting filter shape.
+<Calendar
+  mode="range"
+  numberOfMonths={2}
+  selected={range}
+  onSelect={setRange}
+/>
+```

package/components/ui/card.md

@@ -0,0 +1,25 @@
+---
+name: Card
+import: "@gradeui/ui"
+subcomponents: [CardHeader, CardTitle, CardDescription, CardContent, CardFooter]
+props:
+  - Each subcomponent accepts native div HTML attrs (className, etc.)
+  - No variants — Card is a flexible container surface
+when_to_use: Grouped content with a distinct surface — settings panels, dashboard tiles, list-of-cards layouts. Pair CardHeader (title + description) with CardContent and optional CardFooter (actions).
+composes_with: [Button (in CardFooter), Badge, Separator, Avatar, any form controls]
+---
+
+Canonical structure — do NOT skip CardHeader if the card has a title:
+
+```jsx
+<Card>
+  <CardHeader>
+    <CardTitle>Billing</CardTitle>
+    <CardDescription>Manage your subscription.</CardDescription>
+  </CardHeader>
+  <CardContent>…</CardContent>
+  <CardFooter>
+    <Button>Save</Button>
+  </CardFooter>
+</Card>
+```

package/components/ui/chart.md

@@ -0,0 +1,48 @@
+---
+name: ChartContainer
+import: "@gradeui/ui"
+subcomponents: [ChartTooltip, ChartTooltipContent, ChartLegend, ChartLegendContent, ChartStyle]
+notes: ChartContainer wraps a Recharts chart — bring your own Bar/Line/Area/Pie/Radar from "recharts" and place it inside. The wrapper threads design-system tokens through Recharts' style props and provides a styled tooltip + legend.
+props:
+  - ChartContainer: config: ChartConfig — `{ [seriesKey]: { label: string; color?: string; theme?: { light: string; dark: string } } }`; the keys here are the names you reference in your Recharts <Bar dataKey="…" /> calls
+  - ChartContainer: id?: string — used for the inlined <style> tag
+  - ChartContainer: children: React.ReactNode — typically a single Recharts ResponsiveContainer or chart
+  - ChartTooltip: passes through to Recharts <Tooltip> — pair with `content={<ChartTooltipContent />}`
+  - ChartTooltipContent: indicator? "dot" | "line" | "dashed"; hideLabel?, hideIndicator?, nameKey?, labelKey?
+  - ChartLegend / ChartLegendContent: pair the same way for the legend
+when_to_use: Reporting dashboards, single-purpose analytics cards (revenue, conversions, active users), or anywhere you'd otherwise hand-roll a Recharts setup. Bring the actual chart type from `recharts` — ChartContainer doesn't pick the chart shape for you, it themes whatever you nest. For sparkline-style decorative trends consider just rendering a small SVG line directly; ChartContainer is overkill for non-interactive ornament.
+composes_with: [Card (chart-in-a-card pattern), Tabs (multi-metric switcher), Recharts components (Bar, Line, Area, Pie, Radar from "recharts")]
+aliases: [chart, charts, graph, bar chart, line chart, area chart, recharts, analytics chart]
+---
+
+```jsx
+// Revenue-by-month bar chart inside a Card.
+import { Bar, BarChart, CartesianGrid, XAxis } from "recharts";
+
+const data = [
+  { month: "Jan", revenue: 12400 },
+  { month: "Feb", revenue: 14210 },
+  { month: "Mar", revenue: 15880 },
+  { month: "Apr", revenue: 17050 },
+];
+
+const config = {
+  revenue: { label: "Revenue", color: "hsl(var(--primary))" },
+} satisfies ChartConfig;
+
+<Card>
+  <CardHeader>
+    <CardTitle>Revenue</CardTitle>
+  </CardHeader>
+  <CardContent>
+    <ChartContainer config={config} className="h-64">
+      <BarChart data={data}>
+        <CartesianGrid vertical={false} />
+        <XAxis dataKey="month" tickLine={false} axisLine={false} />
+        <ChartTooltip content={<ChartTooltipContent />} />
+        <Bar dataKey="revenue" fill="var(--color-revenue)" radius={4} />
+      </BarChart>
+    </ChartContainer>
+  </CardContent>
+</Card>
+```

package/components/ui/checkbox.md

@@ -0,0 +1,19 @@
+---
+name: Checkbox
+import: "@gradeui/ui"
+props:
+  - checked?: boolean | "indeterminate"
+  - onCheckedChange?: (checked: boolean) => void
+  - defaultChecked?: boolean
+  - disabled?: boolean
+  - id?: string — bind a Label's htmlFor to this
+when_to_use: Binary on/off tied to a list (select multiple, agree to terms). Single on/off that controls a setting is better with Switch.
+composes_with: [Label (via htmlFor), Card, Form rows, Table (for row selection)]
+---
+
+```jsx
+<div className="flex items-center gap-2">
+  <Checkbox id="terms" />
+  <Label htmlFor="terms">I agree to the terms</Label>
+</div>
+```

package/components/ui/collapsible.md

@@ -0,0 +1,28 @@
+---
+name: Collapsible
+import: "@gradeui/ui"
+subcomponents: [CollapsibleTrigger, CollapsibleContent]
+props:
+  - Collapsible: open?: boolean — controlled open state
+  - Collapsible: defaultOpen?: boolean — uncontrolled initial state
+  - Collapsible: onOpenChange?: (open: boolean) => void
+  - CollapsibleTrigger: children: React.ReactNode — the clickable header (often a Button asChild)
+  - CollapsibleContent: children: React.ReactNode — the content that animates in/out
+when_to_use: A single show/hide reveal — "Show advanced settings" rows, expandable inline help, "More details" sections inside cards. For multiple rows of expandable content where one-at-a-time matters, reach for Accordion. For a separate panel that floats above content, use Popover.
+composes_with: [Button (as the trigger, asChild), Card (expandable settings group), Row (header + chevron)]
+aliases: [collapsible, expand, show more, disclosure, advanced settings]
+---
+
+```jsx
+<Collapsible defaultOpen={false}>
+  <CollapsibleTrigger asChild>
+    <Button variant="ghost" size="sm">
+      Advanced settings <ChevronDown />
+    </Button>
+  </CollapsibleTrigger>
+  <CollapsibleContent className="space-y-2 pt-2">
+    <Label htmlFor="cors">CORS origins</Label>
+    <Input id="cors" placeholder="https://example.com" />
+  </CollapsibleContent>
+</Collapsible>
+```

package/components/ui/command.md

@@ -0,0 +1,38 @@
+---
+name: Command
+import: "@gradeui/ui"
+subcomponents: [CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator, CommandShortcut, CommandDialog]
+props:
+  - Command: value?: string — controlled active item value
+  - Command: onValueChange?: (value: string) => void
+  - CommandInput: placeholder?: string
+  - CommandList: children: React.ReactNode — wraps groups and empty state
+  - CommandEmpty: children: React.ReactNode — fallback when no items match
+  - CommandGroup: heading?: string
+  - CommandItem: value?: string — used for filter matching and selection emit
+  - CommandItem: onSelect?: (value: string) => void
+  - CommandItem: disabled?: boolean
+  - CommandShortcut: children: React.ReactNode — right-aligned keyboard hint (⌘K, ⌥F)
+  - CommandDialog: open, onOpenChange — when you want the command palette mounted in a modal (cmd+k pattern)
+when_to_use: A searchable list of actions or destinations — global ⌘K palettes, "jump to" inputs, account switchers with filter. Wrap in CommandDialog when it should pop over the entire app on a hotkey. For straight forms with filter, prefer a Select with a search input. For free-text autocomplete tied to a single value, prefer Combobox built on Popover + Command.
+composes_with: [Dialog (CommandDialog wraps it), Popover (inline combobox), Tooltip]
+aliases: [command palette, command menu, cmd k, quick switcher, action menu]
+---
+
+```jsx
+// Global ⌘K palette — toggled with a keydown listener at the app root.
+<CommandDialog open={open} onOpenChange={setOpen}>
+  <CommandInput placeholder="Type a command…" />
+  <CommandList>
+    <CommandEmpty>No results found.</CommandEmpty>
+    <CommandGroup heading="Navigate">
+      <CommandItem onSelect={() => router.push("/docs")}>
+        <Book /> Docs <CommandShortcut>⌘D</CommandShortcut>
+      </CommandItem>
+      <CommandItem onSelect={() => router.push("/studio")}>
+        <Sparkles /> Studio <CommandShortcut>⌘S</CommandShortcut>
+      </CommandItem>
+    </CommandGroup>
+  </CommandList>
+</CommandDialog>
+```

package/components/ui/date-picker.md

@@ -0,0 +1,52 @@
+---
+name: DatePicker
+import: "@gradeui/ui"
+props:
+  - value?: Date (single) | DateRange (range)
+  - onChange?: (value) => void — called on select or clear
+  - placeholder?: string — trigger label when empty (default "Pick a date" / "Pick a date range")
+  - disabled?: boolean
+  - format?: string — date-fns format token for the trigger label (default "PPP" single, "LLL dd, y" range)
+  - align?: "start" | "center" | "end" — popover align (default "start")
+  - side?: "top" | "right" | "bottom" | "left" — popover side
+  - captionLayout?: "label" | "dropdown" | "dropdown-months" | "dropdown-years"
+  - className?: string — on the trigger button
+  - contentClassName?: string — on the PopoverContent
+  - icon?: ReactNode — replaces the default CalendarIcon
+  - numberOfMonths?: number — DateRangePicker only, default 2
+when_to_use: Any date or date-range entry. Use DatePicker for a single date (DOB, due date, booking). Use DateRangePicker for a span (report period, stay dates, filter window). Prefer these over <Input type="date"> — consistent theming, keyboard nav, a11y, and no browser-native UI drift.
+composes_with: [Label, Form, Card (in CardContent), Button (form submit)]
+subcomponents: [DateRangePicker]
+aliases: [datepicker, calendar input, date field, date range]
+---
+
+```jsx
+// Single date
+<div className="grid gap-1.5">
+  <Label htmlFor="dob">Date of birth</Label>
+  <DatePicker
+    value={date}
+    onChange={setDate}
+    placeholder="Select your birthday"
+  />
+</div>
+```
+
+```jsx
+// Date range
+<DateRangePicker
+  value={range}
+  onChange={setRange}
+  numberOfMonths={2}
+/>
+```
+
+```jsx
+// With presets — pair with Button shortcuts
+<div className="flex items-center gap-2">
+  <DatePicker value={date} onChange={setDate} />
+  <Button variant="outline" size="sm" onClick={() => setDate(new Date())}>Today</Button>
+</div>
+```
+
+Built internally from Popover + Button + Calendar. If you need a custom trigger or different popover positioning, compose the primitives directly — Calendar and Popover are exported from the same barrel.

package/components/ui/dialog.md

@@ -0,0 +1,29 @@
+---
+name: Dialog
+import: "@gradeui/ui"
+subcomponents: [DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter, DialogClose]
+props:
+  - Dialog: open?, onOpenChange? — Radix controlled/uncontrolled pattern
+  - DialogTrigger: asChild? (wrap a Button)
+  - DialogContent: accepts native div HTML attrs
+  - DialogFooter: used for action rows
+when_to_use: Modal interruptions — confirmations, focused forms, detail views. For non-blocking messaging use Alert or Sonner. Always include DialogTitle (a11y requirement).
+composes_with: [Button (as DialogTrigger asChild, and inside DialogFooter), Input/Textarea/Select inside DialogContent]
+aliases: [modal, popup, overlay]
+---
+
+```jsx
+<Dialog>
+  <DialogTrigger asChild><Button>Delete</Button></DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Delete project?</DialogTitle>
+      <DialogDescription>This cannot be undone.</DialogDescription>
+    </DialogHeader>
+    <DialogFooter>
+      <Button variant="outline">Cancel</Button>
+      <Button variant="destructive">Delete</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```

package/components/ui/dropdown-menu.md

@@ -0,0 +1,39 @@
+---
+name: DropdownMenu
+import: "@gradeui/ui"
+subcomponents: [DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuGroup, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent]
+props:
+  - DropdownMenu: open?, defaultOpen?, onOpenChange?, modal? (default true)
+  - DropdownMenuTrigger: asChild?: boolean — usually wraps a Button
+  - DropdownMenuContent: align? "start" | "center" | "end"; side? "top" | "right" | "bottom" | "left"; sideOffset? number
+  - DropdownMenuItem: onSelect?, disabled?, asChild?, inset?
+  - DropdownMenuCheckboxItem / DropdownMenuRadioItem: checked? / value, onCheckedChange? / onValueChange? (radio is on the group)
+  - DropdownMenuSub / DropdownMenuSubTrigger / DropdownMenuSubContent: nested menu — sub-trigger shows children, sub-content holds the deeper items
+  - DropdownMenuShortcut: children — right-aligned kbd hint
+when_to_use: A small action menu attached to a trigger — overflow "…" buttons on cards, user-avatar menus in headers, "Insert" menus in editors. For a full searchable list, use Command. For ONE primary action plus a secondary, use a Button next to a smaller ghost Button instead of a dropdown.
+composes_with: [Button (as trigger asChild), Avatar (user menu), Card (overflow on a tile), Tooltip (on the trigger)]
+aliases: [dropdown, dropdown menu, overflow menu, kebab menu, more menu, action menu, context-style menu]
+---
+
+```jsx
+// Overflow menu on a card/row — trigger an icon-only Button.
+<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <Button variant="ghost" size="icon" aria-label="Open menu">
+      <MoreHorizontal />
+    </Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent align="end">
+    <DropdownMenuItem onSelect={onDuplicate}>
+      <Copy /> Duplicate
+    </DropdownMenuItem>
+    <DropdownMenuItem onSelect={onShare}>
+      <Share2 /> Share
+    </DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem onSelect={onDelete} className="text-destructive">
+      <Trash /> Delete
+    </DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```

package/components/ui/flex.md

@@ -0,0 +1,41 @@
+---
+name: Flex
+import: "@gradeui/ui"
+role: layout
+props:
+  - direction?: "row" | "col" | "row-reverse" | "col-reverse" (default "row") — main-axis direction
+  - gap?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" (default "none") — gap between children
+  - align?: "start" | "center" | "end" | "stretch" | "baseline" (default "stretch") — cross-axis alignment
+  - justify?: "start" | "center" | "end" | "between" | "around" | "evenly" (default "start") — main-axis distribution
+  - wrap?: "nowrap" | "wrap" | "wrap-reverse" (default "nowrap") — wrap behaviour when children overflow
+  - asChild?: boolean (default false) — render as the child element via Slot
+  - className?: string
+  - children: React.ReactNode
+when_to_use: The unopinionated flexbox primitive — reach for Flex when Stack, Row, or Grid don't quite fit. Specifically when you need reverse direction (`row-reverse` / `col-reverse`), CSS defaults instead of Row's baked-in `items-center gap-md`, or baseline alignment. Otherwise prefer Stack / Row / Grid — they're easier to read and tuned for the 95% case. Flex is the escape hatch, not the default.
+composes_with: [any content component]
+aliases: [flex, flexbox, flex container, hstack, vstack, horizontal, vertical]
+---
+
+```jsx
+// Reverse direction — last child appears first (e.g. timestamp before avatar).
+<Flex direction="row-reverse" gap="sm" align="center">
+  <Avatar />
+  <span>2m ago</span>
+</Flex>
+```
+
+```jsx
+// CSS-default Flex — no rhythm baked in, opt into each axis deliberately.
+<Flex direction="col" justify="between" className="h-full">
+  <Header />
+  <Footer />
+</Flex>
+```
+
+```jsx
+// Baseline alignment for icon + text where the caps line should line up.
+<Flex gap="sm" align="baseline">
+  <Icon />
+  <h2 className="text-2xl">Heading</h2>
+</Flex>
+```