hoja-cli 0.21.4__tar.gz

hoja_cli-0.21.4/.agents/skills/migrate-radix-to-base/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: migrate-radix-to-base
+description: Migrates React projects and components from Radix UI to Base UI. Use when asked to migrate from radix, move to base-ui, convert radix primitives, or switch a shadcn project's base library. Handles single components ("migrate accordion") and whole projects.
+---
+
+# Radix UI -> Base UI migration
+
+You migrate shadcn wrappers, hand-rolled radix compositions, and their
+consumers to `@base-ui/react`, keeping the project buildable at every step.
+Be precise; never guess a mapping. When a prop or part is not in these
+reference files, check `node_modules/@base-ui/react/**/*.d.ts` before
+transforming, and record gaps in the report.
+
+## Preflight (always)
+
+1. `npx shadcn@latest info --json` (or the project's runner): gives the
+   current base, STYLE (e.g. `radix-lyra`), tailwind version, aliases,
+   installed components, and package manager. Trust it over inference.
+2. Detect the package manager (packageManager field / lockfile:
+   pnpm-lock.yaml, bun.lock, yarn.lock, package-lock.json) and use IT for
+   every install. Never leave a stale lockfile.
+3. Require a clean git tree; work on a branch; one commit per component.
+4. Baseline check BEFORE touching dependencies: run the project's
+   typecheck/build so pre-existing failures are never attributed to you.
+5. Install `@base-ui/react` alongside radix. Radix packages are removed only
+   after the LAST component is migrated (both coexist fine).
+
+## Strategy: golden pair first, transformation engine second
+
+- **Golden pair via the CLI (preferred).** If the project is shadcn with a
+  known style (`radix-<style>`), the shadcn CLI itself is the golden-pair
+  executor:
+  1. Classify each ui wrapper FIRST: diff the user's file against its stock
+     origin, using the components.json style VERBATIM in the URL
+     (`https://ui.shadcn.com/r/styles/<style>/<component>.json`,
+     files[0].content). This works for prefixed styles (radix-nova) AND
+     legacy unprefixed ones (new-york, new-york-v4, default), which are all
+     still served.
+  2. WHOLE-PROJECT mode: flip `components.json` style `radix-<style>` ->
+     `base-<style>` now. PROGRESSIVE mode: do NOT flip yet (the project is
+     still mostly radix; the flip happens once, after the last component);
+     fetch base variants directly by URL instead
+     (`https://ui.shadcn.com/r/styles/base-<style>/<component>.json`).
+  3. PRISTINE wrappers, whole-project mode: `shadcn add <component>
+     --overwrite` delivers the base variant with the project's exact
+     icon/font/preset resolution. Never bulk `--all --overwrite`; go
+     component by component, or you drown in unrelated registry version
+     drift. PROGRESSIVE mode: never use `--overwrite` (it destroys the
+     original that consumers still import); write the fetched base variant
+     content to `<component>-base.tsx` instead.
+  4. CUSTOMIZED wrappers: fetch the base variant and replay the user's diff
+     onto it (their customizations must SURVIVE; `--overwrite` would destroy
+     them). Mechanical implementation that works at scale:
+     `git merge-file user.tsx radix-golden.tsx base-golden.tsx` (three-way
+     merge, radix golden as ancestor) auto-resolves most files; hand-resolve
+     conflicts with the reference tables.
+  5. MANDATORY leftover sweep on EVERY golden-pair file, including ones that
+     merged "clean": `grep -n "radix-ui\|@radix-ui\|IconPlaceholder"` per
+     file. The registry sometimes reorders functions between variants, which
+     makes three-way merges report zero conflicts while leaving stale radix
+     hunks in place. A clean merge is NOT proof of a clean file.
+  This is more reliable than reconstructing transforms; use it whenever the
+  pair exists. Consumer/app code has no CLI mechanism: always hand-migrate it
+  against `consumer-props.md`.
+- **Legacy styles (new-york, new-york-v4, default): classification only, no
+  replay.** These have no base counterpart (there is no base-new-york), and
+  retargeting onto a base-<style> variant would restyle the user's app. Use
+  the radix golden ONLY to detect customizations, then run the transformation
+  engine on the user's OWN file: rewire primitives, keep their exact classes,
+  apply class-mapping renames. Their look stays theirs. At the end of a
+  legacy whole-project migration, FLAG (do not fix): the style name still
+  reads as radix to the CLI, so future `shadcn add` will deliver radix
+  variants; the user decides whether to switch style or add manually.
+- **Transformation engine (fallback).** Hand-rolled radix code, non-shadcn
+  projects, unknown styles: transform using `universal-patterns.md` (imports
+  in BOTH forms: `radix-ui` and `@radix-ui/react-*`; asChild->render with the
+  worked example; Portal>Positioner>Popup; the positioner FORWARD rule; part
+  renames), the per-family props tables (`overlays.md`, `menus.md`,
+  `form-controls.md`, `disclosure.md`, `display-misc.md`), `class-mapping.md`
+  for data-attribute/CSS-var rewrites, and `wrapper-shapes.md` for exact
+  target shapes (tooltip arrow, SubContent defaults, select anatomy).
+
+## Modes
+
+**Progressive (default).** "Migrate accordion" = one component, strangler-fig:
+1. Detect in-progress state first: an existing `<component>-base.tsx`,
+   consumers split between old/new imports. The files ARE the state; resume,
+   never restart.
+2. If the component imports other ui wrappers still on radix (select ->
+   button), STOP and recommend migrating those first, bottom-up.
+3. Write the migrated version to `<component>-base.tsx` (original untouched;
+   golden-pair content fetched by URL, or transformed by hand, per the
+   strategy above); typecheck. Repoint consumers ONE AT A TIME (imports + the
+   call-site props in `consumer-props.md`); typecheck each. When no consumer
+   imports the original: delete it, rename `-base` -> original, flip imports
+   back, final check, commit. When the LAST radix wrapper in the project is
+   finalized, flip `components.json` to `base-<style>` and remove radix deps.
+
+**Whole project** (only when explicitly asked): same per-component work in
+dependency order (leaf/shared wrappers like button and label first). After
+wrappers, sweep ALL app code against `consumer-props.md` — the call-site
+break surface is much larger than asChild. Then remove radix deps, install,
+full build.
+
+## Hard rules
+
+- NEVER touch non-radix libraries or their wrappers: cmdk (command), vaul
+  (drawer), sonner, input-otp, react-day-picker (calendar), recharts (chart).
+  Report them as intentionally untouched.
+- No Base UI counterpart: AspectRatio -> CSS aspect-ratio div; Label ->
+  native `<label>`; VisuallyHidden -> `sr-only`; Direction -> Direction
+  Provider (`direction` prop, not `dir`). Popover Anchor and NavigationMenu
+  Indicator have no equivalent: inert passthrough + flag.
+- `button.tsx` migrates to the REAL `@base-ui/react/button` primitive, never
+  a hand-rolled useRender wrapper.
+- Behavior deltas are FLAGGED, never silently patched (tabs manual
+  activation, menu items not closing on click, nav-menu 50ms delay). The
+  target is idiomatic Base UI matching the shadcn base registry.
+- Honest reporting: skipped/reverted files are listed as flagged, never as
+  migrated. Pre-existing failures are named as pre-existing.
+
+## Verify and report
+
+Typecheck per file, build per batch, full build at the end vs the baseline.
+
+Reports live in a `.migration/` directory at the project root, ONE FILE PER
+COMPONENT: `.migration/<component>.md` (e.g. `.migration/accordion.md`).
+Rules:
+- Each run writes (or fully overwrites) the file for each component it
+  migrated. Re-running a component replaces its report; never touch other
+  components' files.
+- A multi-component run ("migrate alert-dialog and dropdown-menu") writes one
+  file per component, each self-contained; shared consumer-sweep notes are
+  repeated in every affected file.
+- Whole-project mode writes the per-component files plus
+  `.migration/project.md` (dependency swap, app-code sweep summary, final
+  build result).
+- There is NO index file. Migration status is derived from disk, not
+  maintained: scan the project's ui directory (the `ui` alias from shadcn
+  info, e.g. components/ui or src/components/ui) for remaining radix imports
+  when asked "what's left". End every run's summary with that derived count
+  ("N wrappers remain on Radix").
+
+Each `.migration/<component>.md` uses EXACTLY this structure (it is
+documented publicly; reports must match it):
+
+```md
+# <component>
+
+<date, strategy used (golden pair via CLI / merge / engine), one-line verdict>
+
+## Changed
+
+<every file touched, with what changed and why; include file:line for
+anything notable. Confirm the leftover scan is clean:
+grep -n "radix-ui\|@radix-ui" on this component's files>
+
+## Left alone
+
+<files that look related but were intentionally not touched, with the reason
+(cmdk/vaul/sonner are not radix; unrelated drift; etc.)>
+
+## Behavior changes
+
+<differences that compile fine but act differently; flagged, never patched
+(tabs activation, menu close-on-click, delays...). Empty section if none>
+
+## Verify by hand
+
+<short manual QA checklist for this primitive family: focus return on
+dialogs, keyboard nav + typeahead on menus/select, tooltip delay feel,
+slider commit events. Concrete steps, one minute of clicking>
+```

