@gradeui/ui 1.1.0 → 1.3.0

package/components/ui/message.md

@@ -0,0 +1,263 @@
+---
+name: Message
+import: "@gradeui/ui"
+props:
+  - author: string — display name of the message author
+  - timestamp?: ReactNode — string ("11:24", "2 hours ago") or any node for custom formatting
+  - avatar?: ReactNode — slot for any `<Avatar>` composition; omit for grouped messages from the same author
+  - badge?: ReactNode — small chip(s) next to the author name (OP, Bot, Admin, role tag)
+  - edited?: boolean | string — renders "(edited)" hint next to timestamp; pass a string to customise ("(edited 2 minutes ago)")
+  - pinned?: boolean — renders a pin glyph + "Pinned" label above the header row for sticky / pinned messages
+  - actions?: ReactNode — end-of-header slot, typically hover-revealed icon buttons (reply / react / more)
+  - reactions?: ReactNode — slot below the body, typically a Row of reaction chips (emoji + count)
+  - threadCount?: number — renders a "N replies" link affordance below the body
+  - onThreadClick?: () => void — handler for the threadCount affordance
+  - align?: "start" | "end" — `start` (default) puts the avatar on the left; `end` mirrors for "your messages" in DM threads
+  - density?: "default" | "compact" — `default` is the canonical chat / channel-feed rhythm; `compact` tightens text sizes + gaps for dense side panels (Studio comments, activity feeds). Pair with `Avatar size="xs"` for the tightest stack.
+  - children: ReactNode — body content (plain text or rich nodes)
+  - className?: string
+when_to_use: |
+  The canonical "avatar + author + timestamp + body" row. THE PRIMITIVE
+  for any chat surface, comment thread, post-reply, activity log, or
+  notification feed that follows the people-and-text shape.
+
+  CONCRETE TEST — if you find yourself composing an `<Avatar>` followed
+  by a `<Row>` of author name + timestamp, with a `<p>` or `<span>`
+  body below, STOP. That is `<Message>`. Reach for it directly.
+
+  Slack-style channel feed, Discord messages, Teams chat, Linear /
+  GitHub / Jira comments, Reddit replies, Twitter/X posts in a thread,
+  Notion comment sidebars, in-app activity logs, notification rows —
+  every one of these IS `<Message>`. Do not roll the layout inline.
+
+  For non-people activity (system events, log lines, status pings) use
+  Callout or a plain Row instead — Message implies a human author.
+composes_with: [Avatar (in the avatar slot — pair with AvatarFallback tone="..." for stable per-author colour), Badge (in the badge slot for role / OP / bot tags), Button (in actions, typically size="icon" + variant="ghost"), Stack (host multiple Messages in a thread), Card (wrap a Stack of Messages for a comment-thread block)]
+aliases: [
+  message, chat message, comment, post, reply, activity row, notification row,
+  thread row, channel message, dm message, slack message, discord message,
+  teams message, channel feed message, feed item, feed row, message row,
+  user message, user post, conversation message, conversation row,
+  inline comment, threaded reply, message bubble, chat bubble, talk bubble
+]
+---
+
+```jsx
+// Comment thread shape — avatar left, body below the author row.
+<Stack gap="md">
+  <Message
+    author="alice"
+    timestamp="2 hours ago"
+    avatar={
+      <Avatar size="sm">
+        <AvatarFallback tone="violet">A</AvatarFallback>
+      </Avatar>
+    }
+  >
+    Splitting this into two PRs makes the review tractable.
+  </Message>
+  <Message
+    author="ben"
+    timestamp="1 hour ago"
+    badge={<Badge variant="outline" className="text-[10px]">OP</Badge>}
+    avatar={
+      <Avatar size="sm">
+        <AvatarFallback tone="amber">B</AvatarFallback>
+      </Avatar>
+    }
+  >
+    Agreed. I'll take the schema PR.
+  </Message>
+</Stack>
+```
+
+```jsx
+// Chat shape — your messages right-aligned via align="end".
+<Stack gap="md">
+  <Message
+    author="alice"
+    timestamp="11:24"
+    avatar={
+      <Avatar size="xs">
+        <AvatarFallback tone="violet">A</AvatarFallback>
+      </Avatar>
+    }
+  >
+    Hey, how's the launch going?
+  </Message>
+  <Message
+    author="you"
+    timestamp="11:26"
+    align="end"
+    avatar={
+      <Avatar size="xs">
+        <AvatarFallback tone="emerald">Y</AvatarFallback>
+      </Avatar>
+    }
+  >
+    Launch image is in, scheduling now.
+  </Message>
+</Stack>
+```
+
+```jsx
+// Full Slack-style message — edited indicator, pinned flag, reactions
+// row, threaded reply count, role badge, hover actions.
+<Message
+  author="alice"
+  timestamp="11:24"
+  edited
+  pinned
+  badge={<Badge variant="secondary" className="text-[10px]">Designer</Badge>}
+  avatar={
+    <Avatar size="md">
+      <AvatarFallback tone="violet">A</AvatarFallback>
+    </Avatar>
+  }
+  reactions={
+    <>
+      <Badge variant="outline" className="gap-1 cursor-pointer">👍 4</Badge>
+      <Badge variant="outline" className="gap-1 cursor-pointer">🎉 2</Badge>
+    </>
+  }
+  threadCount={3}
+  onThreadClick={() => openThread(messageId)}
+>
+  Updated the token spec — review when you have a chance.
+</Message>
+```
+
+```jsx
+// Slack / Discord channel feed — with role badge + hover-revealed actions.
+<Stack gap="lg">
+  {messages.map((m) => (
+    <Message
+      key={m.id}
+      author={m.user}
+      timestamp={m.time}
+      badge={<Badge variant="secondary" className="text-[10px]">{m.role}</Badge>}
+      avatar={
+        <Avatar size="md">
+          <AvatarImage src={m.avatar} />
+          <AvatarFallback tone="sky">{m.user.charAt(0)}</AvatarFallback>
+        </Avatar>
+      }
+      actions={
+        <Row gap="xs" className="opacity-0 group-hover:opacity-100 transition-opacity">
+          <Button size="icon" variant="ghost" className="h-6 w-6"><Smile className="h-3 w-3" /></Button>
+          <Button size="icon" variant="ghost" className="h-6 w-6"><Reply className="h-3 w-3" /></Button>
+          <Button size="icon" variant="ghost" className="h-6 w-6"><MoreHorizontal className="h-3 w-3" /></Button>
+        </Row>
+      }
+      className="group"
+    >
+      {m.text}
+    </Message>
+  ))}
+</Stack>
+```
+
+```jsx
+// Compact density — for narrow side panels (Studio Comments tab,
+// activity feeds, notification rows). Notice the smaller Avatar size
+// pairs naturally with density="compact".
+<Stack gap="sm">
+  <Message
+    density="compact"
+    author="alice"
+    timestamp="2m ago"
+    edited="· edited 1m ago"
+    avatar={
+      <Avatar size="xs">
+        <AvatarFallback tone="violet">A</AvatarFallback>
+      </Avatar>
+    }
+  >
+    Splitting this into two PRs makes the review tractable.
+  </Message>
+  <Message
+    density="compact"
+    author="ben"
+    timestamp="1m ago"
+    avatar={
+      <Avatar size="xs">
+        <AvatarFallback tone="amber">B</AvatarFallback>
+      </Avatar>
+    }
+  >
+    Agreed. I'll take the schema PR.
+  </Message>
+</Stack>
+```
+
+## Anti-patterns
+
+```jsx
+// ❌ Rolling the message layout by hand from Avatar + Row + Badge + spans.
+//    This is the EXACT shape Message exists to consolidate — caught in
+//    the wild on a "Slack clone" prompt where the model assembled this
+//    inline instead of reaching for Message. The result loses the
+//    align="end" knob, the actions slot, the data-gds-part hooks, and
+//    duplicates the same flex template across every consumer.
+{messages.map((msg) => (
+  <div className="group flex gap-4">
+    <Avatar className="w-9 h-9 shrink-0">
+      <AvatarImage src={msg.avatar} />
+      <AvatarFallback>{msg.user.charAt(0)}</AvatarFallback>
+    </Avatar>
+    <div className="flex-1 min-w-0">
+      <Row gap="sm" align="baseline">
+        <span className="font-semibold text-sm">{msg.user}</span>
+        <Badge variant="secondary" className="text-[10px]">{msg.role}</Badge>
+        <span className="text-[10px] text-muted-foreground">{msg.time}</span>
+      </Row>
+      <p className="text-sm mt-1">{msg.text}</p>
+    </div>
+  </div>
+))}
+
+// ✅ The Grade way.
+{messages.map((msg) => (
+  <Message
+    key={msg.id}
+    author={msg.user}
+    timestamp={msg.time}
+    badge={<Badge variant="secondary" className="text-[10px]">{msg.role}</Badge>}
+    avatar={
+      <Avatar size="md">
+        <AvatarImage src={msg.avatar} />
+        <AvatarFallback>{msg.user.charAt(0)}</AvatarFallback>
+      </Avatar>
+    }
+  >
+    {msg.text}
+  </Message>
+))}
+```
+
+```jsx
+// ❌ Building a custom "AuthorDot" or "MessageRow" component inline as
+//    a one-off helper inside a scaffold. Three scaffolds did this before
+//    Message landed; the pattern is always identical.
+function MessageRow({ user, body, time }) {
+  return (
+    <div className="flex gap-3 items-start">
+      <div className="h-7 w-7 rounded-full bg-violet-500/20 ...">{user[0]}</div>
+      <div>
+        <Row><strong>{user}</strong> <small>{time}</small></Row>
+        <p>{body}</p>
+      </div>
+    </div>
+  );
+}
+
+// ✅ Use Message. The colored-initials avatar pattern is covered by
+//    Avatar + AvatarFallback tone="...".
+<Message
+  author={user}
+  timestamp={time}
+  avatar={<Avatar size="sm"><AvatarFallback tone="violet">{user[0]}</AvatarFallback></Avatar>}
+>
+  {body}
+</Message>
+```

