@uselets/ui 1.20.4 → 2.0.0

package/dist/resolve-class-name-BurP8ngI.js

@@ -0,0 +1,2 @@
+import"./rolldown-runtime-BhWHdk3m.js";function resolveClassName(e,t){return typeof e==`function`?e(t):e}export{resolveClassName as t};
+//# sourceMappingURL=resolve-class-name-BurP8ngI.js.map

package/dist/resolve-class-name-BurP8ngI.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-class-name-BurP8ngI.js","names":["className","state"],"sources":["../src/utils/resolve-class-name.ts"],"sourcesContent":["/** Resolves a Base UI `className`, which can also be a function of the component state, for that state. */\nexport function resolveClassName<State>(\n  className: string | ((state: State) => string | undefined) | undefined,\n  state: State\n) {\n  return typeof className === 'function' ? className(state) : className\n}\n"],"mappings":"uCACA,SAAgB,iBACd,EACA,EACA,CACA,OAAO,OAAOA,GAAc,WAAaA,EAAUC,CAAK,EAAID,CAC9D"}

package/dist/skills/uselets-ui/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: uselets-ui
-description: Use @uselets/ui in apps: install it, configure themes, choose public imports/components, and inspect the installed package API.
+description: >-
+  Use @uselets/ui in apps: install it, configure themes, choose public imports/components, inspect the installed package API, and migrate from v1 to v2 (Radix → Base UI). Use whenever code imports from @uselets/ui, including upgrades or v1-only APIs such as Accordion `type="single"`, `delayDuration`, `PopoverAnchor`, `NavigationMenuViewport`, `checked="indeterminate"`, or `onSelect` on menu items.
 ---
 
 # @uselets/ui
@@ -53,12 +54,14 @@ To set up a consumer project after installing `@uselets/ui`, run `bun uselets in
   app's entry file (`import '@fontsource-variable/inter'` in `app/layout.tsx`, `pages/_app.tsx`, or `src/main.tsx`),
   not via `@import` in CSS — some bundlers, including Next.js, don't resolve third-party CSS `@import`s reliably.
 - Recommend `@uselets/ui/postcss.config` when the app needs the package PostCSS preset for Tailwind v4.
+- Interactive components are built on Base UI (`@base-ui/react`). Use `asChild` (Radix-style, single child element) for polymorphism; the child replaces the part's content. Not supported on `ScrollArea`, `ScrollBar`, `SelectContent`, `SelectItem`, `AccordionContent`, `Checkbox`, `Switch`, `RadioGroupItem`, `Progress`, `Slider`, `NavigationMenu`, `NumberFieldScrubArea`, `ComboboxInput`, `ComboboxClear`, `ComboboxChipsInput`, `NumberField`, `NumberFieldInput` (their internal structure is required). Do not pass Base UI's `render` prop — it is not part of the public API. When `asChild` wraps a button-like part (triggers, closes, `TabsTrigger`, `AccordionTrigger`, `Toggle`, `SelectTrigger`, `AlertDialogAction`/`Cancel`) with a non-`<button>` child, also pass `nativeButton={false}` (not needed for `TooltipTrigger`/`HoverCardTrigger`). Change callbacks of Base UI-backed components (`onOpenChange`, `onValueChange`, `onCheckedChange`, …) receive `(value, eventDetails)`; `DateRangePicker`, `SidebarProvider` and `Stepper` callbacks don't.
+- Popups unmount when closed. `keepMounted?: boolean` (default `false`) keeps them mounted while hidden on `DialogContent`, `AlertDialogContent`, `DrawerContent`, `PopoverContent`, `DropdownMenuContent`, `DropdownMenuSubContent`, `TooltipContent`/`Tooltip`, `HoverCardContent`, `ComboboxContent` and `NavigationMenuPositioner`; `SelectContent` does not accept it. `sticky?: boolean` (default `false`) keeps `PopoverContent`, `SelectContent`, `DropdownMenuContent`, `DropdownMenuSubContent`, `TooltipContent`/`Tooltip`, `HoverCardContent` and `ComboboxContent` in the viewport after the anchor scrolls out of view. Other positioner props (`collisionPadding`, `collisionBoundary`, `arrowPadding`, `collisionAvoidance`) are only exposed on `ComboboxContent`.
 - For Vite apps, `@tailwindcss/vite` (registered in `vite.config.ts`, no `postcss.config.mjs`) is a valid alternative to PostCSS; prefer it when the project uses isolated installs (pnpm, Bun workspaces). See `references/package-guide.md`.
-- For tooltip-heavy apps, wrap the app with `TooltipProvider`; use `Tooltip label={...}` for common trigger/content usage and `TooltipRoot` only when manual composition is needed.
+- For tooltip-heavy apps, wrap the app with `TooltipProvider` (`delay`, not `delayDuration`); use `Tooltip label={...}` for common trigger/content usage (it accepts `delay`/`closeDelay`) and `TooltipRoot` only when manual composition is needed.
 - Use `UnstyledButton` when button semantics are needed without `Button` variants; it provides reset styles, pointer cursor, focus ring, default `type="button"`, and `asChild`.
 - For toast usage, mount `Toaster` near the app root before calling `toast(...)`.
 - For package theme helpers, use `ThemeProvider`, `useTheme`, and `ModeToggle` from `@uselets/ui/theme` or the root barrel.
-- For form fields, `Field` automatically shares a generated control id with `FieldLabel` and labelable controls when explicit ids are omitted; pass explicit matching `htmlFor` and `id` only when a stable custom id is required.
+- For form fields, `Field` automatically shares a generated control id with `FieldLabel` and labelable controls when explicit ids are omitted; pass explicit matching `htmlFor` and `id` only when a stable custom id is required. Use one control per `Field` (a `RadioGroup` counts as one control); for several checkboxes/switches use `FieldSet` + `FieldLegend` with one `Field` each. Mark errors with `<Field invalid>` (not `aria-invalid` on each control): it colors the label and propagates `aria-invalid` to the control; `Checkbox`/`Switch`/`RadioGroup` get the attribute but no red style.
 - For client-side tabular data, use `DataTable` from `@uselets/ui/data-table`. Defaults are bare: `enableRowSelection`, `enableSorting`, and `showPagination` are all `false`. Set `enableRowSelection` to auto-prepend the selection checkbox column (no need to add `createDataTableSelectColumn` manually); set `enableSorting` to make `DataTableColumnHeader` clickable for sort. `filterColumns` accepts a single id or an array; with 2+ ids the toolbar renders an `InputGroup` with a column selector on the left. `toolbarActions` always sits at the right of the toolbar. All labels default to pt-BR; override any subset through `labels` (`Partial<DataTableLabels>`), with full defaults exposed as `defaultDataTableLabels`. Use `variant` on `DataTable` (or directly on the base `Table`) to switch chrome: `"line"` (default) renders only horizontal separators between rows; `"outline"` adds a rounded outer border around the table. The base `Table` from `@uselets/ui/table` renders only the `<table>` element and is striped by default (pass `striped={false}` to disable). Wrap it in `TableContainer` to control scroll; `minWidth` lives on `TableContainer`. Combine `stickyHeader` on `Table` with `max-h` + `overflow-y-auto` on the `TableContainer` to keep the `<thead>` visible during vertical scroll. `DataTable` wraps its `Table` in `TableContainer` automatically.
 
 ## Quick Routing
@@ -66,6 +69,7 @@ To set up a consumer project after installing `@uselets/ui`, run `bun uselets in
 - Need installation or global setup: run `bun uselets init` or read `references/package-guide.md`.
 - Need to install or update this skill locally: run `bun uselets skill`.
 - Need to choose a component: read `references/component-catalog.md`.
