# Environment band

A slim strip naming the account and the environment in scope, in the environment's own colour. It's a safety cue, not decoration: you always know where your next change lands. Production turns the strip to a warning. An expired connection says so before you ask for anything.

- Registry name: `environment-band` (`@candor/environment-band`)
- 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/environment-band

## Install

```bash
npx candor-ui add environment-band
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/environment-band`.
It brings in: dropdown-menu, locale, team, terms, utils.
npm packages: lucide-react@^1.67.0.

## Example

```tsx
"use client"

import * as React from "react"
import { EnvironmentBand } from "@/components/environment-band"
import type { Environment } from "@/lib/team"

const environments: Environment[] = [
  { id: "prod", name: "Storefront", production: true, hue: 1, connection: "connected" },
  { id: "staging", name: "Storefront", detail: "staging", production: false, hue: 2, connection: "connected" },
  { id: "dev", name: "Storefront", detail: "dev-2", production: false, hue: 3, connection: "expired" },
]

export default function Example() {
  const [environment, setEnvironment] = React.useState(environments[1]!)
  return (
    <div className="max-w-2xl overflow-hidden rounded-lg border">
      <EnvironmentBand account="Acme" environment={environment} environments={environments} onSelect={setEnvironment} onReconnect={() => {}} />
    </div>
  )
}
```

## <EnvironmentBand>

Props:

- `account: string`: The account's name, shown before the environment on wider screens.
- `environment: Environment`: The environment in scope; its hue colours the strip, and production turns it to a warning.
- `environments?: Environment[] | undefined`: The environments to switch between; with `onSelect`, the name becomes a menu.
- `onSelect?: ((environment: Environment) => void) | undefined`: Called with the environment chosen from the menu.
- `onReconnect?: (() => void) | undefined`: Shows Reconnect when the connection is expired or missing; called when it's pressed.
- `className?: string | undefined`

## <EnvironmentMark>

Props:

- `environment: Pick<Environment, "hue">`: The environment whose hue colours the dot; without a hue, the first chart colour.
- `className?: string | undefined`

## Strings (`environmentBand`)

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

- `production`: Production
- `nonProduction`: Non-production
- `environmentsIn`: {environments} in {account}
- `notConnected`: Not connected
- `current`: Current
- `connectionExpired`: Connection expired
- `reconnect`: Reconnect

## 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` (fixed strings) and `TermsProvider` (nouns); entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.