package/components/ui/radio-card.md

@@ -0,0 +1,41 @@
+---
+name: RadioCard
+import: "@gradeui/ui"
+props:
+  - value: string (required) — the radio value
+  - label?: ReactNode — title line
+  - description?: ReactNode — secondary line
+  - aside?: ReactNode — slot before the indicator (a Badge, price, hint)
+  - hideIndicator?: boolean — hide the dot; selection shown by the card border + background
+  - indicatorPosition?: "leading" | "trailing" — default trailing
+  - children?: ReactNode — arbitrary static content (image, custom layout) instead of label/description
+when_to_use: Single-select where each option is a whole selectable card (shipping options, plan picker, onboarding choices). The whole card is the control, so focus and the checked state live on the card surface and the entire card is clickable. MUST sit inside a RadioGroup (keeps roving focus + single-select). Static content only — never nest an interactive control (Slider/Input/Button/link) inside. For a plain radio + label row use Field instead.
+composes_with: [RadioGroup (required parent), Badge (in aside), MediaSurface (custom children)]
+aliases: [radio card, selectable card, option card, plan picker, choice card, pricing tier, segmented choice card]
+---
+
+```jsx
+<RadioGroup defaultValue="standard" className="grid gap-3">
+  <RadioCard value="standard" label="Standard" description="4–10 business days" />
+  <RadioCard value="fast" label="Fast" description="2–5 business days" />
+  <RadioCard value="next-day" label="Next day" description="1 business day" />
+</RadioGroup>
+```
+
+Indicator on the leading edge instead of trailing:
+
+```jsx
+<RadioGroup defaultValue="standard" className="grid gap-3">
+  <RadioCard value="standard" indicatorPosition="leading" label="Standard" description="4–10 business days" />
+  <RadioCard value="fast" indicatorPosition="leading" label="Fast" description="2–5 business days" />
+</RadioGroup>
+```
+
+No visible dot (selection reads from the card border + background), laid out in a grid via className on the group:
+
+```jsx
+<RadioGroup defaultValue="m" className="grid grid-cols-2 gap-3">
+  <RadioCard value="s" hideIndicator label="Small" description="Up to 10 seats" />
+  <RadioCard value="m" hideIndicator label="Medium" description="Up to 50 seats" />
+</RadioGroup>
+```