+- Upgrading from v1, or the code uses v1-only APIs (Radix-era props like `type="single"`, `delayDuration`, `PopoverAnchor`, `data-[state=...]` selectors): read `references/migration-v1-to-v2.md` and follow it step by step.
 - Need the exact local API: run `scripts/print-public-api.mjs`.
 - Need exact props for one module: open the matching `.d.ts` file in `node_modules/@uselets/ui/dist`.
 
@@ -76,3 +80,4 @@ To set up a consumer project after installing `@uselets/ui`, run `bun uselets in
 - "Show me the correct import for `TooltipProvider`, `Tooltip`, `UnstyledButton`, or `Sidebar`."
 - "Inspect the installed version of `@uselets/ui` and tell me what `button` exports."
 - "Build this screen only with `@uselets/ui` components."
+- "Upgrade this app from `@uselets/ui` v1 to v2."

package/dist/skills/uselets-ui/references/component-catalog.md

@@ -5,7 +5,7 @@ This file is a portable snapshot of the public package API for `@uselets/ui`.
 Snapshot basis:
 
 - package name: `@uselets/ui`
-- snapshot version: `0.5.0`
+- snapshot version: `2.x` (Base UI-based major; see `migration-v1-to-v2.md` for v1 differences)
 
 Use this snapshot to choose modules and imports when the package is not yet installed.
 When `@uselets/ui` is installed locally, confirm exact exports with:
@@ -57,14 +57,14 @@ Unless noted otherwise, each module also exports its public `*Props` types from
 - `use-mask`
   - Import path: `@uselets/ui/hooks/use-mask`
   - Exports: `useMask`, `UseMaskOptions`, `MaskOptions`, `Replacement`, `Track`, `TrackingData`, `Modify`, `ModifiedData`
-  - Notes: thin wrapper over `@react-input/mask`'s `useMask` that defaults `replacement` to `{ 9: /\d/, a: /[A-Za-z]/, '*': /./ }`; returns a `MutableRefObject<HTMLInputElement>` to attach to any input. Consumers may override `replacement`.
+  - Notes: thin wrapper over `@react-input/mask`'s `useMask` that defaults `replacement` to `{ _: /\d/, '#': /[A-Za-z]/, '*': /./ }`; returns a `MutableRefObject<HTMLInputElement>` to attach to any input. Consumers may override `replacement`.
 - `utils`
   - Import path: `@uselets/ui/utils`
   - Exports: `cn`, `randomId`
 - `color`
   - Import path: `@uselets/ui/lib/color`
   - Exports: `uiColors`, `UIColor`, `selectionControlColorVariants`
-  - Notes: canonical public color list used by `Button`, `Toggle`, `Checkbox`, `RadioGroupItem`, and `Switch`; `ButtonColor` is a compatibility alias for `UIColor`; `selectionControlColorVariants` is an internal styling map for checked selection controls
+  - Notes: canonical public color list used by `Button`, `Toggle`, `Checkbox`, `RadioGroupItem`, and `Switch`; `ButtonColor` (exported from `@uselets/ui/lib/button`, not this module) is a compatibility alias for `UIColor`; `selectionControlColorVariants` is an internal styling map for checked selection controls
 - `compose-refs`
   - Import path: `@uselets/ui/lib/compose-refs`
   - Exports: `composeRefs`, `setRef`
@@ -119,7 +119,7 @@ Unless noted otherwise, each module also exports its public `*Props` types from
   - Exports: `Empty`, `EmptyContent`, `EmptyDescription`, `EmptyHeader`, `EmptyMedia`, `EmptyTitle`
 - `progress`
   - Exports: `Progress`, `progressVariants`
-  - Notes: linear progress bar driven by a single `value` (0–100); `size: 'sm' | 'md' | 'lg'` (default: `md`) controls bar height and `color: UIColor` (default: `primary`) controls the indicator
+  - Notes: linear progress bar driven by a single `value` (0–100); `size: 'sm' | 'md' | 'lg'` (default: `md`) controls bar height and `color: UIColor` (default: `primary`) controls the indicator; omitting `value` (or passing `null`) renders the indeterminate state
 - `ring-progress`
   - Exports: `RingProgress`, `ringProgressVariants`
   - Notes: circular progress indicator driven by a single `value` (0–100); `size: 'sm' | 'md' | 'lg'` (default: `md`, `32/40/48px`), `thickness: 'thin' | 'md' | 'thick'` (default: `md`), and `color: UIColor` (default: `primary`); normalized `viewBox` means the size can also be set via `className` (e.g. `size-5`); rounded line caps
@@ -132,8 +132,9 @@ Unless noted otherwise, each module also exports its public `*Props` types from
 ## Forms and input composition
 
 - `field`
-  - Exports: `Field`, `FieldContent`, `FieldDescription`, `FieldError`, `FieldGroup`, `FieldLabel`, `FieldLegend`, `FieldSeparator`, `FieldSet`, `FieldTitle`, `useFieldControlId`
-  - Notes: form layout and validation helpers; `Field` automatically provides a generated control id to `FieldLabel` and labelable descendants when explicit ids are omitted
+  - Exports: `Field`, `FieldContent`, `FieldDescription`, `FieldError`, `FieldGroup`, `FieldLabel`, `FieldLegend`, `FieldSeparator`, `FieldSet`, `FieldTitle`, `useFieldControlId`, `useFieldInvalid`, `useFieldLabelId`
+  - Notes: form layout and validation helpers; `Field` automatically provides a generated control id to `FieldLabel` and labelable descendants when explicit ids are omitted. One control per `Field`: a `RadioGroup` placed directly in a `Field` takes the `FieldLabel` as its group label (`aria-labelledby`) and its items keep their own ids; never put several `Checkbox`/`Switch` controls in one `Field` (they would share the control id) — use `FieldSet` + `FieldLegend` with one `Field` per control. `useFieldLabelId()` returns the current `FieldLabel` id (or `undefined` outside a `Field`) for custom group controls
+  - Invalid state: `Field.invalid?: boolean` (or legacy `data-invalid="true"`; `invalid` wins when both are set) renders `data-invalid="true"` (label/description turn destructive) and sets `aria-invalid` on the control inside. Styled red: `Input` (incl. `InputGroupInput`, `PhoneInput`), `Textarea`, `NativeSelect`, `SelectTrigger`, `ComboboxInput`, `ComboboxChipsInput`, `InputOTP` (+ slots), `NumberField`. `aria-invalid` only, no red style: `Checkbox`, `Switch`, `RadioGroup` (on the group). Not propagated: `Slider`, `DatePicker`/`DateRangePicker` triggers. A control's own `aria-invalid` (including `false`) overrides the `Field`. Do: `<Field invalid><FieldLabel/><Input/><FieldError/></Field>`. Don't: repeat `aria-invalid` on every control inside an invalid `Field`. Custom controls: `const invalid = useFieldInvalid(props['aria-invalid'])` → `aria-invalid={invalid}` (returns `undefined` outside a `Field`)
 - `grid`
   - Exports: `Grid`, `GridItem`
   - Notes: 12-column CSS grid by default. `Grid` supports spacing props plus direct `templateRows` and `templateColumns`; spacing values `xs` to `xl` map to `4/8/16/24/32px`; `GridItem` defaults to `colSpan={12}` and supports numeric `colSpan` and `rowSpan`. Use `useBreakpointValue` when these values need to change by breakpoint.
@@ -163,15 +164,16 @@ Unless noted otherwise, each module also exports its public `*Props` types from
   - Notes: international phone input built on `react-phone-number-input`, composed from the existing `Input` and `Combobox` (country select, with flags); matches `Input`'s styling and single size (no `variant`/size prop). `value` / `onChange` use the E.164 `Value` string from `react-phone-number-input`; `defaultCountry` defaults to `BR`.
 - `checkbox`
   - Exports: `Checkbox`
-  - Notes: supports `size: 'sm' | 'md' | 'lg'`, `color: UIColor` (default `primary`), `label?: React.ReactNode`, `labelProps`, and automatic `id`/`htmlFor` wiring when a label is provided without an explicit `id`; composed label text follows checkbox size (`sm` 12px, `md` 14px, `lg` 20px)
+  - Notes: supports `size: 'sm' | 'md' | 'lg'`, `color: UIColor` (default `primary`), `indeterminate?: boolean` for the mixed state (use it alongside a boolean `checked`; `checked="indeterminate"` is not supported), `label?: React.ReactNode`, `labelProps`, and automatic `id`/`htmlFor` wiring when a label is provided without an explicit `id`; composed label text follows checkbox size (`sm` 12px, `md` 14px, `lg` 18px); `description?: React.ReactNode` + `descriptionProps` render muted helper text (a `<p>`) below the label, linked via `aria-describedby`; description text is `sm` 12px, `md` 12px, `lg` 14px
 - `switch`
   - Exports: `Switch`
-  - Notes: supports `size: 'sm' | 'md' | 'lg'`, `color: UIColor` (default `green`), `label?: React.ReactNode`, `labelProps`, and automatic `id`/`htmlFor` wiring when a label is provided without an explicit `id`; `color` controls the checked track and indicator color only; track size is `sm` 34x16px, `md` 42x20px, and `lg` 48x22px; the thumb and internal indicator scale with the switch; composed label text follows switch size (`sm` 14px, `md` 16px, `lg` 18px)
+  - Notes: supports `size: 'sm' | 'md' | 'lg'`, `color: UIColor` (default `green`), `label?: React.ReactNode`, `labelProps`, and automatic `id`/`htmlFor` wiring when a label is provided without an explicit `id`; `color` controls the checked track and indicator color only; track size is `sm` 30x14px, `md` 34x16px, and `lg` 42x20px (control heights match `Checkbox`); the thumb and internal indicator scale with the switch; composed label text follows switch size (`sm` 12px, `md` 14px, `lg` 18px (same as `Checkbox` and `RadioGroupItem`)); `description?: React.ReactNode` + `descriptionProps` render muted helper text (a `<p>`) below the label, linked via `aria-describedby`; description text is `sm` 12px, `md` 12px, `lg` 14px
 - `radio-group`
   - Exports: `RadioGroup`, `RadioGroupItem`
-  - Notes: `RadioGroup` supports `color: UIColor` (default `primary`) for the group; `RadioGroupItem` supports `size: 'sm' | 'md' | 'lg'`, optional `color: UIColor` item overrides, `label?: React.ReactNode`, `labelProps`, and automatic `id`/`htmlFor` wiring when a label is provided without an explicit `id`; composed label text follows item size (`sm` 12px, `md` 14px, `lg` 20px)
+  - Notes: `RadioGroup` supports `color: UIColor` (default `primary`) for the group; `RadioGroupItem` supports `size: 'sm' | 'md' | 'lg'`, optional `color: UIColor` item overrides, `label?: React.ReactNode`, `labelProps`, and automatic `id`/`htmlFor` wiring when a label is provided without an explicit `id`; composed label text follows item size (`sm` 12px, `md` 14px, `lg` 18px); `description?: React.ReactNode` + `descriptionProps` render muted helper text (a `<p>`) below the label, linked via `aria-describedby`; description text is `sm` 12px, `md` 12px, `lg` 14px
 - `select`
   - Exports: `Select`, `SelectContent`, `SelectGroup`, `SelectItem`, `SelectLabel`, `SelectScrollDownButton`, `SelectScrollUpButton`, `SelectSeparator`, `SelectTrigger`, `SelectValue`
+  - Notes: pass `items` to `Select` (array of `{ value, label }` or a `value → label` record) whenever item labels differ from their values — otherwise `SelectValue` shows the raw value. `SelectTrigger.size: 'sm' | 'md'`; `SelectContent` accepts `side`, `sideOffset`, `align`, `alignOffset`, and `alignItemWithTrigger` (default `true`). `onValueChange` may receive `null`.
 - `native-select`
   - Exports: `NativeSelect`, `NativeSelectOptGroup`, `NativeSelectOption`
 - `combobox`
@@ -188,6 +190,7 @@ Unless noted otherwise, each module also exports its public `*Props` types from
   - Notes: compound popover picker using `Calendar` range mode with two months; draft changes from fixed presets, relative-day inputs, date inputs, and calendar stay synchronized until apply; reset and applied clear emit `null` through `onValueChange`; preset buttons show selected state when the draft range matches by calendar day
 - `slider`
   - Exports: `Slider`
+  - Notes: `onValueChange` receives `number | readonly number[]` (an array when `value`/`defaultValue` is an array)
 - `label`
   - Exports: `Label`
 - `toggle`
@@ -195,22 +198,28 @@ Unless noted otherwise, each module also exports its public `*Props` types from
   - Notes: `secondary`, `outline`, and `ghost` variants; supports `color: UIColor` using the same color variants as `Button`
 - `toggle-group`
   - Exports: `ToggleGroup`, `ToggleGroupItem`
-  - Notes: shares `toggleVariants` with `Toggle` (`secondary`, `outline`, `ghost`)
+  - Notes: shares `toggleVariants` with `Toggle` (`secondary`, `outline`, `ghost`); single-selection by default, set `multiple` for multi-selection. `value`/`defaultValue`/`onValueChange` always use string arrays (no `type="single" | "multiple"`)
 
 ## Overlays and floating UI
 
 - `dialog`
   - Exports: `Dialog`, `DialogBody`, `DialogClose`, `DialogContent`, `DialogDescription`, `DialogFooter`, `DialogHeader`, `DialogOverlay`, `DialogPortal`, `DialogTitle`, `DialogTrigger`
-  - Notes: `Dialog` supports `size: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | 'full'` with default `md`; `full` occupies the entire viewport. `DialogContent` caps its height at `calc(100dvh - 2rem)` and lays out children as a flex column. For long content, wrap the middle in `DialogBody` (`flex-1 overflow-y-auto`) so the body scrolls while `DialogHeader` and `DialogFooter` remain pinned; for short content, omit `DialogBody`. `DialogContent.showCloseButton` defaults to `true`; `DialogFooter.showCloseButton` defaults to `false`. `Dialog.dismissible` defaults to `true`; set it to `false` to prevent closing via outside click and Esc (the close button and `DialogClose` still work). `DialogOverlay` and `DialogContent` stop `click`/`submit` propagation to ancestor elements by default, since Radix portals move them elsewhere in the DOM but React still propagates their synthetic events through the component tree
+  - Notes: `Dialog` supports `size: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | 'full'` with default `md`; `full` occupies the entire viewport. `DialogContent` caps its height at `calc(100dvh - 2rem)` and lays out children as a flex column. For long content, wrap the middle in `DialogBody` (`flex-1 overflow-y-auto`) so the body scrolls while `DialogHeader` and `DialogFooter` remain pinned; for short content, omit `DialogBody`. `DialogContent.showCloseButton` defaults to `true`; `DialogFooter.showCloseButton` defaults to `false`. `Dialog.dismissible` defaults to `true`; set it to `false` to prevent closing via outside click and Esc (the close button and `DialogClose` still work). `DialogOverlay` and `DialogContent` stop `click`/`submit` propagation to ancestor elements by default, since portals move them elsewhere in the DOM but React still propagates their synthetic events through the component tree
+- `direction`
+  - Exports: `DirectionProvider`, `useDirection`, types `DirectionProviderProps`, `TextDirection`
+  - Notes: `DirectionProvider.direction: 'ltr' | 'rtl'` (default `'ltr'`) sets the text direction for keyboard navigation (`Tabs`, `ToggleGroup`, `RadioGroup`, `DropdownMenu`), `Slider`, `ScrollArea`, `Select`, `NavigationMenu`, `Combobox` and popup positioning. A `dir` prop/attribute on those components does not change their behavior; wrap the RTL subtree (or the app) in `DirectionProvider` and also set `dir` on the HTML for text layout. `useDirection()` reads the current direction
 - `drawer`
   - Exports: `Drawer`, `DrawerBody`, `DrawerClose`, `DrawerContent`, `DrawerDescription`, `DrawerFooter`, `DrawerHeader`, `DrawerOverlay`, `DrawerPortal`, `DrawerTitle`, `DrawerTrigger`
-  - Notes: `Drawer` supports `size: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | 'full'` with default `md`; `DrawerBody` provides padded auto-scroll content; `DrawerFooter` stacks actions on mobile and aligns them to the end on larger breakpoints; `DrawerContent.showCloseButton` controls the automatic close button and defaults to `true`. `Drawer.dismissible` defaults to `true`; set it to `false` to prevent closing via outside click and Esc (the close button and `DrawerClose` still work). `Drawer.direction: 'top' | 'right' | 'bottom' | 'left'` (default: `right`) controls which edge the drawer slides in from. `DrawerOverlay` and `DrawerContent` stop `click`/`submit` propagation to ancestor elements by default, since Radix portals move them elsewhere in the DOM but React still propagates their synthetic events through the component tree
+  - Notes: `Drawer` supports `size: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | 'full'` with default `md`; `DrawerBody` provides padded auto-scroll content; `DrawerFooter` stacks actions on mobile and aligns them to the end on larger breakpoints; `DrawerContent.showCloseButton` controls the automatic close button and defaults to `true`. `Drawer.dismissible` defaults to `true`; set it to `false` to prevent closing via outside click and Esc (the close button and `DrawerClose` still work). `Drawer.direction: 'top' | 'right' | 'bottom' | 'left'` (default: `right`) controls which edge the drawer slides in from. `DrawerOverlay` and `DrawerContent` stop `click`/`submit` propagation to ancestor elements by default, since portals move them elsewhere in the DOM but React still propagates their synthetic events through the component tree
 - `popover`
-  - Exports: `Popover`, `PopoverAnchor`, `PopoverContent`, `PopoverDescription`, `PopoverHeader`, `PopoverTitle`, `PopoverTrigger`
+  - Exports: `Popover`, `PopoverClose`, `PopoverContent`, `PopoverDescription`, `PopoverHeader`, `PopoverTitle`, `PopoverTrigger`
+  - Notes: `PopoverContent` accepts `side`, `sideOffset`, `align`, `alignOffset`, and `anchor` (element, ref, or virtual element) to position against something other than the trigger; there is no `PopoverAnchor` component. `Popover.modal: boolean | 'trap-focus'` (default `false`) traps focus only when a `PopoverClose` (supports `asChild`) is rendered inside `PopoverContent`; without it, `modal` still blocks outside clicks and page scroll but `Tab` leaves the popup. Hide the close with `className="sr-only"` when there is no visible close button
 - `hover-card`
   - Exports: `HoverCard`, `HoverCardTrigger`, `HoverCardContent`
+  - Notes: open/close timing lives on `HoverCardTrigger` (`delay` default `700`, `closeDelay` default `300`)
 - `dropdown-menu`
   - Exports: `DropdownMenu`, `DropdownMenuCheckboxItem`, `DropdownMenuContent`, `DropdownMenuGroup`, `DropdownMenuItem`, `DropdownMenuLabel`, `DropdownMenuPortal`, `DropdownMenuRadioGroup`, `DropdownMenuRadioItem`, `DropdownMenuSeparator`, `DropdownMenuShortcut`, `DropdownMenuSub`, `DropdownMenuSubContent`, `DropdownMenuSubTrigger`, `DropdownMenuTrigger`
+  - Notes: use `onClick` on `DropdownMenuItem` to react to selection (there is no `onSelect`); every part (trigger, content, items, label, sub trigger…) accepts `asChild`; `DropdownMenuCheckboxItem`/`DropdownMenuRadioItem` keep the menu open on toggle by default; pass `closeOnClick` to close it
 
 ## Navigation
 
@@ -221,8 +230,10 @@ Unless noted otherwise, each module also exports its public `*Props` types from
   - Exports: `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis`
 - `command`
   - Exports: `Command`, `CommandDialog`, `CommandInput`, `CommandList`, `CommandEmpty`, `CommandGroup`, `CommandItem`, `CommandShortcut`, `CommandSeparator`
+  - Notes: `CommandDialog` accepts the `Dialog` props and defaults to `size="sm"` (plain `Dialog` defaults to `md`)
 - `navigation-menu`
-  - Exports: `NavigationMenu`, `NavigationMenuList`, `NavigationMenuItem`, `NavigationMenuContent`, `NavigationMenuTrigger`, `NavigationMenuLink`, `NavigationMenuIndicator`, `NavigationMenuViewport`, `navigationMenuTriggerStyle`
+  - Exports: `NavigationMenu`, `NavigationMenuList`, `NavigationMenuItem`, `NavigationMenuContent`, `NavigationMenuTrigger`, `NavigationMenuLink`, `NavigationMenuIndicator`, `NavigationMenuPositioner`, `navigationMenuTriggerStyle`
+  - Notes: `NavigationMenu` renders `NavigationMenuPositioner` automatically (forwarding `align`); there is no `viewport` prop. Place `NavigationMenuIndicator` inside a `NavigationMenuItem`. `NavigationMenuLink` supports `active`, `asChild` and `closeOnClick` (default `false`: the menu stays open after a click; pass it for client-side routing). It has no `onSelect`; use `onClick`
 - `pagination`
   - Exports: `Pagination`, `PaginationContent`, `PaginationEllipsis`, `PaginationItem`, `PaginationLink`, `PaginationNext`, `PaginationPrevious`
   - Notes: `Pagination` highlights the current page and keeps other links neutral. `Pagination.color` (a `UIColor`, default `primary`) controls only the current page's color. Each `PaginationLink`/`PaginationPrevious`/`PaginationNext` can still pass its own `color`, but `Pagination`'s wins when set.
@@ -240,6 +251,7 @@ Unless noted otherwise, each module also exports its public `*Props` types from
 
 - `accordion`
   - Exports: `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`
+  - Notes: single-item expansion by default; set `multiple` to allow several open items. `value`/`defaultValue` are string arrays (no `type`/`collapsible` props — items can always be collapsed)
 - `avatar`
   - Exports: `Avatar`, `AvatarBadge`, `AvatarFallback`, `AvatarGroup`, `AvatarGroupCount`, `AvatarImage`
 - `card`
@@ -247,11 +259,14 @@ Unless noted otherwise, each module also exports its public `*Props` types from
   - Notes: supports `size: 'sm' | 'md' | 'lg'` with default `md`
 - `carousel`
   - Exports: `Carousel`, `CarouselContent`, `CarouselItem`, `CarouselPrevious`, `CarouselNext`, `CarouselIndicators`, `useCarousel`
+  - `Carousel` renders `role="region"` with `aria-roledescription="carousel"`; give it an accessible name with `aria-label`.
+  - Keyboard: arrows navigate along the orientation (`ArrowLeft`/`ArrowRight` horizontal, swapped when `opts.direction === 'rtl'`; `ArrowUp`/`ArrowDown` vertical). Arrows are left alone inside text fields and when a control in the slide already called `preventDefault`.
+  - `CarouselPrevious`/`CarouselNext`: a consumer `onClick` runs before scrolling; call `event.preventDefault()` to skip the scroll. Default accessible names are English ("Previous slide"/"Next slide") — translate with `aria-label`. Indicators default to "Go to slide N" — translate with `getIndicatorProps={(index) => ({ 'aria-label': ... })}`.
 - `center`
   - Exports: `Center`, `centerVariants`
 - `chart`
   - Exports: `ChartContainer`, `ChartLegend`, `ChartLegendContent`, `ChartStyle`, `ChartTooltip`, `ChartTooltipContent`, `ChartConfig`, `ChartColorKey`, `CHART_COLOR_KEYS`, `DEFAULT_CHART_PALETTE`, `resolveChartColor`
-  - Notes: low-level chart primitives. For app usage prefer the high-level `area-chart`, `bar-chart`, `pie-chart`, `donut-chart` modules. Import raw recharts primitives (`Bar`, `XAxis`, etc.) directly from `recharts` when composing with `ChartContainer`. `ChartColorKey` is the union of theme color tokens accepted by every high-level chart (`primary | brand | gray | zinc | red | yellow | green | blue | indigo | pink`) and resolves to `var(--{key}-500)` via `resolveChartColor`.
+  - Notes: low-level chart primitives. For app usage prefer the high-level `area-chart`, `bar-chart`, `pie-chart`, `donut-chart` modules. Import raw recharts primitives (`Bar`, `XAxis`, etc.) directly from `recharts` when composing with `ChartContainer`. `ChartColorKey` is the union of theme color tokens accepted by every high-level chart (`primary | brand | gray | zinc | red | yellow | green | blue | indigo | pink`) and resolves to the semantic token `var(--{key})` (step 500 in light mode, 400 in dark) via `resolveChartColor`; any other string passes through unchanged.
 - `area-chart`
   - Exports: `AreaChart`, `AreaChartSeries`, `AreaChartType`, `AreaChartCurveType`, `AreaChartGridAxis`
   - Notes: high-level area chart. Pass `data`, `series` (array of `{ name, label?, color?, colorKey? }`), and `dataKey` (X axis field). Supports `type` (default/stacked/percent/split), `curveType`, `withXAxis`, `withYAxis`, `gridAxis`, `withDots`, `withTooltip`, `withLegend`. Use `colorKey: ChartColorKey` for theme colors (`'blue'`, `'primary'`, etc.) or `color` for raw CSS values; explicit `color` wins. Defaults to chart colors `--chart-1..5`. Pass `areaProps` to spread props (e.g. `onClick`) onto each underlying recharts `<Area>`. Pass `areaChartProps` to spread props (e.g. `margin`) onto the wrapping recharts `<AreaChart>`.
@@ -298,7 +313,7 @@ Unless noted otherwise, each module also exports its public `*Props` types from
   - Exports: `DataTable`, `DataTableRoot`, `DataTableToolbar`, `DataTableHeader`, `DataTableBody`, `DataTablePagination`, `DataTableColumnHeader`, `createDataTableSelectColumn`, `useDataTable`, `useDataTableContext`, `defaultDataTableLabels`, `DataTableLabels`, `UseDataTableOptions`, `DataTableRootProps`, `DataTableToolbarProps`
   - Notes: dual API — high-level `DataTable` (monolithic, simple cases) and compound (`DataTableRoot` + sub-parts, power cases including virtualization). Both share the same underlying logic via `useDataTable`.
   - **High-level `DataTable`:** client-side TanStack Table composition. Defaults are bare — `enableRowSelection`, `enableSorting`, `showPagination` all default to `false` and must be explicitly enabled. Setting `enableRowSelection` auto-prepends the selection column; setting `enableSorting` activates sort buttons in `DataTableColumnHeader`. `filterColumns` accepts `string | string[]`; with 2+ ids the toolbar renders an `InputGroup` with a column selector at the left. `toolbarActions` always renders at the right of the toolbar. `variant` (`"line"` default | `"outline"`) is forwarded to the internal `Table` — pass `"outline"` to wrap the table in a rounded border. All user-facing labels default to pt-BR and are overridable through the `labels` prop (`Partial<DataTableLabels>`)
-  - **Compound API:** `DataTableRoot` accepts either `{ columns, data, ...options }` (uncontrolled — creates the `table` instance internally) or `{ table }` (controlled — table instance comes from `useDataTable` called by the consumer). `DataTableToolbar`, `DataTableHeader`, `DataTableBody`, and `DataTablePagination` read the `table` instance from context. `DataTableHeader` renders a full `<thead>`; `DataTableBody` renders a full `<tbody>` — to virtualize, omit `<DataTableBody />` and render your own `<tbody>` instead. `useDataTable(options)` is a thin wrapper around `useReactTable` that bakes in the same defaults `DataTable` uses (row models, selection auto-injection); pass `enablePagination: false` when virtualizing so `table.getRowModel()` returns all rows. `useDataTableContext<TData>()` retrieves the current `table` and merged `labels` inside a custom compound child
+  - **Compound API:** `DataTableRoot` accepts either `{ columns, data, ...options }` (uncontrolled — creates the `table` instance internally) or `{ table }` (controlled — table instance comes from `useDataTable` called by the consumer). `DataTableToolbar`, `DataTableHeader`, `DataTableBody`, and `DataTablePagination` read the `table` instance from context. Uncontrolled `DataTableRoot` paginates automatically while a `DataTablePagination` is mounted inside it (explicit `enablePagination` wins); `useDataTable` defaults to `enablePagination: false`. Changing `pageSize` applies the new size and returns to the first page. Removing a column from `filterColumns` clears its filter. `DataTableHeader` renders a full `<thead>`; `DataTableBody` renders a full `<tbody>` — to virtualize, omit `<DataTableBody />` and render your own `<tbody>` instead. `useDataTable(options)` is a thin wrapper around `useReactTable` that bakes in the same defaults `DataTable` uses (row models, selection auto-injection); pass `enablePagination: false` when virtualizing so `table.getRowModel()` returns all rows. `useDataTableContext<TData>()` retrieves the current `table` and merged `labels` inside a custom compound child
   - **Virtualization:** the package is virtualizer-agnostic — it has zero runtime dependency on `@tanstack/react-virtual`. Bring your own virtualizer (TanStack Virtual, `react-window`, `virtua`, or manual). See the *Virtualized lists* section in `references/package-guide.md` for the canonical TanStack Virtual recipe
 - `timeline`
   - Exports: `Timeline`, `TimelineConnector`, `TimelineContent`, `TimelineDescription`, `TimelineEmpty`, `TimelineHeader`, `TimelineIcon`, `TimelineItem`, `TimelineTime`, `TimelineTitle`, `timelineVariants`