Skip to content

Migrate from Base UI to ui-sdk - #12

Draft
aayushbtw wants to merge 155 commits into
mainfrom
ui-sdk
Draft

aayushbtw wants to merge 155 commits into
mainfrom
ui-sdk

Conversation

@aayushbtw

@aayushbtw aayushbtw commented Nov 14, 2026 •

Copy link
Copy Markdown
Owner

Why

Constella moves from Base UI to Vercel's ui-sdk. ui-sdk's agent bridge lets an AI agent read and drive every component through its own API. Base UI has nothing like it. This PR holds the whole port and lands once.

What's in it

  • Every Base UI part is ported to @ui-sdk/react 0.1.0-beta.13, one unit PR each into ui-sdk. @base-ui/react is gone from every package and the lockfile.
  • Calendar and Date Range Picker moved off react-day-picker. react-textarea-autosize is gone too.
  • Agent bridge: every part is named in snapshot(), and the AI and TanStack pages have Agent sections. vpr agent-audit gates unnamed and ambiguous names.
  • Readiness fixes (fix(site): one search trigger, so the dialog has a name (#114) #118 to fix(sidebar): onOpenChange alone stays uncontrolled; active rows set aria-current (#95) #127): the search dialog is named, CI runs the tests, the test pins assert exact gaps, live regions go through announce(), shortcuts go through useShortcut and pause behind modals, avatars, groups and tables have names, collapsed toasts are inert, and the sidebar state is fixed.
  • Status, rules and the full log are in docs/ui-sdk-migration.md. Why we're moving, and the readiness criteria, are under "UI SDK watch" in docs/ARCHITECTURE.md.

Verification

Whole-branch run at eb9526f, against main:

  • vpr check, vpr test (400 tests, run twice, no flakes), vpr build (98 pages) and vpr agent-audit (0 gated failures) all pass. CI is green.
  • The branch merges into main with no conflicts. The merged tree also passes check, test and build.
  • Visual sweep of 83 pages, light and dark: 688 of 746 demo shots are pixel-identical to main. The rest are intended changes, such as copy, new demos, and calendar day names. No blank stages and no new console errors.

Before merging

  • Three of the five "Ready when" rows in ARCHITECTURE.md are still unmet: ui-sdk is beta, shadcn ships no ui-sdk base, and the agent key is experimental. Landing over them is the owner's call.
  • The upstream issue drafts for vercel-labs/ui are written and wait on the owner's OK.
  • The agent bridge ships to production with the landing flip PR into ui-sdk; merge it first so this PR carries it.

Closes #32, closes #58, closes #67, closes #70, closes #94, closes #95, closes #105, closes #106, closes #107, closes #114.

@aayushbtw aayushbtw added the ui-sdk Base UI to ui-sdk migration label Nov 14, 2026
* feat(theme): declare the ui-sdk layer below StyleX's

* fix(theme): declare the ui-sdk layer in the app's global stylesheet

* docs(installation): clarify the ui-sdk layer sentence
* build(site): diff prerendered pages between two builds

* refactor(site): let git diff the normalized pages

* fix(site): escape backslashes and exit 2 on unreadable folders in diff-prerender
# Conflicts:
#	docs/ARCHITECTURE.md
…ops (#16)

* refactor(ui): render wrappers with ui-sdk's renderElement and mergeProps

* refactor(ui): own attributes first in AttachmentGroup, drop leftover use client
* test(ui): run ui-sdk tests in jsdom with StyleX

* test(ui): keep the site on StyleX unplugin 0.19.1
# Conflicts:
#	package.json
* feat(popover): port to ui-sdk

* refactor(popover): skip motion through useSkipMotion

* fix(input-group): ignore clicks from in-place popover content

* fix(model-picker): skip the close motion on pick, and test pick and focus

* docs(popover): mark #23 and #24 fixed, point comments at useSkipMotion
* docs(ui-sdk): record the 2026-11-21 review fixes and filed upstream issues

* docs(ui-sdk): #326 accepted the tradeoff, it didn't fix it
* test(data-table): a Shift-click that unchecks a checkbox unchecks the range

* fix(data-table): a Shift-click that unchecks a checkbox unchecks the range
Record unselectRange and its anchor reset after #137.
…ugh withStyles (#140)

* test(tanstack): a className from an outer part reaches the chart parts

Fails on this commit: the six parts drop it silently instead of throwing. The next commit moves them onto withStyles.

* refactor(tanstack): chart tooltip parts and Chart Indicator style through withStyles

Reran #134's codemod over components/tanstack: 6 sites in 2 files, 0
skipped. The Data Table parts and Chart's root take only explicit props,
so no outer className reaches them; ARCHITECTURE.md now says withStyles
covers parts that take element props.
…ng stays hidden (#141)

* test(markdown): footnote links open in a new tab and the Footnotes heading shows

Fails on purpose. The fix follows in the next commit.

* fix(markdown): footnote links stay in the tab and the Footnotes heading stays hidden

An in-page href (#…) gets no target or rel. The h2 mapping keeps GFM's sr-only as visuallyHidden.base instead of dropping it.
…a collapsible sub-menu (#142)

* refactor(sidebar): stable trigger name and tooltip aria refs

* fix(sidebar): rows keep their selectors when a trigger renders them

* docs(sidebar): collapsible menu, trigger name and row tooltips
apps/site and packages/ui now read @ui-sdk/* versions from one catalog entry. check-registry fails if either package pins its own.
* feat(message-scroller): build on ui-sdk stick-to-bottom

* fix(message-scroller): expose prepend and build the viewport on scroll area

* chore(message-scroller): deslop
* feat(questionnaire): build on ui-sdk radio and checkbox

* fix(questionnaire): lean on ui-sdk shortcuts, focus, field and progress

* fix(questionnaire): point focus styles at the new slots

* chore(questionnaire): deslop
…e, press real keys in tests (#145)

* test: press real keys where a test claims a keyboard source

Sidebar and Date Range Picker faked a keyboard source with withSource around fireEvent.click. pressKeys drives trusted keys through a throwaway mount from @ui-sdk/core/testing, since keys isn't exported. Collapsible gains the keyboard case its comment said needed a browser.

* refactor(site): pin the agent audit's name matching to the bridge

ui-sdk's agent bridge doesn't export its matcher, so the audit keeps a
copy. It moves to agent-names.ts, and a test checks it against a real
createAgent: the copy flags an address exactly when act refuses it
with "names N components". The copy now skips empty word strings, as
the bridge does. Collator folds like ø and ł stay a pinned test.fails.
…es (#147)

* test(prompt-input): Send and Stop share one agent ref while streaming

The submit button is one element whose name flips, so the agent's ref for Send becomes Stop mid-stream and a stale press stops the stream. These tests fail until Send and Stop are separate elements.

* fix(prompt-input): Send and Stop are separate buttons with stable names

While an answer streams, a Stop button replaces Send instead of Send renaming itself. Each keeps its own name and agent ref, so a stale Send ref can't stop a stream. Focus follows the swap when the leaving button held it, falling back to the textarea when Send comes back disabled. The icon still crossfades: SwapIcon takes a `from` and starts from it with `@starting-style`. A swap made from keyboard focus stays instant. New `stopLabel` names Stop.

* docs(prompt-input): Stop is its own button, named by stopLabel

Documents the separate Stop button, `stopLabel`, the focus handoff, and SwapIcon's `from`.

* fix(prompt-input): Send and Stop write their state as data-state

* docs(design): Prompt Input's Send and Stop swap restarts instead of reversing
* refactor(dialog): drop the backdrop's dead zIndex

ui-sdk shows the backdrop with showPopover(), so it sits in the top layer and z-index does nothing. layers.dialog had no other reader.

* fix(dropdown-menu): omit data-inset when inset is false

inset={false} wrote data-inset="false", which still matches the [data-inset] selector and indented the row.

* refactor(trace): keep the mounted flag in state, not a ref read in render

useArrival read live.current in a useState initializer, a ref read during render. Trace now sets a boolean after mount and passes it through Live. Steps in the first render still land without an entrance; later ones still play it, pinned by a new test.

* refactor(site): make dialog and side panel controllers per mount

The site search, the agent activity panel, the Command demo and its docs snippet created their controller at module scope, shared by every instance and alive across server requests. Each now comes from useState in the component that owns it, as ui-sdk's React examples do. ARCHITECTURE.md records the rule.

* refactor(button): share one CloseButton across Dialog, Sheet and Side Panel

Dialog, Sheet and Side Panel each drew the ghost icon-sm X by hand. CloseButton in button.tsx now draws it, and each surface renders its own Close part through it. Placement is unchanged. Side Panel's close gains the side-panel-close-button slot. Toast keeps its own smaller, muted close.

* refactor(settings-dialog): compose as root, trigger and content like Dialog

SettingsDialog put its children inside the popup, so a trigger had nowhere to go and the demo opened it with a separate Button and state. SettingsDialog is now the root, SettingsDialogTrigger is DialogTrigger, and SettingsDialogContent draws the popup and its close button.

* refactor(ui): mark "use client" only where a file runs client code

Twelve wrappers carried the directive with no hook, handler, browser API or client value read of their own; ui-sdk's parts carry their own. swap-icon gains it, since it calls createContext and use. A test now fails when a file without the directive calls a hook or reads a value from a "use client" file.

* fix(site): side panel, hover card and dropdown menu demos create their controller per mount
* feat(combobox): mark the typed text in results

ComboboxItemText and CommandItemText wrap ui-sdk's item text parts: the matched text is textPrimary in medium weight and the rest of the label steps back to textSecondary. Demos, docs and tests for Combobox, Command and Model Picker use them.

* chore(combobox): deslop
* feat(select): search inside the list

* chore(select): deslop
* feat(trace): announce when a step finishes or fails

* fix(trace): don't repeat failed in error announcements

* chore(trace): deslop
* feat(prompt-input): recall earlier prompts with ArrowUp

* fix(prompt-input): record only sent prompts

* chore(prompt-input): deslop

* fix(prompt-input): record a prompt when the send goes through

PromptInput now skips a submit while its PromptInputSubmit is disabled or not ready, and records the prompt at submit time when it goes through. Drops the clear-after-submit proxy, which a user's own Backspace could trip.

* fix(prompt-input): reset history on every send
* docs(ui-sdk): record the UX audit fixes

* docs(ui-sdk): use the legend's merged status

The tracker used status words outside its own legend. This switches them to merged, marks #153 merged, and fixes the intro paths.
* refactor(ui): share the popup surface as popupSurface

Popover, Hover Card, Select, Combobox, Dropdown Menu, Prompt Input's menu and Model Picker's command each wrote out the raised fill, lg corners and lg shadow. popupSurface.base in styles.ts now holds them, beside popupReset, and each popup applies it before its own styles.

* docs(architecture): popupSurface bullet matches Model Picker
Moves the 11 resolved open follow-ups into the Review fixes table with their PRs (#137-#147, #157), adds the 9 follow-ups those PRs found, marks the swap-icon cleanup done by #143, and logs the batch.
…its own footnote (#159)

@tanstack/markdown 1.0.0 hardcodes user-content-fn-*, user-content-fnref-*
and footnote-label, so two answers using [^1] on one page share ids and
every ref and backref jumps into the first. Each Markdown root now
prefixes those ids with useId, which matches between server and client.
The docs demo gains a footnote so the page shows two blocks using [^1].
* fix(ui): close five primitive a11y and styling gaps

Slider thumb rings on keyboard focus. Command input keeps the input-group slot, so it rings. Trace step trigger shows its chevron on keyboard focus with a hover pointer. Data Table sets aria-sort on sorted headers. Swap Text's sx overrides Torph's root rule.

Fixes #57, #69, #39, #82, #10

* revert(trace): #39 was already fixed

* docs(command): the search field keeps the input group's ring and padding
…SkipMotion (#163)

* test(motion): Alert Dialog and Side Panel rows; Side Panel's instant open paints offstage

Side Panel's entering style has no skip-motion guard (#64), so its row fails until the fix.

* fix(dialog): keyboard opens and Esc closes skip motion through createSkipMotion

Dialog, Alert Dialog and Side Panel roots never tracked how they opened, so a
keyboard open or Esc close faded and scaled like a pointer one (#47, #64).

createSkipMotion gives each popup family one root wrapper and one part hook.
Dialog, Alert Dialog, Side Panel and Command Dialog share the dialog instance;
Select, Combobox, Dropdown Menu and Popover drop their copied context. A
finished close clears the skip, so a controlled reopen by pointer animates.
Side Panel's motion moves into popupMotion with a skip guard.

Sheet still slides: ui-sdk Drawer has no instant open or close.

Refs #47, #64
…s stop (#97) (#164)

* test(site): demo intervals stop at their end state (#97)

* fix(site): Progress, Markdown and Trace demos clear their interval at the end, and Replay starts a new one (#97)

* fix(site): theme builder picks its preset with Toggle Group, not pressed-looking Buttons

* fix(site): scroll area's both-axes demo scrolls a tile grid instead of a hand-styled table

* fix(site): mobile nav group rows are ui-sdk Buttons

* fix(site): hover card mention styles through sx (#52)

* fix(site): sidebar account row is named by its full text, shadcn Pro

* feat(input-group): InputGroupToggle, a Toggle at the addon's button inset; the favorite demo uses it

* fix(site): button group demos use InputGroupToggle for voice mode and ui-sdk's Label for the URL prefix
…uttons named by language (#161)

* fix(site): search results are router links, so a modified click opens a new tab

Each result renders as a TanStack Router Link. Enter clicks the anchor and
navigates once; a modified click leaves the page to the browser and keeps
search open; an agent's run, which has no click, navigates in onSelect.
The result arrow carries data-rtl-flip.

Fixes #71, fixes #72.

* fix(site): each prose copy button is named by its block's language

parsePage turns every fence into an md-code component labelled at build
time: "Copy code, <lang>", numbered from 1 when a language repeats on the
page. A test runs every content page through ambiguousIn.

* docs(command): docs search results are router links
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment