makersclaw 0.2.0 → 0.3.1

package/registry/blocks/chat/README.md

@@ -0,0 +1,273 @@
+# Chat
+
+The parts of a chat, and a thread made of them. `Message` is one turn:
+avatar, name, time, the words in a `Bubble`, its files, its state
+(sending, streaming, failed with Retry) and the actions that appear on
+hover or focus (copy, regenerate, a menu of yours). `MessageScroller` is
+the list: it keeps to the bottom while a reply streams unless the reader
+scrolled up, then offers "Jump to latest"; it puts a day between days,
+runs consecutive messages from one author together, loads older messages
+from the top and says each finished reply to a screen reader.
+`Composer` is the input: it grows with the text, Enter sends,
+Shift+Enter is a new line, files come by paperclip, paste or drop, and
+Send becomes Stop while a reply streams; it comes as a box or as the
+round "ask anything" pill, with a "+" menu, your tools in its bar and
+suggestion chips. An assistant reply can fold its reasoning away
+("Thought for 4s") and take a thumbs up or down; a user message can be
+edited in place. `ChatHeader` is the strip over a thread (name, status,
+actions). `Attachment` is one file. `ChatThread` puts them together from
+`messages` and `onSend`.
+
+```jsx
+import { ChatThread } from "../components/blocks/chat";   // a Makersclaw app ("./blocks/chat" from components/)
+import { ChatThread } from "@/components/makersclaw/blocks/chat";   // a shadcn project
+```
+
+Every part is a client component: render them from a `"use client"`
+component. The block imports nothing but React and the kit — it holds no
+conversation and calls no model. The messages come in as a prop and the
+send goes out as `onSend`; where the reply comes from (your server action,
+the AI SDK's `useChat`, a support inbox table) is the surface's.
+
+This is not the app window's Agent tab — the OS draws that. It is for a
+conversation that lives on your own screen: a support reply pane, a
+customer-facing assistant, comments on a record.
+
+## The data
+
+A message:
+
+```js
+{
+  id: "m5",                       // stable; the list is keyed on it
+  role: "user",                   // user · assistant · system
+  content: "It's still showing…", // a string — or `parts: [{ type: "text", text }]`
+  createdAt: "2026-09-23T10:04:00Z",
+  author: { name: "Maya Chen", src: "https://…" },   // optional
+  status: "failed",               // sending · streaming · failed · nothing (sent)
+  error: "you are offline",       // shown with a failed message
+  attachments: [{ id, name, size, type, url }],      // size in bytes; url shows an image's thumbnail
+  reasoning: "They asked about the double charge…",  // assistant only: folded over the reply
+  reasoningDuration: 4,           // seconds: "Thought for 4s"
+  feedback: "up",                 // up · down — the thumbs already given (assistant only)
+}
+```
+
+`reasoning` is drawn in a kit `Collapsible`, closed, over the reply.
+While the message streams with no answer yet it reads "Thinking…"; give
+`reasoning: ""` from the start to show that line instead of the three
+dots.
+
+A message with `parts` (the AI SDK's shape) is drawn from its text parts;
+other parts are not drawn. A `system` message is a centred muted line.
+An assistant message with `status: "streaming"` and no text yet shows
+three dots; with text it shows a caret after it.
+
+The words are drawn by a small safe renderer — never as HTML, and with no
+markdown library. It understands fenced code blocks (with a Copy button;
+an unclosed fence runs to the end, so a block still streaming already
+looks like one), `code spans`, `**bold**` and line breaks. Everything else
+(links, lists, headings) is plain text. `<script>` in a message is shown,
+not run.
+
+## Props
+
+### ChatThread
+
+- `messages` — the conversation, oldest first.
+- `onSend(text, attachments)` — send it. The composer clears at once;
+  return `{ ok: false, error }` (or throw) and the text comes back to the
+  field with the reason under it. The usual pattern is to add the message
+  with `status: "sending"` here, then mark it sent or `failed`.
+- `streaming` — a reply is streaming: Send becomes Stop, Esc stops.
+  Default: true while any message has `status: "streaming"`.
+- `onStop()` — stop the reply.
+- `onRetry(message)` — the Retry on a failed message. Without it, a
+  failed message says so and offers nothing.
+- `onRegenerate(message)` — a regenerate button on assistant messages.
+- `actionsOf(message)` — more items for a message's menu, kit `Menu`
+  shape: `[{ label, onSelect, icon?, tone?: "danger" }]`.
+- `onFeedback(message, "up" | "down" | null)` — thumbs up and down on
+  assistant replies (pressing the chosen one again clears it: `null`).
+  The choice shows at once; return `{ ok: false, error }` (or throw) and
+  it goes back, with the reason under the message. Store it and pass it
+  back as `message.feedback`.
+- `onEdit(message, text)` — an edit button on your own messages. The
+  words come back in a field: Enter or Save saves, Esc or Cancel leaves
+  them. Return `{ ok: false, error }` and the field stays open with the
+  reason. Up arrow in an empty composer edits the last message you sent.
+  What an edit does next (drop the replies after it, ask again) is yours.
+- `header` — a node over the list, or the props of a `ChatHeader`
+  (`{ title, status, actions, menu }`).
+- `shape` — the composer: `"box"` (default) or `"pill"` (see Composer).
+- `tools` · `menu` — the composer's bar: nodes of yours, and kit `Menu`
+  items behind a "+" (see Composer).
+- `suggestions` — prompt chips over the composer:
+  `[{ label, prompt?, icon?, description? }]`. Shown while the thread is
+  empty; `suggestionsWhen="always"` keeps them. `suggestionMode`
+  `"send"` (the default here: a press sends `prompt ?? label`) or
+  `"fill"` (puts it in the field). `suggestionsLook` `"chips"` (default)
+  or `"cards"`.
+- `onLoadMore()` · `hasMore` (false) · `loadingMore` (false) — older
+  messages. Reaching the top (or pressing "Load earlier messages") calls
+  `onLoadMore`; prepend them to `messages` and the reader keeps their place.
+- `attachments` · `onAttach(files)` · `onRemoveAttachment(att)` · `accept`
+  — files waiting in the composer. `onAttach` gets the browser's `File`s:
+  upload them and pass them back in `attachments` as
+  `{ id, name, size, type, url?, progress?, error? }` (`progress` 0–100
+  draws a bar; Send waits until every upload is at 100). Without
+  `onAttach` there is no paperclip. They reach `onSend` as its second
+  argument.
+- `disabled` (false) · `disabledPlaceholder` · `placeholder` — a closed
+  or read-only thread.
+- `variant` — how assistant words sit: `"plain"` (default, on the page)
+  or `"bubble"`. User messages are always filled bubbles at the end.
+- `assistantName` ("Assistant") · `assistantAvatar` · `userName` ("You")
+  · `userAvatar` · `showUserAvatar` (false) — who is who, when a message
+  has no `author`.
+- `emptyTitle` · `emptyBody` · `emptyState` — what an empty thread says;
+  `emptyState` replaces the whole thing.
+- `height` — default `"min(40rem, 80dvh)"`; the list scrolls inside it.
+- `label` — what the thread is called to a screen reader.
+- `className` — layout around it (width, margin). Never colour.
+
+### Message
+
+`message` (the shape above), `first` / `last` (its place in a run from
+one author: `first` shows the avatar, name and time), `latest` (the
+newest reply: its actions stay in view instead of waiting for hover), and `variant`,
+`assistantName`, `assistantAvatar`, `userName`, `userAvatar`,
+`showUserAvatar`, `onRetry`, `onRegenerate`, `actionsOf`, `onFeedback`,
+`onEdit` as above. `editing` / `onEditingChange(next)` control the edit
+field (leave them out and the message keeps its own).
+`onCopy(message, text)` replaces the clipboard write; `formatTime(date)`
+replaces the time's format.
+
+### Bubble
+
+`from` (`"user"` · `"assistant"`), `variant` (`"bubble"` · `"plain"`),
+`first` / `last`, `streaming` (draws the caret), and `text` (drawn by the
+safe renderer) or `children`.
+
+### ChatHeader
+
+`title`, then `status` (`{ tone: "success", label: "Online", pulse? }`,
+a kit `StatusDot`) or `subtitle` (a muted line) under it, `avatar`
+(`{ name?, src?, status? }`), `actions` (nodes at the end: a "New chat"
+Button), `menu` (kit `Menu` items behind a "⋯") and `menuLabel`.
+
+### Attachment
+
+`name`, `size` (bytes), `type` (MIME; the extension is used when it is
+missing), `url` (an image shows itself; anything else opens it),
+`href` (open this instead), `progress` (0–100, a bar until 100), `error`,
+`onRemove`, `removeLabel`. An image's thumbnail is a kit `Image`: a
+skeleton while it loads, the image glyph if it fails.
+
+### MessageScroller
+
+`messages`, `renderMessage(message, { first, last, latest })` (default: a plain
+`Message`), `idOf(message, i)`, `onLoadMore` · `hasMore` · `loadingMore`,
+`emptyState`, `formatDay(date)` ("Today", "Yesterday", "Mon 21 Sep"),
+`announce(message)` (what a screen reader hears when a reply is whole),
+`jumpLabel`, `loadMoreLabel`, `label`, `className` (give it a bounded
+height, or put it in a flex column), `children` (drawn after the last
+message — a typing line, say).
+
+The list is a kit `ScrollArea`. Once it overflows it joins the tab order
+as a region named `label`, so a keyboard can scroll it.
+
+### Composer
+
+`onSend`, `onStop`, `streaming`, `disabled`, `disabledPlaceholder`,
+`placeholder`, `attachments` · `onAttach` · `onRemoveAttachment` ·
+`accept` as in ChatThread, and `value` / `onValueChange` (control the
+text — to quote a message into it, say), `maxRows` (8), `canSendEmpty`
+(false), `label` ("Message"), `hint` (true: the Enter / Shift+Enter keys
+under the field, from md up), `autoFocus`, and:
+
+- `shape` — `"box"` (default: the text on top, the bar under it) or
+  `"pill"`: the "ask anything" box, one round row with the "+" menu and
+  the paperclip before the text and `tools` and Send after it. Past one
+  line (or with files waiting) it opens into a rounded box, text on top;
+  emptied, it is a pill again. The pill shows no key hint.
+- `tools` — nodes in the bar: a model `Select`, a kit `Menu` of
+  settings with checkbox items, a `Toggle` for "Auto", a mic. The
+  composer draws them; what they choose is yours (read it in `onSend`).
+- `menu` · `menuLabel` ("Add to the message") — kit `Menu` items behind
+  a "+" at the start of the bar: "Add files", "Search the web".
+- `suggestions` — `[{ label, prompt?, icon?, description?, onSelect? }]`,
+  drawn `suggestionsPlacement` `"below"` (default) or `"above"` the
+  field. `suggestionMode` `"fill"` (default: the prompt goes in the
+  field, caret at its end) or `"send"`; an item's own `onSelect(item)`
+  replaces both. `suggestionsLook` `"chips"` (round, centred) or
+  `"cards"` (a two-column grid with `description` under each label).
+  `suggestionsLabel` names the list to a reader.
+- `onEditLast()` — Up arrow in the empty field (ChatThread opens the last
+  message you sent for editing).
+
+The field is the kit's multi-line `InputGroup`: the waiting files sit
+above the text inside its one border, the paperclip (a kit `FileInput`)
+and the hint in its bar, Send at the end. The picker leaves out files
+`accept` rules out; a drop or a paste is passed on as it comes.
+
+## Example
+
+```jsx
+// components/SupportChat.jsx — client: one ticket's conversation
+"use client";
+import { useState } from "react";
+import { insertRow } from "../lib/actions";
+import { ChatThread } from "./blocks/chat";
+
+export default function SupportChat({ ticket, initial }) {
+  const [messages, setMessages] = useState(initial);
+  const patch = (id, change) => setMessages((all) => all.map((m) => (m.id === id ? { ...m, ...change } : m)));
+
+  async function send(text) {
+    const id = crypto.randomUUID();
+    const draft = { id, role: "user", content: text, createdAt: new Date().toISOString(), status: "sending" };
+    setMessages((all) => [...all, draft]);
+    const r = await insertRow({ source: "public.ticket_messages", values: { id, ticket_id: ticket.id, body: text }, detail: text });
+    patch(id, r.ok ? { status: undefined } : { status: "failed", error: r.error });
+  }
+
+  return (
+    <ChatThread
+      messages={messages}
+      onSend={send}
+      onRetry={(m) => { setMessages((all) => all.filter((x) => x.id !== m.id)); send(m.content); }}
+      assistantName={ticket.agent_name}
+      userName="You"
+      label={`Ticket ${ticket.number}`}
+    />
+  );
+}
+```
+
+With the AI SDK in a shadcn project, `useChat()` already has the shape:
+`<ChatThread messages={messages} onSend={(text) => sendMessage({ text })}
+streaming={status === "streaming" || status === "submitted"} onStop={stop}
+onRegenerate={() => regenerate()} />`.
+
+## What it will not do
+
+- Call a model, store a message or upload a file: those are the
+  surface's, through `onSend`, `onAttach` and the rows it passes back.
+- Render HTML or full markdown: links, lists, tables and images inside
+  the text stay plain text.
+- Keep the feedback or the edit: `onFeedback` and `onEdit` hand them to
+  you, and the rows you pass back are what shows. Emoji reactions are
+  yours, in `actionsOf`.
+- Record audio or pick a model: a mic or a model `Select` is a node you
+  put in `tools`.
+- Draw the app window's Agent tab, or a job the founder commissioned —
+  that is `job-panel`.
+
+A chat it cannot be is your own component in `components/`, built from
+these parts and the kit — not an edit to this block. Its files are fixed:
+`npm run check` refuses a change, and `makersclaw add chat` restores them.
+
+## Credits
+
+The pill composer, tools, suggestions, feedback, edit, reasoning and header are ported from blocks.so (https://blocks.so, ai-01–05 and chat-01–03, MIT) and Creative Tim UI (https://github.com/creativetimofficial/ui, ai-chat-streaming-01, MIT), rewritten on the Makersclaw kit.

package/registry/blocks/chat/attachment.jsx

@@ -0,0 +1,95 @@
+"use client";
+
+import { Icon, IconButton, Image, Progress, cx } from "../../ui";
+
+// Attachment — one file on a message or waiting in the composer: an icon
+// for its kind (or the picture itself when it is an image with a `url`),
+// its name and size, a bar while it uploads, the reason when it failed,
+// and a remove button when `onRemove` is given.
+
+const KINDS = [
+  [/^image\//, "image", "Image"],
+  [/^(audio|video)\//, "play", "Media"],
+  [/(zip|tar|gzip|compressed|x-7z|rar)/, "archive", "Archive"],
+  [/(spreadsheet|excel|csv)/, "grid", "Spreadsheet"],
+  [/(pdf|word|document|text|rtf|presentation|powerpoint)/, "file", "Document"],
+];
+const BY_EXT = {
+  png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp", svg: "image/svg+xml",
+  pdf: "application/pdf", doc: "application/msword", docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  txt: "text/plain", md: "text/markdown", csv: "text/csv", xls: "application/vnd.ms-excel", xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  zip: "application/zip", mp3: "audio/mpeg", mp4: "video/mp4", mov: "video/quicktime",
+};
+
+export function kindOf(type, name) {
+  const mime = type || BY_EXT[String(name ?? "").split(".").pop()?.toLowerCase()] || "";
+  for (const [re, icon, label] of KINDS) if (re.test(mime)) return { icon, label, image: icon === "image" };
+  return { icon: "file", label: "File", image: false };
+}
+
+/** 2048 → "2 KB", 5_300_000 → "5.1 MB". */
+export function formatBytes(bytes) {
+  const n = Number(bytes);
+  if (!Number.isFinite(n) || n < 0) return "";
+  if (n < 1024) return `${n} B`;
+  const units = ["KB", "MB", "GB", "TB"];
+  let v = n / 1024;
+  let u = 0;
+  while (v >= 1024 && u < units.length - 1) {
+    v /= 1024;
+    u += 1;
+  }
+  return `${v >= 10 ? Math.round(v) : Math.round(v * 10) / 10} ${units[u]}`;
+}
+
+export function Attachment({ name, size, type, url, href, progress, error, onRemove, removeLabel, className }) {
+  const kind = kindOf(type, name);
+  const uploading = typeof progress === "number" && progress < 100 && !error;
+  const thumb = kind.image && url;
+  const open = href ?? (!uploading && !error ? url : undefined);
+  const facts = error ? error : uploading ? `Uploading… ${Math.round(progress)}%` : [kind.label, formatBytes(size)].filter(Boolean).join(" · ");
+
+  const title = open ? (
+    // raw: an attachment opens a file URL (often a blob: or a storage
+    // link) in a new tab; Button's href is next/link, which is for pages.
+    <a
+      href={open}
+      target="_blank"
+      rel="noreferrer"
+      className="block truncate rounded-sm text-sm font-medium outline-none hover:underline focus-visible:ring-2 focus-visible:ring-ring"
+    >
+      {name}
+    </a>
+  ) : (
+    <p className="truncate text-sm font-medium">{name}</p>
+  );
+
+  return (
+    <div
+      className={cx(
+        "flex w-64 max-w-full min-w-0 items-center gap-2.5 rounded-lg border bg-card p-2 text-card-foreground",
+        error ? "border-destructive/50" : "border-border",
+        className,
+      )}
+    >
+      {thumb ? (
+        <Image src={url} alt="" ratio="square" className="size-10 shrink-0" />
+      ) : (
+        <span className="flex size-10 shrink-0 items-center justify-center rounded-md bg-muted text-muted-foreground">
+          <Icon name={error ? "warning" : kind.icon} size={18} className={error ? "text-destructive" : undefined} />
+        </span>
+      )}
+      <div className="grid min-w-0 flex-1 gap-1">
+        {title}
+        {uploading ? (
+          <Progress value={progress} aria-label={`Uploading ${name}`} valueText={`${Math.round(progress)}%`} />
+        ) : (
+          <p className={cx("truncate text-xs", error ? "text-destructive" : "text-muted-foreground")}>{facts}</p>
+        )}
+      </div>
+      {onRemove ? (
+        <IconButton icon="x" size="sm" label={removeLabel ?? `Remove ${name}`} onClick={onRemove} className="-my-1" />
+      ) : null}
+    </div>
+  );
+}

package/registry/blocks/chat/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "chat",
+  "title": "Chat",
+  "description": "The parts of a chat: messages with avatars, times, grouping, sending/failed/streaming states, hover actions, thumbs up/down feedback, in-place editing and a folding reasoning section; a scroller that sticks to the bottom with day separators and older-message loading; a composer (a box or an \"ask anything\" pill) with attachments, a + menu, tools, suggestion chips, Enter to send and Stop; a header; and ChatThread, which composes them from messages + onSend.",
+  "useWhen": "A conversation lives inside the app's own screen: a support inbox reply pane, a customer-facing assistant, comments between teammates on a record, a thread per object. Not the app window's Agent tab (the OS draws that) and not a one-off job the founder commissions (job-panel).",
+  "tags": ["chat", "messages", "conversation", "thread", "assistant", "ai", "support", "inbox", "composer", "attachments", "streaming", "bubble", "reply", "feedback", "reasoning", "prompt", "suggestions", "ask anything", "header"],
+  "exports": ["ChatThread", "ChatHeader", "Message", "Bubble", "Attachment", "MessageScroller", "Composer"],
+  "files": ["index.js", "chat.jsx", "header.jsx", "message.jsx", "text.jsx", "attachment.jsx", "scroller.jsx", "composer.jsx"],
+  "requires": []
+}

package/registry/blocks/chat/chat.jsx

@@ -0,0 +1,132 @@
+"use client";
+
+import { isValidElement, useState } from "react";
+import { Empty, cx } from "../../ui";
+import { Composer } from "./composer";
+import { ChatHeader } from "./header";
+import { Message } from "./message";
+import { MessageScroller } from "./scroller";
+
+// ChatThread — a whole conversation from `messages` and `onSend`: the
+// scrolling list (MessageScroller) of Message rows, and the Composer under
+// it; a header over it when given one. The common case in one element;
+// when a thread needs a shape this cannot take, compose the same parts
+// yourself (README.md).
+//
+//   <ChatThread messages={messages} onSend={send} streaming={busy} onStop={stop}
+//               onRetry={resend} assistantName="Support" height="36rem" />
+
+export function ChatThread({
+  messages,
+  onSend,
+  onStop,
+  streaming,
+  onRetry,
+  onRegenerate,
+  actionsOf,
+  onFeedback,
+  onEdit,
+  onLoadMore,
+  hasMore = false,
+  loadingMore = false,
+  attachments,
+  onAttach,
+  onRemoveAttachment,
+  accept,
+  disabled = false,
+  disabledPlaceholder,
+  placeholder,
+  variant = "plain",
+  assistantName = "Assistant",
+  assistantAvatar,
+  userName = "You",
+  userAvatar,
+  showUserAvatar = false,
+  emptyTitle = "No messages yet",
+  emptyBody = "Write the first one below.",
+  emptyState,
+  header,
+  shape = "box",
+  tools,
+  menu,
+  suggestions,
+  suggestionsWhen = "empty",
+  suggestionsLook = "chips",
+  suggestionMode = "send",
+  label = "Conversation",
+  height = "min(40rem, 80dvh)",
+  className,
+}) {
+  const list = messages ?? [];
+  // Streaming when told so, or when the last message says it still is.
+  const busy = streaming ?? list.some((m) => m.status === "streaming");
+  // The message being edited: one at a time, and ArrowUp in an empty
+  // composer opens the last one you sent.
+  const [editingId, setEditingId] = useState(null);
+  const lastMine = onEdit ? [...list].reverse().find((m) => m.role === "user" && m.status !== "sending") : null;
+  const showSuggestions = suggestions && suggestions.length && (suggestionsWhen === "always" || list.length === 0);
+
+  const top = !header ? null : isValidElement(header) || typeof header !== "object" ? header : <ChatHeader {...header} />;
+
+  return (
+    <section
+      aria-label={label}
+      style={height ? { height } : undefined}
+      className={cx("flex min-h-0 flex-col overflow-hidden rounded-lg border border-border bg-card text-card-foreground", className)}
+    >
+      {top}
+      <MessageScroller
+        messages={list}
+        onLoadMore={onLoadMore}
+        hasMore={hasMore}
+        loadingMore={loadingMore}
+        label={`${label} messages`}
+        className="flex-1"
+        emptyState={emptyState ?? <Empty icon="mail" title={emptyTitle} body={emptyBody} className="my-auto" />}
+        renderMessage={(m, ctx) => (
+          <Message
+            message={m}
+            first={ctx.first}
+            last={ctx.last}
+            latest={ctx.latest}
+            variant={variant}
+            assistantName={assistantName}
+            assistantAvatar={assistantAvatar}
+            userName={userName}
+            userAvatar={userAvatar}
+            showUserAvatar={showUserAvatar}
+            onRetry={onRetry}
+            onRegenerate={onRegenerate}
+            actionsOf={actionsOf}
+            onFeedback={onFeedback}
+            onEdit={onEdit}
+            editing={onEdit ? editingId === m.id : undefined}
+            onEditingChange={(next) => setEditingId(next ? m.id : null)}
+          />
+        )}
+      />
+      <div className="border-t border-border p-2 sm:p-3">
+        <Composer
+          onSend={onSend}
+          onStop={onStop}
+          streaming={busy}
+          disabled={disabled}
+          disabledPlaceholder={disabledPlaceholder}
+          placeholder={placeholder}
+          attachments={attachments}
+          onAttach={onAttach}
+          onRemoveAttachment={onRemoveAttachment}
+          accept={accept}
+          shape={shape}
+          tools={tools}
+          menu={menu}
+          suggestions={showSuggestions ? suggestions : undefined}
+          suggestionsLook={suggestionsLook}
+          suggestionsPlacement="above"
+          suggestionMode={suggestionMode}
+          onEditLast={lastMine && !disabled && !busy ? () => setEditingId(lastMine.id) : undefined}
+        />
+      </div>
+    </section>
+  );
+}