hoja_cli-0.21.4/.agents/skills/migrate-radix-to-base/class-mapping.md

@@ -0,0 +1,62 @@
+# Class-string rewrites (layer 2)
+
+Apply these across ALL class strings (className, cva definitions, cn calls),
+including app code. They are safe, mechanical rewrites.
+
+## Data-attribute selectors
+
+| Radix pattern | Base UI pattern |
+|---|---|
+| `data-[state=open]:` | `data-open:` |
+| `data-[state=closed]:` | `data-closed:` |
+| `data-[state=checked]:` | `data-checked:` |
+| `data-[state=unchecked]:` | `data-unchecked:` |
+| `data-[state=active]:` (tabs) | `data-active:` |
+| `data-[state=on]:` (toggle) | `data-pressed:` |
+| `data-[highlighted]:` | `data-highlighted:` (unchanged) |
+| `data-[disabled]:` | `data-disabled:` (unchanged) |
+| `data-[side=...]:` | `data-[side=...]:` (unchanged, still parameterized) |
+| `group-data-[state=open]` / `peer-data-[state=open]` | `group-data-open` / `peer-data-open` |
+| submenu trigger open marker `data-[state=open]:` | `data-popup-open:` |
+
+## Animation idiom
+
+Radix (tw-animate/keyframes):
+`data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=closed]:animate-out data-[state=closed]:fade-out-0`
+
+Base UI (transition + starting/ending styles):
+`transition-[opacity,transform] data-starting-style:opacity-0 data-ending-style:opacity-0` (plus translate/scale equivalents).
+
+Do not translate animate-in/out utilities 1:1; restate the intent with
+`data-starting-style:` / `data-ending-style:` transitions. When the original
+uses per-side slide classes, keep the `data-[side=...]` or
+`data-[swipe-direction=...]` parameterization.
+
+## CSS variables
+
+| Radix var | Base UI var |
+|---|---|
+| `--radix-<comp>-content-transform-origin` | `--transform-origin` |
+| `--radix-<comp>-content-available-height` | `--available-height` |
+| `--radix-<comp>-content-available-width` | `--available-width` |
+| `--radix-<comp>-trigger-width` | `--anchor-width` |
+| `--radix-<comp>-trigger-height` | `--anchor-height` |
+| `--radix-accordion-content-height` | `--accordion-panel-height` |
+| `--radix-collapsible-content-height` | `--collapsible-panel-height` |
+| `--radix-navigation-menu-viewport-height/width` | `--positioner-height` / `--positioner-width` |
+
+## Element changes kill pseudo-class variants
+
+When a part's rendered element changes from a form control to a generic
+element (checkbox/switch/radio Roots render `<span>` in Base UI), `disabled:`
+and `:disabled` Tailwind variants become dead code. Replace them with
+`data-disabled:` equivalents. (Note: the shadcn base registry's checkbox
+still carries the dead `disabled:*` classes; treat that as an upstream quirk,
+not a pattern to copy.)
+
+## Disabled-state hooks
+
+Some Base UI triggers surface disabled state as `aria-disabled` rather than
+the `disabled` attribute (accordion trigger, tabs tab). Where the radix code
+used `disabled:opacity-50`, add or substitute `aria-disabled:opacity-50`
+according to the wrapper's reference file.

