Environment promotion

Preview

Install

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

Brings in: bidi, button, change-diff, environment-band, heading-level, heading-scope, locale, locked, team, tokens, work, utils · npm: lucide-react@^1.67.0

Usage

"use client"

import * as React from "react"
import { EnvironmentPromotion, type PromotionDecision } from "@/components/candor/environment-promotion"
import type { FileDiff } from "@/lib/candor/work"

const files: FileDiff[] = [
  {
    path: "config/checkout.json",
    change: "update",
    language: "json",
    hunks: [
      {
        header: "@@ -3,4 +3,4 @@",
        lines: [
          { kind: "context", text: '  "currency": "EUR",', oldNo: 3, newNo: 3 },
          { kind: "remove", text: '  "paymentRetries": 2,', oldNo: 4 },
          { kind: "add", text: '  "paymentRetries": 3,', newNo: 4 },
          { kind: "remove", text: '  "receiptTemplate": "receipt-v2"', oldNo: 5 },
          { kind: "add", text: '  "receiptTemplate": "receipt-v3"', newNo: 5 },
        ],
      },
    ],
  },
]

export default function Example() {
  const [state, setState] = React.useState<"pending" | "promoting" | "promoted" | "declined">("pending")
  const [decision, setDecision] = React.useState<PromotionDecision>()
  return (
    <EnvironmentPromotion
      className="max-w-2xl"
      title="Checkout settings v14"
      from={{ id: "stg", name: "Shop", detail: "staging", production: false, hue: 2, connection: "connected" }}
      to={{ id: "prd", name: "Shop", detail: "production", production: true, hue: 1, connection: "connected" }}
      files={files}
      hash="9f2c41d07be35a18c6e0d2f4"
      requestedBy={{ name: "Release agent", at: "2026-11-10T08:12:00Z" }}
      approvals={{
        needed: 2,
        given: [
          { by: "Priya Shah", at: "2026-11-10T09:30:00Z", note: "Checked the retries against last month’s failures." },
          { by: "Jonas Berg", at: "2026-11-10T10:05:00Z" },
        ],
      }}
      rollback={{
        can: ["The checkout settings, back to version 13"],
        cannot: ["Receipts already sent with the new template", "Payments retried a third time"],
        how: "Promote version 13 again from the history page.",
      }}
      state={state}
      decision={decision}
      onPromote={async () => {
        setState("promoting")
        await new Promise((r) => setTimeout(r, 900))
        setDecision({ by: "You", at: new Date().toISOString() })
        setState("promoted")
      }}
      onDecline={() => {
        setDecision({ by: "You", at: new Date().toISOString() })
        setState("declined")
      }}
    />
  )
}

<EnvironmentPromotion>

Strings

Types

PromotionApproval

One approval given for the promotion, as the app recorded it.

{ /** Who approved, by name, from the app's data. */ by: string; /** When (ISO). */ at: string; /** What they said, if anything. */ note?: string | undefined; }

PromotionRollback

What can and can't be undone if the promotion goes wrong, in the app's words.

{ /** What a rollback puts back: "The settings, to version 13". */ can: string[]; /** What it doesn't: "Emails already sent with the new template". */ cannot: string[]; /** How to roll back, when it isn't obvious: "Promote version 13 again from the history page." */ how?: string | undefined; }

PromotionDecision

Who decided and when, once the promotion is promoted or declined.

{ by: string; at: string; note?: string | undefined }

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"; }

FileDiff from @/lib/candor/work

{ path: string; /** What the file is, e.g. a field or a layout. */ entity?: EntityRef | undefined; change: "create" | "update" | "delete"; /** e.g. "xml", "ts", "python"; shown as a label. */ language?: string | undefined; hunks: DiffHunk[]; }

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

EntityRef from @/lib/candor/chat

{ kind: EntityKind; /** The identifier, e.g. "orders.status" or "billing.invoice.due_date". */ name: string; /** A friendlier label when there is one, e.g. "Region". */ label?: string | undefined; /** Where it lives, when more than one place is in scope, e.g. "Shop staging". */ location?: string | undefined; }

DiffHunk from @/lib/candor/work

{ header?: string | undefined; lines: DiffLine[] }