Comment thread

Preview

Install

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/comment-thread

Brings in: agent-avatar, alert-dialog, avatar, bidi, button, chat, composer, data, heading-level, heading-scope, locale, motion, page-state, relative-time, textarea, tokens, use-arrivals, utils · npm: lucide-react@^1.67.0

Usage

"use client"

import * as React from "react"
import { CommentThread, type CommentAuthor, type CommentResolution, type ThreadComment } from "@/components/candor/comment-thread"

const ago = (m: number) => new Date(Date.now() - m * 60_000).toISOString()
const wait = (ms: number) => new Promise((r) => setTimeout(r, ms))

const ana: CommentAuthor = { person: { id: "u-ana", name: "Ana Ruiz" } }
const checker: CommentAuthor = { agent: { id: "a-review", name: "Checker", role: "reviewer" } }
const you: CommentAuthor = { person: { id: "u-sam", name: "Sam Reyes" } }

export default function Example() {
  const [comments, setComments] = React.useState<ThreadComment[]>([
    { id: "c1", author: ana, text: "Should this round each line before summing? Finance rounds per line.", at: ago(42) },
    { id: "c2", author: checker, text: "Rounding per line changes 14 of last month's invoices, each by one cent.", at: ago(38), replyTo: "c1", unread: true },
    { id: "c3", author: you, text: "Then keep it as it is and round the total.", at: ago(20), replyTo: "c2", mine: true },
  ])
  const [resolved, setResolved] = React.useState<CommentResolution | undefined>()
  const next = React.useRef(4)

  return (
    <CommentThread
      className="max-w-xl"
      anchor={{
        kind: "line",
        id: "billing.ts:42",
        label: "src/billing.ts, line 42",
        quote: "const total = lines.reduce((sum, l) => sum + l.amount, 0)",
        code: true,
        status: "changed",
      }}
      comments={comments}
      resolved={resolved}
      viewer={you}
      onComment={async (text, { replyTo }) => {
        await wait(600)
        const id = `c${next.current++}`
        setComments((list) => [...list, { id, author: you, text, at: new Date().toISOString(), replyTo, mine: true }])
        return id
      }}
      onEdit={async (id, text) => {
        await wait(400)
        setComments((list) => list.map((c) => (c.id === id ? { ...c, text, editedAt: new Date().toISOString() } : c)))
      }}
      onDelete={async (id) => {
        await wait(400)
        setComments((list) => list.map((c) => (c.id === id ? { ...c, text: "", deletedAt: new Date().toISOString() } : c)))
      }}
      onResolve={async () => {
        await wait(400)
        setResolved({ by: you, at: new Date().toISOString() })
      }}
      onReopen={async () => {
        await wait(400)
        setResolved(undefined)
      }}
      onMarkRead={(ids) => setComments((list) => list.map((c) => (ids.includes(c.id) ? { ...c, unread: false } : c)))}
      onShowAnchor={() => {}}
    />
  )
}

<CommentThread>

Strings

Motion

Set with --cd-motion-comment-thread-<moment>-* in your brand file; the families are in the design reference.

Types

CommentAnchor

What a thread is about: a thing in the app, by its kind and id, with a short quote of what it pointed at.

{ /** The app's noun for the thing, as it reads in a sentence: "line", "step", "field", "output". */ kind: string; /** The app's id for it. Not shown; the app uses it to find the thing again. */ id: string; /** Where it is, in the app's words: "Step 3: Back up the table", "src/billing.ts, line 42". Without it, the kind. */ label?: string | undefined; /** A short quote of what it pointed at when the thread began, shown as text. */ quote?: string | undefined; /** Show the quote in the code font, for a diff line or a value. */ code?: boolean | undefined; /** Whether the thing is still as quoted: "current" (the default), "changed" since, or "gone". The app decides; nothing here checks. */ status?: "current" | "changed" | "gone" | undefined; /** What happened to it, in the app's words, in place of the default line: "The line moved to 48 and was rewritten." */ statusNote?: string | undefined; }

CommentPerson

A person commenting: a teammate, a reviewer.

{ id: string; name: string; image?: string | undefined }

CommentAuthor

Who wrote a comment or resolved a thread: a person, or an agent named by the app (never by model output).

{ person: CommentPerson } | { agent: AgentIdentity }

ThreadComment

One comment, as the app's server has it.

{ id: string; author: CommentAuthor; /** The comment's text. Shown as text, never as markup or a link, whoever wrote it. Ignored once `deletedAt` is set. */ text: string; /** When it was written (ISO). */ at: string; /** When it was last edited (ISO); the comment says "edited". */ editedAt?: string | undefined; /** When it was deleted (ISO). It stays as a line saying so, in its place, with its replies under it. */ deletedAt?: string | undefined; /** The id of the comment it answers. Replies sit under the first comment of their chain. */ replyTo?: string | undefined; /** Whether the viewer hasn't read it, as the app records it. */ unread?: boolean | undefined; /** Whether the viewer wrote it: their own comments can be edited and deleted, and aren't announced as new. */ mine?: boolean | undefined; }

CommentResolution

Who resolved the thread, and when.

{ by: CommentAuthor; at: string }

Types from other items

The props above take these. Each is defined by another item; import it from the path shown.

MentionOption from @/lib/candor/chat

{ id: string; /** The heading it sits under in the menu, e.g. "Files", "People". Groups appear in the order first used. */ group: string; entity?: EntityRef | undefined; label: string; description?: string | undefined; /** A short state at the end of its row, such as "Connected"; `tone` colours the dot beside it. */ status?: { label: string; tone?: "success" | "warning" | "neutral" | undefined; } | undefined; /** Why it can't be chosen now, e.g. "The server isn't answering". It stays in the menu, says why, and inserts nothing. */ unavailable?: string | undefined; /** Called in place of inserting it, e.g. to sign in to a source first. The typed @ text is removed and the menu closes. */ onChoose?: (() => void) | undefined; }

ListState from @/lib/candor/data

What a list or table is showing, the same shape as `ChartState` and as page-state's `ListState` (which the free tier ships, so it declares its own rather than import this file): its rows (ready), the shape of rows still coming (loading), nothing and why (empty), the rows it has with a note on what's missing (partial), or why it couldn't load (error). Lists without a `state` show their rows.

ChartState

HeadingLevel from @/lib/candor/heading-level

A heading's level in the page's outline: `1` is `<h1>`, `6` is `<h6>`. Every Candor item that draws a heading takes its `headingLevel` as this type; the level is where the heading sits in the outline, never how large it looks.

1 | 2 | 3 | 4 | 5 | 6

AgentIdentity from @/lib/candor/chat

{ id: string; /** The displayed name, e.g. "Architect agent". Never derived from model output. */ name: string; role: AgentRole; specialty?: string | undefined; }

EntityRef from @/lib/candor/chat

{ kind: EntityKind; /** The identifier, e.g. "orders.status" or "billing.invoice.due_date". */ name: string; /** A friendlier label when there is one, e.g. "Region". */ label?: string | undefined; /** Where it lives, when more than one place is in scope, e.g. "Shop staging". */ location?: string | undefined; }

ChartState from @/lib/candor/data

{ kind: "ready"; } | { kind: "loading"; } /** Nothing to plot, and why. */ | { kind: "empty"; reason: string; } /** Some of the range is missing. */ | { kind: "partial"; note: string; } | { kind: "error"; reason: string; }

AgentRole from @/lib/candor/chat

What an agent does: "assistant", "coder", "reviewer"… The app registers each role's glyph and hue (AgentRolesProvider).

string