Composer scope picker

Pro

Where the next message's work lands, as a pill that opens a picker, for Composer's tools slot (leave Composer's own scope out). A scope can be an environment, a client, a project or the person's own ("Just me"), each with its icon and words; production is a warning in words, not only colour. The picker groups the scopes by kind in the order each kind first appears, ticks the current one and starts focus on it; Up, Down, Home and End move without choosing, and a press chooses. Nothing is chosen for the person: the pill shows the scope the app says is current.

Markdown

Version 5.2.0· other versions

This page is for 5.2.0, the current release. An earlier release’s page is the Markdown that release published, so the docs match the version you have installed (candor-lock.json records it).

Not in the docs of 1.3.0, 1.4.0, 1.5.0, 1.5.1, 1.6.0, 1.7.0, 1.8.0, 1.8.1, 1.9.0, 1.9.1, 2.0.0, 2.1.0, 2.2.0, 2.3.0, 2.4.0, 2.5.0, 2.5.1, 2.6.0, 2.6.1, 2.6.2, 2.7.0, 2.8.0, 2.9.0, 2.10.0, 3.0.0, 4.0.0, 4.0.1, 4.0.2, 4.1.0, 4.2.0 and 4.3.0: the page came later, or had another name then.

Docs pages weren’t kept for 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.2.0 and 1.2.1: they are kept from 1.3.0 on, and before that only llms.txt was published.

Preview

Install

With the Candor CLI

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

Brings in: bidi, chat, locale, popover, tokens, utils · npm: lucide-react@^1.67.0

Usage

TSX · The example above

"use client"

import * as React from "react"
import { Composer } from "@/components/candor/composer"
import { ComposerScopePicker, type ComposerScopeChoice } from "@/components/candor/composer-scope-picker"

// The places a message's work can land, by kind: the pill opens a picker of them, the current one ticked.
const scopes: ComposerScopeChoice[] = [
  { id: "client", kind: "client", environment: "Harbour Trading", production: false },
  { id: "project", kind: "project", environment: "Spring release", production: false },
  { id: "staging", environment: "Shop", detail: "staging", production: false },
  { id: "prod", environment: "Shop", production: true },
  { id: "me", kind: "personal", environment: "", production: false },
]

export default function Example() {
  const [value, setValue] = React.useState("")
  const [scope, setScope] = React.useState(scopes[2]!)
  // Composer's own `scope` is left out: the picker in `tools` shows it.
  return (
    <Composer
      className="max-w-2xl"
      value={value}
      onValueChange={setValue}
      onSubmit={() => setValue("")}
      tools={<ComposerScopePicker scope={scope} scopes={scopes} onScopeChange={setScope} />}
    />
  )
}

<ComposerScopePicker>

Prop	Type	Default	Description
scoperequired	`ComposerScopeChoice`	—	Where the next message's work lands now, from your app. Production turns the pill to a warning.
scopesrequired	`ComposerScopeChoice[]`	—	The scopes the person can choose: environments, clients, projects and their own ("Just me").
onScopeChangerequired	`(scope: ComposerScopeChoice) => void`	—	Called with the scope the person chooses; set `scope` to it.
className	`string \| undefined`	—	Classes, merged with Candor's.

Strings

The fixed words, in English by default. Change any of them under composerScopePicker in <LocaleProvider strings={{ … }}>; the table is exported as composerScopePickerStrings.

Key	English
production	Production
nonProduction	Non-production
personal	Just me
scopeKind	({kind})
kindEnvironment	{environment}
kindClient	client
kindProject	project
kindPersonal	personal
groupEnvironment	{Environments}
groupClient	Clients
groupProject	Projects
groupPersonal	Personal
scopeMenu	Where this message’s work lands

Motion

Moment	Family	What it does
tint	tint	The pill's and each option's background changes when the pointer is over it.

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

Types

ComposerScopeKind: What kind of place a scope is.; "environment" | "client" | "project" | "personal"
ComposerScopeChoice: A place the next message's work can land: Composer's `ComposerScope`, with a kind and an id. Without `kind` it is an environment, as Composer draws it. With a `kind`, `environment` is that scope's name (a client's or a project's), and `production` still turns it to a warning.; ComposerScope & { /** * What kind of place it is: "environment" (the default), "client", "project", or "personal" (the person's own, not * tied to a client or project), each drawn with its icon and words. A personal scope reads "Just me". */ kind?: ComposerScopeKind | undefined; /** Tells scopes apart; without it, kind, account, name and detail do. */ id?: string | undefined; }

Types from other items

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

ComposerScope from @/lib/candor/chat: Where the next message's work lands.; { account?: string | undefined; environment: string; detail?: string | undefined; production: boolean }