Repository navigation
Candor 5.0.0
Released 2026-11-13.
A major release, with CLI 3.0.0 and @candor-ui/react 5.0.0: one heading outline, one name per idea, and strings a
translation can reach. Every item that draws a heading takes headingLevel (1 to 6) and, without it, draws one level
below the nearest HeadingScope, else <h2>, so a page's outline skips no level; dialogs, sheets, drawers, settings
sections and dashboard tiles set the scope. The nav items' selected item is activeId, Tree's and EnvironmentBand's
onSelect passes an id, and an accessible name is label. The " · " between parts is one string,
locale.separator, and sentences that were joined in code are one string each with {placeholders}. The six data
types are MessageData, ToolCallData and so on, as @candor-ui/react already named them, and the English exports
kept for compatibility are gone. CLI 3.0 runs the upgrade (npx candor-ui@3 update --to 5.0.0, then npx candor-ui@3 migrate 5.0.0) and no longer takes a 3.x project, which keeps CLI 2. heading-level and heading-scope
are new, so the kit has 401 items: 74 free and 370 in Pro.
Upgrading from 4.x
Start from a committed tree, so you can see what each step changed. Then, from the app's folder (the one with
components.json):
- Look first:
npx candor-ui@3 update --to 5.0.0 --dry-runprints what 5.0 changes for the items in
candor-lock.json, and writes nothing. - Update:
npx candor-ui@3 update --to 5.0.0updates every item, merging your changes into Candor's asupdate
always has. - Migrate:
npx candor-ui@3 migrate 5.0.0runs each of 5.0's codemods that an entry on your installed items names,
in this order:types-data,props,strings-keys,headings. Each lists what it couldn't change under "Left for
you".--dry-runshows it first. - Finish and check: make the changes the "Left for you" lines name and those marked "by hand" below, then
type-check (npx tsc --noEmit) and build.
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 3 brings, so there is nothing to install for the run. Strings you override are checked only
where they are written as a strings object Candor can see: on LocaleProvider or CandorProvider, in a
CandorConfig, or typed StringOverrides. The type check doesn't find an override of a key 5.0 removes, since
StringOverrides takes any key: it still compiles and isn't read, so migrate strings-keys is what moves or lists it.
Every change, by its id in scripts/breaking.json (the same entries update --to 5.0.0 prints, and the Upgrading to
5.0 page lists):
types-data(codemodtypes-data):MessageandToolCall(lib/candor/chat),ApprovalRequestand
ResultTable(lib/candor/work),Finding(lib/candor/data) andRunReceipt(lib/candor/ops) areMessageData,
ToolCallData,ApprovalRequestData,ResultTableData,FindingDataandRunReceiptData, the names
@candor-ui/reactalready used. No alias is kept. The codemod renames each import and its uses; an import you
aliased keeps your local name. Imports from@candor-ui/reactdon't change.heading-default(codemodheadings, which lists): withoutheadingLevel, an item's top heading is one level
below the nearestHeadingScope, else<h2>, and its sub-headings sit below it. Most items that drew<h3>or
<h4>now draw<h2>outside a scope; they look the same. DialogContent, SheetContent, DrawerContent,
AlertDialogContent, SettingsSection, DashboardTile, ArtifactPanel, AppLayout's chat, a floating DockWindow,
ReportSheet and ReportSection put their content in a scope, so a Candor item inside draws one level lower than
before. ReportSheet's cover, a fixed<h1>in 4.x, is<h2>: passheadingLevel={1}where a ReportSheet is the
whole page. The free PermissionPrompt draws<h2>(was<h3>) and reads no scope. PageHeader stays<h1>,
AccountState (a whole page) keeps its<h1>, EmailPreview keeps<h3>, and RestoreDialog's "not undone"
heading keeps<h3>, under the dialog's<h2>title. The codemod lists each use without
headingLevelwith the level it drew in 4.x, and changes nothing: where a page or a test needs that level, pass
headingLevel={n}, or wrap a section in<HeadingScope level={n}>(lib/candor/heading-scope).heading-level-type(no codemod: nothing to change):headingLevelisHeadingLevel(1 to 6) on every item,
where DataTable, ReorderableList, Board and BoardCard, NarrativeBlock, PortfolioCard, MonitorCard, DashboardTile and
EnvironmentList took2 | 3 | 4 | 5 | 6. A level you pass still type-checks. Where you type a level of your own,
importHeadingLevelfrom lib/candor/heading-level (layout/headingstill exports it).props-active-id-nav(codemodprops): TabBar's and NavRail'scurrent, AppSidebar'sactiveNavand
SettingsLayout'sactiveareactiveId, with the same value. Stepper's, PlanPicker's and InlineSuggestion's
currentmean something else and stay.props-label-name(codemodprops): SettingsLayout's and DocumentViewer'stitle, their accessible name, which
isn't drawn, islabel;titleis Candor's word for a heading that is drawn.props-popup-class(codemodprops): PersonMenu's and ScopeSwitcher'slayerClassprop, the classes for the
menu's popup, ispopupClassName.on-select-id(by hand): Tree's and EnvironmentBand'sonSelectpasses the id of the node or environment, not
the object. WriteonSelect={(id) => …}and look it up by id where the handler needs it.migrate propslists each
onSelecton them, and the type check finds a handler that still takes the object.strings-compat-exports(codemodstrings-keys):statusLabel(lib/candor/status),environmentLabel
(lib/candor/team),approvalStateLabel(approval-request),reviewLevels(review-ladder) andstandardCards
(standard-cards), English only, are removed. The codemod rewritesstandardCardsused inside a component toconst standardCards = useStandardCards()at its top, and lists the others, andstandardCardsused outside a component,
with what to use:useStatusLabel()(label("running")); EnvironmentBand'sproductionandnonProduction
strings joined withuseFormat().join;useStrings("approvalRequest", approvalRequestStrings);
useStrings("reviewLadder", reviewLadderStrings). SessionList'sstatusLabelprop is a different thing and stays.chart-strings(codemodstrings-keys):barChart.byCategory,lineChart.over,lineChart.chartValuesand
heatmap.heatmap, unread since 4.2, are removed. An override of one still compiles and draws nothing; the codemod
deletes it.strings-separator(codemodstrings-keys): the " · " between parts is one string,strings.locale.separator,
read throughuseFormat().separatoranduseFormat().join. The keys that held it are removed:
message.metaSeparator,payload.titleSeparator,permissionPrompt.scopeSeparator,reasoning.summarySeparator,
composer.hintSeparator,searchTrace.domainSeparator,changeSetReview.hintSeparator,taskTray.countSeparator,
workflowEditor.hintSeparatorandmarkSeparator, andreviewQueue.hintSeparator. The codemod moves an override
of one tolocale.separator; where two give different values, it lists them for you to choose.subscoreCard.separator
andtableScrubberMap.kindSeparator(", ") are removed too: those lists follow the locale's list format, and the
codemod lists an override of either. These strings no longer hold the mark, since Candor joins the parts:
integrationConnect.connectedSince("since {when}") andcheckedAt("checked {when}"),
subscriptionStatus.cardExpires("expires {expires}"),membersTable.invitedBy("Invited by {name}", with the new
expiresIn),awayDigest.group("{label}"),blastRadius.group("{noun}s"),escalation.sentLineand
acknowledged,environmentPromotion.requestedBy,promotedanddeclined(each without{when}),
taskTray.started("started"),clarifyingQuestions.progress("question {step} of {total}", with the new
before),agentRoster.failed("{count} failed") andcolumnMapper.suggested("Suggested", with the new
percentSure, "{percent}% sure"). Four that held it between parts are removed, their parts joined by Candor:
reconcileTable.summary(openCount,resolvedCount,matchedCount),evalScorecard.passedFailed
(passedCount,failedCount),reviewQueue.progress(position, "{position} of {total}", andgradedCount) and
dataTable.aggregateLine, which has nothing to translate; the codemod lists an override of one with the keys that
say it now. An override of a kept string that kept its own " · " shows it twice. One that kept a placeholder
Candor no longer fills ({when},{count},{status},{expires}or{percent}) shows it as written:{when}
on screen. The codemod lists an override that still has either: take it out.strings-sentences(codemodstrings-keys, which lists): sentences built by joining strings and numbers in
code are one string each with{placeholders}, or are parts Candor joins with the separator. The removed keys, and
what says them now:scheduleEditor.announceNext(announceRule,announceRuleAlone);dataRetention.policy
(policyVersion,policyChanged);subscriptionStatus.price(pricePerSeat,priceTotal);inviteChooser.from
(fromName,expiresIn);dualListbox.addedandremoved(addedNowandremovedNow, "Added 3 to Members, which
now holds 5.") andtotal;subscoreCard.outOf100(scoreOutOf, "{score} / {max}");freshnessStamp.stampOverdue
(overdue);memoryManager.summary(inferredCount);blastRadius.reach(reachChanged,reachRead);
changeSetReview.summary(keptCount,droppedCount,toDecide);documentProgressQueue.counts(countDone,
countWorking,countQueued,countFailed);logStream.problemsCountandworkflowEditor.graphProblems
(problems);plan.sentBackSummary(notAccepted);shipReview.summary(createdCount,updatedCount,
deletedCount); andenvironmentConnect.nameDetail,environmentPromotion.nameDetailandapprovedAt,
driftChange.whereandplan.proposedSummary, whose parts Candor joins with nothing to translate; so do
composer.scopeChip,composerScopePicker.scopeChip,searchTrace.counts,appSidebar.labelCount,
inbox.needsYouCountandsessionList.contextKindShown, which held " · " in 4.x; andinbox.needsYouCountAtLeast
(countAtLeast, "{count}+", joined toneedsYou). The codemod
lists each override of a removed key with the key to translate and its placeholders; your words can't be moved for
you, since the sentence is different. New keys that replace none, so the codemod doesn't list them and a translated
app says them in English until you translate them:modelKey.keyFor(ModelKey's field label for one provider),
runTree.verdictNote,presence.hereStale,progressButton.measuredFailedandfailedWithFiles.card-deck-backspace(no codemod: behaviour): CardDeck no longer dismisses a card on Backspace; Delete does.
The hint keeps its space and names "Left and right arrows" (cardDeck.keysMoveDismiss,keysMove). Where your own
help names Backspace for CardDeck, name Delete. A dismissal is announced once the app has answered: on the redraw
afteronDismiss, or when the promise it returns settles. WhereonDismisssaves before it takes the card out,
return the promise (anasynchandler does), or the dismissal isn't announced.locked-not-disabled(no codemod: behaviour): a control that waits on something stays focusable and is
aria-disabledwith the reason, throughLocked, where it was nativelydisabled; a press does nothing until it
can be used. It covers 32 items, three of them free (ToolCall, PermissionPrompt and Composer), each with its reasons
as newlocked…strings. Composer's box and TypeToConfirm's arereadOnlywhile locked. WithonGoTo, every
StepWalker stage is a button: a stage not reached yet is locked, and the current one is markedaria-current="step",
so the stage the person pressed keeps focus when it becomes the current one. A ToolCall or SearchTrace row that has
finished with nothing behind it is text, not a button (one still running is locked until it has something to show).
In a test, checktoHaveAttribute("aria-disabled", "true")in place oftoBeDisabled(), and find such a row by its
text. Nothing changes in the app's code.cli-3(no codemod): usenpx candor-ui@3for 5.0. It works with Candor 4.0 and later.npx candor-ui@2stays
on npm for a 3.x project (upgrade it to 4.0 with@2first), forupdate --fold, and forupdate --from, which
records items installed before the lockfile.
New items (Pro)
heading-level: theHeadingLeveltype (1 to 6), in lib/candor/heading-level. The free items type their
headingLevelwith the same union written out.heading-scope:HeadingScope, which says the content inside sits under a heading of a level, so Candor items
in it draw one below;useHeadingLevel(headingLevel), the level an item draws at; andbelowLevel(level, n), for
the headings under it. Never deeper than 6.
Components
Headings (KIT-226, KIT-205, KIT-220). These take headingLevel and follow the rule above, most for the first time
or with a new default:
- Shell: McpConnect and ModelKey draw
<h2>(were<h3>); ArtifactPanel, StopAll, AppLayout's chat heading,
DockWindow's window title and SettingsSection keep<h2>outside a scope and draw one below inside one. AccountState
keeps<h1>, takesheadingLevel, and its controls and steps sit one level below its title. - Chat: EntityDisambiguation (a fixed
<h3>in 4.x), ThreadHeader and FormErrorSummary takeheadingLevel. The
free MessageContent takesheadingLevel, the level a model's#is drawn at (default 3, as before;##and###
below it, to 6), and reads no scope; ArtifactPanel passes one below its title, so a document's headings sit under it
where in 4.x they were always<h3>to<h5>. - Data, reports, ops and evals: DataTable, ReorderableList, Board, BoardCard, DetailsList, ReconcileTable,
ColumnMapper, Finding, NarrativeBlock, PortfolioCard, ReportSheet, ReportSection, MonitorCard, RunLog, RunEstimate,
FailureClusters, ReviewQueue and DashboardTile; ColumnMapper, RunEstimate, ReviewQueue, ReportSheet and ReportSection
gain the prop. Without a title, DataTable's stacked group heads and cards take the table's own level, so no level
is skipped. A loading, empty or failed list's heading sits below the list's own. - Work, knowledge and collaboration: ApprovalRequest, ApprovalDecision, ChangeSetReview, ExtractionReview (still
<h2>outside a scope), ResultCard, FileList, Proposal, Plan, CheckpointList, RestoreDialog, WorkflowEditor,
ProseDiff, VersionHistory, CommentThread, Escalation, BlastRadius, AgentScreen, ClarifyingQuestions,
DocumentProgressQueue, DriftChange, EnvironmentPromotion, ShipReview, RunRecovery, KnowledgeSources, MemoryManager,
RetrievalInspector and AwayDigest. ApprovalRequest sets a scope roundchange, ResultCard and Plan round their
actions, EnvironmentPromotion round its diff. - Admin, team and billing: ApiKeys, ChannelSetup, DataRegion, DataRetention, DeviceSessions, EnvironmentConnect,
EnvironmentList (default 3 to 2, and it accepts 1), IntegrationConnect, ScheduleEditor, ScheduleList, SsoSetup,
Webhooks, AccountCreate, ConsentCeremony, InviteChooser, SetupChecklist, SignIn, TermsConsent, BillingDetails,
InvoiceHistory and PlanGate. EmailPreview's prop is typedHeadingLeveland keeps its default of 3, since an email
is rendered on the server and can't read a scope.
Names (KIT-227): TabBar, NavRail, AppSidebar and SettingsLayout take activeId; SettingsLayout and DocumentViewer
take label; PersonMenu and ScopeSwitcher take popupClassName; Tree's and EnvironmentBand's onSelect passes the
id. SettingsLayout's contentLabel doc says to set "{item}" where the items' labels already say "settings" (KIT-204).
The separator and sentences (KIT-229, KIT-202, KIT-188): every " · " typed into an item, about forty of them, reads
locale.separator. Text from a model, a tool or another person stays in its own <bdi> beside it: Message's model
and cost, ColumnMapper's sample values and DriftChange's agent name each are. ThreadHeader's agent names and
InstructionsEditor's unknown variables are joined as the locale joins a list ("a and b"). DualListbox says one
sentence in the list's own name, and ProgressButton names the files that failed. SubscoreCard's score is "{score} /
{max}" in the locale's digits, and a total it can't compute says "Not computed".
CardDeck (KIT-157): Backspace no longer dismisses; the hint keeps its space; a dismissal the app refuses isn't
announced later; onDismiss may return a promise, and a card the app takes out before it settles is announced. ScheduleEditor (KIT-156) no longer reads announceNext.
@candor-ui/react 5.0.0
- PermissionPrompt's heading defaults to
<h2>(was<h3>); passheadingLevel={3}to keep 4.x's. - PageState and ListStateView take
headingLevel(default 2); PageHeader takes it (default 1). Additive. - MessageContent takes
headingLevel(default 3, as before): the level a model's#heading is drawn at. Additive. - Message, Payload, PermissionPrompt, Reasoning, ToolCall, Composer, ThreadEvent and ShimmerLabel read
strings.locale.separator;message.metaSeparator,payload.titleSeparator,permissionPrompt.scopeSeparator,
reasoning.summarySeparator,composer.hintSeparator,composer.scopeChipandsearchTrace.domainSeparatorare
gone, as above. localeStringsis exported, withlocale.separator;useFormat()givesseparatorandjoin(parts).statusLabelis no longer exported: useuseStatusLabel(). The data types' names don't change here.- ToolCall, PermissionPrompt and Composer: a control that waits on something is
aria-disabledwith the reason, and
stays focusable, where it was nativelydisabled(locked-not-disabledabove). Composer's box isreadOnlywhile
it is locked. A finished ToolCall row with no details is text (data-slot="tool-call-row"), not a button, and
Composer's scope chip is aspanunless you passonScopeClick. In a test, check
toHaveAttribute("aria-disabled", "true")in place oftoBeDisabled(), and find such a row by its text. A
translated app translates the new reasons: ToolCall'slockedNoDetail; PermissionPrompt'slockedBusy,
lockedInvalidandlockedUnanswered; Composer'slockedUnavailable,lockedHeld,lockedEmpty,lockedSending
andlockedStreaming.
CLI 3.0.0
- New:
migrate 5.0.0, with the codemodstypes-data,props(5.0's renames andonSelectlisting),
strings-keys(the separator, the removed keys and the English exports) andheadings(lists only). A codemod
table's row says which release it belongs to, somigrate 4.0.0makes none of 5.0's changes. add,updateandmigraterefuse a project older than 4.0, namingnpx candor-ui@2(and@1for 2.x).- Removed, with 3.x:
migrate motion-aliasesand its tables; strings-keys'message.thinkingand
useAnsweringApprovalsrows;update --fold, which now refuses and namesnpx candor-ui@2 update --fold; and
update --from, which namesnpx candor-ui@2 update <items> --from <version>. - Kept: 4.0's codemods, and
theme check's errors for 2.2's motion tokens, which now namenpx candor-ui@2 migrate motion-aliases. - Fixed: a table rename keeps an inline
typemodifier on the import. migrate, andupdatewhere it moves files, run on a TypeScript 7 project: where the project'stypescripthas no
JavaScript API, or there is none, they parse with the TypeScript 5 candor-ui depends on, where CLI 2 stopped and said
to install it. The Base UIasChildrewrite inaddandupdatestill uses the project's own, else shadcn's
preview.
For maintainers
- The react build fails on a name two modules both export, where it renamed the data types before.
scripts/check-slots.mjslooks throughHeadingScopeto an item's root.