Skip to content

Candor 5.0.0

Choose a tag to compare

@arunk3 arunk3 released this 13 Nov 13:02
· 9 commits to main since this release

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-run prints what 5.0 changes for the items in
    candor-lock.json, and writes nothing.
  • Update: npx candor-ui@3 update --to 5.0.0 updates every item, merging your changes into Candor's as update
    always has.
  • Migrate: npx candor-ui@3 migrate 5.0.0 runs 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-run shows 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 (codemod types-data): Message and ToolCall (lib/candor/chat), ApprovalRequest and
    ResultTable (lib/candor/work), Finding (lib/candor/data) and RunReceipt (lib/candor/ops) are MessageData,
    ToolCallData, ApprovalRequestData, ResultTableData, FindingData and RunReceiptData, the names
    @candor-ui/react already 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/react don't change.
  • heading-default (codemod headings, which lists): without headingLevel, an item's top heading is one level
    below the nearest HeadingScope, 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>: pass headingLevel={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
    headingLevel with 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): headingLevel is HeadingLevel (1 to 6) on every item,
    where DataTable, ReorderableList, Board and BoardCard, NarrativeBlock, PortfolioCard, MonitorCard, DashboardTile and
    EnvironmentList took 2 | 3 | 4 | 5 | 6. A level you pass still type-checks. Where you type a level of your own,
    import HeadingLevel from lib/candor/heading-level (layout/heading still exports it).
  • props-active-id-nav (codemod props): TabBar's and NavRail's current, AppSidebar's activeNav and
    SettingsLayout's active are activeId, with the same value. Stepper's, PlanPicker's and InlineSuggestion's
    current mean something else and stay.
  • props-label-name (codemod props): SettingsLayout's and DocumentViewer's title, their accessible name, which
    isn't drawn, is label; title is Candor's word for a heading that is drawn.
  • props-popup-class (codemod props): PersonMenu's and ScopeSwitcher's layerClass prop, the classes for the
    menu's popup, is popupClassName.
  • on-select-id (by hand): Tree's and EnvironmentBand's onSelect passes the id of the node or environment, not
    the object. Write onSelect={(id) => …} and look it up by id where the handler needs it. migrate props lists each
    onSelect on them, and the type check finds a handler that still takes the object.
  • strings-compat-exports (codemod strings-keys): statusLabel (lib/candor/status), environmentLabel
    (lib/candor/team), approvalStateLabel (approval-request), reviewLevels (review-ladder) and standardCards
    (standard-cards), English only, are removed. The codemod rewrites standardCards used inside a component to const standardCards = useStandardCards() at its top, and lists the others, and standardCards used outside a component,
    with what to use: useStatusLabel() (label("running")); EnvironmentBand's production and nonProduction
    strings joined with useFormat().join; useStrings("approvalRequest", approvalRequestStrings);
    useStrings("reviewLadder", reviewLadderStrings). SessionList's statusLabel prop is a different thing and stays.
  • chart-strings (codemod strings-keys): barChart.byCategory, lineChart.over, lineChart.chartValues and
    heatmap.heatmap, unread since 4.2, are removed. An override of one still compiles and draws nothing; the codemod
    deletes it.
  • strings-separator (codemod strings-keys): the " · " between parts is one string, strings.locale.separator,
    read through useFormat().separator and useFormat().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.hintSeparator and markSeparator, and reviewQueue.hintSeparator. The codemod moves an override
    of one to locale.separator; where two give different values, it lists them for you to choose. subscoreCard.separator
    and tableScrubberMap.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}") and checkedAt ("checked {when}"),
    subscriptionStatus.cardExpires ("expires {expires}"), membersTable.invitedBy ("Invited by {name}", with the new
    expiresIn), awayDigest.group ("{label}"), blastRadius.group ("{noun}s"), escalation.sentLine and
    acknowledged, environmentPromotion.requestedBy, promoted and declined (each without {when}),
    taskTray.started ("started"), clarifyingQuestions.progress ("question {step} of {total}", with the new
    before), agentRoster.failed ("{count} failed") and columnMapper.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}", and gradedCount) 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 (codemod strings-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.added and removed (addedNow and removedNow, "Added 3 to Members, which
    now holds 5.") and total; 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.problemsCount and workflowEditor.graphProblems
    (problems); plan.sentBackSummary (notAccepted); shipReview.summary (createdCount, updatedCount,
    deletedCount); and environmentConnect.nameDetail, environmentPromotion.nameDetail and approvedAt,
    driftChange.where and plan.proposedSummary, whose parts Candor joins with nothing to translate; so do
    composer.scopeChip, composerScopePicker.scopeChip, searchTrace.counts, appSidebar.labelCount,
    inbox.needsYouCount and sessionList.contextKindShown, which held " · " in 4.x; and inbox.needsYouCountAtLeast
    (countAtLeast, "{count}+", joined to needsYou). 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.measuredFailed and failedWithFiles.
  • 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
    after onDismiss, or when the promise it returns settles. Where onDismiss saves before it takes the card out,
    return the promise (an async handler does), or the dismissal isn't announced.
  • locked-not-disabled (no codemod: behaviour): a control that waits on something stays focusable and is
    aria-disabled with the reason, through Locked, where it was natively disabled; 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 new locked… strings. Composer's box and TypeToConfirm's are readOnly while locked. With onGoTo, every
    StepWalker stage is a button: a stage not reached yet is locked, and the current one is marked aria-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, check toHaveAttribute("aria-disabled", "true") in place of toBeDisabled(), and find such a row by its
    text. Nothing changes in the app's code.
  • cli-3 (no codemod): use npx candor-ui@3 for 5.0. It works with Candor 4.0 and later. npx candor-ui@2 stays
    on npm for a 3.x project (upgrade it to 4.0 with @2 first), for update --fold, and for update --from, which
    records items installed before the lockfile.

New items (Pro)

  • heading-level: the HeadingLevel type (1 to 6), in lib/candor/heading-level. The free items type their
    headingLevel with 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; and belowLevel(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>, takes headingLevel, and its controls and steps sit one level below its title.
  • Chat: EntityDisambiguation (a fixed <h3> in 4.x), ThreadHeader and FormErrorSummary take headingLevel. The
    free MessageContent takes headingLevel, 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 round change, 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 typed HeadingLevel and 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>); pass headingLevel={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.scopeChip and searchTrace.domainSeparator are
    gone, as above.
  • localeStrings is exported, with locale.separator; useFormat() gives separator and join(parts).
  • statusLabel is no longer exported: use useStatusLabel(). The data types' names don't change here.
  • ToolCall, PermissionPrompt and Composer: a control that waits on something is aria-disabled with the reason, and
    stays focusable, where it was natively disabled (locked-not-disabled above). Composer's box is readOnly while
    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 a span unless you pass onScopeClick. In a test, check
    toHaveAttribute("aria-disabled", "true") in place of toBeDisabled(), and find such a row by its text. A
    translated app translates the new reasons: ToolCall's lockedNoDetail; PermissionPrompt's lockedBusy,
    lockedInvalid and lockedUnanswered; Composer's lockedUnavailable, lockedHeld, lockedEmpty, lockedSending
    and lockedStreaming.

CLI 3.0.0

  • New: migrate 5.0.0, with the codemods types-data, props (5.0's renames and onSelect listing),
    strings-keys (the separator, the removed keys and the English exports) and headings (lists only). A codemod
    table's row says which release it belongs to, so migrate 4.0.0 makes none of 5.0's changes.
  • add, update and migrate refuse a project older than 4.0, naming npx candor-ui@2 (and @1 for 2.x).
  • Removed, with 3.x: migrate motion-aliases and its tables; strings-keys' message.thinking and
    useAnsweringApprovals rows; update --fold, which now refuses and names npx candor-ui@2 update --fold; and
    update --from, which names npx 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 name npx candor-ui@2 migrate motion-aliases.
  • Fixed: a table rename keeps an inline type modifier on the import.
  • migrate, and update where it moves files, run on a TypeScript 7 project: where the project's typescript has 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 UI asChild rewrite in add and update still 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.mjs looks through HeadingScope to an item's root.