Skip to content

Candor 6.0.0

Choose a tag to compare

@arunk3 arunk3 released this 14 Nov 15:12
· 4 commits to main since this release

Released 2026-11-14.

A major release, with CLI 3.4.0 and @candor-ui/react 6.0.0: one way to say who, approvals that invent nothing, and
headings the free tier can follow. Who did something is one type, Actor, wherever Candor draws it;
ApprovalRequestData's onBehalfOf stays { name }, since it is always a person, the one an agent asked for. An
approval needn't be a deploy: its environment, production flag and build hash are optional, and Candor draws nothing
for one that is missing. HeadingScope and HeadingLevel are free, and the free items that draw a heading follow the
nearest scope, as the Pro items already do. Five things a minor couldn't change are put right: TypedText has one composition
prop, ColumnMapper's percent is the locale's, UsageMeters says "No limit set", a linked ScopeSwitcher or
ScopeBreadcrumb option calls onChange as every other Candor nav item does, and the nulls earlier minors let in are
recorded. CLI 3.4 runs the upgrade (npx candor-ui@3 update --to 6.0.0, then npx candor-ui@3 migrate 6.0.0). No
item is new; heading-level and heading-scope move to the free tier, so the kit has 420 items: 76 free and 389 in
Pro.

Upgrading from 5.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 6.0.0 --dry-run prints what 6.0 changes for the items in
    candor-lock.json, and writes nothing.
  • Update: npx candor-ui@3 update --to 6.0.0 updates every item, merging your changes into Candor's as update
    always has.
  • Migrate: npx candor-ui@3 migrate 6.0.0 runs each of 6.0's codemods that an entry on your installed items names,
    in this order: data-types, props, strings-keys, headings. Each lists what it couldn't change under "Left for
    you". --dry-run shows it first.
  • Finish by hand: make the changes the "Left for you" lines name and those marked "by hand" below.
  • Check: type-check (npx tsc --noEmit) and build, then run your tests.

A project still on 4.x goes to 5.0 first, with the same CLI: npx candor-ui@3 update --to 5.0.0, then
npx candor-ui@3 migrate 5.0.0 (Upgrading to 5.0), then the steps above. update --to 6.0.0 and migrate 6.0.0 on a
4.x project stop, change nothing and name them.

The codemods change your own files only: Candor's installed files come with the update, and in one you've changed,
what a codemod finds is listed. 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 usageMeters.noCap, since StringOverrides takes any key: it still compiles and
isn't read, so migrate strings-keys is what moves it.

