# Upgrading to 6.1

Every change Candor UI 6.1 makes, with what breaks, where it shows, what to do and the codemod that does it, or the edit you make by hand, and the commands that run the codemods on your own code. The same list is in each item's registry entry and is what `candor-ui update --to 6.1.0` prints. The release's notes are in the changelog: https://candor.themethodic.com/changelog#6-1-0.

## The commands

### 1. Look first

From the app's folder (the one with `components.json`), with your work committed and Candor's files at 6.1 or later. This lists what 6.1's codemods would change in your own files, and what they would leave for you, and writes nothing.

```bash
npx candor-ui@4 migrate 6.1.0 --dry-run
```

### 2. Run 6.1's codemods

Runs those of 6.1's codemods (`items`, `strings-keys`, `tokens`) that an entry on one of your installed items names, and lists the ones it leaves out; `npx candor-ui@4 migrate <codemod>` runs one anyway. Each says what it changed and lists what it couldn't under "Left for you".

```bash
npx candor-ui@4 migrate 6.1.0
```

### 3. Finish by hand, then check

Make the changes `migrate` lists under "Left for you", then the ones below marked "By hand", which the type check finds. Then type-check, build and run your tests. `verify` checks each installed file and its copy in `.candor/base/` against `candor-lock.json`, without the network.

```bash
npx tsc --noEmit && npm run build && npx candor-ui@4 verify
```

### 4. From before 6.1

The registry serves only the current release, so no update from 5.4 or 6.0 can read the files Candor installed there. Commit and delete `candor-lock.json`. From 5.x, run `npx candor-ui@4.1 migrate 6.0.0` (6.0's codemods are CLI 4.1's); then `npx candor-ui@4 migrate 6.1.0`. With no lockfile, each runs all of its release's codemods. Then install the current release over Candor's files with `npx candor-ui@4 add <your items> --overwrite`, which writes a lockfile CLI 3 can't read, and take your edits back from git. An item 6.1 removed can't be added: the list below says what replaced it.

## Before you start

- **From now on, `@4`.** A project CLI 4 has installed into has a version-2 `candor-lock.json`, which CLI 3 can't read: run every `candor-ui` command with `npx candor-ui@4`, and commit `.candor/base/` with the lockfile.
- `migrate` parses your source with the project's TypeScript or, on TypeScript 7 (which has no JavaScript API) or with none, with the TypeScript 5 that CLI 4 brings: there is nothing to install for the run.
- **Only the current release is served.** `npx candor-ui@4 update` merges against the copies in `.candor/base/`, so it needs no earlier version from the registry.

## What changes (16)

### decision-card

ApprovalDecision is DecisionCard, in decision-review beside DecisionReview and DecisionBar, and `approvalDecisionStrings` is `decisionCardStrings`. Its props and what it draws are unchanged, and it still takes a `Decision` from lib/candor/work. ApprovalRequest, `approvalRequestStrings` and `approvalStateTone` stay in approval-request.

- **On:** `approval-request`, `decision-review`
- **What breaks:** An import of `ApprovalDecision` or `approvalDecisionStrings` from approval-request fails the type check (`has no exported member`).
- **Shows in:** imports, the type check
- **What to do:** `npx candor-ui@4 migrate items` moves each import of `ApprovalDecision` and `approvalDecisionStrings` from approval-request to decision-review as `DecisionCard` and `decisionCardStrings`, and renames their uses, `<ApprovalDecision …>` included. Every prop stays as it is.
- **Codemod:** `npx candor-ui@4 migrate items`, which `migrate 6.1.0` runs.

### decision-card-strings

DecisionCard's strings are the `decisionCard` table, which was `approvalDecision`. Every key and its words are the same.

- **On:** `approval-request`, `decision-review`
- **What breaks:** An override under `approvalDecision` isn't read, so the card draws Candor's words. It still compiles: `StringOverrides` takes any key.
- **Shows in:** what is drawn
- **What to do:** `npx candor-ui@4 migrate strings-keys` renames `approvalDecision` to `decisionCard` in a LocaleProvider strings object written as a literal, and lists one built at run time. Translations stored outside your source: rename the table there.
- **Codemod:** `npx candor-ui@4 migrate strings-keys`, which `migrate 6.1.0` runs.

### decision-bar-merged

DecisionBar is in decision-review, with `decisionBarChangeGuard` and `decisionBarStrings`; the decision-bar item is gone. Its props, strings and behaviour are unchanged. `DecisionBarAction` and `DecisionReviewAction` are one type, `DecisionAction`, with the same fields.

