Connection picker
ProAn in-chat access card: the person picks which of their existing connections the agent may use, so a connection is reused rather than set up again. Each connection is a radio row with its kind (the icon and label come from the app's kinds), its name, an environment badge, what it can reach in plain words, what uses it already, and when access ends. A "Connect another…" row after the list calls onConnectNew, and says the sign-in happens outside the chat; a note in the app's words can say what never appears here ("Live instances never appear here").
Nothing is chosen until the person chooses. The app may recommend one connection with a reason: that row is marked "Recommended" and says why, and is still not chosen. A connection that can't be used here (production, say) takes locked with the reason and stays in the list, or the app leaves it out and says so in note.
It is headed "Access request" with a key, so it reads as a request for access and is never taken for a question about the work. The rows are one radio group: arrow keys move between them and choose, and it is one tab stop. Names, scopes and the rest are drawn as text, with bidi controls marked.
Preview
Loading the preview
Install
First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/connection-picker
Brings in: badge, bidi, chat, choice-card-group, heading-level, heading-scope, locale, locked, relative-time, tokens, utils · npm: lucide-react@^1.67.0
Usage
"use client"
import * as React from "react"
import { Cloud, GitBranch } from "lucide-react"
import { ConnectionPicker } from "@/components/candor/connection-picker"
const kinds = {
crm: { label: "CRM instance", icon: Cloud },
repo: { label: "Code repository", icon: GitBranch },
}
const inDays = (n: number) => new Date(Date.now() + n * 86_400_000).toISOString()
/** Nothing is chosen until the person chooses; the recommended row is only marked. */
export default function Example() {
const [value, setValue] = React.useState<string | null>(null)
return (
<div className="max-w-lg">
<ConnectionPicker
kinds={kinds}
value={value}
onValueChange={setValue}
recommended={{ id: "sandbox", reason: "You built the last prototype here." }}
connections={[
{ id: "sandbox", name: "Acme sandbox", kind: "crm", environment: "Sandbox", scopes: ["read records", "deploy changes"], usedBy: ["Renewal board"], accessEnds: inDays(6) },
{ id: "dev", name: "Acme dev", kind: "crm", environment: "Developer edition", scopes: ["read records"], usedBy: [], accessEnds: null },
{ id: "repo", name: "acme/prototypes", kind: "repo", scopes: ["open pull requests"] },
]}
onConnectNew={() => {}}
note="Live instances never appear here."
/>
</div>
)
}<ConnectionPicker>
| Prop | Type | Default | Description |
|---|---|---|---|
| connectionsrequired | readonly PickerConnection[] | — | The person's connections, in the order to show them. |
| kindsrequired | Readonly<Record<string, ConnectionKind>> | — | The app's kinds of connection by key: each connection's `kind` names one. A kind not in it is shown by its key. |
| value | string | null | undefined | — | The chosen connection's id, when the app controls it; `null` while nothing is chosen. Never set it for the person. |
| onValueChange | ((id: string) => void) | undefined | — | Called with the id of the connection the person chooses. |
| recommended | { id: string; reason: string } | undefined | — | The connection the app recommends and why, in its words. Marked "Recommended" with the reason; never chosen for the person. |
| onConnectNew | (() => void) | undefined | — | Shows the dashed "Connect another…" row; called when it's pressed. Open the sign-in in the browser from here. |
| connectNewLocked | string | null | undefined | — | Why another connection can't be added right now, if it can't. The row stays and says why. |
| note | string | undefined | — | A line in the app's words under the list, such as which kinds never appear here: "Live instances never appear here." |
| agent | AgentIdentity | undefined | — | The agent that will use the connection, named by the app. With it, the title names the agent. |
| title | string | undefined | — | The card's title, in the app's words, in place of "Choose a connection". |
| className | string | undefined | — | Classes, merged with Candor's. |
| headingLevel | HeadingLevel | undefined | — | The level of its title. Defaults to one below the nearest `HeadingScope`, else 2. |
Strings
The fixed words, in English by default. Change any of them under connectionPicker in <LocaleProvider strings={{ … }}>; the table is exported as connectionPickerStrings.
| Key | English |
|---|---|
| kind | Access request |
| title | Choose a connection |
| titleAgent | Choose a connection for {agent} to use |
| recommended | Recommended |
| recommendedWhy | Why: {reason} |
| scopes | Access: {scopes} |
| scopesUnknown | What it can reach isn’t listed |
| usedBy | Used by {names} |
| usedByNone | Not used by anything yet |
| accessEnds | Access ends {time} |
| accessEnded | Access ended {time} |
| accessNoEnd | Access has no end date |
| accessEndsUnknown | When access ends isn’t known |
| connectNew | Connect another… |
| connectNewNote | Sign-in opens in your browser, outside this chat. Nothing is connected until you finish there. |
| none | No connections to choose from yet. |
Motion
| Moment | Family | What it does |
|---|---|---|
| tint | tint | A row's border changes colour when the person chooses it, as ChoiceCard's does, and the "Connect another…" row's ground tints on hover; a ring fades in on keyboard focus. |
Set with --cd-motion-connection-picker-<moment>-* in your brand file; the families are in the design reference.
Types
- ConnectionKind
- How the app shows one kind of connection: its label ("Code repository") and, if it has one, its icon.
{ /** The kind's name, in the app's words. */ label: string; /** Drawn beside the connection's name, for the eye only. */ icon?: LucideIcon | undefined; }- PickerConnection
- One connection the person already has, as the app describes it.
{ /** The value reported when this connection is chosen. */ id: string; /** Its name, in the app's or the service's words. */ name: string; /** A key into the picker's `kinds`. */ kind: string; /** Where it points, in the app's words ("Staging", "Test"), drawn as a badge beside the name. */ environment?: string | undefined; /** What it lets the agent do, each in plain words ("read records", "deploy changes"). Empty says they aren't listed. */ scopes: readonly string[]; /** What already uses it, by name. Left out, nothing is said; empty says nothing uses it yet. */ usedBy?: readonly string[] | undefined; /** * When access through it ends, as an ISO date: drawn as "Access ends in 6 days". `null` says it has no end date; left * out, it says when access ends isn't known. */ accessEnds?: string | null | undefined; /** Why it can't be chosen here, if it can't (a production connection, say). It stays in the list and says why. */ locked?: string | null | undefined; }
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; }- 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- AgentRole from @/lib/candor/chat
- What an agent does: "assistant", "coder", "reviewer"… The app registers each role's glyph and hue (AgentRolesProvider).
string