hoja_cli-0.21.4/.agents/skills/migrate-radix-to-base/consumer-props.md

@@ -0,0 +1,58 @@
+# Consumer-side prop changes (call sites, not wrappers)
+
+The shadcn wrapper NAMES survive a radix -> base-ui migration, but these props
+change or disappear at CALL SITES in app code. Sweep every consumer for this
+list after migrating the wrappers. All entries verified against
+@base-ui/react@1.6.0 type definitions during real migrations; when in doubt,
+check node_modules/@base-ui/react/**/*.d.ts, never guess.
+
+## Universal
+
+| Radix | Base UI | Call-site action |
+|---|---|---|
+| `asChild` (any wrapper) | `render` prop | `<Trigger asChild><Button/></Trigger>` -> `<Trigger render={<Button/>}>...` |
+
+## Per component
+
+| Component | Radix prop | Base UI fate | Call-site action |
+|---|---|---|---|
+| Accordion | `type="single"\|"multiple"` + `collapsible` | dropped; `value`/`defaultValue` are ALWAYS arrays; multiple-open via `multiple` | `type="single" collapsible` -> remove both; wrap values in arrays; `type="multiple"` -> `multiple` |
+| Tabs | `activationMode="manual"` | dropped; Base UI defaults to MANUAL activation | remove prop; near-equivalent opt-in is `Tabs.List activateOnFocus` (behavior delta: flag, do not auto-add) |
+| Select | `position="popper"\|"item-aligned"` | `alignItemWithTrigger` boolean (on Positioner; wrappers expose it) | `position="popper"` -> `alignItemWithTrigger={false}`; `item-aligned` -> `alignItemWithTrigger` (default) |
+| TooltipProvider | `delayDuration`, `skipDelayDuration` | `delay`; skip-delay concept dropped | rename / remove |
+| Tooltip | `disableHoverableContent` | NO equivalent | remove; FLAG the behavior change in the report |
+| Avatar.Image | `delayMs` | `delay` | rename |
+| ScrollArea | `type="always"\|"scroll"\|...` | dropped | remove |
+| Separator | `decorative` | dropped | remove |
+| Checkbox | `checked="indeterminate"` | `indeterminate` is a SEPARATE boolean prop | `checked="indeterminate"` -> `indeterminate` + boolean `checked` |
+| Slider | `onValueChange(value)` | signature gains event details; also `inverted` REMOVED | check handler arity; remove `inverted` (flag vertical-inverted usage) |
+| Select | `onValueChange(value: string)` | widens to `(value: Value \| null, eventDetails)` | `useState<string>` + `onValueChange={setState}` breaks: widen state to `string \| null` or wrap the setter |
+| Slider | `onValueCommit` | `onValueCommitted` | rename |
+| ToggleGroup | `type="single"\|"multiple"` | `multiple` boolean; value shape arrays | same treatment as Accordion |
+| ToggleGroup / Toolbar | `rovingFocus={false}` | dropped (roving focus always on); `loop` -> `loopFocus` | remove / rename |
+| Menubar | `value`/`onValueChange` (active menu) | dropped; control per Menu.Root `open` | restructure if used; usually unused |
+| Menubar | `loop` | `loopFocus` | rename |
+| ContextMenu.Root | `modal` | REMOVED | remove |
+| ContextMenu.Trigger | `disabled` | REMOVED | remove; gate the trigger yourself |
+| DropdownMenu/ContextMenu items | (Radix closed menu on select) | `closeOnClick` defaults FALSE on CheckboxItem/RadioItem | behavior delta: flag; add `closeOnClick` only if the user asks |
+| NavigationMenu | `delayDuration`(200), `skipDelayDuration`, `viewport` | `delay`(50) + `closeDelay`; viewport prop gone (Positioner handles it) | rename/remove; flag the 200->50 hover-delay feel change |
+| Popover / HoverCard | `openDelay`/`closeDelay` on Root | move to TRIGGER as `delay`/`closeDelay` | relocate props Root -> Trigger |
+| Dialog / AlertDialog | `onOpenAutoFocus` | `initialFocus` (element/ref-based, not event-based) | restructure: pass target instead of preventDefault handler |
+| Dialog / AlertDialog | `onCloseAutoFocus` | `finalFocus` | same restructure |
+| Dialog family | `onEscapeKeyDown`, `onPointerDownOutside`, `onInteractOutside` | consolidated; see the overlays reference for exact per-part signatures | consult overlays.md; do not guess |
+| DirectionProvider | `dir` | `direction` | rename |
+
+## Callback signature rule
+
+Base UI callbacks commonly gain an event-details argument:
+`onOpenChange(open, eventDetails)`, `onValueChange(value, eventDetails)`.
+Passing an existing single-arg handler stays type-safe; handlers that USED
+Radix's event parameter need review against the family reference file.
+
+## Sweep procedure
+
+1. grep app code (outside components/ui) for each LHS token above plus
+   `asChild`.
+2. Fix call sites file by file; typecheck after each file.
+3. Anything on this list marked FLAG goes into the migration report as a
+   behavior delta, never silently patched.