- **On:** `decision-bar`, `decision-review`
- **What breaks:** `update` keeps decision-bar's file as your own and stops recording it, so an import from it gets no more fixes, and fails once you delete the file. An import of `DecisionReviewAction` from decision-review fails the type check (`has no exported member`).
- **Shows in:** imports, the type check
- **What to do:** `npx candor-ui@4 update --to 6.1.0` installs decision-review if your project hasn't got it. `npx candor-ui@4 migrate items` points each import from decision-bar at decision-review and renames `DecisionBarAction` and `DecisionReviewAction` to `DecisionAction`. Then delete decision-bar's file once nothing imports it.
- **Codemod:** `npx candor-ui@4 migrate items`, which `migrate 6.1.0` runs.

### review-ladder-removed

ReviewLadder and the `ReviewLevel` type are removed: PermissionMode with your own modes does the job. PermissionMode gains `label`, the control's name in place of "Permission mode". The `reviewLadder` strings go too.

- **On:** `review-ladder`, `permission-mode`
- **What breaks:** `update` keeps review-ladder's file as your own and stops recording it; once lib/candor/work is updated it no longer has `ReviewLevel`, so that file and any import of `ReviewLevel` fail the type check until you move to PermissionMode.
- **Shows in:** imports, the type check, what is drawn
- **What to do:** By hand, with PermissionMode: `value` is `mode`; `onValueChange` gets the mode's id as a string; each `locked[level]` is that mode's `locked`; the rungs' words (`reviewLadder.R1` to `R5Detail`) are each mode's `label` and `detail`, in your words; the heading is `label="Review level"`. No mode asks for confirmation unless it sets `confirm: true`. `npx candor-ui@4 update --to 6.1.0` installs permission-mode if your project hasn't got it, and `npx candor-ui@4 migrate items` lists each `<ReviewLadder>` and each `ReviewLevel` import with this mapping, changing nothing. Then delete review-ladder's file. A ladder with no `onValueChange` (a display): leave `onValueChange` out of PermissionMode too, and its other modes say they can't be changed here; pass `locked` with your reason to say why in your words.
- **Codemod:** `npx candor-ui@4 migrate items`, which `migrate 6.1.0` runs.

### review-ladder-strings

The `reviewLadder` strings are gone with ReviewLadder.

- **On:** `review-ladder`, `permission-mode`
- **What breaks:** An override under `reviewLadder` isn't read. It still compiles: `StringOverrides` takes any key.
- **Shows in:** what is drawn
- **What to do:** `npx candor-ui@4 migrate strings-keys` lists each override under `reviewLadder`, changing nothing: the rungs' words (`R1` to `R5Detail`) become each of your modes' `label` and `detail` for PermissionMode, and `label` its `label` prop. Then delete the overrides. Translations stored outside your source: move them there.
- **Codemod:** `npx candor-ui@4 migrate strings-keys`, which `migrate 6.1.0` runs.

### review-canvas-removed

ReviewCanvas is removed. ApprovalRequest's docs page has an example in its place, "Approve with the evidence beside it", composing Plan, LogStream, ChangeDiff, BlastRadius, Reasoning and ApprovalRequest. The `reviewCanvas` strings go too.

- **On:** `review-canvas`
- **What breaks:** `update` keeps review-canvas's file as your own and stops recording it, so an import from it gets no more fixes, and fails once you delete the file.
- **Shows in:** imports
- **What to do:** By hand: compose the page from the items it drew, starting from the example on /docs/approval-request, and keep its rule that a tab with nothing for the chosen step says so. `npx candor-ui@4 migrate items` lists each `<ReviewCanvas>` and each import from review-canvas, changing nothing. Then delete review-canvas's file.
- **Codemod:** `npx candor-ui@4 migrate items`, which `migrate 6.1.0` runs.

### review-canvas-strings

The `reviewCanvas` strings are gone with ReviewCanvas.

- **On:** `review-canvas`
- **What breaks:** An override under `reviewCanvas` isn't read. It still compiles: `StringOverrides` takes any key.
- **Shows in:** what is drawn
- **What to do:** `npx candor-ui@4 migrate strings-keys` lists each override under `reviewCanvas`, changing nothing: nothing reads them, and the page you compose in ReviewCanvas's place has your own words. Then delete them, and their translations stored outside your source.
- **Codemod:** `npx candor-ui@4 migrate strings-keys`, which `migrate 6.1.0` runs.

### usage-meter-variants

UsageGlance and UsageRing are UsageMeter's `glance` and `ring` variants, in usage-meters; the usage-glance and usage-ring items are gone. UsageMeter takes the props they took (`period` and `href` for a glance, `estimateBasis` for a ring, `unknown` and `paused` for every variant). UsageMeters is unchanged, and PortfolioCard draws its line with UsageMeter's glance (its markup gains `data-variant="glance"`), so it needs usage-meters in place of usage-glance. `usageGlanceStrings` and `usageRingStrings` are `usageMetersStrings`.

