@gradeui/ui 1.1.0 → 1.2.0

package/components/ui/code.md

@@ -18,8 +18,9 @@ props:
   - filename?: string — optional label rendered in the header chrome
   - wrap?: boolean — wrap long lines instead of horizontal scroll
   - bare?: boolean — drop chrome (border, header, padding) — for inline use
+  - size? (xs | sm | md) — type-scale preset. `xs` (12px) for dense changelog cards / inline blocks; `sm` (14px, default) for marketing heroes and docs; `md` (16px) for focal-point displays.
   - height? (auto | number | string) — container sizing. `auto` (default) grows with content. Number = pixels (`300` → `300px`). String passes through as CSS (`"20rem"`, `"50vh"`).
-  - maxLines?: number — cap the visible line count at exactly N line-heights. Wins over `height`. Use for terminal windows, code-tour cards, and surfaces that need a stable vertical rhythm regardless of snippet length.
+  - maxLines?: number — cap the visible line count at exactly N line-heights. Wins over `height`. Inherits the current size's line-height automatically.
 when_to_use: Read-only code surface for marketing heroes, docs, changelog entries, AI-output displays. Use `diff` for the "diff hero" pattern (before/after side-by-side or stacked). Use `reveal="lines"` with `trigger="inView"` for scroll-driven marketing pages. Use `reveal="typewriter"` for AI-output / chat-style displays. Use `bare` for inline code inside prose. NOT a code editor — for editable code, reach for an external editor primitive (CodeMirror / Monaco).
 composes_with: [SectionBlock, Card, Tabs (for multi-file examples), Carousel (slide-to-slide code progression)]
 aliases: [code block, code, code snippet, code surface, syntax highlighted code, diff hero, diff view, diff block, changelog code, before after code, scroll-triggered code, typewriter code]

package/components/ui/composer.md