Each entry below has its id in scripts/breaking.json (the same entries update --to 6.0.0 prints, and the Upgrading
to 6.0
page lists), what changed, and what to do:

  • actor (codemod data-types; work, digest, digest-email, change-list, decision-review, approval-request,
    approval-queue, review-canvas, environment-promotion; Pro): who did something is one type, Actor
    ({ kind: "agent"; agent } | { kind: "person"; name }), from lib/candor/work (KIT-346). DigestActor (Digest,
    DigestEmail) and ChangeListAuthor (ChangeList) were already that shape and are gone. ApprovalRequestData's
    requester (ApprovalRequest, ApprovalQueue, ReviewCanvas, the approvals-inbox template, approve-from-anywhere and
    approval-gated-change) was { name } or { agent }, and DecisionReviewItem's requester a string or an
    AgentIdentity; both take an Actor. Each item draws what 5.4 drew for the same who. migrate data-types moves
    each import of the old names to Actor from lib/candor/work and renames their uses (an import you aliased keeps
    its local name). In a file that imports from lib/candor/work, ApprovalRequest, ApprovalQueue or ReviewCanvas, it
    writes a literal requester: { name } or { agent } as { kind: "person", name } or { kind: "agent", agent },
    and lists every other requester there; in a file that imports DecisionReview, it lists each requester not written
    with a kind (a string or an AgentIdentity in 5.x). A requester built in a file that imports none of these isn't
    seen. The type check finds the rest; a check like "agent" in requester still narrows an Actor.
    The Premium blocks' stored requester column is unchanged; requesters stored in your own database are data, so map
    them to the kind shape where you read them. EnvironmentPromotion's requestedBy takes an Actor with at as
    well as { name, at } (KIT-358), so code that reads it through ComponentProps fails the type check at
    requestedBy.name. No codemod lists it: by hand, read the name by its shape
    ("agent" in requestedBy ? requestedBy.agent.name : requestedBy.name).
  • approval-optional (codemod data-types; work, approval-request, approval-queue, review-canvas,
    approvals-inbox; Pro and Premium): ApprovalRequestData's environment, production and artifactHash are
    optional, so an approval that isn't a deploy says nothing about an environment or a build (KIT-233). ApprovalRequest,
    ApprovalQueue and ReviewCanvas draw nothing for a missing one: no Where line, no hash, no production warning, and
    never "Non-production" for a production left out. A request with all three draws as in 5.4. onApprove and
    onReject on ApprovalRequest and ReviewCanvas take hash: string | undefined, undefined for a request without a
    hash. migrate data-types lists each read of the three fields in a file that imports ApprovalRequestData, and
    each onApprove or onReject on ApprovalRequest or ReviewCanvas whose handler's first parameter is typed string
    (written inline, or as a function or const in the same file), with its file and line (CLI-62). By hand: handle
    undefined there, and where a handler passes hash on as a string; with strictNullChecks the type check finds
    each.
  • typed-text-as (codemod props; typed-text; Pro): TypedText's as is gone; render (since 5.1) chooses the
    element (KIT-262). migrate props writes as="h2" as render={<h2 />}, keeping the other props, and lists an as
    that isn't an element's name (as={tag}: pass render={<Tag />}) and a TypedText with both as and render.
  • column-mapper-percent (codemod strings-keys; column-mapper; Pro): {percent} in columnMapper.percentSure
    is the locale's percent, sign and all ("85%", "85 %" in French), and the default is "{percent} sure" (KIT-263). An
    override that typed its own % would draw it twice. migrate strings-keys takes the % (and a space before it)
    out where it follows {percent}, and lists an override it can't read or with % anywhere else. Translations stored
    outside your source: take it out there.
  • usage-meters-no-limit (codemod strings-keys; usage-meters; Pro): UsageMeters says "No limit set"
    (usageMeters.noLimit) for a usage with no limit, as UsageRing does, where it said "No cap on your plan."
    (KIT-355). usageMeters.noCap is gone. migrate strings-keys moves an override of noCap to noLimit, and lists a
    table that has both, for you to keep one. Translate noLimit if you hadn't.
  • scope-link-click (codemod props; scope-switcher, scope-breadcrumb; Pro): a plain click (or Enter) on an
    option with href calls onChange instead of following the link, as every other Candor nav item does; a click that
    opens a new tab (a modifier key, or the middle button) follows the link and calls nothing (KIT-270). Choosing the
    option already in place does neither, where 5.x followed its link. An app that passes href with an onChange that
    only sets state stops going to the option's page. migrate props lists each ScopeSwitcher and ScopeBreadcrumb with
    onChange; by hand, navigate in onChange (with your router), or leave out href where the option isn't a page of
    its own.
  • locked-null (by hand; command-palette, scope-switcher, scope-breadcrumb, settings-layout, dashboard-tile,
    permission-mode, plan, tree, app-sidebar, nav-rail, tab-bar, know and the other items 5.1 to 5.3 widened; know and
    slider are free): 5.1 to 5.3 widened these to accept null, which a minor shouldn't have done for code that reads
    them, and 6.0 records it (KIT-281); know's locked map (ToolSetting.locked) accepts null too (KIT-294). 5.1:
    the locked field of PaletteItem, ScopeLevel, SettingsItem, DashboardTileView, PermissionModeOption and
    PlanAutonomyOption, the locked prop of 28 components, and Tree's onSelect's second parameter. 5.2: the
    …Locked props of RunEstimate, PlanGate, DataControls, SsoSetup, AgentScreen and Plan, AccountState's
    actions[].locked, the locked maps of ArtifactToolbar, RestoreDialog, ReviewLadder and NotificationPreferences,
    and Inbox's and ApprovalQueue's defaultActiveId. 5.3: AppSidebar's, NavRail's and TabBar's defaultActiveId. Code
    that reads one into a string | undefined of its own fails the type check, as does a wrapper that types Tree's
    onSelect as (id: string) => void through ComponentProps. No codemod: where you read one, write ?? undefined
    (null and left out both mean unlocked), and type a Tree onSelect wrapper (id: string, node: TreeNode) => void.
    Code that passes them is unchanged.
  • heading-default-free (codemod headings, which lists; heading-scope, heading-level, permission-prompt,
    page-state, message-content, message, accordion; free): HeadingScope and HeadingLevel are free (D109, D110).
    PermissionPrompt, PageState (and ListStateView), AccordionTrigger and the headings in a model's message
    (MessageContent, and Message through it) draw one level below the nearest HeadingScope, as the Pro items have
    since 5.0 (KIT-261, KIT-260); Candor's dialogs, sheets, drawers, settings sections and dashboard tiles set one.
    Outside a scope PermissionPrompt and PageState stay <h2> and a model's # stays <h3>; AccordionTrigger is <h2>
    there, where 5.x drew <h3> always. PageHeader is unchanged: its title stays <h1>, and it sets no scope, since it
    draws no page content. migrate headings changes nothing: it lists each use without headingLevel that draws at a
    new level, with the level it drew in 5.x (a model's message only inside a scope; Message, which takes no
    headingLevel, with a <HeadingScope> to wrap it in). By hand: pass headingLevel where a page or a test needs
    5.x's level (headingLevel={3} keeps AccordionTrigger's <h3>), or take the new outline.
  • thread-jump-safe-area (by hand; thread; free): Thread's Jump to latest pill sits above the phone's safe area
    (env(safe-area-inset-bottom)), so it isn't under the home indicator (KIT-349). Elsewhere the inset is 0 and nothing
    moves; a screenshot test on a phone that pins its place differs. To keep 5.x's place, set
    --cd-thread-jump-offset: calc(-1 * env(safe-area-inset-bottom, 0px)) where you style the thread.

