Copilot panel

Preview

Install

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

Brings in: ai-disclosure, bidi, button, chat, composer, locale, message, motion, prompt-suggestions, sheet, thread, tokens, utils · npm: lucide-react@^1.67.0

Usage

"use client"

import * as React from "react"
import { CopilotPanel, type CopilotViewer } from "@/components/candor/copilot-panel"
import type { MessageData } from "@/lib/candor/chat"

const agent = { id: "help", name: "Help assistant", role: "assistant" }

const text = (id: string, author: MessageData["author"], words: string): MessageData => ({
  id,
  author,
  status: "complete",
  blocks: [{ kind: "paragraph", nodes: [{ kind: "text", text: words }] }],
})

export default function Example() {
  const [messages, setMessages] = React.useState<MessageData[]>([])
  const [unread, setUnread] = React.useState(2)
  const [signedIn, setSignedIn] = React.useState(false)
  const viewer: CopilotViewer = signedIn
    ? { kind: "signed-in", name: "sam@keel.dev" }
    : { kind: "guest", note: "This conversation isn't kept after you leave.", onSignIn: () => setSignedIn(true) }
  return (
    <div className="flex h-24 items-center text-sm text-muted-foreground">
      <p>The launcher sits in the page; here it is inline rather than pinned to the corner.</p>
      <CopilotPanel
        launcher="inline"
        className="ms-auto"
        agent={agent}
        viewer={viewer}
        unread={unread}
        // In this product, opening the panel counts as reading it.
        onOpenChange={(open) => open && setUnread(0)}
        disclosure="Run by Keel. Ask for a person at any time."
        suggestions={[
          { id: "s1", text: "How do I invite my team?" },
          { id: "s2", text: "Why did my last export fail?" },
        ]}
        messages={messages}
        onSend={(words) =>
          setMessages((m) => [...m, text(`u${m.length}`, { role: "user" }, words), text(`a${m.length}`, { role: "agent", agent }, "I’ll look into that for you.")])
        }
      />
    </div>
  )
}

<CopilotPanel>

Strings

Motion

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

Types

CopilotViewer

Who is using the copilot, as the app knows it. A guest sees that they aren't signed in, with the app's own note (what happens to the conversation) only when the app gives one, and a Sign in button when `onSignIn` is given.

{ kind: "guest"; /** The app's own plain text about guest use ("This conversation isn't kept after you leave."). Nothing is said without it. */ note?: string | undefined; /** Shows Sign in in the panel; called when it's pressed. */ onSignIn?: (() => void) | undefined; /** Whether a guest may send. On by default; when off, the composer stays visible and says to sign in. */ canSend?: boolean | undefined; } | { kind: "signed-in"; /** The person's name or email, from the app. */ name: string; }

Types from other items

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

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; }

MessageData from @/lib/candor/chat

{ id: string; author: MessageAuthor; /** When it was sent. Absent when the source doesn't say; then no time is shown. */ createdAt?: string | undefined; status: MessageStatus; blocks: MessageBlock[]; reasoning?: ReasoningEntry[] | undefined; /** How long the agent spent before answering, e.g. "6s". Only once known. */ thoughtFor?: string | undefined; /** * When the request for this reply went out, as the app measured it: an ISO time or milliseconds since the epoch. * While the reply streams and nothing of it has arrived, its working line counts up from here ("Working · 4.2s"), * and so does its reasoning's. Left out, no time is shown. */ startedAt?: string | number | undefined; sources?: MessageSource[] | undefined; /** Shown under an agent's reply: model, cost. Only values the service measured. */ attribution?: { model?: string | undefined; cost?: string | undefined; } | undefined; }

PromptSuggestion from @/lib/candor/chat

{ id: string; text: string }

AgentRole from @/lib/candor/chat

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

string

MessageAuthor from @/lib/candor/chat

{ role: "user"; name?: string | undefined; } | { role: "agent"; agent: AgentIdentity; } /** A person on the app's own team (support staff, a reviewer), not the user: shown by name, with their team. */ | { role: "person"; name: string; team?: string | undefined; } /** System lines are the app's own strings, never model text. */ | { role: "system"; }

MessageStatus from @/lib/candor/chat

"streaming" | "complete" | "interrupted" | "failed"

MessageBlock from @/lib/candor/chat

{ kind: "paragraph"; nodes: InlineNode[]; /** * The "\n" in its text are line breaks, drawn as such: set by `markdownBlocks(text, { breaks: true })` on a * paragraph it joined from several lines. Left out, a "\n" is drawn as a space, as HTML draws it. */ breaks?: true | undefined; } /** * Text exactly as someone typed it: line breaks and spacing kept, nothing parsed. For a person's own words, so * `*this*` stays `*this*` and a pasted list keeps its lines. */ | { kind: "plain"; text: string; } /** A heading inside a reply. Levels are relative to the message, 1 the largest; the page's own headings sit above. */ | { kind: "heading"; level: 1 | 2 | 3; nodes: InlineNode[]; } | { kind: "list"; ordered?: boolean | undefined; items: InlineNode[][]; } | { kind: "payload"; language: PayloadLanguage; text: string; title?: string | undefined; } | { kind: "tools"; calls: ToolCallData[]; } /** Something the agent could not do, and what is missing because of it. */ | { kind: "degraded"; reason: string; missing?: string | undefined; } /** * A typed card (a result table, a plan, an approval) rendered by the app's * card registry. `summary` is the service's plain-text version, used for copy * and whenever the card can't be shown. */ | { kind: "card"; card: string; props: unknown; summary: string; } /** Files sent with the message, shown as tiles. New in 1.1: a `switch` over kinds needs a `default` branch. */ | { kind: "attachments"; files: Attachment[]; }

ReasoningEntry from @/lib/candor/chat

| (ReasoningBase & { basis: "verified"; evidence: string }) | (ReasoningBase & { basis: "believed" | "assumed"; assumption: string })

MessageSource from @/lib/candor/chat

{ id: string; /** The [n] shown inline. Assigned by the service, so it is stable across renders. */ marker: number; kind: SourceKind; label: string; /** An inert excerpt shown in the popover. Text only. */ snippet?: string | undefined; /** Where it came from in a human sense: "Docs · Sales process v3", "Query on orders". */ origin?: string | undefined; provisional?: boolean | undefined; }