hoja_cli-0.21.4/.agents/skills/migrate-radix-to-base/disclosure.md

@@ -0,0 +1,353 @@
+# Radix → Base UI props mapping: disclosure + toggle family
+
+Scope: accordion, collapsible, tabs, toggle, toggle-group, toolbar.
+Sources: radix-ui.com primitives docs + base-ui.com `.md` docs, cross-checked against installed `@base-ui/react@1.6.0` `.d.ts` files (the published docs page for accordion lagged; types are authoritative here).
+
+Conventions that apply to every component below:
+
+- `asChild` (boolean, default `false`) → `render` (`ReactElement | (props: HTMLProps, state) => ReactElement`). Signature changed: instead of a lone child element, pass the element to `render`; Base UI merges props onto it. Button-rendering parts additionally accept `nativeButton` (default `true`), set it to `false` when `render` produces a non-`<button>` element.
+- Base UI `className` and `style` also accept a `(state) => value` function form.
+- Radix `data-[state=...]` value attributes become Base UI presence attributes (`data-open`, `data-closed`, `data-pressed`, `data-active`).
+- Base UI change callbacks all gained a second `eventDetails` argument (`{ reason, event, cancel(), ... }`).
+- Radix `dir` props are dropped everywhere; Base UI reads direction from the DOM `dir` attribute / `DirectionProvider`.
+
+---
+
+# accordion
+
+Part mapping: `Root → Root`, `Item → Item`, `Header → Header`, `Trigger → Trigger`, `Content → Panel`.
+
+## Accordion.Root → Accordion.Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. Pass element to `render` instead of wrapping a child. |
+| `type` (required) | `"single" \| "multiple"` / — | `multiple` | Signature changed. `type="multiple"` → `multiple` (boolean, default `false`); `type="single"` → omit. |
+| `value` | `string` (single) or `string[]` (multiple) / — | `value` | Signature changed. Base UI is ALWAYS an array (`Value[]`, `Value = any`), even in single mode: `value="a"` → `value={["a"]}`. |
+| `defaultValue` | `string` or `string[]` / — | `defaultValue` | Same array caveat as `value`. |
+| `onValueChange` | `(value: string) => void` or `(value: string[]) => void` / — | `onValueChange` | Signature changed: `(value: Value[], eventDetails: Accordion.Root.ChangeEventDetails) => void`. Always receives an array; unwrap `value[0]` for single mode. |
+| `collapsible` | `boolean` / `false` | — dropped | Base UI single mode is always collapsible. To forbid closing the last open item (Radix `collapsible={false}` default), control `value` and ignore updates where the array is empty, or call `eventDetails.cancel()` when `value.length === 0`. |
+| `disabled` | `boolean` / `false` | `disabled` (default `false`) | Same. |
+| `dir` | `"ltr" \| "rtl"` / `"ltr"` | — dropped | Use DOM `dir` attribute / `DirectionProvider`. |
+| `orientation` | `"vertical" \| "horizontal"` / `"vertical"` | — dropped (prop exists but deprecated no-op) | Base UI removed roving arrow-key focus per the APG guidance update, so `orientation` (and `loopFocus`) no longer affect keyboard behavior. Do not carry it over. |
+
+## Accordion.Item → Accordion.Item
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `value` (required) | `string` / — | `value` | Renamed constraint: Base UI `value` is `any` and OPTIONAL (auto-generated from index when omitted). Keep passing strings for parity. |
+| `disabled` | `boolean` / `false` | `disabled` (default `false`) | Same. |
+
+## Accordion.Header → Accordion.Header
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. Both render `<h3>` by default. |
+
+## Accordion.Trigger → Accordion.Trigger
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` (+ `nativeButton`, default `true`) | Signature changed. |
+
+## Accordion.Content → Accordion.Panel
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `forceMount` | `true \| undefined` / — | `keepMounted` (boolean, default `false`) | Renamed. `forceMount` → `keepMounted` (closed panel stays in DOM, hidden). Also available on `Root` to apply to all panels. |
+
+## Base UI only props worth knowing
+
+- `Root.hiddenUntilFound` / `Panel.hiddenUntilFound` (default `false`): uses `hidden="until-found"` so browser find-in-page can expand panels; overrides `keepMounted`. No Radix equivalent.
+- `Root.keepMounted`: root-level version of the per-panel prop.
+- `Item.onOpenChange`: `(open: boolean, eventDetails: Accordion.Item.ChangeEventDetails) => void`, per-item open callback. No Radix equivalent.
+- `Trigger.nativeButton` (default `true`).
+- `className` / `style` state-function forms on every part.
+
+## Data-attribute mapping
+
+| Radix | Base UI | Note |
+|---|---|---|
+| `Item/Header/Content [data-state="open" \| "closed"]` | `Item`, `Header`: `data-open` (presence); `Panel`: `data-open` (presence) | No `data-closed` on accordion parts (unlike collapsible); style closed state as the absence of `data-open`. |
+| `Trigger [data-state="open"]` | `Trigger [data-panel-open]` | Renamed. Trigger specifically uses `data-panel-open`, NOT `data-open`. |
+| `[data-disabled]` | `[data-disabled]` | Same (Root, Item, Header, Trigger, Panel). |
+| `[data-orientation]` (all parts) | `Root`, `Panel`: `data-orientation` | Deprecated along with orientation; avoid relying on it. |
+| — | `Item/Header/Panel [data-index]` | Base UI only: numeric item index. |
+| — | `Panel [data-starting-style]`, `[data-ending-style]` | Base UI only: CSS-transition animation hooks (replace Radix mount/unmount animation pattern). |
+
+## CSS var mapping
+
+| Radix | Base UI |
+|---|---|
+| `--radix-accordion-content-height` | `--accordion-panel-height` |
+| `--radix-accordion-content-width` | `--accordion-panel-width` |
+
+---
+
+# collapsible
+
+Part mapping: `Root → Root`, `Trigger → Trigger`, `Content → Panel`.
+
+## Collapsible.Root → Collapsible.Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `defaultOpen` | `boolean` / — | `defaultOpen` (default `false`) | Same. |
+| `open` | `boolean` / — | `open` | Same. |
+| `onOpenChange` | `(open: boolean) => void` / — | `onOpenChange` | Signature changed: `(open: boolean, eventDetails: Collapsible.Root.ChangeEventDetails) => void`. |
+| `disabled` | `boolean` / — | `disabled` (default `false`) | Same. |
+
+## Collapsible.Trigger → Collapsible.Trigger
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` (+ `nativeButton`, default `true`) | Signature changed. |
+
+## Collapsible.Content → Collapsible.Panel
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `forceMount` | `true \| undefined` / — | `keepMounted` (boolean, default `false`) | Renamed. |
+
+## Base UI only props worth knowing
+
+- `Panel.hiddenUntilFound` (default `false`): find-in-page support via `hidden="until-found"`; overrides `keepMounted`.
+- `Trigger.nativeButton` (default `true`).
+- `className` / `style` state-function forms.
+
+## Data-attribute mapping
+
+| Radix | Base UI | Note |
+|---|---|---|
+| `Root/Content [data-state="open" \| "closed"]` | `Panel [data-open]` / `[data-closed]` | Renamed to presence attributes. Base UI Root renders a plain `<div>`; state attrs live on Panel/Trigger. |
+| `Trigger [data-state="open"]` | `Trigger [data-panel-open]` | Renamed; trigger-specific name. |
+| `[data-disabled]` | — (not emitted on collapsible parts) | Gate styles on the `disabled` prop / `:disabled` on the trigger instead. |
+| — | `Panel [data-starting-style]`, `[data-ending-style]` | Base UI only: animation hooks. |
+
+## CSS var mapping
+
+| Radix | Base UI |
+|---|---|
+| `--radix-collapsible-content-height` | `--collapsible-panel-height` |
+| `--radix-collapsible-content-width` | `--collapsible-panel-width` |
+
+---
+
+# tabs
+
+Part mapping: `Root → Root`, `List → List`, `Trigger → Tab`, `Content → Panel`. Base UI adds an `Indicator` part with no Radix equivalent.
+
+## Tabs.Root → Tabs.Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `defaultValue` | `string` / — | `defaultValue` | Signature changed: Base UI value type is `Tabs.Tab.Value` (`any`), default `0` (first tab active by default; Radix has no default active tab). Strings still work unchanged. |
+| `value` | `string` / — | `value` | Same shape for string values; type widened to `any`. |
+| `onValueChange` | `(value: string) => void` / — | `onValueChange` | Signature changed: `(value: Tabs.Tab.Value, eventDetails: Tabs.Root.ChangeEventDetails) => void`. |
+| `orientation` | `"horizontal" \| "vertical"` / `"horizontal"` | `orientation` (default `'horizontal'`) | Same. |
+| `dir` | `"ltr" \| "rtl"` / — | — dropped | Use DOM `dir` / `DirectionProvider`. |
+| `activationMode` | `"automatic" \| "manual"` / `"automatic"` | moved + renamed: `List.activateOnFocus` (boolean, default `false`) | Moved from Root to List and inverted DEFAULT: Radix defaults to automatic, Base UI 1.6.0 defaults to `false` (manual). To preserve Radix default behavior set `<Tabs.List activateOnFocus>`; `activationMode="manual"` → omit. |
+
+## Tabs.List → Tabs.List
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `loop` | `boolean` / `true` | `loopFocus` (default `true`) | Renamed. |
+
+## Tabs.Trigger → Tabs.Tab
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` (+ `nativeButton`, default `true`) | Signature changed. |
+| `value` (required) | `string` / — | `value` (required) | Type widened to `Tabs.Tab.Value` (`any`); strings unchanged. |
+| `disabled` | `boolean` / `false` | `disabled` | Same. |
+
+## Tabs.Content → Tabs.Panel
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `value` (required) | `string` / — | `value` (required) | Type widened; strings unchanged. |
+| `forceMount` | `true \| undefined` / — | `keepMounted` (boolean, default `false`) | Renamed. Hidden panels stay in DOM with `data-hidden`. |
+
+## Base UI only props worth knowing
+
+- `Tabs.Indicator`: new part, a `<span>` that tracks the active tab for sliding-highlight UIs; `renderBeforeHydration` (default `false`) for SSR-flash avoidance. Exposes the `--active-tab-*` CSS vars below.
+- `List.activateOnFocus` (see above).
+- `Tab.nativeButton`, state-function `className`/`style` on all parts.
+
+## Data-attribute mapping
+
+| Radix | Base UI | Note |
+|---|---|---|
+| `Trigger [data-state="active" \| "inactive"]` | `Tab [data-active]` (presence) | Renamed. Inactive = absence of `data-active`. |
+| `Content [data-state="active" \| "inactive"]` | `Panel [data-hidden]` (presence when hidden) | Inverted polarity: Radix marks the active state, Base UI marks the hidden state. |
+| `[data-orientation]` (all parts) | `[data-orientation]` (Root, List, Tab, Panel, Indicator) | Same. |
+| `Trigger [data-disabled]` | `Tab [data-disabled]` | Same. |
+| — | `[data-activation-direction]` (`'left' \| 'right' \| 'up' \| 'down' \| 'none'`, all parts) | Base UI only: direction of the last tab change, useful for directional animations. |
+| — | `Panel [data-index]`, `[data-starting-style]`, `[data-ending-style]` | Base UI only. |
+
+## CSS var mapping
+
+Radix Tabs exposes no CSS variables. Base UI only (on `Indicator`): `--active-tab-left`, `--active-tab-right`, `--active-tab-top`, `--active-tab-bottom`, `--active-tab-width`, `--active-tab-height`.
+
+---
+
+# toggle
+
+Part mapping: `Toggle.Root → Toggle` (single-part; Base UI export is directly callable, no `.Root`).
+
+## Toggle.Root → Toggle
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` (+ `nativeButton`, default `true`) | Signature changed. |
+| `defaultPressed` | `boolean` / — | `defaultPressed` (default `false`) | Same. |
+| `pressed` | `boolean` / — | `pressed` | Same. |
+| `onPressedChange` | `(pressed: boolean) => void` / — | `onPressedChange` | Signature changed: `(pressed: boolean, eventDetails: Toggle.ChangeEventDetails) => void`. |
+| `disabled` | `boolean` / — | `disabled` (default `false`) | Same. |
+
+## Base UI only props worth knowing
+
+- `value?: string`: identifies the toggle inside a Base UI `ToggleGroup` (this replaces Radix `ToggleGroup.Item`'s `value`, see toggle-group below).
+- `nativeButton` (default `true`), state-function `className`/`style`.
+
+## Data-attribute mapping
+
+| Radix | Base UI | Note |
+|---|---|---|
+| `[data-state="on" \| "off"]` | `[data-pressed]` (presence) | Renamed. Off = absence of `data-pressed`. |
+| `[data-disabled]` | `[data-disabled]` | Same. |
+
+## CSS var mapping
+
+None on either side.
+
+---
+
+# toggle-group
+
+Part mapping: `ToggleGroup.Root → ToggleGroup` (callable single export), `ToggleGroup.Item → Toggle` (Base UI reuses the Toggle primitive as group items).
+
+## ToggleGroup.Root → ToggleGroup
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `type` (required) | `"single" \| "multiple"` / — | `multiple` (boolean, default `false`) | Signature changed, same pattern as accordion. |
+| `value` | `string` (single) or `string[]` (multiple) / — | `value` | Signature changed: always `readonly Value[]` (array), even single mode. `value="bold"` → `value={["bold"]}`. |
+| `defaultValue` | `string` or `string[]` / — | `defaultValue` | Same array caveat. |
+| `onValueChange` | `(value: string) => void` or `(value: string[]) => void` / — | `onValueChange` | Signature changed: `(groupValue: Value[], eventDetails: ToggleGroup.ChangeEventDetails) => void`. Always an array; single mode with nothing pressed = `[]` (Radix single mode signals this as `""`). |
+| `disabled` | `boolean` / `false` | `disabled` (default `false`) | Same. |
+| `rovingFocus` | `boolean` / `true` | — dropped | Roving focus is always on in Base UI; no opt-out. If you relied on `rovingFocus={false}` (every item tabbable), there is no direct workaround. |
+| `orientation` | `"horizontal" \| "vertical"` / `undefined` | `orientation` (default `'horizontal'`) | Same name; Base UI has an explicit default. |
+| `dir` | `"ltr" \| "rtl"` / — | — dropped | Use DOM `dir` / `DirectionProvider`. |
+| `loop` | `boolean` / `true` | `loopFocus` (default `true`) | Renamed. |
+
+## ToggleGroup.Item → Toggle
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` (+ `nativeButton`, default `true`) | Signature changed. |
+| `value` (required) | `string` / — | `value` | Same meaning; on Base UI's `Toggle` it is optional in the type but required in practice for group membership. |
+| `disabled` | `boolean` / — | `disabled` (default `false`) | Same. |
+
+Note: the item also gains the full standalone `Toggle` API (`pressed`, `defaultPressed`, `onPressedChange` with `eventDetails`) since it IS the Toggle primitive; inside a group the group value normally drives pressed state.
+
+## Base UI only props worth knowing
+
+- `multiple` (covered above) and the always-array value model.
+- Items are plain `Toggle`s, so per-item `onPressedChange` is available.
+- State-function `className`/`style`.
+
+## Data-attribute mapping
+
+| Radix | Base UI | Note |
+|---|---|---|
+| `Item [data-state="on" \| "off"]` | `Toggle [data-pressed]` (presence) | Renamed. |
+| `Item [data-disabled]` | `Toggle [data-disabled]` | Same. |
+| `Root/Item [data-orientation]` | `ToggleGroup [data-orientation]` | On the group only; items (Toggles) do not emit it. |
+| — | `ToggleGroup [data-disabled]`, `[data-multiple]` | Base UI only. |
+
+## CSS var mapping
+
+None on either side.
+
+---
+
+# toolbar
+
+Part mapping: `Root → Root`, `Button → Button`, `Link → Link`, `Separator → Separator`. `Toolbar.ToggleGroup`/`Toolbar.ToggleItem` are DROPPED as dedicated parts: compose the standalone `ToggleGroup` with `<Toolbar.Button render={<Toggle />} value="...">` as items (Base UI docs pattern). Base UI adds `Group` and `Input` parts with no Radix equivalent.
+
+## Toolbar.Root → Toolbar.Root
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `orientation` | `"horizontal" \| "vertical"` / `"horizontal"` | `orientation` (default `'horizontal'`) | Same. |
+| `dir` | `"ltr" \| "rtl"` / — | — dropped | Use DOM `dir` / `DirectionProvider`. |
+| `loop` | `boolean` / `true` | `loopFocus` (default `true`) | Renamed. |
+
+## Toolbar.Button → Toolbar.Button
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` (+ `nativeButton`, default `true`) | Signature changed. |
+
+## Toolbar.Link → Toolbar.Link
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. Both render `<a>`. |
+
+## Toolbar.ToggleGroup → ToggleGroup (standalone, composed)
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| `type` (required) | `"single" \| "multiple"` / — | `multiple` (boolean, default `false`) | Moved: use the standalone `ToggleGroup` component inside `Toolbar.Root`; same mapping as toggle-group above. |
+| `value` / `defaultValue` | `string` or `string[]` / — | `value` / `defaultValue` on `ToggleGroup` | Always an array (see toggle-group). |
+| `onValueChange` | `(value: string \| string[]) => void` / — | `onValueChange` on `ToggleGroup` | `(groupValue: Value[], eventDetails) => void`. |
+| `disabled` | `boolean` / `false` | `disabled` on `ToggleGroup` | Same. |
+
+## Toolbar.ToggleItem → Toolbar.Button render={<Toggle />}
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | — | Moved: the composition IS the render prop: `<Toolbar.Button render={<Toggle />} value="bold" />`. Toolbar.Button supplies toolbar focus behavior, Toggle supplies pressed state. |
+| `value` (required) | `string` / — | `value` (on the composed element) | Same. |
+| `disabled` | `boolean` / — | `disabled` (on `Toolbar.Button`, default `false`) | Same; note `focusableWhenDisabled` defaults to `true` (disabled items stay focusable, Radix disabled items are not). |
+
+## Toolbar.Separator → Toolbar.Separator
+
+| Radix prop | Type / default | Base UI equivalent | Migration note |
+|---|---|---|---|
+| `asChild` | `boolean` / `false` | `render` | Signature changed. |
+| — | — | `orientation` | Base UI only: defaults to the OPPOSITE of the toolbar's orientation (horizontal toolbar → vertical separator), which matches Radix's automatic behavior; usually omit. |
+
+## Base UI only props worth knowing
+
+- `Root.disabled`: disables the entire toolbar (no Radix equivalent).
+- `Toolbar.Group` (new part): groups related items, with a group-level `disabled` (default `false`).
+- `Toolbar.Input` (new part): `<input>` wired into toolbar arrow-key navigation; `defaultValue`, `disabled` (default `false`), `focusableWhenDisabled` (default `true`).
+- `Button.disabled` (default `false`) + `Button.focusableWhenDisabled` (default `true`): disabled buttons remain focusable for discoverability; set `focusableWhenDisabled={false}` for Radix-like behavior.
+- `Button.nativeButton` (default `true`), state-function `className`/`style` on all parts.
+
+## Data-attribute mapping
+
+| Radix | Base UI | Note |
+|---|---|---|
+| `[data-orientation]` (Root, Button, ToggleGroup, ToggleItem, Separator) | `[data-orientation]` (Root, Button, Link, Input, Group, Separator) | Same; Separator's value is perpendicular to the toolbar. |
+| `ToggleItem [data-state="on" \| "off"]` | `[data-pressed]` (presence, from the composed `Toggle`) | Renamed. |
+| `ToggleItem [data-disabled]` | `[data-disabled]` (Root, Button, Input, Group) | Same. |
+| — | `Button/Input [data-focusable]` | Base UI only: present when focusable-while-disabled. |
+
+## CSS var mapping
+
+None on either side.