Free tier

On the owner's calls (D197): no item is added, and none leaves Pro.

  • heading-level and heading-scope are free (D109, D110's alternative): HeadingLevel, HeadingScope,
    useHeadingLevel, useHeadingScope (the nearest scope's level, or undefined outside any) and belowLevel, in
    lib/candor/heading-level and lib/candor/heading-scope as before. The free
    items' headingLevel props are typed with HeadingLevel rather than the union written out. Breaking for the free
    items that follow a scope: heading-default-free above.
  • ListState is declared once, in the free status (KIT-232). page-state re-exports it, and the Pro data
    module's ListState and ChartState are the same type, so every name you import still works.

New exports

  • useStringsOverridden(name) (locale, free): (key) => boolean, whether the app set a key of a component's
    strings under name in LocaleProvider's strings, even to the default's own words, which comparing t(key) with
    the default can't tell (KIT-352). useStrings is unchanged.
  • isShown(element) (use-announcer, Pro): whether an element is on screen for a screen reader and a sighted person
    alike: not under hidden, inert or aria-hidden="true", and not display: none or visibility: hidden
    (KIT-353).
  • Actor (work, Pro): above. DigestActor and ChangeListAuthor are removed.

Components (Pro)

  • An app's words marked for bidi controls (KIT-350, KIT-357): EnvironmentBand (the account, the environment's
    name and detail), Inbox (the environment filter, an app's own kind), NotificationCenter (a notice's title, detail and
    action), CommandPalette (an item's label, detail and locked reason, a group's heading), SettingsLayout (the nav's
    labels, a locked reason, a section's title, and its description when it is a string), AccountState (its title, a
    detail given as a string, the actions' labels and the signed-in email), ServiceNotice (its title, detail and action)
    and SectionNav (its labels) draw them with neutralizeBidi, in a <bdi> where they sit among other words.
  • The rest of the kit's words marked for bidi controls (KIT-360): every free and Pro item was read for text the
    app or a model supplies that it drew without neutralizeBidi, and 182 Pro items now mark it: titles, headings,
    labels, names, emails, descriptions, details, badges, reasons (a locked reason among them) and the values Candor
    puts into its own sentences and aria-labels, in a <bdi> where they sit among other words. Among them ChartFrame
    (so every chart's title, legend, table and tooltip), DataTable, DetailsList, Board and Tree, the work items
    (ApprovalRequest, Plan, ChangeList, WorkflowEditor and 28 more), the shell's navigation (AppSidebar, NavRail, TabBar,
    PersonMenu), the team, admin and billing screens, CommentThread, Escalation, McpConnect, ModelKey and the report
    cards. An app's own note, label or sentence passed whole in place of one of Candor's (a strings override of one
    too), children, and an attribute passed whole are left as they were. A value Candor puts into one of its visible
    sentences sits in its own <bdi>, except in a list joined by the locale, an <option>, text read only by a screen
    reader, and email markup. Text the person edits and values that are copied or sent stay exactly as given (CopyField
    and DetailsList copy the value itself). Nothing to do.
  • DecisionBar, TurnRequest and ScreenGuide announce a change only while shown, through isShown (KIT-353).
    DecisionBar now stays quiet under aria-hidden and visibility: hidden too (it checked inert and hidden);
    ScreenGuide checked nothing, and a step that changes while it is hidden isn't said later.
  • FilterChips announces a filter that goes only while the chips are shown; once the last chip has gone, that is
    asked of the element they were in (KIT-356).
  • ChangeDiff: a click after a click asks again; only the click that follows a focus request in the same press is
    dropped, where two bare clicks counted as one (KIT-354).
  • SettingsLayout reads which of its strings the app set with useStringsOverridden, so one set to the default's
    own words counts as the app's (KIT-352).
  • EnvironmentPromotion's requestedBy takes an Actor with at as well as { name, at }, so an agent asking for
    a promotion is named as one; its own approval isn't counted, as a person's isn't (KIT-358). A wrapper that reads the
    prop through ComponentProps sees the wider type (actor, under Upgrading from 5.x).
  • ApprovalRequest says "What this changes has changed since it was requested…" (approvalRequest.staleUnnamed)
    for a stale request with no hash, and productionShort is the warning for a production request with no
    environment (KIT-233).

@candor-ui/react 6.0.0

  • HeadingScope, HeadingLevel, useHeadingLevel, useHeadingScope and belowLevel are in the package (D109,
    D110's alternative).
  • PermissionPrompt, PageState and ListStateView follow the nearest HeadingScope; outside one they draw <h2> as
    before (KIT-261). Breaking: heading-default-free.
  • MessageContent's model headings start one below the nearest HeadingScope; outside one they start at <h3> as
    before. Message passes no level, so its content follows the scope round it (KIT-261). Breaking, as above.
  • AccordionTrigger takes headingLevel; left out, it is one below the scope, else <h2> (5.x: always <h3>)
    (KIT-260). Breaking, as above.
  • Thread's Jump to latest sits above the phone's safe area (KIT-349). Breaking: thread-jump-safe-area.
  • know's ToolSetting.locked takes null per permission, unlocked as left out (KIT-294). Code reading a value into
    string | undefined adds ?? undefined (locked-null).
  • ListState is declared once, in status; page-state's is the same type (KIT-232). No change to make.
  • PageHeader's breadcrumb and tab labels, and PageState's action and secondary labels, are marked for bidi controls
    in a <bdi> (KIT-350).
  • The free items' words are marked for bidi controls too (KIT-360): Locked's reason (so every control locked through
    it), Slider's locked reason, Progress's label, StepList's steps, CopyField's label and value, DegradedPanel's reason
    and what's missing, PageHeader's title and description, PageState's title, detail and ListStateView's note and
    reason, AgentBadge's name and an app's own role noun, AiDisclosure, AttachmentPreview, CardRegistry, Citation,
    Composer (its menus' options, commands, reasons and scope), ContextMeter's segments, EntityChip, FoldedTurns'
    summary, Message, PermissionPrompt, PromptSuggestions, Reasoning, ThreadDivider's label and ToolCall. CopyField
    still copies the value as given. Nothing to do.
  • useStringsOverridden is exported from locale (KIT-352).
  • FoldedTurns' defaultOpen doc says when it holds its own state: given open, the app does; given defaultOpen
    alone, it starts there; given neither, it starts folded, as in 5.x (KIT-279). No change.
  • The package doesn't export Actor, DigestActor or ChangeListAuthor, which are Pro. Update it with your package
    manager.

New string keys

Translators: one key is new, one is removed, and two defaults change.

  • New: approvalRequest.staleUnnamed ("What this changes has changed since it was requested. The change is re-checked
    before it applies, and refused if it no longer matches."). Until you translate it, it says its English words.
  • Removed: usageMeters.noCap; usageMeters.noLimit ("No limit set") is drawn instead (usage-meters-no-limit).
  • Changed: columnMapper.percentSure is "{percent} sure", and {percent} brings its own sign
    (column-mapper-percent).

Some DOM your CSS may match

  • AccordionTrigger's header is an <h2> outside a HeadingScope, where it was an <h3>; inside one, one below it.
  • A <bdi> round an app's words where there was a <span> or bare text: PageHeader's crumbs and tabs, PageState's
    buttons, and the Pro items under Components above. In NotificationCenter, CommandPalette, SettingsLayout and Inbox's
    detail, the <bdi> takes the old span's classes. ServiceNotice's title is in a <bdi>. Nothing looks different.
  • KIT-360's <bdi>s, round an app's or a model's words that sit among other words or beside an icon, in the items
    the sweep changed (a string that is a whole block, cell, heading or flex item is marked with no <bdi>, so Locked's
    reason and AgentBadge's name keep their markup). Where a <span> held only the words, the <bdi> takes its
    classes. Email markup (EmailLayout, DigestEmail) gets none. Nothing looks different.
  • Thread's Jump to latest wrapper's bottom margin is
    mb-[calc(env(safe-area-inset-bottom,0px)+var(--cd-thread-jump-offset,0px))], where it was
    mb-[var(--cd-thread-jump-offset,0px)].

Docs

  • Upgrading to 6.0 (/upgrading-to-6 and its Markdown) lists every change above with its codemod (CLI-58).
  • The site's and the docs' install lines name the CLI's major, npx candor-ui@3 add: the docs MCP's install
    commands, the Get started steps and prompt, the patterns', themes' and screens' lines (CLI-56), and the setup guides,
    the hosted templates' pages, the apps' note, the theme builder's export, brief and sound panel, the home page's
    install answer and the licence key page (CLI-59).
  • An item's page lists a type it re-exports from another item, saying where it is declared: ListState on
    page-state's, HeadingLevel on heading's, the phrase and noun types on locale's (DOC-18).
  • PermissionPrompt's example shows the prompt in a Dialog following the Dialog's scope; heading-scope's example uses
    native tags, so a free reader can copy it (KIT-261).
  • --cd-thread-jump-offset's description says the pill sits above the safe area and how to keep 5.x's place.

CLI 3.4.0

  • New: migrate 6.0.0 runs data-types, props, strings-keys and headings. data-types (new) moves
    DigestActor and ChangeListAuthor to Actor in lib/candor/work, rewrites literal requesters, and lists the
    approval fields' reads and each onApprove or onReject handler on ApprovalRequest or ReviewCanvas whose first
    parameter is typed string (CLI-62); props writes TypedText's as as render and lists ScopeSwitcher's and ScopeBreadcrumb's
    onChange; strings-keys takes the % out of columnMapper.percentSure and moves usageMeters.noCap to
    noLimit; headings lists the free items whose level 6.0 changes. update --to 6.0.0 ends its list with a link to
    Upgrading to 6.0 (CLI-58).
  • New: update --to 6.0.0 (or later) and migrate 6.0.0 on a 4.x project stop, changing nothing, and name
    update --to 5.0.0, migrate 5.0.0, then update --to 6.0.0, migrate 6.0.0 (CLI-58, CLI-60).
  • Fixed: update took items that answered 404 at the target as removed when any breaking entry was there for
    them, an unrelated one too, and cleared them from candor-lock.json. It reads the registry's index of the target
    (/r/v/<version>/index.json) instead: an index it can't read, or one that lists an item it 404s on, stops the update
    with nothing changed (CLI-57).
  • Fixed: the docs MCP's install commands and the site's install lines name npx candor-ui@3 (CLI-56, CLI-59).

For maintainers

  • The registry serves each released version's index, public, at /r/v/<version>/index.json (vercel.json,
    api/registry.ts), and scripts/registry-server.mjs serves the same, this branch's from public/r/registry.json
    (CLI-57). It must be live before CLI 3.4.0 is published.
  • The registry's earlier versions are served from the snapshot store in Vercel Blob, and git no longer tracks
    snapshots/ (ARCH-34); the tests that read earlier releases fetch them from the store or skip (HK-17). Only the
    build's own version is static. While the store can't answer, an earlier version's files answer 503, and
    /r/versions.json answers with the version list the build read (build/versions.json, bundled with the function
    and not served), so candor-ui update and the docs MCP still start.
  • release:check's upgrade steps are a row per kit major (UPGRADE_STEPS): for 6.x, the 5.4 fixture
    (tests/upgrade/5.4/) in the normal, --base, --radix and --monorepo apps, and the 5.0 fixture to this
    checkout. The 4.5 fixture left release:check (4.5 to 6.0 crosses two majors) (CLI-58).
  • migrate headings' table has 6.0's rows; a model's message is listed only inside a scope (onlyInScope), and
    tests/kit/heading-outline.test.tsx runs the free items' rows.
  • ProgressRing's aria-valuetext already said the value past the limit; a test now says so (KIT-351).
  • The markup tests for the Actor items compare full server renders captured at 5.4 (*.5-4.json), with 6.0's
    <bdi> round a name or environment inside a sentence applied to the capture first; the rest is compared exactly.