Change set review

Preview

Install

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

Brings in: bidi, button, change-hash, chat, entity-chip, heading-level, heading-scope, locale, locked, tokens, use-keyboard-review, work, utils · npm: lucide-react@^1.67.0

Usage

"use client"

import * as React from "react"
import { ChangeSetReview, type ChangeSetEdit } from "@/components/candor/change-set-review"

const proposed: ChangeSetEdit[] = [
  {
    id: "c-1042",
    kind: "change",
    record: { kind: "record", name: "customer/1042", label: "Northwind Traders" },
    fields: [
      { field: "segment", label: "Segment", from: "SMB", to: "Mid-market" },
      { field: "owner", label: "Owner", from: "Priya Shah", to: "Jonas Berg" },
    ],
  },
  {
    id: "c-1187",
    kind: "change",
    record: { kind: "record", name: "customer/1187", label: "Fabrikam" },
    fields: [{ field: "billing_email", label: "Billing email", from: null, to: "ap@fabrikam.example" }],
  },
  {
    id: "c-new-1",
    kind: "add",
    record: { kind: "record", name: "customer/new-1", label: "Tailspin Toys" },
    fields: [
      { field: "segment", label: "Segment", to: "SMB" },
      { field: "owner", label: "Owner", to: "Priya Shah" },
    ],
  },
  {
    id: "c-0981",
    kind: "remove",
    record: { kind: "record", name: "customer/0981", label: "Contoso (duplicate)" },
    fields: [
      { field: "segment", label: "Segment", from: "SMB" },
      { field: "open_invoices", label: "Open invoices", from: "0" },
    ],
  },
]

export default function Example() {
  const [applying, setApplying] = React.useState(false)
  const [sent, setSent] = React.useState<string>()
  return (
    <div className="flex max-w-2xl flex-col gap-3">
      <ChangeSetReview
        title="Customer clean-up proposed by the data agent"
        edits={proposed}
        busy={applying}
        undo={{
          add: { available: true, how: "Delete the new customer from its page." },
          change: { available: true, how: "Each field can be set back from the customer’s history." },
          remove: { available: false, reason: "a removed customer is deleted with its notes." },
        }}
        onApply={(kept, hash) => {
          setApplying(true)
          // Your server rebuilds the kept edits from the ids it holds, recomputes the hash, and applies them only if it matches.
          window.setTimeout(() => {
            setApplying(false)
            setSent(`${kept.map((e) => e.id).join(", ")} · sha256:${hash.slice(0, 12)}…`)
          }, 1200)
        }}
      />
      {sent && <p className="text-xs text-muted-foreground">Sent to the server: {sent}</p>}
    </div>
  )
}

<ChangeSetReview>

Strings

Motion

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

Types

ChangeSetKind

What an edit does to its record: adds it, changes some of its fields, or removes it.

"add" | "change" | "remove"

ChangeSetField

One field of a record, before and after, as text your app formatted. `null` means no value ("Not set"). Leaving `from` out of a change means your app didn't record what it was, which is shown as that and never guessed. An added record's fields need only `to`, a removed one's only `from`.

{ field: string; label?: string | undefined; from?: string | null | undefined; to?: string | null | undefined }

ChangeSetEdit

One record edit the agent proposes: the record, what it does to it, and the fields it touches.

{ /** Stable for this edit in this set. It is part of what's hashed, so your server can find the edit by it. */ id: string; kind: ChangeSetKind; /** The record, named by your app: its kind, identifier and label. */ record: EntityRef; /** The fields, in the order to show them. */ fields: ChangeSetField[]; }

Terms used here

Change hash

The SHA-256 of a change in one canonical form (object keys sorted at every depth), the same in the browser and on the server. An approval is made against a hash, so the server can check that what runs is the change the person saw. If the person edits the change before allowing it, the hash is worked out again for the edited version.

Every term is defined in the glossary (Markdown).

Types from other items

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

Rollback from @/lib/candor/work

{ available: true; how: string } | { available: false; reason: string }

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

EntityKind from @/lib/candor/chat

What kind of thing an entity is: "record", "table", "workflow"… Any string; the app registers each kind's icon and noun (see EntityKindsProvider), and presets cover the kinds of the systems an app commonly works with.

string