- **On:** `usage-glance`, `usage-ring`, `usage-meters`, `portfolio-card`
- **What breaks:** `update` keeps usage-glance's and usage-ring's files as your own and stops recording them, so an import from them gets no more fixes, and fails once you delete the files.
- **Shows in:** imports, the type check
- **What to do:** `npx candor-ui@4 update --to 6.1.0` installs usage-meters if your project hasn't got it. `npx candor-ui@4 migrate items` points each import of UsageGlance and UsageRing at usage-meters as `UsageMeter`, writes `<UsageGlance …>` as `<UsageMeter variant="glance" …>` and `<UsageRing …>` as `<UsageMeter variant="ring" …>` with the same props, renames `usageGlanceStrings` and `usageRingStrings` to `usageMetersStrings`, and lists a read of a key `usageMetersStrings` has under another name. Then delete the two files once nothing imports them.
- **Codemod:** `npx candor-ui@4 migrate items`, which `migrate 6.1.0` runs.

### usage-meter-strings

The `usageGlance` and `usageRing` tables are gone and their keys are in `usageMeters`. A key both had with the same words is one key. Two keep the bar's words under the old name and take a new one for the glance's and ring's: their `usedOfLimit` ("{used} of {limit}") is `usedOfLimitWords`, and the ring's `estimateValue` is `estimateWithBasis`.

- **On:** `usage-glance`, `usage-ring`, `usage-meters`
- **What breaks:** An override under `usageGlance` or `usageRing` isn't read, so a glance or a ring draws Candor's words, or your `usageMeters` ones. It still compiles: `StringOverrides` takes any key.
- **Shows in:** what is drawn
- **What to do:** `npx candor-ui@4 migrate strings-keys` moves each override in `usageGlance` and `usageRing` into `usageMeters` under its new key, in a strings object written as a literal, and lists one built at run time. Where the glance and the ring worded one key differently, it writes the glance's and lists the ring's, for you to choose. Translations stored outside your source: move them there, with the table on /upgrading-to-6-1.
- **Codemod:** `npx candor-ui@4 migrate strings-keys`, which `migrate 6.1.0` runs.

### change-tree-merged

ChangeTree, `ChangeTreeFile` and `changeTreeStrings` are in change-diff; the change-tree item is gone. ChangeTree's props are unchanged, and ChangeDiff can draw one beside its diff with `navigation="tree"`.

- **On:** `change-tree`, `change-diff`
- **What breaks:** `update` keeps change-tree's file as your own and stops recording it, so an import from it gets no more fixes, and fails once you delete the file.
- **Shows in:** imports
- **What to do:** `npx candor-ui@4 update --to 6.1.0` installs change-diff if your project hasn't got it. `npx candor-ui@4 migrate items` points each import from change-tree at change-diff, and lists each file with a ChangeTree beside a ChangeDiff, which you can make one `<ChangeDiff navigation="tree">` by hand if you want. Then delete change-tree's file once nothing imports it.
- **Codemod:** `npx candor-ui@4 migrate items`, which `migrate 6.1.0` runs.

### change-tree-strings

ChangeTree's chips read `changeDiff.create`, `update` and `delete`, the words ChangeDiff's tabs use; `changeTree.create`, `update` and `delete` are gone. ChangeTree's other keys stay.

- **On:** `change-tree`, `change-diff`
- **What breaks:** An override of `changeTree.create`, `update` or `delete` isn't read, so the chips say "New", "Changed" and "Deleted", or your `changeDiff` words. It still compiles: `StringOverrides` takes any key.
- **Shows in:** what is drawn
- **What to do:** `npx candor-ui@4 migrate strings-keys` moves an override of the three into `changeDiff` where `changeDiff` doesn't set them, and lists one where it does, for you to keep one word for each change.
- **Codemod:** `npx candor-ui@4 migrate strings-keys`, which `migrate 6.1.0` runs.

### away-digest-merged

AwayDigest is removed: Digest does its job, with `since` ("Since you were last here" and how long ago, under the title) and a `failed` section, which DigestEmail draws too. Digest's rows take an `at`, drawn as a relative time. `DigestItem` leaves lib/candor/ops.

- **On:** `away-digest`, `digest`, `digest-email`
- **What breaks:** `update` keeps away-digest's file as your own and stops recording it; once lib/candor/ops is updated it no longer has `DigestItem`, so that file and any import of `DigestItem` fail the type check until you move to Digest. The rows AwayDigest headed "Waiting on you" and "Finished" are headed "Needs you" and "What was done" in Digest.
- **Shows in:** imports, the type check, what is drawn
- **What to do:** By hand, since the data changes shape: draw `<Digest digest={…} since={since} onOpen={…}>` with a `DigestData` whose `title` is your heading (AwayDigest's was "While you were away"), the items of kind `waiting` in `needsYou` and `failed` in `failed`, each as `{ id, title, detail, at }`, and those of kind `finished` in `done` as `{ id, title, at }`, without `by` (`DigestDone` has no `detail`: fold a finished item's detail into its title, or leave it out). `onOpen(id)` is unchanged. `npx candor-ui@4 update --to 6.1.0` installs digest if your project hasn't got it, and `npx candor-ui@4 migrate items` lists each `<AwayDigest>` and each `DigestItem` with this mapping, changing nothing. Then delete away-digest's file.
- **Codemod:** `npx candor-ui@4 migrate items`, which `migrate 6.1.0` runs.

