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
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 first02: 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 codemods03: Finish by hand, then check
Make the changes
migratelists under "Left for you", then the ones below marked "By hand", which the type check finds. Then type-check, build and run your tests.verifychecks each installed file and its copy in.candor/base/againstcandor-lock.json, without the network.Finish by hand, then check04: 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, runnpx candor-ui@4.1 migrate 6.0.0(6.0's codemods are CLI 4.1's); thennpx 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 withnpx 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-2candor-lock.json, which CLI 3 can't read: run everycandor-uicommand withnpx candor-ui@4, and commit.candor/base/with the lockfile. migrateparses 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 updatemerges 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
ApprovalDecisionorapprovalDecisionStringsfrom approval-request fails the type check (has no exported member). - Shows in
- imports, the type check
- What to do
npx candor-ui@4 migrate itemsmoves each import ofApprovalDecisionandapprovalDecisionStringsfrom approval-request to decision-review asDecisionCardanddecisionCardStrings, and renames their uses,<ApprovalDecision …>included. Every prop stays as it is.- Codemod
npx candor-ui@4 migrate items, whichmigrate 6.1.0runs.
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
approvalDecisionisn't read, so the card draws Candor's words. It still compiles:StringOverridestakes any key. - Shows in
- what is drawn
- What to do
npx candor-ui@4 migrate strings-keysrenamesapprovalDecisiontodecisionCardin 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, whichmigrate 6.1.0runs.
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
updatekeeps 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 ofDecisionReviewActionfrom 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.0installs decision-review if your project hasn't got it.npx candor-ui@4 migrate itemspoints each import from decision-bar at decision-review and renamesDecisionBarActionandDecisionReviewActiontoDecisionAction. Then delete decision-bar's file once nothing imports it.- Codemod
npx candor-ui@4 migrate items, whichmigrate 6.1.0runs.
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
updatekeeps review-ladder's file as your own and stops recording it; once lib/candor/work is updated it no longer hasReviewLevel, so that file and any import ofReviewLevelfail the type check until you move to PermissionMode.- Shows in
- imports, the type check, what is drawn
- What to do
- By hand, with PermissionMode:
valueismode;onValueChangegets the mode's id as a string; eachlocked[level]is that mode'slocked; the rungs' words (reviewLadder.R1toR5Detail) are each mode'slabelanddetail, in your words; the heading islabel="Review level". No mode asks for confirmation unless it setsconfirm: true.npx candor-ui@4 update --to 6.1.0installs permission-mode if your project hasn't got it, andnpx candor-ui@4 migrate itemslists each<ReviewLadder>and eachReviewLevelimport with this mapping, changing nothing. Then delete review-ladder's file. A ladder with noonValueChange(a display): leaveonValueChangeout of PermissionMode too, and its other modes say they can't be changed here; passlockedwith your reason to say why in your words. - Codemod
npx candor-ui@4 migrate items, whichmigrate 6.1.0runs.
review-ladder-strings
The reviewLadder strings are gone with ReviewLadder.
- On
review-ladder,permission-mode- What breaks
- An override under
reviewLadderisn't read. It still compiles:StringOverridestakes any key. - Shows in
- what is drawn
- What to do
npx candor-ui@4 migrate strings-keyslists each override underreviewLadder, changing nothing: the rungs' words (R1toR5Detail) become each of your modes'labelanddetailfor PermissionMode, andlabelitslabelprop. Then delete the overrides. Translations stored outside your source: move them there.- Codemod
npx candor-ui@4 migrate strings-keys, whichmigrate 6.1.0runs.
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
updatekeeps 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 itemslists each<ReviewCanvas>and each import from review-canvas, changing nothing. Then delete review-canvas's file. - Codemod
npx candor-ui@4 migrate items, whichmigrate 6.1.0runs.
review-canvas-strings
The reviewCanvas strings are gone with ReviewCanvas.
- On
review-canvas- What breaks
- An override under
reviewCanvasisn't read. It still compiles:StringOverridestakes any key. - Shows in
- what is drawn
- What to do
npx candor-ui@4 migrate strings-keyslists each override underreviewCanvas, 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, whichmigrate 6.1.0runs.
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
updatekeeps 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.0installs usage-meters if your project hasn't got it.npx candor-ui@4 migrate itemspoints each import of UsageGlance and UsageRing at usage-meters asUsageMeter, writes<UsageGlance …>as<UsageMeter variant="glance" …>and<UsageRing …>as<UsageMeter variant="ring" …>with the same props, renamesusageGlanceStringsandusageRingStringstousageMetersStrings, and lists a read of a keyusageMetersStringshas under another name. Then delete the two files once nothing imports them.- Codemod
npx candor-ui@4 migrate items, whichmigrate 6.1.0runs.
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
usageGlanceorusageRingisn't read, so a glance or a ring draws Candor's words, or yourusageMetersones. It still compiles:StringOverridestakes any key. - Shows in
- what is drawn
- What to do
npx candor-ui@4 migrate strings-keysmoves each override inusageGlanceandusageRingintousageMetersunder 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, whichmigrate 6.1.0runs.
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
updatekeeps 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.0installs change-diff if your project hasn't got it.npx candor-ui@4 migrate itemspoints 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, whichmigrate 6.1.0runs.
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,updateordeleteisn't read, so the chips say "New", "Changed" and "Deleted", or yourchangeDiffwords. It still compiles:StringOverridestakes any key. - Shows in
- what is drawn
- What to do
npx candor-ui@4 migrate strings-keysmoves an override of the three intochangeDiffwherechangeDiffdoesn'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, whichmigrate 6.1.0runs.
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
updatekeeps away-digest's file as your own and stops recording it; once lib/candor/ops is updated it no longer hasDigestItem, so that file and any import ofDigestItemfail 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 aDigestDatawhosetitleis your heading (AwayDigest's was "While you were away"), the items of kindwaitinginneedsYouandfailedinfailed, each as{ id, title, detail, at }, and those of kindfinishedindoneas{ id, title, at }, withoutby(DigestDonehas nodetail: 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.0installs digest if your project hasn't got it, andnpx candor-ui@4 migrate itemslists each<AwayDigest>and eachDigestItemwith this mapping, changing nothing. Then delete away-digest's file. - Codemod
npx candor-ui@4 migrate items, whichmigrate 6.1.0runs.
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
awayDigestisn't read. It still compiles:StringOverridestakes any key. - Shows in
- what is drawn
- What to do
npx candor-ui@4 migrate strings-keysmovesawayDigest.sinceLastHeretodigest.since,failedtodigest.failedandnothingHappenedtodigest.nothingSinceandthingstodigest.total, and listswhileAway,waiting,finishedandgroupas removed, with where their words come from now (the heading is yourtitle; the sections aredigest.needsYouanddigest.done). Translations stored outside your source: move them there.- Codemod
npx candor-ui@4 migrate strings-keys, whichmigrate 6.1.0runs.
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
onOpenpassed, done rows withouthrefbecome buttons that call it with their id. Code that reads a done row'sbyfails the type check understrictNullChecks(possibly 'undefined'). - Shows in
- the type check, behaviour, what is drawn
- What to do
- Give done and failed rows an
href, open them inonOpenby id, or leaveonOpenout. Handleundefinedwhere you read a done row'sby. 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 tokensrenames the two usage tokens and their suffixes in your CSS andvar()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-rungas removed.- Codemod
npx candor-ui@4 migrate tokens, whichmigrate 6.1.0runs.
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
switchover a block'skindthat ends in anevercheck fails the type check until it handlestableandquoteor 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
tableandquotein a switch over a block'skind, or give it a default; from 6.1 a minor may add a kind, andMessageBlock'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.