# Connection picker

An 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.

- Registry name: `connection-picker` (`@candor/connection-picker`)
- Tier: Pro. Installing it needs a Pro, Premium or Team licence key: the person runs `npx candor-ui key <key>` themselves; never ask for the key in chat or write it to a file.
- Docs: https://candor.themethodic.com/docs/connection-picker

## Install

```bash
npx candor-ui@4 add connection-picker
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/connection-picker`.
It brings in: badge, bidi, chat, choice-card-group, heading-level, heading-scope, locale, locked, relative-time, tokens, utils.
npm packages: lucide-react@^1.67.0.

## Example

```tsx
"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>

Props:

- `connections: readonly PickerConnection[]`: The person's connections, in the order to show them.
- `kinds: 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 (`connectionPicker`)

The fixed words, English by default. Override any of them under `connectionPicker` in `<LocaleProvider strings={{ connectionPicker: { … } }}>`; the table is exported as `connectionPickerStrings`.

- `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.

## Types

### ConnectionKind

How the app shows one kind of connection: its label ("Code repository") and, if it has one, its icon.

```ts
{
  /** 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.

```ts
{
  /** 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

Import: `import type { AgentIdentity } from "@/lib/candor/chat"` (item `chat`, https://candor.themethodic.com/docs/chat.md)

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

### HeadingLevel

Import: `import type { HeadingLevel } from "@/lib/candor/heading-level"` (item `heading-level`, https://candor.themethodic.com/docs/heading-level.md)

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.

```ts
1 | 2 | 3 | 4 | 5 | 6
```

### AgentRole

Import: `import type { AgentRole } from "@/lib/candor/chat"` (item `chat`, https://candor.themethodic.com/docs/chat.md)

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

```ts
string
```

## Motion

- **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.

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider`: its fixed strings in `strings`, its nouns in `nouns`; entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.