package/components/ui/radio-group.md

@@ -12,8 +12,8 @@ props:
   - 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)]
+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. When each option should be a whole clickable card (label + description, selected state on the card), use RadioCard inside the RadioGroup instead of a Card with a radio in the corner. For a plain label + description row, wrap RadioGroupItem in Field. 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), Field (label + description row), RadioCard (whole-card selectable option), Stack (vertical list)]
 aliases: [radio group, radio buttons, single-choice, pricing options, payment method, radio buttons, radio control, single-select]
 ---
 

package/components/ui/select.md

@@ -4,11 +4,11 @@ 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
+  - SelectTrigger: size?: "default" | "sm" | "xs" — control density; 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.
+  - SelectContent: size?: "default" | "sm" | "xs" — menu density; cascades to every SelectItem inside via context so a compact trigger gets a compact menu. Accepts items via children.
+  - SelectItem: value: string — required; content is the label. Inherits density from SelectContent.
+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. In dense tool panels, set size="xs" on BOTH the trigger and the content so the closed control and open menu match.
 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]
 ---
@@ -22,3 +22,15 @@ aliases: [dropdown, combobox, picker, select, pop-up button, popup button, popup
   </SelectContent>
 </Select>
 ```
+
+Compact, for dense panels — match the trigger and menu density:
+
+```jsx
+<Select defaultValue="md">
+  <SelectTrigger size="xs"><SelectValue /></SelectTrigger>
+  <SelectContent size="xs">
+    <SelectItem value="sm">Small</SelectItem>
+    <SelectItem value="md">Medium</SelectItem>
+  </SelectContent>
+</Select>
+```

package/components/ui/switch-card.md

@@ -0,0 +1,30 @@
+---
+name: SwitchCard
+import: "@gradeui/ui"
+props:
+  - checked? / defaultChecked? / onCheckedChange? — standard switch state
+  - label?: ReactNode — title line
+  - description?: ReactNode — secondary line
+  - aside?: ReactNode — slot before the indicator (a Badge, price, hint)
+  - hideIndicator?: boolean — hide the switch glyph; state shown by the card border + background
+  - indicatorPosition?: "leading" | "trailing" — default trailing
+  - children?: ReactNode — arbitrary static content instead of label/description
+when_to_use: A prominent on/off setting presented as a whole selectable card. The whole card is the switch, so the toggled state lives on the card surface. Standalone. For a row of compact settings (label left, small Switch right) use Field layout="setting" instead — SwitchCard is for the heavier, card-sized toggle.
+composes_with: [Badge (in aside), Stack (stacking several)]
+aliases: [switch card, toggle card, setting card, feature toggle card]
+---
+
+```jsx
+<SwitchCard label="Auto-renew" description="Renew this plan automatically each month" defaultChecked />
+```
+
+Indicator on the leading edge:
+
+```jsx
+<SwitchCard
+  indicatorPosition="leading"
+  label="Auto-renew"
+  description="Renew this plan automatically each month"
+  defaultChecked
+/>
+```

package/components/ui/switch.md

@@ -7,8 +7,8 @@ props:
   - defaultChecked?: boolean
   - disabled?: boolean
   - id?: string
-when_to_use: Instant on/off setting ("Enable notifications", "Dark mode"). Commits on toggle — no submit button needed. For selecting-from-a-list use Checkbox.
-composes_with: [Label (via htmlFor), Card (settings rows)]
+when_to_use: Instant on/off setting ("Enable notifications", "Dark mode"). Commits on toggle — no submit button needed. For selecting-from-a-list use Checkbox. For a settings row (label + description on the left, Switch on the right) use Field layout="setting". For a prominent on/off presented as a whole selectable card, use SwitchCard.
+composes_with: [Label (via htmlFor), Field (layout="setting" settings row), SwitchCard (whole-card toggle), Card (settings rows)]
 aliases: [toggle, switch, on/off switch, ios toggle, toggle switch, switch control, react native switch]
 ---
 

package/components/ui/textarea.md

@@ -2,8 +2,9 @@
 name: Textarea
 import: "@gradeui/ui"
 props:
+  - size?: "default" | "sm" | "xs" — control density, mirrors Input. default = min-h-80 / text-sm; sm and xs shrink the min-height + padding for dense panels.
   - All native textarea HTML attrs (rows, value, onChange, placeholder, disabled)
-when_to_use: Multi-line text entry (descriptions, messages, comments). Pair with a Label. Single-line input → use Input instead.
+when_to_use: Multi-line text entry (descriptions, messages, comments). Pair with a Label. Single-line input → use Input instead. Use size="sm"/"xs" in dense tool panels.
 composes_with: [Label, Form, Card (in CardContent)]
 aliases: [text area, multiline, comment box, message field, text editor, multi-line text, multiline input, multiline text field, comments box, multiline textinput]
 ---

package/components/ui/three-scene.md

@@ -2,7 +2,7 @@
 name: ThreeScene
 import: "@gradeui/ui"
 props:
-  - preset?: "space" | "plasma" | "voronoi" | "synthwave" — shader preset id from the registry
+  - preset?: "mesh" | "waves" | "space" | "plasma" | "voronoi" | "synthwave" — shader preset id from the registry
   - fragmentShader?: string — user-authored GLSL body; takes precedence over preset
   - onShaderError?: (error: ShaderCompileError) => void — fires on compile failure; scene falls back to `preset="space"`
   - postPreset?: "none" | "vhs" | "cinematic" | "synthwave" | "crt" (default "vhs") — post-processing pass
@@ -23,6 +23,8 @@ notes: |
   ## Path 1 — `preset` (pick one, fastest, highest quality)
 
   Valid `preset` ids (complete list — do NOT invent any others):
+    - "mesh"      — smooth moving blobs of primary/secondary/accent over the background; soft, theme-reactive. THE default soft background. Default post: "none".
+    - "waves"     — flowing banded ribbons rippling across the surface; clean motion for headers/heroes. Default post: "none".
     - "space"     — Hyperspace starfield, streaking stars. Default post: "vhs".
     - "plasma"    — soft rolling colour clouds, ambient/abstract. Default post: "synthwave".
     - "voronoi"   — jittered cellular grid with glowing edges. Default post: "crt".
@@ -118,6 +120,25 @@ notes: |
   ## Fullscreen backgrounds
 
   Surface defaults to `aspect="video"` (16:9). For a full-bleed hero background using `className="absolute inset-0"`, ALWAYS also pass `aspect="auto"` — otherwise the aspect-ratio constraint fights the absolute positioning and you get letterboxing.
+
+  ## Layering & tweakable params (direction)
+
+  Shaders are composable, not monolithic. A rendered visual is a BASE
+  layer (the generative scene — gradient, dots, waves, space…) plus a
+  stack of EFFECT layers applied on top (grain, dither, vignette,
+  chromatic…). This is the same model as the post-FX composer — an
+  effect is independent of the base it sits over, so e.g. `grain`
+  applies to ALL bases (mix-and-match).
+
+  Every layer — base and effect — declares a `params: ParamSpec[]`
+  schema (see lib/three/types.ts): `range` (slider + number),
+  `segmented`, `select`, `toggle`, `color`, `colorList`. A param's
+  `key` doubles as the GLSL uniform name, so values map to uniforms
+  generically. The same `ParamSpec` shape is what a controls panel
+  renders from — the Paper-style "Presets + sliders + swatches" panel —
+  and is the canonical "this section is a form" descriptor shared with
+  the inspector controls kit (Input slots, sized Select, segmented
+  control, slider+number).
 ---
 
 ```jsx