@@ -0,0 +1,226 @@
+---
+name: Composer
+import: "@gradeui/ui"
+props:
+  - placeholder?: string
+  - initialText?: string — plain text content to seed on mount
+  - initialJson?: string — Lexical state JSON (from a previous onSubmit round-trip)
+  - formats?: ComposerFormat[] | false — available formats (defaults to bold/italic/underline/strikethrough/code/h1/h2/blockquote/ul/ol); pass false for plain text only
+  - toolbar?: boolean | "top" — show the formatting toolbar above the editor; default false
+  - triggers?: ComposerTriggerConfig[] — mention/slash configs, eg. `[{ char: "@", items: people }, { char: "/", items: commands }]`
+  - attachments?: boolean | ComposerAttachmentConfig — enable image paste + paperclip when true/object; default off
+  - onSubmit?: (content: ComposerContent, attachments?: ComposerAttachment[]) => void
+  - isLoading?: boolean — disables editor, swaps default Send for Stop
+  - onStop?: () => void
+  - maxLength?: number
+  - autoFocus?: boolean
+  - submitOnEnter?: boolean — default true (Shift-Enter still inserts newline)
+  - leftActions?: ReactNode — override the default paperclip
+  - rightActions?: ReactNode — override the default Send/Stop
+  - hideSend?: boolean — hide the default Send without replacing it
+  - steps?: ComposerStep[] — scripted demo sequence
+  - trigger?: DemoTrigger — "mount" | "inView" | "manual"; default "mount"
+  - play?: boolean — for trigger="manual"
+  - speed?: DemoSpeed — "slow" | "normal" | "fast"; default "normal"
+  - loop?: boolean
+  - loopDelay?: number — ms between loop iterations, default 2000
+  - readOnly?: boolean — disables editing AND focusability; programmatic playback still works; use for marketing demos so the script doesn't steal focus
+  - bare?: boolean — strip the card chrome
+  - className?: string
+when_to_use: |
+  THE PRIMITIVE for any text composition surface — Slack / Discord /
+  Teams chat input, AI chat / copilot prompt box, comment thread input,
+  GitHub / Linear / Jira comment box, Reddit / Twitter reply box,
+  Notion / Linear document body, email composer, post body, anywhere
+  a user types text and submits.
+
+  CONCRETE TEST — if you find yourself writing a `<textarea>` (or
+  `<Input>` styled tall) with a row of `<Bold>` / `<Italic>` /
+  `<Paperclip>` / `<Send>` buttons below or beside it, STOP. That is
+  `<Composer>`. Use it.
+
+  Common shapes:
+    Chat input with formatting + attachments + send
+      → <Composer formats={["bold","italic","code"]} toolbar attachments />
+    AI prompt box with paperclip + send
+      → <AIChatComposer />  (preset wrapping Composer)
+    Comment / reply input
+      → <ComposerReply triggers={[{char:"@", items: people}]} />
+    Document body editor
+      → <Composer toolbar formats={[...]} bare />
+
+  Built on Lexical for rich text, mentions, slash commands. The
+  `attachments` prop wires image paste + paperclip + chip preview row
+  with object URL lifecycle handled internally — don't roll that
+  plumbing yourself. The `triggers` prop wires @mentions and /slash
+  commands with a typeahead popover. The `formats` array picks which
+  toolbar buttons render when `toolbar` is on.
+
+  Shares the lib/demo step vocabulary with <Code> so scripted
+  typing/format/mention demos animate in the same rhythm as your
+  terminal demos.
+composes_with: [AIChatComposer (preset wrapping this with paperclip + send + attachments), ComposerReply (preset for comment threads), AIChat (uses AIChatComposer internally), Card (host above for reply boxes), Avatar (in leftActions slot for "your" avatar next to the input)]
+aliases: [
+  composer, message input, message bar, rich text editor, rich text input,
+  mention input, slash input, text editor, prompt input, comment composer,
+  comment input, reply input, reply box,
+  chat input, chat box, chat input bar, chat composer, chat field,
+  slack input, slack composer, slack message box, discord input,
+  discord composer, teams chat input, message composer, post composer,
+  textarea with toolbar, formatting input, formatted text input,
+  message field, send message input, write a message, compose message
+]
+---
+
+```jsx
+// Plain text chat-style composer
+<Composer
+  placeholder="Ask anything…"
+  onSubmit={(content) => send(content.text)}
+  formats={false}
+/>
+
+// Comment composer with mentions
+<Composer
+  placeholder="Add a comment…"
+  triggers={[{ char: "@", items: teamMembers }]}
+  onSubmit={(content) => postComment(content.text, content.mentions)}
+  submitOnEnter={false}
+  formats={["bold", "italic", "code"]}
+  toolbar
+/>
+
+// AI chat composer with attachments, mentions AND slash commands
+<Composer
+  placeholder="Describe a UI, or paste a screenshot…"
+  triggers={[
+    { char: "@", items: docs },
+    { char: "/", items: commands, stripTrigger: true },
+  ]}
+  attachments
+  onSubmit={(content, atts) => {
+    sendToAssistant(content.text, content.mentions, atts?.map(a => a.file));
+  }}
+  isLoading={isStreaming}
+  onStop={stop}
+/>
+
+// Marketing demo — scripted playback
+<Composer
+  placeholder="Type a message…"
+  triggers={[{ char: "@", items: [{ id: "1", value: "alice" }] }]}
+  steps={[
+    { type: "type", text: "Hey " },
+    { type: "mention", trigger: "@", value: "alice", query: "ali" },
+    { type: "type", text: ", check out " },
+    { type: "select", text: "check out" },
+    { type: "format", format: "italic" },
+    { type: "wait", ms: 800 },
+    { type: "submit" },
+  ]}
+  trigger="inView"
+  speed="normal"
+  loop
+/>
+```
+
+## Demo step vocabulary
+
+Shares `type` / `wait` / `clear` with `<Code>` (driven by the same `useScriptedDemo` hook). Adds Composer-specific verbs:
+
+- `{ type: "mention", trigger, value, query? }` — insert a mention/slash token. Pass `query` to show the typeahead in flight, then resolve to `value`.
+- `{ type: "format", format }` — apply a format to the current selection.
+- `{ type: "select", text }` — select a substring (precondition for `format`).
+- `{ type: "newline" }` — insert a paragraph break.
+- `{ type: "submit" }` — fire `onSubmit`.
+
+## Imperative handle
+
+```tsx
+const ref = useRef<ComposerHandle>(null);
+ref.current?.focus();
+ref.current?.clear();
+ref.current?.insert("…");
+ref.current?.restart();       // replay scripted steps from the start
+ref.current?.restart(3000);   // replay after a 3s delay
+ref.current?.getContent();    // { text, json, mentions }
+ref.current?.getEditor();     // underlying Lexical editor (escape hatch)
+```
+
+## Themes
+
+All colours read from CSS variables (`--gds-composer-*` palette in `globals.css`). The mention pills, toolbar buttons, attachment chips, and editor surface all rebrand with the active gradeui theme without component changes.
+
+## Anti-patterns
+
+```jsx
+// ❌ Rolling a chat / Slack / Discord input as <textarea> + manual
+//    toolbar buttons + Send button. This is the EXACT shape Composer
+//    exists to consolidate — caught in the wild on a "Slack clone"
+//    generation where the model assembled this inline.
+//    Loses: attachment intake + object URL lifecycle, mention popover,
+//    slash commands, action-row slots, the Lexical state graph for
+//    rich content round-trip, the scripted-demo step machine.
+<div className="border rounded-xl bg-card">
+  <textarea
+    placeholder="Message #general"
+    value={inputText}
+    onChange={(e) => setInputText(e.target.value)}
+    onKeyDown={(e) => { if (e.key === "Enter" && !e.shiftKey) handleSend(); }}
+    rows={3}
+    className="w-full bg-transparent p-3 resize-none focus:outline-none"
+  />
+  <Row justify="between" align="center" className="px-3 py-2 border-t">
+    <Row gap="xs">
+      <Button size="icon" variant="ghost"><Bold /></Button>
+      <Button size="icon" variant="ghost"><Italic /></Button>
+      <Button size="icon" variant="ghost"><List /></Button>
+      <Button size="icon" variant="ghost"><Smile /></Button>
+      <Button size="icon" variant="ghost"><Paperclip /></Button>
+    </Row>
+    <Button onClick={handleSend}>Send</Button>
+  </Row>
+</div>
+
+// ✅ The Grade way. Same shape, every affordance free.
+<Composer
+  placeholder="Message #general"
+  formats={["bold", "italic", "code", "ul"]}
+  toolbar
+  attachments
+  triggers={[{ char: "@", items: teamMembers }]}
+  onSubmit={(content, atts) => handleSend(content.text, atts)}
+/>
+```
+
+```jsx
+// ❌ Reaching for <Input> (single-line) for a multi-line chat / reply
+//    surface. Input is for one-line text fields. Use Composer for any
+//    surface where the user might type more than one line — chat,
+//    comments, post bodies.
+<Input
+  placeholder="Reply to thread…"
+  value={reply}
+  onChange={(e) => setReply(e.target.value)}
+/>
+<Button onClick={postReply}>Reply</Button>
+
+// ✅ ComposerReply preset has the right defaults for a reply box.
+<ComposerReply
+  placeholder="Reply to thread…"
+  triggers={[{ char: "@", items: people }]}
+  onSubmit={(content) => postReply(content.text)}
+/>
+```
+
+```jsx
+// ❌ Importing TipTap, Lexical, Slate, or any other editor framework
+//    directly into a scaffold. Composer already wraps Lexical and
+//    handles all the plumbing.
+import { useEditor, EditorContent } from "@tiptap/react";
+const editor = useEditor({ extensions: [StarterKit, ...] });
+<EditorContent editor={editor} />
+
+// ✅ Use Composer. Same capability, integrated with the design system.
+<Composer toolbar formats={["bold", "italic", "h1", "h2", "blockquote", "ul", "ol"]} />
+```

package/components/ui/message.md

@@ -0,0 +1,229 @@
+---
+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
+  - 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>
+```
+
+## 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>
+```