### away-digest-strings

The `awayDigest` strings are gone. `digest` gains `since` ("Since you were last here"), `failed` ("Failed"), `nothingSince` ("Nothing happened while you were away.") and `total` ("{count} thing" / "{count} things"), and `digestEmail` gains `failed`.

- **On:** `away-digest`, `digest`
- **What breaks:** An override under `awayDigest` isn't read. It still compiles: `StringOverrides` takes any key.
- **Shows in:** what is drawn
- **What to do:** `npx candor-ui@4 migrate strings-keys` moves `awayDigest.sinceLastHere` to `digest.since`, `failed` to `digest.failed` and `nothingHappened` to `digest.nothingSince` and `things` to `digest.total`, and lists `whileAway`, `waiting`, `finished` and `group` as removed, with where their words come from now (the heading is your `title`; the sections are `digest.needsYou` and `digest.done`). Translations stored outside your source: move them there.
- **Codemod:** `npx candor-ui@4 migrate strings-keys`, which `migrate 6.1.0` runs.

### digest-open-rows

Digest calls `onOpen` for a done or failed row without `href` too, not only a needs-you row, so those rows are buttons when you pass it. `DigestDone`'s `by` is optional: a done row without it draws no "by" line.

- **On:** `digest`
- **What breaks:** With `onOpen` passed, done rows without `href` become buttons that call it with their id. Code that reads a done row's `by` fails the type check under `strictNullChecks` (`possibly 'undefined'`).
- **Shows in:** the type check, behaviour, what is drawn
- **What to do:** Give done and failed rows an `href`, open them in `onOpen` by id, or leave `onOpen` out. Handle `undefined` where you read a done row's `by`. Only you know which rows should open, so there is no codemod.
- **Codemod:** By hand: no codemod can make this change safely.

### consolidation-motion

Motion tokens follow their components. `--cd-motion-usage-glance-fill` is `--cd-motion-usage-meters-glance-fill` and `--cd-motion-usage-ring-fill` is `--cd-motion-usage-meters-ring-fill`, each with its suffixes. DecisionCard's answer and its mark read `--cd-motion-decision-review-card-outcome` and `--cd-motion-decision-review-card-outcome-mark` (with `-dur`, `-ease` and `-variant`) where ApprovalDecision read ApprovalRequest's `--cd-motion-approval-request-outcome` and `-outcome-mark`, which ApprovalRequest keeps. `--cd-motion-review-ladder-rung` is gone.

- **On:** `usage-glance`, `usage-ring`, `approval-request`, `decision-review`, `review-ladder`
- **What breaks:** A brand file or stylesheet that sets an old name no longer changes the glance's or the ring's fill or DecisionCard's answer: those move as Candor's defaults do. Nothing fails to build.
- **Shows in:** styling
- **What to do:** `npx candor-ui@4 migrate tokens` renames the two usage tokens and their suffixes in your CSS and `var()` uses, adds a DecisionCard declaration beside each of the approval-request outcome ones (it can't tell which component you meant, so it keeps both: delete the one you don't want), and lists `--cd-motion-review-ladder-rung` as removed.
- **Codemod:** `npx candor-ui@4 migrate tokens`, which `migrate 6.1.0` runs.

### message-block-kinds

`MessageBlock` gains two kinds: `table`, a GFM pipe table in model text, its cells inline text, and `quote`, `>` lines as inline text, one level. MessageContent draws them as a `<table>` that scrolls sideways and a `<blockquote>`, text only, never HTML. A fenced block whose language the highlighter knows is highlighted.

- **On:** `chat`, `safe-markdown`, `message-content`
- **What breaks:** A `switch` over a block's `kind` that ends in a `never` check fails the type check until it handles `table` and `quote` or has a default. Model text with a pipe table, `>` lines or a fenced block in a highlighted language draws differently: as a table, a quote and highlighted code, where 6.0 drew paragraphs and plain code.
- **Shows in:** the type check, what is drawn
- **What to do:** Handle `table` and `quote` in a switch over a block's `kind`, or give it a default; from 6.1 a minor may add a kind, and `MessageBlock`'s doc comment says so. A model's pipe table now draws as a table, its > lines as a quote, and a fence in a language Payload highlights is highlighted in it when highlighting is on; check any CSS that matched those as paragraphs or plain code.
- **Codemod:** By hand: no codemod can make this change safely.
