Skip to content

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.

The commands

  1. 01: 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.

    Look first
  2. 02: 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".

    Run 6.1's codemods
  3. 03: 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.

    Finish by hand, then check
  4. 04: 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.