@uselets/ui 1.20.4 → 2.0.0

package/dist/skills/uselets-ui/references/migration-v1-to-v2.md

@@ -0,0 +1,599 @@
+# Migrating `@uselets/ui` v1 → v2
+
+v2 replaces `radix-ui` with Base UI (`@base-ui/react`) under every interactive component. Visual design and
+runtime behavior are intended to stay the same; what changes is the **component API** wherever Radix and Base UI
+differ, plus three intentional visual changes: the `Switch`/`Checkbox`/`RadioGroupItem` size scale (section 14),
+the `Dialog` default size (section 17), and invalid `Checkbox`/`Switch`/`RadioGroupItem` no longer turning red
+(section 19).
+
+Use this guide when an app upgrades to `@uselets/ui@2`, or when you see v1-only APIs (the "Detect" patterns
+below) in code that imports from `@uselets/ui`.
+
+## Contents
+
+1. [How to run the migration](#how-to-run-the-migration)
+2. [Polymorphism: `asChild` only](#1-polymorphism-aschild-only)
+3. [Change callbacks receive `eventDetails`](#2-change-callbacks-receive-eventdetails)
+4. [Accordion](#3-accordion)
+5. [ToggleGroup](#4-togglegroup)
+6. [Checkbox indeterminate](#5-checkbox-indeterminate)
+7. [Tooltip](#6-tooltip)
+8. [Select](#7-select)
+9. [Popover](#8-popover)
+10. [NavigationMenu](#9-navigationmenu)
+11. [DropdownMenu](#10-dropdownmenu)
+12. [HoverCard](#11-hovercard)
+13. [Progress](#12-progress)
+14. [Slider](#13-slider)
+15. [Switch, Checkbox and RadioGroupItem sizes](#14-switch-checkbox-and-radiogroupitem-sizes)
+16. [Styling against component state (CSS selectors and variables)](#15-styling-against-component-state)
+17. [Tests](#16-tests)
+18. [Dialog default size](#17-dialog-default-size)
+19. [Removed and renamed props](#18-removed-and-renamed-props)
+20. [Other behavior changes](#19-other-behavior-changes)
+21. [Unchanged APIs](#unchanged-apis)
+
+## How to run the migration
+
+1. Bump `@uselets/ui` to `^2`. Remove any direct `radix-ui` / `@radix-ui/*` dependency the app only had for
+   `@uselets/ui` (the package no longer depends on it).
+2. Run the app's typecheck first. Most breaking changes are prop renames or type changes, so `tsc` points at
+   almost every call site. Fix those using the sections below.
+3. Then grep for the patterns listed under each **Detect** heading — some changes still type-check but behave
+   differently (for example `SelectValue` showing the raw value, `data-[state=...]` selectors silently no longer
+   matching, or tests that open menus with `pointerDown`).
+4. Run the app's tests and check the affected screens visually (popovers, menus, dialogs, selects, switches).
+
+Do the mechanical rewrites exactly as shown; don't re-architect the surrounding code while migrating.
+
+## 1. Polymorphism: `asChild` only
+
+`asChild` is supported on triggers, closes, items, links, labels, titles/descriptions, contents/popups, overlays,
+`Label`, `Toggle`, `ToggleGroupItem`, `TabsTrigger`, `AccordionTrigger`, `SelectTrigger`, `NavigationMenuTrigger`,
+`AlertDialogAction`/`AlertDialogCancel`, and so on. Semantics: pass exactly one child element; the part's props,
+classes, event handlers and ref are merged into it, and the child replaces the part's content.
+`AlertDialogAction`/`AlertDialogCancel` with `asChild` keep the `Button` variant/color/size styles on the child.
+
+Parts whose internal structure is required for them to work no longer accept `asChild`: `ScrollArea`, `ScrollBar`, `SelectContent`, `SelectItem`, `AccordionContent`, `Checkbox`, `Switch`, `RadioGroupItem`, `Progress`, `Slider`, `NavigationMenu` and `NumberFieldScrubArea`. In v1
+these accepted `asChild` through Radix but broke or ignored the child when it was used. Render the part normally
+and put your element inside it (or around it) instead.
+
+- **Detect:** `asChild` on any of the parts above.
+
+Base UI's own `render` prop is **not** part of the public API — don't introduce it. This now includes `Combobox`
+and `NumberField`, which were already Base UI-based in v1 and accepted `render`: their parts take `asChild`
+instead (`ComboboxTrigger`, `ComboboxItem`, `ComboboxList`, `ComboboxGroup`, `ComboboxLabel`, `ComboboxEmpty`,
+`ComboboxSeparator`, `ComboboxContent`, `ComboboxChips`, `ComboboxChip`, `NumberFieldGroup`,
+`NumberFieldIncrement`, `NumberFieldDecrement`). `ComboboxInput`, `ComboboxClear`, `ComboboxChipsInput`,
+`NumberField`, `NumberFieldInput` and `NumberFieldScrubArea` accept neither.
+
+```tsx
+// v1
+<ComboboxTrigger render={<Button variant="outline" />} />
+// v2
+<ComboboxTrigger asChild>
+  <Button variant="outline">…</Button>
+</ComboboxTrigger>
+```
+
+- **Detect:** `render=` on any `@uselets/ui` component.
+
+New gotcha: parts that render a native `<button>` (`DialogTrigger`, `PopoverTrigger`, `DropdownMenuTrigger`,
+`CollapsibleTrigger`, `AlertDialogTrigger`, `DrawerTrigger`, `DialogClose`, `TabsTrigger`, `AccordionTrigger`,
+`Toggle`, `ToggleGroupItem`, `SelectTrigger`, `AlertDialogAction`/`AlertDialogCancel`, …) assume their `asChild`
+child is a `<button>`. If the child is something else (`<a>`, `<div>`, a router `Link`), also pass
+`nativeButton={false}` so the part adds the right keyboard/ARIA behavior. `TooltipTrigger` and `HoverCardTrigger`
+don't need it.
+
+```tsx
+// v2
+<PopoverTrigger asChild nativeButton={false}>
+  <a href="#details">Details</a>
+</PopoverTrigger>
+```
+
+- **Detect:** `asChild` on a part whose child is not a `<button>`/`Button`/`UnstyledButton`.
+
+The `asChild` child must be the element that should receive the part's props. A wrapper component that doesn't
+forward its props to the element it renders (for example `Tooltip`, which passes extra props to its popup) swallows
+the trigger's handlers and ref, so the part never opens. Nest the wrapper outside the part instead:
+
+```tsx
+// v1
+<DialogTrigger asChild>
+  <Tooltip label="Test data">
+    <Button size="icon">…</Button>
+  </Tooltip>
+</DialogTrigger>
+
+// v2
+<Tooltip label="Test data">
+  <DialogTrigger asChild>
+    <Button size="icon">…</Button>
+  </DialogTrigger>
+</Tooltip>
+```
+
+- **Detect:** `asChild` whose child is `Tooltip` or another wrapper component instead of the clickable element.
+
+## 2. Change callbacks receive `eventDetails`
+
+`onOpenChange`, `onValueChange`, `onCheckedChange`, `onPressedChange`, etc. of Base UI-backed components now
+receive `(value, eventDetails)`. Package-level callbacks that aren't Base UI parts (`DateRangePicker`,
+`SidebarProvider`, `Stepper`) keep their v1 signatures. Passing a state setter directly still works when the
+state already has the v2 value type; the extra argument is ignored. It no longer type-checks where the value type
+changed: `Select` (`string | null`, section 7), `Accordion` and `ToggleGroup` (`string[]`, sections 3 and 4) and
+`Slider` (`number | readonly number[]`, section 13).
+
+```tsx
+const [reason, setReason] = useState('')
+// v1
+<Select value={reason} onValueChange={setReason}>…</Select>
+// v2
+<Select value={reason} onValueChange={(value) => value !== null && setReason(value)}>…</Select>
+```
+
+Otherwise, only code that relies on the argument count, or tests asserting exact arguments, need updates:
+
+```ts
+// v1
+expect(onValueChange).toHaveBeenCalledWith('banana')
+// v2
+expect(onValueChange).toHaveBeenCalledWith('banana', expect.anything())
+```
+
+`eventDetails.reason` (`'escape-key'`, `'outside-press'`, `'trigger-press'`, …) and `eventDetails.cancel()` let
+you veto a change. You rarely need this: `Dialog`/`Drawer` still have `dismissible={false}`. To replace a v1
+`onInteractOutside={(event) => event.preventDefault()}`, cancel both outside reasons:
+
+```tsx
+<Popover
+  onOpenChange={(open, eventDetails) => {
+    if (!open && ['outside-press', 'focus-out'].includes(eventDetails.reason)) eventDetails.cancel()
+  }}
+>
+```
+
+## 3. Accordion
+
+`type="single" | "multiple"` and `collapsible` are gone. The accordion is single-item by default (items can
+always be collapsed). Set `multiple` to allow several open items. `value`/`defaultValue` are **always arrays**.
+
+```tsx
+// v1
+<Accordion type="single" collapsible defaultValue="item-1">…</Accordion>
+<Accordion type="multiple" defaultValue={['a', 'b']}>…</Accordion>
+
+// v2
+<Accordion defaultValue={['item-1']}>…</Accordion>
+<Accordion multiple defaultValue={['a', 'b']}>…</Accordion>
+```
+
+- **Detect:** `<Accordion` with `type=` or `collapsible`; a string `value`/`defaultValue`.
+- A disabled `AccordionTrigger` now uses `aria-disabled="true"` instead of the native `disabled` attribute.
+- Arrow keys, `Home` and `End` no longer move focus between triggers; `Tab` moves through them like regular
+  buttons. `orientation` and `loopFocus` still type-check but are deprecated by Base UI and do nothing: remove them.
+  - **Detect:** `orientation=`, `loop` or `loopFocus` on `<Accordion`.
+
+## 4. ToggleGroup
+
+Same shape as Accordion: no `type`. Single selection is the default, and `multiple` enables multi-selection.
+`value`/`defaultValue`/`onValueChange` always use `string[]`.
+
+```tsx
+// v1
+const [view, setView] = useState('board')
+<ToggleGroup type="single" value={view} onValueChange={setView}>…</ToggleGroup>
+
+// v2
+const [view, setView] = useState(['board'])
+<ToggleGroup value={view} onValueChange={setView}>…</ToggleGroup>
+```
+
+- **Detect:** `<ToggleGroup` with `type=`; string state passed to `value`.
+- Items are now toggle buttons (`aria-pressed`, `data-pressed`). They no longer use `role="radio"`/`aria-checked`
+  or `data-state="on"`.
+
+## 5. Checkbox indeterminate
+
+`checked="indeterminate"` / `defaultChecked="indeterminate"` is no longer accepted. Use the boolean
+`indeterminate` prop next to a boolean `checked`. `onCheckedChange` always receives a boolean, so drop
+`Boolean(value)` / `value === true` coercions.
+
+```tsx
+// v1
+<Checkbox
+  checked={allSelected || (someSelected && 'indeterminate')}
+  onCheckedChange={(value) => toggleAll(Boolean(value))}
+/>
+
+// v2
+<Checkbox
+  checked={allSelected}
+  indeterminate={someSelected && !allSelected}
+  onCheckedChange={(value) => toggleAll(value)}
+/>
+```
+
+- **Detect:** `'indeterminate'` string literal near `Checkbox`; `data-state="indeterminate"`.
+
+## 6. Tooltip
+
+| v1 | v2 |
+| --- | --- |
+| `<TooltipProvider delayDuration={n}>` | `<TooltipProvider delay={n}>` (also `closeDelay`, `timeout`) |
+| `<Tooltip delayDuration={n}>` | `<Tooltip delay={n} closeDelay={m}>` (forwarded to the trigger) |
+| `<Tooltip disableHoverableContent>` | `<Tooltip disableHoverablePopup>` |
+| `<TooltipRoot delayDuration={n}>` | put `delay` on `TooltipTrigger` instead |
+
+`Tooltip label`, `disabled`, `TooltipRoot`, `TooltipTrigger asChild`, and `TooltipContent`
+(`side`/`sideOffset`/`align`/`alignOffset`) are unchanged.
+
+- **Detect:** `delayDuration`, `disableHoverableContent`.
+
+## 7. Select
+
+- `SelectValue` renders the **raw value** unless `Select` receives `items`. Whenever an item's label differs from
+  its value, pass `items` (array of `{ value, label }` or a `value → label` record). If value and label are
+  identical (for example page sizes `'10'`, `'20'`), nothing to do. Neither `tsc` nor tests flag a missing
+  `items`: the trigger just shows `READY_FOR_PICKUP` instead of `Ready for pickup`. Review **every** `<Select`.
+- `SelectContent`'s `position="item-aligned" | "popper"` → `alignItemWithTrigger` (default `true`, the old
+  item-aligned behavior). `position="popper"` → `alignItemWithTrigger={false}`.
+- `onValueChange` may receive `null`. Guard before converting: `value !== null && setPageSize(Number(value))`.
+
+```tsx
+// v1
+<Select defaultValue="design-system">
+  …<SelectItem value="design-system">Design System</SelectItem>…
+</Select>
+
+// v2: keep one { value, label } list and use it for both `items` and the rendered items
+const categories = [{ value: 'design-system', label: 'Design System' }]
+<Select items={categories} defaultValue="design-system">
+  <SelectTrigger>
+    <SelectValue />
+  </SelectTrigger>
+  <SelectContent>
+    {categories.map((category) => (
+      <SelectItem key={category.value} value={category.value}>
+        {category.label}
+      </SelectItem>
+    ))}
+  </SelectContent>
+</Select>
+```
+
+When the list is built inline or the label is derived (`{item.displayName}`, `{format(item)}`), map it to
+`{ value, label }` for `items` with the same expression used in the `SelectItem`.
+
+- **Detect:** `<Select` without `items` whose `SelectItem` content is anything other than the literal value
+  (`{item.label}`, `{option.name}`, a hard-coded label); `position=` on `SelectContent`; `Number(value)` / string
+  methods on `onValueChange` values.
+
+## 8. Popover
+
+`PopoverAnchor` was removed. To position against something other than the trigger, pass `anchor` (element,
+ref, or virtual element) to `PopoverContent`.
+
+```tsx
+// v1
+<Popover>
+  <PopoverAnchor><div ref={…}>Anchor</div></PopoverAnchor>
+  <PopoverTrigger>Open</PopoverTrigger>
+  <PopoverContent>…</PopoverContent>
+</Popover>
+
+// v2
+const anchorRef = useRef<HTMLDivElement>(null)
+<div ref={anchorRef}>Anchor</div>
+<Popover>
+  <PopoverTrigger>Open</PopoverTrigger>
+  <PopoverContent anchor={anchorRef}>…</PopoverContent>
+</Popover>
+```
+
+`PopoverTitle`/`PopoverDescription` now wire `aria-labelledby`/`aria-describedby` on the popup automatically.
+
+`modal` only traps focus when a `PopoverClose` is rendered inside `PopoverContent`. Without one, it still blocks
+outside clicks and page scroll, but `Tab` moves focus out of the popup. Add a `PopoverClose` (visually hidden if the
+design has no close button):
+
+```tsx
+<Popover modal>
+  <PopoverTrigger>Open</PopoverTrigger>
+  <PopoverContent>
+    …
+    <PopoverClose className="sr-only">Close</PopoverClose>
+  </PopoverContent>
+</Popover>
+```
+
+- **Detect:** `PopoverAnchor`; `<Popover modal` whose content has no `PopoverClose`.
+
+## 9. NavigationMenu
+
+- The `viewport` prop and the `NavigationMenuViewport` export were removed. Content always renders through the
+  new `NavigationMenuPositioner` (portaled, added automatically by `NavigationMenu`). `NavigationMenu` accepts
+  `align` and forwards it to the positioner.
+- `NavigationMenuIndicator` must be placed **inside** a `NavigationMenuItem` (next to its trigger). It throws
+  when rendered directly in the list.
+- `NavigationMenuLink` keeps `active` (`data-active` + `aria-current="page"`) and supports `asChild` for router
+  links.
+- `NavigationMenuLink` no longer closes the menu when clicked (`closeOnClick` defaults to `false`). With full page
+  loads nothing changes, but in client-side routing the popup stays open over the new page: pass `closeOnClick`.
+  `onSelect` still type-checks (it is the DOM text-selection event) but never fires on click: move its logic to
+  `onClick`, and drop `onSelect={(event) => event.preventDefault()}` (the menu already stays open).
+
+```tsx
+// v1
+<NavigationMenuLink asChild onSelect={() => track('nav')}>
+  <Link href="/orders">Orders</Link>
+</NavigationMenuLink>
+
+// v2
+<NavigationMenuLink asChild closeOnClick onClick={() => track('nav')}>
+  <Link href="/orders">Orders</Link>
+</NavigationMenuLink>
+```
+
+- Hover timing: `delayDuration` (default 200ms) → `delay` (default 50ms); `skipDelayDuration` was removed;
+  `closeDelay` (default 50ms) is new. Pass `delay={200}` to keep the v1 opening delay.
+- The closed `value` is `null`, not `''`, and `onValueChange` receives `null` when the menu closes. Any non-`null`
+  value counts as open, so a controlled `value=""` keeps the menu open:
+
+```tsx
+// v1
+const [value, setValue] = useState('')
+<NavigationMenu value={value} onValueChange={setValue}>…</NavigationMenu>
+setValue('') // close
+
+// v2
+const [value, setValue] = useState<string | null>(null)
+<NavigationMenu value={value} onValueChange={setValue}>…</NavigationMenu>
+setValue(null) // close
+```
+
+- **Detect:** `NavigationMenuViewport`, `viewport={`, `NavigationMenuIndicator` outside an item; every
+  `NavigationMenuLink` used with client-side routing; `onSelect=` on `NavigationMenuLink`; `delayDuration` /
+  `skipDelayDuration` on `NavigationMenu`; a controlled `NavigationMenu` `value` that uses `''` for closed.
+
+## 10. DropdownMenu
+
+- `DropdownMenuItem` has no `onSelect`. Use `onClick`. The menu still closes after the click.
+- `DropdownMenuCheckboxItem`/`DropdownMenuRadioItem` now keep the menu open when toggled (v1 closed it). Drop
+  any v1 `onSelect={(event) => event.preventDefault()}` used to keep it open; pass `closeOnClick` where the menu
+  should close after toggling.
+- `DropdownMenuSub` / `DropdownMenuSubTrigger` / `DropdownMenuSubContent` keep their names.
+- `DropdownMenuLabel` works inside or outside `DropdownMenuGroup`/`DropdownMenuRadioGroup`. Inside a group it
+  also labels the group for assistive tech.
+- `DropdownMenuContent` keeps `side`, `sideOffset`, `align`, `alignOffset`.
+
+```tsx
+// v1
+<DropdownMenuItem onSelect={() => logout()}>Sair</DropdownMenuItem>
+// v2
+<DropdownMenuItem onClick={() => logout()}>Sair</DropdownMenuItem>
+```
+
+- **Detect:** `onSelect=` on `DropdownMenuItem`/`CheckboxItem`/`RadioItem`.
+
+## 11. HoverCard
+
+Open/close timing moved from the root to the trigger: `<HoverCard openDelay closeDelay>` →
+`<HoverCardTrigger delay closeDelay>`. The defaults stay at the v1 timing: `delay` `700`, `closeDelay` `300`.
+
+- **Detect:** `openDelay` / `closeDelay` on `<HoverCard`.
+
+## 12. Progress
+
+Omitting `value` or passing `null` now renders the **indeterminate** state (`data-indeterminate`, no width on the
+indicator), matching Radix semantics. v1 silently treated it as `0`. Pass `value={0}` if you want an empty
+determinate bar.
+
+## 13. Slider
+
+`onValueChange` receives `number | readonly number[]` (an array when `value`/`defaultValue` is an array). A
+`useState<number[]>` setter no longer type-checks directly:
+
+```tsx
+<Slider
+  value={value}
+  onValueChange={(next) => setValue(Array.isArray(next) ? [...next] : [next])}
+/>
+```
+
+## 14. Switch, Checkbox and RadioGroupItem sizes
+
+`Switch` now uses the same height scale as `Checkbox` (14 / 16 / 20px). Every switch size moved **down one
+step**:
+
+| v1 size | rendered track | v2 size for the same look |
+| --- | --- | --- |
+| `sm` | 34×16px | `md` (new default) |
+| `md` (default) | 42×20px | `lg` |
+| `lg` | 48×22px | removed: use `lg` (42×20px) |
+| — | — | new `sm` is 30×14px |
+
+To keep a v1 screen pixel-identical: `size="sm"` → `size="md"` (or drop it), and no `size` / `size="md"` →
+`size="lg"`. If the v1 code was just using defaults with no visual requirement, prefer the new default (`md`). It
+now lines up with a default `Checkbox`.
+
+Composed label text is now the same across `Switch`, `Checkbox` and `RadioGroupItem`: `sm` 12px, `md` 14px,
+`lg` 18px. Before, checkbox/radio `lg` was 20px and switch labels were one step larger.
+
+- **Detect:** `<Switch` (every usage: decide per the table above).
+
+## 15. Styling against component state
+
+If the app styles `@uselets/ui` parts by state (custom `className`, global CSS, or `group-*`/`peer-*`
+variants), update the selectors. `data-open`, `data-closed`, `data-checked`, `data-unchecked`, `data-active`,
+`data-disabled`, `data-horizontal` and `data-vertical` Tailwind variants keep working, because the package's
+`shadcn/tailwind.css` maps them, but only on parts that set those attributes:
+
+- `data-open:` / `data-closed:` match contents, popups and panels, **not triggers**. A trigger only gets
+  `data-popup-open` or `data-panel-open` while open and has no closed marker, so `data-open:rotate-180` on a
+  trigger silently stops matching. Use `data-popup-open:` / `data-panel-open:`, or `aria-expanded:`.
+- `data-checked:` matches checkboxes, radios, switches and menu checkbox/radio items, **not `SelectItem`**. The
+  selected `SelectItem` gets an empty `data-selected` attribute, which the `data-selected:` variant (it expects
+  `data-selected="true"`) does not match. Use `data-[selected]:` or `aria-selected:`.
+
+Literal `data-[state=…]` selectors and Radix CSS variables do not keep working:
+
+| v1 (Radix) | v2 (Base UI) |
+| --- | --- |
+| `data-[state=open]` on a trigger | `data-popup-open` (popover, menu, select, dialog, alert dialog, drawer, tooltip and hover card triggers), `data-panel-open` (collapsible/accordion triggers) |
+| `data-[state=open]` / `[state=closed]` on content | `data-open` / `data-closed` |
+| `data-[state=checked]` / `[state=unchecked]` | `data-checked` / `data-unchecked` |
+| `data-[state=checked]` on `SelectItem` | `data-[selected]` |
+| `data-[state=indeterminate]` | `data-indeterminate` |
+| `data-[state=on]` (Toggle, ToggleGroupItem) | `data-pressed` |
+| `data-[state=active]` (TabsTrigger) | `data-active` |
+| `data-[state=delayed-open]` / `[state=instant-open]` (Tooltip) | `data-open`; an instant open also sets `data-instant` |
+| `data-[state=active]` / `[state=inactive]` (TabsContent) | inactive panels get `data-hidden`; the active one has no marker |
+| `data-[state=loading]` / `[state=complete]` (Progress) | `data-progressing` / `data-complete` |
+| `data-value`, `data-max` (Progress) | removed; style from your own `value` |
+| `data-disabled` (Collapsible parts) | removed; `CollapsibleTrigger` still gets the native `disabled` attribute (`disabled:`) |
+| `data-orientation` (NavigationMenu, NavigationMenuList, NavigationMenuItem) | removed |
+| `data-[state=visible]` / `[state=hidden]` (ScrollBar) | `data-hovering` / `data-scrolling` while shown |
+| `data-motion` (NavigationMenuContent) | `data-activation-direction="left" \| "right"` with `data-starting-style` / `data-ending-style` |
+| `focus:` on menu/select items | still works. `data-highlighted` is also set |
+| `disabled:` on Checkbox/Radio/Switch roots | `data-disabled:` (roots are `<span>`, not native inputs) |
+| `peer-disabled:` on a label next to those controls | `peer-data-disabled:` |
+| `--radix-*-content-transform-origin` | `--transform-origin` |
+| `--radix-*-content-available-height` | `--available-height` |
+| `--radix-*-content-available-width` | `--available-width` |
+| `--radix-*-trigger-width` | `--anchor-width` |
+| `--radix-*-trigger-height` | `--anchor-height` |
+| `--radix-accordion-content-height` / `-width` | `--accordion-panel-height` / `--accordion-panel-width` |
+| `--radix-collapsible-content-height` / `-width` | `--collapsible-panel-height` / `--collapsible-panel-width` |
+| `--radix-navigation-menu-viewport-width/height` | `--popup-width` / `--popup-height` |
+
+- **Detect:** `data-open:`/`data-closed:` on a trigger className, `data-checked:` on `SelectItem`. Also
+  `data-[state=`, `--radix-`, `[data-state=` in CSS/TSX. Ignore matches that aren't Radix state:
+  `TableRow data-state="selected"` (and `data-[state=selected]` table styles) and the Sidebar's own
+  `data-state="expanded" | "collapsed"` are package attributes and keep working unchanged.
+
+## 16. Tests
+
+Base UI reacts to different DOM events than Radix. In `@testing-library/react` with `fireEvent`:
+
+- Menus (`DropdownMenuTrigger`, `ModeToggle`) open with `fireEvent.click(trigger)`, not
+  `pointerDown`/`pointerUp`.
+- Select options need `fireEvent.pointerDown(option)` followed by `fireEvent.click(option)`. Open the select
+  with `click` or `keyDown` `ArrowDown` on the trigger (`Enter` relies on the browser's native button click,
+  which jsdom doesn't synthesize).
+- Tabs activate on `click`, not `mouseDown`.
+- `role="listbox"` lives on an inner list. Use `closest('[data-slot="select-content"]')` to reach the content
+  slot.
+- Disabled `AccordionTrigger` and `TabsTrigger` expose `aria-disabled="true"`, not `disabled`: assert
+  `toHaveAttribute('aria-disabled', 'true')` instead of `toBeDisabled()`.
+- Assertions on `data-state="..."` must switch to the attributes in section 15
+  (`hasAttribute('data-checked')`, `hasAttribute('data-pressed')`, …).
+- Callback assertions need the extra `eventDetails` argument (`expect.anything()`).
+- Floating parts still need a `ResizeObserver` stub in jsdom.
+
+## 17. Dialog default size
+
+`Dialog` without a `size` now defaults to `md` (v1 rendered `sm`, `sm:max-w-sm`). `CommandDialog` still defaults
+to `sm`. To keep a v1 dialog pixel-identical, pass `size="sm"`.
+
+```tsx
+// v1 (implicit sm) → v2
+<Dialog>…</Dialog>  →  <Dialog size="sm">…</Dialog>
+```
+
+- **Detect:** `<Dialog` without `size=`.
+
+## 18. Removed and renamed props
+
+| v1 (Radix) | v2 |
+| --- | --- |
+| `Slider onValueCommit` | `onValueCommitted` |
+| `Tabs activationMode="automatic" \| "manual"` | `TabsList activateOnFocus` (default `false` = manual: arrow keys only move focus, `Enter`/`Space` or a click selects). v1 defaulted to automatic, so pass `activateOnFocus` to keep it; `activationMode="manual"` → just remove it |
+| `AvatarFallback delayMs` | `delay` |
+| `forceMount` on `AccordionContent` / `CollapsibleContent` / `TabsContent` / `NavigationMenuContent` | `keepMounted` |
+| `forceMount` on overlay contents (`DialogContent`, `PopoverContent`, `DropdownMenuContent`, …) | `keepMounted` on the same content (forwarded to its portal). `SelectContent` has no equivalent |
+| `onOpenAutoFocus` / `onCloseAutoFocus` on contents | `initialFocus` / `finalFocus` (on `DialogContent`, `DrawerContent`, `PopoverContent`, `AlertDialogContent`); `SelectContent` and `DropdownMenuContent` only have `finalFocus` |
+| `onOpenAutoFocus={(event) => event.preventDefault()}` | `initialFocus={false}` |
+| `forceMount` on `DialogPortal` / `AlertDialogPortal` / `DrawerPortal` / `DropdownMenuPortal` | `keepMounted` |
+| `forceMount` on `DialogOverlay` / `AlertDialogOverlay` / `DrawerOverlay` | removed (the overlay follows its portal) |
+| `ScrollBar forceMount` | `keepMounted` |
+| `textValue` on `SelectItem`, `DropdownMenuItem` / `CheckboxItem` / `RadioItem`, `DropdownMenuSubTrigger` | `label` (typeahead text) |
+| `DropdownMenuCheckboxItem checked="indeterminate"` | removed; `checked` is boolean only |
+| `DropdownMenu loop` | `loopFocus` on `DropdownMenu`, default `true` (focus now wraps; v1 stopped at the ends, so pass `loopFocus={false}` to keep it) |
+| `DropdownMenuContent onFocusOutside` | removed; use the root `onOpenChange` with `eventDetails.reason === 'focus-out'` |
+| `loop` on `TabsList` / `ToggleGroup` | `loopFocus` (default `true`) |
+| `ToggleGroup rovingFocus` | removed (roving focus is always on) |
+| `Slider minStepsBetweenThumbs` | `minStepsBetweenValues` |
+| `Slider inverted` | removed |
+| `Progress getValueLabel(value, max)` | `getAriaValueText(formattedValue, value)` |
+| `NavigationMenu delayDuration` | `delay` (default `50`; v1 default was `200`) |
+| `NavigationMenu skipDelayDuration` | removed |
+| `TooltipProvider skipDelayDuration` | `timeout` (default `400`; v1 default was `300`) |
+| `TooltipProvider disableHoverableContent` | `disableHoverablePopup` on each `Tooltip` / `TooltipRoot` |
+| `dir="rtl"` on `Tabs`, `ToggleGroup`, `RadioGroup`, `DropdownMenu`, `Slider`, `ScrollArea`, `Select` | still renders the attribute but no longer flips keyboard navigation or positioning; wrap the subtree in `<DirectionProvider direction="rtl">` from `@uselets/ui/direction` |
+| `onEscapeKeyDown`, `onPointerDownOutside`, `onInteractOutside` on contents | removed; use the root `onOpenChange(open, eventDetails)` and check `eventDetails.reason`, calling `eventDetails.cancel()` to keep it open. `onEscapeKeyDown` → `'escape-key'`; `onPointerDownOutside` → `'outside-press'`; `onInteractOutside` → `'outside-press'` **and** `'focus-out'` (Radix fired it for focus leaving the popup too). For dialogs/drawers, `dismissible={false}` covers the common case |
+| `onEscapeKeyDown`, `onPointerDownOutside`, `onFocusOutside`, `onInteractOutside` on `NavigationMenuContent` | removed; `NavigationMenu` has no `onOpenChange`: use its `onValueChange(value, eventDetails)` with `eventDetails.reason` (`'escape-key'`, `'outside-press'`, `'focus-out'`) and `eventDetails.cancel()` |
+| `onChange` on `Switch` / `Checkbox` | `onCheckedChange` (v1 accepted `onChange` because the root was a `<button>`, but it never fired on toggle) |
+| `sticky="partial" \| "always"` on popover/menu/select/tooltip/hover-card contents | `sticky?: boolean` (default `false`): `true` keeps the popup in the viewport after the trigger scrolls away (the Radix values are not accepted) |
+| `collisionPadding`, `avoidCollisions`, `collisionBoundary`, `arrowPadding`, `hideWhenDetached` on those contents | not exposed |
+| `ScrollArea type` / `scrollHideDelay` | removed; the scrollbar shows while hovering or scrolling |
+| `PopoverAnchor`, `PopoverAnchorProps` | removed (section 8) |
+| `NavigationMenuViewport`, `NavigationMenuViewportProps`, `NavigationMenu viewport` | removed (section 9) |
+
+- **Detect:** each v1 name in the left column.
+
+## 19. Other behavior changes
+
+- Anchored popups (`PopoverContent`, `SelectContent`, `DropdownMenuContent`, `TooltipContent`, `HoverCardContent`)
+  now keep 5px from the viewport edge when they flip or shift (v1: 0px, and 10px for `SelectContent`), and the
+  `Tooltip` arrow keeps 5px from the popup corners. Nothing to change in code; only screenshots of popups near the
+  edge differ.
+- A range `Slider` (two thumbs) now pushes the other thumb when one is dragged into it. In v1 the thumbs crossed
+  and swapped places. Values passed to `onValueChange` stay sorted either way. Pass
+  `thumbCollisionBehavior="swap"` to keep the v1 behavior (or `"none"` to stop at the other thumb).
+  - **Detect:** `<Slider` with a two-value `value`/`defaultValue`.
+- `Checkbox`, `RadioGroupItem` and `Switch` render a `<span>` root plus a hidden `<input>`. The `id` prop (and the
+  `Field` control id) lands on the hidden input, not on the visible element. Code that does
+  `document.getElementById(id)` and expects the visible control, or styles `#id`, must target
+  `[data-slot="checkbox"]` / `[data-slot="switch"]` / `[data-slot="radio-group-item"]` instead.
+- `Progress` renders a root plus an inner track: `className` is applied to the track (the visible bar), and the
+  root wraps it.
+- `Checkbox`, `Switch` and `RadioGroupItem` no longer draw a red border/ring for `aria-invalid` (the attribute is
+  still set for assistive tech). Show the error through the `Field`: `<Field invalid>` colors the label and
+  `FieldError` shows the message. Nothing to change in code; only screenshots of invalid checkboxes/switches differ.
+  - **Detect:** `aria-invalid` on `<Checkbox`, `<Switch` or `<RadioGroupItem`.
+- `Field`'s `data-invalid` is now typed `boolean | 'true' | 'false'`. Passing anything else, such as a
+  react-hook-form `FieldError` object, no longer type-checks (in v1 it rendered `data-invalid="[object Object]"` and
+  the invalid styles never matched). Pass a boolean, preferably through `invalid`:
+  `<Field invalid={!!errors.identifier}>`.
+  - **Detect:** `data-invalid={` on `<Field` with a non-boolean value (`errors.x`, `fieldState.error`).
+
+## Unchanged APIs
+
+No migration is needed for: `Button`, `Badge`, `Anchor`, `Heading`, `Text`, `Marker`, `List`, `UnstyledButton`,
+`Breadcrumb`, `ButtonGroup`, `BottomNav`, `Sidebar` parts (`asChild` still supported everywhere it was),
+`Dialog`/`Drawer` (`direction`, `dismissible`, `showCloseButton`, `overlayRef`/`overlayProps`,
+`DialogBody`/`DrawerBody`; only the `Dialog` default size changed, section 17), `AlertDialog` (`size`,
+`AlertDialogAction` still closes the dialog; see the note below), `Tabs` (`variant`, `grow`, string `value`; see
+the note below and section 18 for `activationMode`), `Separator` (`decorative`, `orientation`), `Collapsible`,
+`RadioGroup` (string `value`; see the note below),
+`ScrollArea` (see section 18), `Avatar` (see section 18), `Combobox` and `NumberField` (except `render`, see section 1), and every non-interactive
+component.
+
+These keep their props but changed behavior:
+
+- `AlertDialog`: opening focuses the first focusable element in the content, not `AlertDialogCancel`. If a link or
+  `AlertDialogAction` comes before the cancel button, pass a ref to the element to focus:
+  `<AlertDialogContent initialFocus={cancelRef}>` with `<AlertDialogCancel ref={cancelRef}>`.
+  - **Detect:** `<AlertDialogContent` whose first focusable child is not `AlertDialogCancel`.
+- `Tabs`: without `value` or `defaultValue`, the first enabled tab is now selected on mount (v1 selected none) and
+  `onValueChange` fires once with `eventDetails.reason === 'initial'`. Pass `defaultValue`, or ignore that reason in
+  handlers with side effects (tracking, fetching).
+  - **Detect:** `<Tabs` with `onValueChange` but neither `value` nor `defaultValue`.
+- `TabsTrigger disabled` now sets `aria-disabled="true"` instead of the native `disabled` attribute. The tab still
+  can't be selected (click and `Enter` do nothing), but arrow keys now stop on it instead of skipping it, so screen
+  reader users can discover it. Style it with `aria-disabled:` / `data-disabled:` (not `disabled:`).
+  - **Detect:** `disabled:` classes on `TabsTrigger`; tests asserting `toBeDisabled()` on a tab.
+- `RadioGroup`: `orientation`, `loop` and `dir` are no longer supported; arrow-key focus always wraps.
+  - **Detect:** `orientation=`, `loop` or `dir=` on `<RadioGroup`.

package/dist/skills/uselets-ui/references/package-guide.md

@@ -21,8 +21,8 @@ If the package is not installed yet, use the bundled references as a snapshot an
 
 ## Requirements
 
-- React `>=19`
-- React DOM `>=19`
+- React `^19.2`
+- React DOM `^19.2`
 - Tailwind CSS 4
 
 ## Installation
@@ -234,7 +234,7 @@ Examples:
 import { Tooltip, TooltipProvider } from '@uselets/ui/tooltip'
 
 export function AppRoot({ children }: { children: React.ReactNode }) {
-  return <TooltipProvider delayDuration={200}>{children}</TooltipProvider>
+  return <TooltipProvider delay={200}>{children}</TooltipProvider>
 }
 
 export function SaveButton() {
@@ -318,13 +318,13 @@ Additional tokens:
 
 The `Button` component can apply those palette families directly through `color: UIColor`, with `primary` as the default. Its public variants are `solid`, `secondary`, `outline`, `subtle`, `ghost`, and `link`, with `solid` as the default. Its public sizes are `xs`, `sm`, `md`, `lg`, `xl`, `icon-xs`, `icon-sm`, `icon`, `icon-lg`, and `icon-xl`; `loading` shows a centered spinner, keeps native button content invisible to preserve size, and disables the button without dimming it.
 
-The `Checkbox` component can be used as a bare checkbox or with `label?: React.ReactNode`. It supports `size: 'sm' | 'md' | 'lg'` and `color: UIColor`, with `primary` as the default color. When `label` is provided, it composes the package `Label`, accepts `labelProps` for that label, and generates an accessible `id`/`htmlFor` pair when no `id` prop is passed. Composed label text follows checkbox size: `sm` 12px, `md` 14px, and `lg` 20px.
+The `Checkbox` component can be used as a bare checkbox or with `label?: React.ReactNode`. It supports `size: 'sm' | 'md' | 'lg'` and `color: UIColor`, with `primary` as the default color. When `label` is provided, it composes the package `Label`, accepts `labelProps` for that label, and generates an accessible `id`/`htmlFor` pair when no `id` prop is passed. Composed label text follows checkbox size: `sm` 12px, `md` 14px, and `lg` 18px. Pass `description?: React.ReactNode` (and `descriptionProps`) to render muted helper text (a `<p>`) below the label, linked to the control via `aria-describedby`; description text is `sm` 12px, `md` 12px, `lg` 14px.
 
-The `Switch` component can be used as a bare switch or with `label?: React.ReactNode`. It supports `size: 'sm' | 'md' | 'lg'` and `color: UIColor`, with `green` as the default color. The `color` prop controls only the checked track and indicator color; unchecked remains neutral. Track size is `sm` 34x16px, `md` 42x20px, and `lg` 48x22px. The thumb and its internal indicator scale with the selected size. Composed label text follows switch size: `sm` 12px, `md` 14px, and `lg` 20px.
+The `Switch` component can be used as a bare switch or with `label?: React.ReactNode`. It supports `size: 'sm' | 'md' | 'lg'` and `color: UIColor`, with `green` as the default color. The `color` prop controls only the checked track and indicator color; unchecked remains neutral. Track size is `sm` 30x14px, `md` 34x16px, and `lg` 42x20px (control heights match `Checkbox`). The thumb and its internal indicator scale with the selected size. Composed label text follows switch size: `sm` 12px, `md` 14px, and `lg` 18px. `description?: React.ReactNode` (and `descriptionProps`) works the same as on `Checkbox`.
 
 The `TabsList` component supports `variant: 'line' | 'enclosed'`, with `line` as the default, and `grow?: boolean` for equal-width horizontal tabs. The `line` variant keeps a neutral border line across tabs and uses the `primary` color for the active indicator; use `enclosed` for the filled container treatment.
 
-The `RadioGroup` component supports `color: UIColor`, with `primary` as the default group color. `RadioGroupItem` can be used as a bare radio item inside `RadioGroup` or with `label?: React.ReactNode`; it supports `size: 'sm' | 'md' | 'lg'` and optional `color: UIColor` item overrides. Composed label text follows item size: `sm` 12px, `md` 14px, and `lg` 20px.
+The `RadioGroup` component supports `color: UIColor`, with `primary` as the default group color. `RadioGroupItem` can be used as a bare radio item inside `RadioGroup` or with `label?: React.ReactNode`; it supports `size: 'sm' | 'md' | 'lg'` and optional `color: UIColor` item overrides. Composed label text follows item size: `sm` 12px, `md` 14px, and `lg` 18px. `description?: React.ReactNode` (and `descriptionProps`) works the same as on `Checkbox`.
 
 The `DateRangePicker` component is a compound popover date range picker built on `Calendar` range mode. Use `DateRange | null` for controlled values; applying an empty draft or resetting emits `null` through `onValueChange`. Fixed presets, relative-day inputs, date inputs, and the calendar all edit the same draft, and `DateRangePickerPreset` displays a selected state when its range matches the current draft by calendar day.
 
@@ -365,7 +365,7 @@ import { Table, TableContainer } from '@uselets/ui/table'
 </DataTableRoot>
 ```
 
-`DataTableRoot` accepts either `{ columns, data, ...options }` (uncontrolled — creates the `table` instance internally) or `{ table }` (controlled — table instance comes from `useDataTable` called by the consumer). Use the controlled form whenever you need access to the `table` instance in the same scope as the JSX (e.g. for virtualization or external action buttons).
+`DataTableRoot` accepts either `{ columns, data, ...options }` (uncontrolled — creates the `table` instance internally) or `{ table }` (controlled — table instance comes from `useDataTable` called by the consumer). In the uncontrolled form, pagination is on while a `<DataTablePagination />` is rendered inside the root and off otherwise (all rows); an explicit `enablePagination` overrides that. In the controlled form, `useDataTable` defaults to `enablePagination: false` — pass `true` when rendering `<DataTablePagination />`. Use the controlled form whenever you need access to the `table` instance in the same scope as the JSX (e.g. for virtualization or external action buttons).
 
 ### Virtualized lists (bring your own virtualizer)