Scope switcher

Preview

Install

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

Brings in: bidi, dropdown-menu, link, locale, motion, scope-breadcrumb, team, tokens, utils · npm: lucide-react@^1.67.0

Usage

"use client"

import * as React from "react"
import { Plus } from "lucide-react"
import { ScopeSwitcher, type ScopeSwitcherLevel } from "@/components/candor/scope-switcher"
import type { Environment } from "@/lib/candor/team"

const clients = [
  { id: "northwind", label: "Northwind" },
  { id: "acme", label: "Acme Robotics" },
]
const environments: Record<string, Environment> = {
  prod: { id: "prod", name: "Northwind", production: true, connection: "connected" },
  uat: { id: "uat", name: "Northwind", detail: "UAT", production: false, connection: "expired" },
}

// The app keeps where the person is; the switcher shows only what the app says, so a change shows once the app has
// made it. "Recommends only" is the app's word for its agent's mode, as the agent last reported it.
export default function Example() {
  const [client, setClient] = React.useState<string | null>("northwind")
  const [env, setEnv] = React.useState("prod")
  const levels: ScopeSwitcherLevel[] = [
    { id: "client", kind: "client", value: clients.find((c) => c.id === client) ?? null, options: clients },
    {
      id: "env",
      kind: "environment",
      value: { id: env, label: env === "prod" ? "Production" : "UAT" },
      // A second line of facts under each option.
      options: [
        { id: "prod", label: "Production", detail: "1,667 components · synced 8 min ago" },
        { id: "uat", label: "UAT", detail: "1,662 components · connection expired" },
      ],
    },
  ]
  return (
    <ScopeSwitcher
      levels={levels}
      onChange={(level, option) => (level === "client" ? setClient(option) : setEnv(option))}
      environment={environments[env]}
      mode={{ label: "Recommends only" }}
      actions={[{ id: "connect", label: "Connect another environment", Icon: Plus, onSelect: () => {} }]}
    />
  )
}

<ScopeSwitcher>

Strings

Motion

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

Types

ScopeSwitcherMode

The agent's mode as it last reported it, and the one asked for that it hasn't reported yet.

{ /** The mode the agent last reported, in the app's words ("Recommends only"). */ label: string; /** A mode asked for that the agent hasn't reported yet; shown as "Changing to {pending}" beside `label`. */ pending?: string | undefined; }

ScopeSwitcherOption

A place a level can be set to, as ScopeBreadcrumb's, with a second line of facts about it.

ScopeOption & { /** A second line under the name, drawn as text ("Production · 1,667 components"). */ detail?: string | undefined; }

ScopeSwitcherLevel

One level of a ScopeSwitcher: ScopeBreadcrumb's `ScopeLevel`, its options able to carry a `detail`.

Omit<ScopeLevel, "options"> & { /** What the level can be changed to. */ options?: ScopeSwitcherOption[] | undefined; }

ScopeSwitcherAction

An action at the menu's foot, after the levels ("Connect another", in the app's words).

{ /** A key for the action. */ id: string; /** Its words, drawn as text. */ label: string; /** An icon before the words. */ Icon?: LucideIcon | undefined; /** Called when the person chooses it. */ onSelect: () => void; }

Types from other items

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

Environment from @/lib/candor/team

Where agents act: a CRM instance, a database, a repository, a project. The app names them; LocaleProvider's `nouns` sets what they're called ("project", "workspace").

{ id: string; /** The name shown everywhere, e.g. "Shop". */ name: string; /** What tells same-named ones apart, e.g. "dev-2" or "staging". */ detail?: string | undefined; /** Changes here reach real users, so components warn and ask for more care. */ production: boolean; /** A chart slot (1–5) so each environment keeps one colour everywhere it appears. */ hue?: 1 | 2 | 3 | 4 | 5 | undefined; connection: "connected" | "expired" | "not-connected"; }