@boxcustodia/library 2.0.0-alpha.13 → 2.0.0-alpha.14

package/src/__doc__/V2.mdx

@@ -0,0 +1,1246 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Documentation/Guía de Migración v1 → v2" />
+
+# Migración v1 → v2
+
+Si venís usando `@boxcustodia/library@1.x`, esta guía te lleva paso a paso a `2.x`. Aplicá los cambios en orden y deberías quedar funcional.
+
+---
+
+## Instalación
+
+v2 todavía está en alpha. Instalá con el tag `@next`:
+
+```bash
+npm i @boxcustodia/library@next
+```
+
+La librería trae todo lo que necesita para funcionar. No tenés que instalar peers manualmente.
+
+### Instalá el MCP de v2
+
+El MCP (Model Context Protocol) le da a Claude acceso directo a la documentación de los componentes de v2: props, variantes, ejemplos y patrones. Sin él, Claude inventa props y genera código que no funciona contra esta librería. Ver la página **Documentation/MCP** para detalles (incluye la instrucción opcional para `CLAUDE.md`).
+
+```bash
+npx mcp-add --type http \
+  --url "https://v2--69de51f0642746d263d5c46f.chromatic.com/mcp" \
+  --client-id "cdf3737dff9d485485968e50b63fd8b4" \
+  --scope global \
+  --clients "claude code"
+```
+
+Se instala una vez por máquina (global). El instalador pregunta el server name — respondé `boxcustodia-library`; los otros prompts quedan vacíos. La primera consulta abre el browser para autenticar contra Chromatic (pedile acceso a Franco si no lo tenés).
+
+### Actualizá el import del CSS
+
+v2 expone un subpath estable para el CSS. Cambiá el `@import` en tu `index.css`:
+
+```diff filename="index.css"
+  @import "tailwindcss";
+- @import "@boxcustodia/library/dist/index.css";
++ @import "@boxcustodia/library/styles";
+```
+
+---
+
+## Migración de Radix UI a Base UI
+
+v2 reemplaza **Radix UI** por **[Base UI](https://base-ui.com)** como capa de primitivos. Este cambio trae dos breaking changes globales que aplican a todos los componentes.
+
+### 1. `asChild` → prop `render`
+
+Base UI no usa el patrón `asChild`. Para renderizar un componente propio en lugar del elemento por defecto, usá la prop `render`:
+
+```diff
+- <DialogTrigger asChild>
+-   <Button>Abrir</Button>
+- </DialogTrigger>
++ <DialogTrigger render={<Button>Abrir</Button>} />
+```
+
+### 2. `onChange` → `onValueChange`
+
+Base UI renombra los callbacks de control. El prop `onChange` desaparece — reemplazalo por `onValueChange`. Los demás siguen igual pero ahora reciben `eventDetails` como segundo argumento:
+
+```diff
+- <Select value={value} onChange={(v) => setValue(v)} />
++ <Select value={value} onValueChange={(v) => setValue(v)} />
+```
+
+Firmas completas de Base UI:
+
+```ts
+onValueChange: (value, eventDetails) => void
+onOpenChange: (open, eventDetails) => void
+onPressedChange: (pressed, eventDetails) => void
+```
+
+---
+
+## Componentes eliminados
+
+Los siguientes componentes fueron removidos en v2:
+
+- `BackgroundImage`
+- `Heading`
+- `MultiSelect`
+- `Show`
+- `TablePagination`
+
+---
+
+## Componentes nuevos
+
+- `Accordion`
+- `Alert`
+- `CheckboxGroup`
+- `DateInput`
+- `OTP`
+- `Progress`
+- `RadioGroup`
+- `ScrollArea`
+
+---
+
+## Subpaths públicos disponibles
+
+- `@boxcustodia/library` — componentes, hooks, utilidades.
+- `@boxcustodia/library/styles` — CSS principal (theme + variantes + estilos de componentes).
+
+---
+
+## Nuevo patrón de composición y estilado
+
+v2 cambia la forma de extender componentes. Estos dos cambios aplican a **todos los composites** de la librería (Autocomplete, Combobox, Select, Dialog, AlertDialog, etc.), no a un componente puntual.
+
+### 1. Se eliminan los `xProps` pass-through
+
+En v1, los composites exponían props pass-through tipo `triggerProps`, `contentProps`, `inputProps`, `popupProps`, `itemProps`, etc. para reenviar atributos al primitivo correspondiente.
+
+```diff
+- <Dialog
+-   triggerProps={{ className: "..." }}
+-   contentProps={{ onEscapeKeyDown: handler, className: "..." }}
+-   titleProps={{ className: "..." }}
+- >
+-   Hola
+- </Dialog>
+```
+
+**Por qué se elimina:**
+
+- **Abstracción que filtra.** Para usar `contentProps` el consumer tiene que conocer el primitivo subyacente, qué props acepta y qué se le omitió. Es decir, ya pagó el costo cognitivo del primitivo — el composite dejó de aportar valor.
+- **Falso intermedio.** Si necesitás tocar 3+ pass-through props, ya estás reescribiendo la composición a mano — solo que con peor ergonomía que usando los primitivos directamente.
+- **Mantenimiento.** Cada cambio en un primitivo se propagaba al tipo del composite y multiplicaba la matriz de casos a probar.
+- **Duplicación de API.** Cada composite terminaba clonando la API de N primitivos prop por prop.
+
+**Qué hacer en su lugar:**
+
+- Para **cambios de estilo** → usá la nueva prop `classNames` (ver abajo).
+- Para **cambios de comportamiento, estructura o props no triviales** → usá los primitivos directamente. Cada componente exporta sus primitivos (`DialogTrigger`, `DialogContent`, `AutocompletePopup`, etc.) y la composición es la API extendida real.
+
+```diff
++ // Estructura custom: usá primitivos directamente
++ <DialogRoot>
++   <DialogTrigger render={<Button variant="outline" />}>Abrir</DialogTrigger>
++   <DialogPortal>
++     <DialogBackdrop />
++     <DialogPopup onEscapeKeyDown={handler}>
++       <DialogTitle>Hola</DialogTitle>
++     </DialogPopup>
++   </DialogPortal>
++ </DialogRoot>
+```
+
+### 2. Nuevo escape hatch de estilado: `classNames`
+
+Para el 80% de los casos de customización (solo CSS) v2 introduce una prop `classNames` namespaceada por slot. Reemplaza a las props sueltas `containerClassName`, `inputClassName`, `listClassName`, `itemClassName`, etc. que existían en v1.
+
+```diff
+- <Autocomplete
+-   containerClassName="w-72"
+-   inputClassName="h-12"
+-   listClassName="max-h-60"
+-   itemClassName="py-2"
+-   emptyClassName="italic"
+- />
++ <Autocomplete
++   className="w-72 h-12"
++   classNames={{
++     popup: "max-h-60",
++     item: "py-2",
++     empty: "italic",
++   }}
++ />
+```
+
+**Convención:**
+
+- `className` → estilá el elemento principal del composite (el campo visible, el trigger, etc.).
+- `classNames` → objeto con un slot por cada parte interna estilable.
+
+**Por qué este patrón y no props sueltas:**
+
+- **API plana y predecible.** Un solo prop adicional (`classNames`) en lugar de N props con el sufijo `ClassName`.
+- **Consistencia entre componentes.** Mismo shape en `Autocomplete`, `Combobox`, `Select`, `Dialog`, etc. — aprendés una vez.
+- **Autocompletado.** TypeScript expone los slots disponibles al destructurar el objeto.
+- **Extensible.** Agregar un slot nuevo no rompe nada.
+- **No es escape hatch de comportamiento.** `classNames` solo toca estilo — para comportamiento, primitivos.
+
+Los slots disponibles están documentados en la página de cada componente.
+
+---
+
+## Componentes
+
+Breaking changes específicos por componente.
+
+### 1. Dialog
+
+`xProps` eliminadas — usá `className` y `classNames` (ver [patrón global](#nuevo-patrón-de-composición-y-estilado)).
+
+Slots de `classNames` disponibles: `backdrop`, `viewport`, `header`, `title`, `description`, `footer`, `closeButton`.
+
+**`DialogContent` → `DialogPopup`** (rename del primitive — Base UI usa `Popup` como naming). Si componés con primitivos, actualizá:
+
+```diff
+- import { DialogRoot, DialogTrigger, DialogContent } from "@boxcustodia/library";
++ import { DialogRoot, DialogTrigger, DialogPopup } from "@boxcustodia/library";
+```
+
+**`trigger: ReactNode → ReactElement`.** v1 aceptaba cualquier `ReactNode`; v2 exige un `ReactElement` porque Base UI usa `render={trigger}` y necesita un componente para clonar props:
+
+```diff
+- <Dialog trigger="Open">…</Dialog>
++ <Dialog trigger={<Button>Open</Button>}>…</Dialog>
+```
+
+### 2. AlertDialog
+
+Migrado al nuevo patrón — se eliminaron los `xProps` pass-through (ver sección [Nuevo patrón de composición y estilado](#nuevo-patrón-de-composición-y-estilado)). Para estilo, usá `className` y `classNames`. Para cambios estructurales (layout custom, slots extra), usá los primitivos.
+
+Slots de `classNames` disponibles: `backdrop`, `header`, `title`, `description`, `footer`, `closeButton`, `actionButton`.
+
+### 3. Autocomplete
+
+**Renombrado.** `AutoComplete` → `Autocomplete` (la `C` mayúscula del medio queda en minúscula). Actualizá los imports:
+
+```diff
+- import { AutoComplete } from "@boxcustodia/library";
++ import { Autocomplete } from "@boxcustodia/library";
+```
+
+Migrado al nuevo patrón — se eliminaron los `xProps` pass-through (ver sección [Nuevo patrón de composición y estilado](#nuevo-patrón-de-composición-y-estilado)). Para estilo, usá `className` y `classNames`. Para cambios estructurales (layout custom, slots extra, búsqueda async, grupos), usá los primitivos.
+
+Slots de `classNames` disponibles: `popup`, `list`, `item`, `empty`, `status`.
+
+**`onSelect` eliminado.** La prop `onSelect: (value: string, item: AutoCompleteItem) => any` ya no existe. Usá `onValueChange` para controlar la selección:
+
+```diff
+- <Autocomplete onSelect={(value, item) => handleSelect(value, item)} />
++ <Autocomplete onValueChange={(item) => handleSelect(item)} />
+```
+
+`onValueChange` recibe el item completo (o `null` cuando se limpia el campo).
+
+### 4. Avatar
+
+Migrado al nuevo patrón — se eliminaron los `xProps` pass-through (ver sección [Nuevo patrón de composición y estilado](#nuevo-patrón-de-composición-y-estilado)). Para estilo, usá `className` y `classNames`. Para cambios estructurales (layout custom, slots extra), usá los primitivos.
+
+Slots de `classNames` disponibles: `image`, `fallback`, `badge`.
+
+**`variant` eliminada.** v1 controlaba la forma con `variant: "circle" | "square"`. v2 no acepta variante — todos los avatares son circulares por defecto. Para esquinas cuadradas, override con `className`:
+
+```diff
+- <Avatar variant="square" src={src} alt={alt} />
++ <Avatar className="rounded-xl" src={src} alt={alt} />
+```
+
+### 5. Button
+
+**`asChild` eliminado.** Base UI no usa `asChild` (ver sección [Migración de Radix UI a Base UI](#migración-de-radix-ui-a-base-ui)). Para renderizar un elemento custom, usá la prop `render`:
+
+```diff
+- <Button asChild><a href="/foo">Ir</a></Button>
++ <Button render={<a href="/foo">Ir</a>} />
+```
+
+Si lo que querés es aplicar los estilos del botón a otro componente, importá `buttonVariants` y componé las clases:
+
+```tsx
+import { buttonVariants } from "@boxcustodia/library";
+
+<a href="/foo" className={buttonVariants({ variant: "outline" })}>
+  Ir
+</a>;
+```
+
+**`showLoader` eliminado.** El loader se activa automáticamente cuando `onClick` devuelve una `Promise`. Para deshabilitarlo, pasá un `onClick` sincrónico:
+
+```diff
+- <Button showLoader={false} onClick={async () => await save()}>Guardar</Button>
++ <Button onClick={() => { void save(); }}>Guardar</Button>
+```
+
+**`iconPosition` eliminado.** La posición del ícono ahora se controla con el atributo `data-icon` en el elemento del ícono:
+
+```diff
+- <Button icon={<TrashIcon />} iconPosition="inline-end">Borrar</Button>
++ <Button icon={<TrashIcon data-icon="inline-end" />}>Borrar</Button>
+```
+
+Valores aceptados: `inline-start` (default) o `inline-end`.
+
+**`shape` eliminado.** Para esquinas custom, override con `className="rounded-..."`.
+
+**`loaderReplace` y `append` eliminados.** El loader siempre **reemplaza** el contenido (efecto antes conocido como `loaderReplace`). El efecto `append` (loader al lado del contenido) ya no se soporta.
+
+### 6. Checkbox
+
+`xProps` eliminadas — usá `className` y `classNames` (ver [patrón global](#nuevo-patrón-de-composición-y-estilado)).
+
+**`onChange` → `onCheckedChange`** (convención Base UI para binario):
+
+```diff
+- <Checkbox checked={value} onChange={setValue} />
++ <Checkbox checked={value} onCheckedChange={setValue} />
+```
+
+**`size` eliminada.** Customizá el tamaño con `className` o estilos:
+
+```diff
+- <Checkbox size="lg" />
++ <Checkbox className="size-5" />
+```
+
+### 7. Calendar
+
+`Calendar` en v2 es un wrapper fino sobre [`react-day-picker`](https://daypicker.dev) (`DayPicker`). El componente adopta su API nativa, lo que implica varios breaking changes respecto a v1.
+
+**Props de selección renombradas.** El par `value` / `onChange` se reemplaza por `selected` / `onSelect`:
+
+```diff
+- <Calendar mode="single" value={date} onChange={setDate} />
++ <Calendar mode="single" selected={date} onSelect={setDate} />
+
+- <Calendar mode="range" value={range} onChange={setRange} />
++ <Calendar mode="range" selected={range} onSelect={setRange} />
+
+- <Calendar mode="multiple" value={dates} onChange={setDates} />
++ <Calendar mode="multiple" selected={dates} onSelect={setDates} />
+```
+
+**Shape de `DateRange` cambió.** v1 usaba `{ start, end }`; DayPicker usa `{ from, to }`. Actualizá los datos al construir y leer:
+
+```diff
+- interface DateRange {
+-   start: Date | null;
+-   end: Date | null;
+- }
++ interface DateRange {
++   from?: Date;
++   to?: Date;
++ }
+
+- <Calendar mode="range" selected={{ start, end }} />
++ <Calendar mode="range" selected={{ from: start, to: end }} />
+```
+
+Tipos de `selected` por modo (vienen de `react-day-picker`):
+
+- `single` → `Date | undefined`
+- `range` → `{ from?: Date; to?: Date } | undefined`
+- `multiple` → `Date[] | undefined`
+
+**Props `view`, `initialView` y `onChangeView` eliminadas.** v1 navegaba entre la grilla de días, la selección de mes y la selección de año con un patrón propio (`view: "month" | "year" | "decade"`). v2 usa el `captionLayout` de `DayPicker` (default `"dropdown"`) — los meses y años se navegan con un dropdown en la cabecera, no con cambios de vista.
+
+```diff
+- <Calendar view="month" onChangeView={setView} initialView="day" />
++ <Calendar captionLayout="dropdown" />
+```
+
+Valores aceptados: `"label" | "dropdown" | "dropdown-months" | "dropdown-years"`.
+
+**Prop `initialDate` eliminada.** Reemplazada por `defaultMonth` (prop nativa de DayPicker) — controla el mes que se muestra al montar el calendario.
+
+```diff
+- <Calendar initialDate={new Date(2025, 0, 1)} />
++ <Calendar defaultMonth={new Date(2025, 0, 1)} />
+```
+
+**Prop `disabled` con semántica más amplia.** v1 solo aceptaba una función `(date: Date) => boolean`. v2 acepta el `Matcher` de DayPicker: función, `Date`, array de `Date`, rangos `{ from, to }`, días de semana `{ dayOfWeek: [0, 6] }`, etc. La forma de función sigue funcionando, pero ahora hay más opciones declarativas (ver [matchers de DayPicker](https://daypicker.dev/docs/selection-modes#disabled-dates)).
+
+**xProps eliminadas.** Las props pass-through del composite (`goBackProps`, `goNextProps`, `changeViewProps`, `monthViewProps`) ya no existen (ver sección [Nuevo patrón de composición y estilado](#nuevo-patrón-de-composición-y-estilado)). Para estilar, usá `className` (al root del calendario) y `classNames` (objeto namespaceado con los slots de `DayPicker`: `day`, `weekday`, `month`, `nav`, etc. — ver [docs de DayPicker](https://daypicker.dev/docs/styling#class-names)).
+
+**Sub-exports eliminados.** v1 exponía `MonthView`, `YearView`, `DecadeView`, `CalendarNavigation`, `useCalendar`, `useCalendarNavigation` y `CalendarContext` para composición custom. v2 los elimina — toda la composición interna queda en `DayPicker`. Si necesitabas algo de eso, usá los slots de `components` de DayPicker (`Day`, `MonthCaption`, etc.).
+
+### 8. Combobox
+
+`xProps` eliminadas — usá `className` y `classNames` (ver [patrón global](#nuevo-patrón-de-composición-y-estilado)).
+
+Slots de `classNames` disponibles: `input`, `chips`, `chipsInput`, `popup`, `list`, `item`, `empty`.
+
+**Props renombradas:**
+
+- `valueKey: string` → `getId: (item) => string`
+- `labelKey: string` → `getLabel: (item) => string`
+- `renderOption` → `renderItem`
+- `emptyMessage` → `emptyText`
+- `searchPlaceholder` → `placeholder`
+
+**Props eliminadas:**
+
+- `searchProps` — en modo `multiple` el input de búsqueda vive en el popup, no en el trigger.
+- `commandProps` — no tiene equivalente; el composite ya no envuelve `cmdk`. Para layouts custom, usá los primitives (`ComboboxRoot`, `ComboboxInput`, `ComboboxPopup`, etc.).
+
+Los string keys pasan a ser funciones tipadas contra el genérico `TItem`. Sirven para campos anidados o valores derivados. Para shapes comunes (`{ id, name }`, `{ label, value }`, primitivos) los defaults los resuelven sin pasar nada.
+
+`getId` reemplaza al `getValue` que existió en alphas previas — el nombre se eligió para reflejar el uso real (id para form value + React key) y evitar la colisión visual con la prop `value` del Combobox.
+
+**`onChange` → `onValueChange` (cambio semántico).** Antes `value` / `onChange` trabajaban con el **key** (`string`). Ahora `value` / `onValueChange` trabajan con el **item completo** (o `null` al limpiar). Actualizá el estado del consumer:
+
+```diff
+- const [selectedId, setSelectedId] = useState<string>("");
++ const [selected, setSelected] = useState<Fruit | null>(null);
+
+- <Combobox
+-   items={fruits}
+-   valueKey="id"
+-   labelKey="name"
+-   renderOption={(item) => item.name}
+-   emptyMessage="Sin resultados"
+-   value={selectedId}
+-   onChange={setSelectedId}
+- />
++ <Combobox
++   items={fruits}
++   // getId / getLabel se pueden omitir si fruits es { id, name } — defaults los resuelven
++   renderItem={(item) => item.name}
++   emptyText="Sin resultados"
++   value={selected}
++   onValueChange={setSelected}
++ />
+```
+
+### 9. Select
+
+`xProps` eliminadas — usá `className` (estiliza el trigger) y `classNames` (ver [patrón global](#nuevo-patrón-de-composición-y-estilado)).
+
+Slots de `classNames` disponibles: `popup`, `item`.
+
+**Props renombradas:**
+
+- `valueKey: string` → `getId: (item) => string`
+- `labelKey: string` → `getLabel: (item) => string`
+- `renderOption` → `renderItem`
+- `disabledItem` → `getDisabled` (alineado con la familia `get*`)
+
+Para shapes comunes (`{ id, name }`, `{ label, value }`, primitivos) los defaults resuelven todo — `getLabel`/`getId` solo hacen falta para shapes custom.
+
+**`onChange` → `onValueChange` (cambio semántico).** Mismo cambio que en Combobox: `value` / `onValueChange` ahora trabajan con el **item completo** (o `null`) en lugar del key. Si guardabas el id como string, ahora guardás el item:
+
+```diff
+- const [animalId, setAnimalId] = useState<string>("");
++ const [animal, setAnimal] = useState<Animal | null>(null);
+
+- <Select
+-   items={animals}
+-   valueKey="id"
+-   labelKey="name"
+-   value={animalId}
+-   onChange={setAnimalId}
+- />
++ <Select
++   items={animals}
++   value={animal}
++   onValueChange={setAnimal}
++ />
+```
+
+### 10. Dropzone
+
+Se agrega `classNames` para estilar los slots internos del composite (ver [patrón global](#nuevo-patrón-de-composición-y-estilado)).
+
+Slots de `classNames` disponibles: `trigger`, `icon`, `label`, `content`.
+
+**`asChild` eliminado de `DropzoneTrigger`.** Estaba marcado deprecated en v1. v2 usa solo la prop `render` (Base UI):
+
+```diff
+- <DropzoneTrigger asChild>
+-   <Button>Upload</Button>
+- </DropzoneTrigger>
++ <DropzoneTrigger render={<Button>Upload</Button>} />
+```
+
+**`onChangeFiles` → `onFilesChange`.** Renombrada para alinearse con la convención Base UI (`onValueChange`, `onOpenChange`, etc.):
+
+```diff
+- <Dropzone onChangeFiles={(files) => setFiles(files)} />
++ <Dropzone onFilesChange={(files) => setFiles(files)} />
+```
+
+### 11. DatePicker
+
+En v1, `DatePicker` era un input tipeable con popover de calendario. En v2 se divide en dos componentes con responsabilidades separadas:
+
+- **`DatePicker`** — trigger tipo botón que abre un popover con el calendario. Soporta tres modos vía discriminated union: `single`, `range`, `multiple`.
+- **`DateInput`** — nuevo componente para el caso "input tipeable con auto-máscara `DD/MM/YYYY`" que cubría el `DatePicker` de v1. Solo modo `single`.
+
+Si en v1 usabas `DatePicker` para escribir la fecha a mano, migrá a `DateInput`:
+
+```diff
+- <DatePicker value={date} onChange={setDate} />
++ <DateInput value={date} onValueChange={setDate} />
+```
+
+**`onChange` → `onValueChange`** (ver [Migración de Radix UI a Base UI](#migración-de-radix-ui-a-base-ui)).
+
+**Shape de `DateRange` cambió** — el modo `range` ahora trabaja con el shape de DayPicker `{ from, to }` (ver [Calendar](#6-calendar)). En el `DatePicker` el shape sigue siendo `{ start, end }` para no romper consumers, pero internamente se mapea a `{ from, to }` al pasar al `Calendar`.
+
+**Footer por defecto eliminado.** v1 renderizaba siempre un footer con botones `Borrar` / `Hoy` (controlable con `hideFooter`). v2 no renderiza ningún footer salvo que pases `renderFooter` explícito. Si querés el comportamiento anterior, implementalo via `renderFooter`:
+
+```diff
+- <DatePicker value={date} onChange={setDate} hideFooter />
++ <DatePicker mode="single" value={date} onValueChange={setDate} />
+
+- <DatePicker value={date} onChange={setDate} />
++ <DatePicker
++   mode="single"
++   value={date}
++   onValueChange={setDate}
++   renderFooter={({ clear, selectToday }) => (
++     <div className="flex justify-between">
++       <Button variant="ghost" onClick={clear}>Borrar</Button>
++       <Button variant="ghost" onClick={selectToday}>Hoy</Button>
++     </div>
++   )}
++ />
+```
+
+**`renderFooter` ahora recibe un discriminated union por `mode`.** `selectToday` solo existe en modo `single` — narrow `mode` antes de usarlo:
+
+```tsx
+renderFooter={(props) => {
+  if (props.mode !== "single") return null;
+  return <Button onClick={props.selectToday}>Hoy</Button>;
+}}
+```
+
+**Navegación del calendario interno cambió.** Las props `view`, `initialView`, `onChangeView` e `initialDate` del Calendar de v1 ya no existen — el popover navega meses y años con un dropdown en la cabecera (ver [Calendar](#6-calendar) para detalles).
+
+`xProps` eliminadas — usá `className` (estiliza el trigger) y `classNames` (ver [patrón global](#nuevo-patrón-de-composición-y-estilado)).
+
+Slots de `classNames` disponibles: `popup`, `calendar`, `footer`.
+
+### 12. Form
+
+**Cambio grande.** v1 era un wrapper sobre Radix Slot + `react-hook-form` + `zod`. v2 usa directamente la API nativa del navegador (Base UI Form): el form es un `<form>` real con validación nativa (`required`, `pattern`, `minLength`, etc.) y `FormData` parseada al submit. No hay schema, no hay context de RHF, no hay re-renders por keystroke.
+
+**`form` eliminado.** v1 esperaba el `UseFormReturn` de `react-hook-form` (que a su vez recibía un schema de zod). v2 no necesita ningún objeto externo: el estado vive en el DOM.
+
+```diff
+- const form = useForm(MySchema, { defaultValues });
+- <Form form={form} onSubmit={(data) => save(data)}>
++ <Form onFormSubmit={(data) => save(data)}>
+```
+
+**`onSubmit` → `onFormSubmit`** (convención Base UI). La firma cambia: ya no recibe el shape tipado del schema sino un `Record<string, unknown>` parseado desde `FormData`.
+
+```diff
+- <Form onSubmit={(data: MySchema) => save(data)} />
++ <Form onFormSubmit={(data, eventDetails) => save(data)} />
+```
+
+`preventDefault()` lo llama Base UI automáticamente cuando definís `onFormSubmit`.
+
+**Validación.** En v2 cada campo vive dentro de un `Field` con `name`, `error` (matchers `valueMissing`, `typeMismatch`, `patternMismatch`, etc.) y opcionalmente `validate`. Los errores de servidor entran por `Form.errors` (objeto `{ [name]: string }`) y se limpian automáticamente al editar el campo.
+
+```tsx
+<Form errors={serverErrors} onFormSubmit={save}>
+  <Field
+    name="email"
+    label="Email"
+    error={[
+      { message: "Email is required.", match: "valueMissing" },
+      { message: "Enter a valid email.", match: "typeMismatch" },
+    ]}
+  >
+    <Input type="email" required />
+  </Field>
+</Form>
+```
+
+**Validación con schema (zod) sin RHF.** Si querés mantener un schema como source of truth pero no necesitás reactividad entre campos, parseá los `formValues` con el helper `parseFormValues(schema, values)`. Devuelve `{ data, errors }` listos para alimentar el prop `errors` del Form:
+
+```tsx
+import {
+  Form,
+  Field,
+  Input,
+  Button,
+  parseFormValues,
+} from "@boxcustodia/library";
+import { useState } from "react";
+import { z } from "zod";
+
+const schema = z.object({
+  name: z.string().min(1, "Name is required."),
+  age: z.coerce.number().positive("Age must be positive."),
+});
+
+function Page() {
+  const [errors, setErrors] = useState({});
+
+  return (
+    <Form
+      errors={errors}
+      onFormSubmit={(values) => {
+        const { data, errors } = parseFormValues(schema, values);
+        setErrors(errors);
+        if (data) save(data);
+      }}
+    >
+      <Field name="name" label="Name">
+        <Input />
+      </Field>
+      <Field name="age" label="Age">
+        <Input />
+      </Field>
+      <Button type="submit">Submit</Button>
+    </Form>
+  );
+}
+```
+
+`data` es `null` cuando alguna validación falla — los mensajes ya viajaron a `errors` y se limpian automáticamente al editar cada campo.
+
+**Escape hatch: `HookForm` + `HookField`.** Para formularios con reactividad real (watchers, dependent fields, wizards multi-step), la librería sigue exponiendo wrappers sobre `react-hook-form`:
+
+```tsx
+import { HookForm, HookField, useHookForm } from "@boxcustodia/library";
+
+const form = useHookForm(MySchema, { defaultValues });
+
+<HookForm form={form} onFormSubmit={(data) => save(data)}>
+  <HookField
+    name="email"
+    label="Email"
+    render={(field) => <Input {...field} type="email" />}
+  />
+</HookForm>;
+```
+
+`HookField` envuelve `Controller` + `Field` — invalid y error se manejan solos.
+
+**Cuándo usar cada API:**
+
+- **Validación HTML simple** → `Form` + `Field` con matchers (`valueMissing`, `typeMismatch`, etc.).
+- **Schema (zod) sin reactividad** → `Form` + `parseFormValues(schema, values)` dentro de `onFormSubmit`.
+- **Watch / dependent fields / multi-step** → `HookForm` + `HookField` + `useHookForm`.
+
+### 13. Field
+
+**Reemplaza a `FormField`.** En v1 había un componente `FormField` que envolvía `Controller` de `react-hook-form` y renderizaba label + control + error automáticamente. Ese componente se eliminó. `Field` es el sucesor conceptual pero con una API distinta: no asume RHF, se integra opcionalmente con el `Form` nativo (Base UI), y usa el pattern de `children` en vez de un `render` callback.
+
+```diff
+- import { FormField } from "@boxcustodia/library";
+- <FormField
+-   name="email"
+-   label="Email"
+-   render={(field) => <Input {...field} type="email" />}
+- />
++ import { Field, Input } from "@boxcustodia/library";
++ <Field name="email" label="Email">
++   <Input type="email" required />
++ </Field>
+```
+
+Para mantener el flujo con `react-hook-form` + `zod`, usá `HookField` (ver [Form](#12-form)).
+
+**Integración con `Form`.** Cuando un `Field` con `name` vive dentro de un `Form`, los errores que llegan por el prop `errors` del Form se rutean automáticamente al Field por su `name` y se limpian solos cuando el usuario edita el campo. Ningún cableado manual:
+
+```tsx
+<Form errors={{ email: "Already taken." }}>
+  <Field name="email" label="Email">
+    <Input />
+  </Field>
+</Form>
+```
+
+**`error` cambia de tipo.** En v1, el error de `FormField` venía del `fieldState` de `react-hook-form` y se renderizaba en un `FormMessage` interno (no era una prop). En v2, `Field.error` es una prop tipada `FieldErrorProp` con tres formas:
+
+- `string` → siempre renderiza una vez que el field es inválido.
+- `{ message, match }` → renderiza sólo cuando la clave del `ValidityState` coincide (`valueMissing`, `typeMismatch`, `tooShort`, etc.).
+- `FieldErrorItem[]` → múltiples mensajes, cada uno con su propio `match`.
+
+```tsx
+<Field
+  name="email"
+  error={[
+    { message: "Email is required.", match: "valueMissing" },
+    { message: "Enter a valid email.", match: "typeMismatch" },
+  ]}
+>
+  <Input type="email" required />
+</Field>
+```
+
+`xProps` eliminadas — usá `className` (root) y `classNames` (ver [patrón global](#nuevo-patrón-de-composición-y-estilado)).
+
+Slots de `classNames` disponibles: `label`, `description`, `error`.
+
+### 14. Input
+
+**`onChange` → `onValueChange`** (convención Base UI para controles con `value: string`). El signature se mantiene `(value, event)` — primer argumento el string parseado, segundo el `ChangeEvent` nativo:
+
+```diff
+- <Input value={value} onChange={(v) => setValue(v)} />
++ <Input value={value} onValueChange={(v) => setValue(v)} />
+```
+
+Sin otros breaking changes.
+
+### 15. Empty
+
+**Renombrado.** `EmptyState` → `Empty`. Actualizá los imports:
+
+```diff
+- import { EmptyState } from "@boxcustodia/library";
++ import { Empty } from "@boxcustodia/library";
+```
+
+**Ícono por defecto cambió.** `FolderSearch` → `Inbox`. Si necesitás el anterior, pasalo explícito:
+
+```diff
+- <Empty />
++ <Empty icon={<FolderSearch />} />
+```
+
+Para estilar partes internas, usá `classNames` (ver [patrón global](#nuevo-patrón-de-composición-y-estilado)).
+
+Slots de `classNames` disponibles: `header`, `media`, `title`, `description`, `content`.
+
+### 16. Kbd
+
+**Variantes eliminadas.** Las props `size` (`default | sm | lg`) y `variant` (`default | error | outline | secondary`) ya no existen. v2 expone un único estilo. Para tamaños o colores custom, override con `className`:
+
+```diff
+- <Kbd variant="error" size="lg">⌘</Kbd>
++ <Kbd className="bg-error text-error-foreground text-lg px-4">⌘</Kbd>
+```
+
+También se eliminó el archivo `kbd.variants.ts` (`KbdVariants`) — no formaba parte del API público, pero si lo importabas directo del subpath ya no existe.
+
+### 17. Loader
+
+**`containerClassName` eliminada.** Se reemplaza por `classNames.container` (slot del wrapper externo). `className` sigue estilando el ícono — sin cambio de semántica:
+
+```diff
+- <Loader containerClassName="rounded-full bg-card p-2" />
++ <Loader classNames={{ container: "rounded-full bg-card p-2" }} />
+```
+
+La prop `center` se mantiene igual.
+
+### 18. Menu
+
+`contentProps` eliminada — usá `className` y `classNames` (ver [patrón global](#nuevo-patrón-de-composición-y-estilado)). Para customizaciones de comportamiento sobre el popup (`onEscapeKeyDown`, `onPointerDownOutside`, etc.), componé con los primitives exportados: `MenuRoot`, `MenuTrigger`, `MenuPopup`.
+
+Slot de `classNames` disponible: `popup`.
+
+**`shortcut` ahora es display-only.** En v1, cada item podía declarar `shortcut`, `onShortcut` y `shortcutOptions` — `MenuShortcut` registraba un keyboard handler real y disparaba el `onShortcut` cuando se presionaba la combinación. En v2, `shortcut` es un string que **solo se renderiza** dentro del item; no se captura ningún teclado. Si dependías del handler, reemplazalo con un listener propio (`useEffect` + `keydown`, o un hook de shortcuts):
+
+```diff
+- items={[
+-   {
+-     type: "item",
+-     label: "Save",
+-     shortcut: "Ctrl+S",
+-     onShortcut: handleSave,
+-   },
+- ]}
++ items={[
++   {
++     type: "item",
++     label: "Save",
++     shortcut: "Ctrl+S",
++     onSelect: handleSave,
++   },
++ ]}
++ // y registrá el atajo de teclado vos mismo en un useEffect
+```
+
+**`trigger` ahora exige un `ReactElement`.** v1 aceptaba cualquier `ReactNode` (strings, fragments, `null`); v2 requiere un elemento React real porque Base UI usa `render={trigger}` para clonar props sobre el componente:
+
+```diff
+- <Menu trigger="Open" items={...} />
++ <Menu trigger={<Button>Open</Button>} items={...} />
+```
+
+### 19. NumberInput
+
+**`onChange` → `onValueChange`** (convención Base UI). El callback recibe `number | null` — `null` cuando el campo está vacío o contiene un valor no parseable:
+
+```diff
+- <NumberInput value={value} onChange={(v) => setValue(v)} />
++ <NumberInput value={value} onValueChange={(v) => v !== null && setValue(v)} />
+```
+
+### 20. Password
+
+**`containerClassName` eliminada.** v1 dejaba estilar el wrapper externo via `containerClassName`. v2 lo absorbe en `className` y suma el slot `classNames.toggle` para el botón del ojo. La arquitectura interna cambió — el wrapper ahora carga todo el styling visual (borde, alto, focus ring) y el input pasa a ser transparente adentro — pero la API desde afuera se simplifica: `className` estila el field visible como hacía v1.
+
+```diff
+- <Password containerClassName="my-2" className="border-primary" />
++ <Password className="my-2 border-primary" />
+```
+
+**`onChange` → `onValueChange`** (convención Base UI, alineado con Input):
+
+```diff
+- <Password value={pwd} onChange={(v) => setPwd(v)} />
++ <Password value={pwd} onValueChange={(v) => setPwd(v)} />
+```
+
+Slots de `classNames`: `input` (texto interno, font / color del texto tipeado), `toggle` (botón del ojo).
+
+### 21. Popover
+
+`xProps` eliminadas — usá `className` y `classNames` (ver [patrón global](#nuevo-patrón-de-composición-y-estilado)). `triggerClassName` también se eliminó: pasá `className` al elemento dentro del `trigger`.
+
+Slot de `classNames` disponible: `viewport`.
+
+**`offset` → `sideOffset`.** v1 tenía una sola prop `offset` para el gap eje-side. v2 la separa: `sideOffset` (gap perpendicular al trigger en el eje del side) y `alignOffset` (desplazamiento paralelo en el eje del align). Si sólo usabas `offset`, mové el valor a `sideOffset`:
+
+```diff
+- <Popover offset={8}>…</Popover>
++ <Popover sideOffset={8}>…</Popover>
+```
+
+**`trigger: ReactNode → ReactElement`.** v1 aceptaba cualquier `ReactNode` (strings, fragments, `null`); v2 requiere un `ReactElement` porque Base UI usa `render={trigger}` y necesita un componente para clonar props.
+
+```diff
+- <Popover trigger="Open">…</Popover>
++ <Popover trigger={<Button>Open</Button>}>…</Popover>
+```
+
+**`triggerAsChild` eliminada.** Base UI no usa el patrón `asChild` (ver [Migración de Radix UI a Base UI](#migración-de-radix-ui-a-base-ui)). Si necesitás un render custom sobre el trigger, componé con el primitive y la prop `render`:
+
+```diff
+- <Popover trigger={<Button>Open</Button>} triggerAsChild={false} />
++ <PopoverRoot>
++   <PopoverTrigger render={<Button>Open</Button>} />
++   <PopoverPopup>…</PopoverPopup>
++ </PopoverRoot>
+```
+
+### 22. Skeleton
+
+**Drop de toda la API custom.** v1 exponía `width`, `height`, `isCircle` y `isLoading`. v2 sólo recibe `className` (más cualquier prop nativa de `div`).
+
+```diff
+- <Skeleton width="15ch" height="1rem" isCircle isLoading={loading} />
++ {loading && <Skeleton className="h-4 w-[15ch] rounded-full" />}
+```
+
+### 23. Stepper
+
+`xProps` eliminadas — usá `className` y `classNames` (ver [patrón global](#nuevo-patrón-de-composición-y-estilado)).
+
+Slots de `classNames` disponibles: `nav`, `item`, `trigger`, `indicator`, `title`, `description`, `separator`, `panel`, `content`.
+
+**`current` → `value`** y **`onChange` → `onValueChange`** (convención Base UI):
+
+```diff
+- <Stepper items={steps} current={step} onChange={(i) => setStep(i)} />
++ <Stepper items={steps} value={step} onValueChange={(i) => setStep(i)} />
+```
+
+**Pasaron a ser 1-indexed.** v1 numeraba los pasos desde `0` (`current={0}` = primer paso). v2 numera desde `1` (`value={1}` = primer paso). Actualizá los valores de estado:
+
+```diff
+- const [step, setStep] = useState(0);   // primer paso en v1
++ const [step, setStep] = useState(1);   // primer paso en v2
+```
+
+`defaultValue` también es 1-indexed.
+
+### 24. Switch
+
+`xProps` eliminadas — usá `className` y `classNames` (ver [patrón global](#nuevo-patrón-de-composición-y-estilado)).
+
+Slots de `classNames` disponibles: `wrapper`, `thumb`, `label`.
+
+**`onChange` → `onCheckedChange`** (convención Base UI para controles binarios). El callback ahora recibe `eventDetails` como segundo argumento:
+
+```diff
+- <Switch checked={on} onChange={(v) => setOn(v)} />
++ <Switch checked={on} onCheckedChange={(v) => setOn(v)} />
+```
+
+**`containerClassName` y `containerProps` eliminadas.** El wrapper externo ahora se estila vía `classNames.wrapper`:
+
+```diff
+- <Switch containerClassName="gap-4" />
++ <Switch classNames={{ wrapper: "gap-4" }} />
+```
+
+### 25. Table
+
+**xProps eliminadas.** v1 exponía pass-through completo (`theadProps`, `tbodyProps`, `trProps`, `thProps`, `tdProps`, `containerProps`) y un set paralelo de `*ClassName` (`theadClassName`, `tbodyClassName`, `trClassName`, `thClassName`, `tdClassName`, `containerClassName`). v2 los reemplaza por un único `classNames` namespaceado (ver [patrón global](#nuevo-patrón-de-composición-y-estilado)).
+
+```diff
+- <Table
+-   theadClassName="bg-muted/50"
+-   thClassName="uppercase"
+-   trClassName="odd:bg-muted/20"
+-   containerClassName="max-h-[500px]"
+- />
++ <Table
++   classNames={{
++     thead: "bg-muted/50",
++     th: "uppercase",
++     tr: "odd:bg-muted/20",
++     container: "max-h-[500px]",
++   }}
++ />
+```
+
+Slots de `classNames` disponibles: `container`, `thead`, `tbody`, `headerRow`, `tr`, `th`, `td`. **`tr` aplica sólo a filas del body**; para la fila del header usá `headerRow`. v1 aplicaba `trClassName` a las dos por bug — si dependías de eso, dividí en `headerRow` + `tr` con la misma clase.
+
+Para comportamientos que `classNames` no cubre (handlers en `<tr>`, refs, custom `tfoot`, layout no estándar), usá los primitives exportados: `TableRoot`, `TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell`, `TableFooter`, `TableCaption`.
+
+**`onDoubleClick` → `onRowDoubleClick`.** v1 usaba `onDoubleClick` (colisionaba con el handler nativo de React sobre `<table>`). v2 lo renombra para alinear con `onRowClick`:
+
+```diff
+- <Table onDoubleClick={(row) => openDetail(row)} />
++ <Table onRowDoubleClick={(row) => openDetail(row)} />
+```
+
+### 26. Tabs
+
+**Componentes renombrados.** Los hijos de `<Tabs>` adoptan el prefijo `Tabs*` (consistente con el root):
+
+```diff
+- import { Tabs, TabList, TabTrigger, TabContent } from "@boxcustodia/library";
++ import { Tabs, TabsList, TabsTab, TabsPanel } from "@boxcustodia/library";
+```
+
+- `TabList` → `TabsList`
+- `TabTrigger` → `TabsTab` (también exportado como `TabsTrigger`)
+- `TabContent` → `TabsPanel` (también exportado como `TabsContent`)
+
+**`variant` se mudó de `<Tabs>` a `<TabsList>`.** El indicator vive dentro del list — la prop pasa donde corresponde:
+
+```diff
+- <Tabs variant="background">
+-   <TabList>…</TabList>
+- </Tabs>
++ <Tabs>
++   <TabsList variant="background">…</TabsList>
++ </Tabs>
+```
+
+**Valores de `variant`:** `"default"` → `"underline"` (default actual). `"background"` se mantiene.
+
+**`onChange` → `onValueChange`** (convención Base UI):
+
+```diff
+- <Tabs value={tab} onChange={(v) => setTab(v)} />
++ <Tabs value={tab} onValueChange={(v) => setTab(v)} />
+```
+
+### 27. Tag
+
+**Variantes renombradas:**
+
+- `primary` → `default`
+- `borderless` → `ghost`
+
+```diff
+- <Tag variant="primary">…</Tag>
++ <Tag variant="default">…</Tag>
+
+- <Tag variant="borderless">…</Tag>
++ <Tag variant="ghost">…</Tag>
+```
+
+**Variante `success` eliminada.** Si la usabas, override con `className`:
+
+```diff
+- <Tag variant="success">Done</Tag>
++ <Tag className="bg-success/10 text-success">Done</Tag>
+```
+
+**`icon` eliminado.** v1 tenía slot dedicado para ícono. v2 acepta el ícono como children, posicionado vía atributo `data-icon`:
+
+```diff
+- <Tag icon={<Check />}>Approved</Tag>
++ <Tag><Check data-icon="inline-start" /> Approved</Tag>
+```
+
+Valores aceptados: `inline-start` (antes del texto) o `inline-end` (después).
+
+**`rounded` eliminado.** v2 siempre renderea pill (rounded total). Para otros radios usá `className`:
+
+```diff
+- <Tag rounded="square">…</Tag>
++ <Tag className="rounded-md">…</Tag>
+```
+
+**`color` eliminado.** v2 no acepta color libre — usá una variant o override con `className`:
+
+```diff
+- <Tag color="purple">…</Tag>
++ <Tag className="bg-purple-500 text-white">…</Tag>
+```
+
+**`closable` y `onClose` eliminados.** v2 no incluye botón de cerrar. Componé el patrón vos:
+
+```diff
+- <Tag closable onClose={handleRemove}>Item</Tag>
++ <Tag>
++   Item
++   <button data-icon="inline-end" onClick={handleRemove}>
++     <XIcon />
++   </button>
++ </Tag>
+```
+
+### 28. Textarea
+
+**`onChange` → `onValueChange`** (convención Base UI, alineado con Input). El callback ahora recibe `(value: string, event)` en lugar del event nativo. Si dependías del signature nativo, usá `onValueChange` con el segundo arg:
+
+```diff
+- <Textarea value={text} onChange={(e) => setText(e.target.value)} />
++ <Textarea value={text} onValueChange={(value) => setText(value)} />
+```
+
+### 29. Timeline
+
+**xProps eliminadas.** v1 exponía `itemsProps` (HTMLProps por item) y `containerProps` (HTMLProps del root). Ambas removidas — para comportamiento custom usá los primitives (`TimelineRoot`, `TimelineItem`, `TimelineHeader`, `TimelineIndicator`, `TimelineSeparator`, `TimelineTitle`, `TimelineDate`, `TimelineContent`).
+
+**Props `className*` consolidadas en `classNames`.** El root se estila con `className`; el resto con el objeto namespaceado:
+
+```diff
+- <Timeline
+-   classNameContainer="max-w-md"
+-   classNameItem="ms-10"
+-   classNameItemDot="bg-primary"
+-   classNameItemContent="text-xs"
+- />
++ <Timeline
++   className="max-w-md"
++   classNames={{
++     item: "ms-10",
++     indicator: "bg-primary",
++     content: "text-xs",
++   }}
++ />
+```
+
+Slots de `classNames` disponibles: `item`, `header`, `title`, `date`, `content`, `indicator`, `separator`.
+
+**Shape de `items` cambió.** v1: `{ content?, icon?, status?, color? }`. v2: `{ title?, content?, date?, indicator? }`.
+
+- `icon` → `indicator`
+- `status` (`done | pending | error`) eliminado. Usá `defaultValue` / `value` en el root para marcar el step activo; los pasos previos quedan completados automáticamente.
+- `color` eliminado. Override visual con `classNames.indicator`.
+
+```diff
+- <Timeline
+-   items={[
+-     { content: "Step 1", icon: <Check />, status: "done" },
+-     { content: "Step 2", icon: <Clock />, status: "pending", color: "amber" },
+-   ]}
+- />
++ <Timeline
++   value={1}
++   items={[
++     { title: "Step 1", content: "...", indicator: <Check /> },
++     { title: "Step 2", content: "...", indicator: <Clock /> },
++   ]}
++ />
+```
+
+### 30. Toast
+
+**`<Toaster />` eliminado.** El render layer ahora vive dentro de `<LibraryProvider>` (un único provider que configura toda la infraestructura de la lib — toasts, tooltips, etc.). Reemplazá el wrapper en la raíz de tu app:
+
+```diff
+- import { Toaster } from "@boxcustodia/library";
+-
+- export function App() {
+-   return (
+-     <>
+-       <Toaster />
+-       <Router />
+-     </>
+-   );
+- }
++ import { LibraryProvider } from "@boxcustodia/library";
++
++ export function App() {
++   return (
++     <LibraryProvider>
++       <Router />
++     </LibraryProvider>
++   );
++ }
+```
+
+Si necesitás un provider de Toast aislado (tests, microfrontends), el `<ToastProvider>` sigue exportado.
+
+**`type` → `variant`** (convención del resto de la lib):
+
+```diff
+- toast({ type: "info", title: "Saved" });
++ toast({ variant: "info", title: "Saved" });
+```
+
+**`type: "loading"` eliminado.** Para estados async usá `toast.promise()`:
+
+```diff
+- toast({ type: "loading", description: "Guardando..." });
++ toast.promise(saveData(), {
++   loading: { description: "Guardando..." },
++   success: () => ({ variant: "success", description: "Guardado!" }),
++   error:   (e) => ({ variant: "error",   description: e.message }),
++ });
+```
+
+**`duration` → `timeout`** (Base UI naming):
+
+```diff
+- toast({ description: "Saved", duration: 5000 });
++ toast({ description: "Saved", timeout: 5000 });
+```
+
+**`useToastStore` eliminado.** El store Zustand interno se reemplaza por la API imperativa `toast()` (funciona desde cualquier lado) o por `useToastManager()` (cuando necesitás acceder al manager como hook):
+
+```diff
+- import { useToastStore } from "@boxcustodia/library";
+- const addToast = useToastStore((s) => s.addToast);
+- addToast({ description: "Saved" });
++ import { toast } from "@boxcustodia/library";
++ toast({ description: "Saved" });
+```
+
+### 31. Tooltip
+
+**`label` → `content`** (rename — alinea con el resto de los composites: la prop que recibe el contenido del popup se llama `content`):
+
+```diff
+- <Tooltip label="Save changes"><Button>Save</Button></Tooltip>
++ <Tooltip content="Save changes"><Button>Save</Button></Tooltip>
+```
+
+**`asChild` eliminada.** Base UI no usa el patrón `asChild` (ver [Migración de Radix UI a Base UI](#migración-de-radix-ui-a-base-ui)). Pasá el trigger directo como children — el composite lo monta sobre `<TooltipTrigger render={...}>` automáticamente:
+
+```diff
+- <Tooltip label="Hint" asChild>
+-   <Button>Hover me</Button>
+- </Tooltip>
++ <Tooltip content="Hint">
++   <Button>Hover me</Button>
++ </Tooltip>
+```
+
+**`children` tightened.** v1 aceptaba cualquier `object`. v2 exige un `ReactElement` único porque Base UI clona el elemento via `render={children}`. Strings, fragments, arrays o `null` no funcionan más:
+
+```diff
+- <Tooltip label="Hint">Save</Tooltip>
++ <Tooltip content="Hint"><span>Save</span></Tooltip>
+```
+
+**`arrowClassName` → `classNames.arrow`** (consolidación al patrón global de slots):
+
+```diff
+- <Tooltip label="Hint" arrowClassName="text-primary">…</Tooltip>
++ <Tooltip content="Hint" classNames={{ arrow: "text-primary" }}>…</Tooltip>
+```
+
+### 32. Tree
+
+**Reescrito de raíz.** v1 estaba construido sobre `react-aria-components` y aceptaba un array recursivo `items: TreeNode[]` con `{ id, title, children }` que el componente paseaba solo. v2 está construido sobre [`@headless-tree/core`](https://headless-tree.lukasbach.com) — el consumer crea una **instancia** de tree (vía `useTree`) y se la pasa al componente. No hay equivalencia 1-a-1 entre las dos APIs: cambia el modelo mental, el shape de los datos, los hooks, el patrón de drag-and-drop y la composición.
+
+```diff
+- import { Tree } from "@boxcustodia/library";
+-
+- <Tree
+-   items={[
+-     { id: 1, title: "Folder", children: [
+-       { id: 2, title: "File", children: [] },
+-     ] },
+-   ]}
+- />
+
++ import { useTree } from "@headless-tree/core";
++ import { TreeRoot, TreeItem } from "@boxcustodia/library";
++
++ const tree = useTree<MyData>({ /* dataLoader, features, ... */ });
++
++ <TreeRoot tree={tree}>
++   {tree.getItems().map((item) => (
++     <TreeItem key={item.getId()} item={item} />
++   ))}
++ </TreeRoot>
+```
+
+### 33. Pagination
+
+**Reescrito como composite + primitivos.** La API es mayormente nueva; el layout por defecto del composite ahora coincide con el viejo `TablePagination` (size selector + "X – Y de Z" + prev / next), no con el layout numerado de v1. El layout numerado se reconstruye componiendo primitivos.
+
+**`TablePagination` eliminado.** Era un componente aparte en v1; en v2 quedó absorbido en el composite `Pagination`. Cambiá el import — el shape de props también cambia (ver más abajo):
+
+```diff
+- import { TablePagination } from "@boxcustodia/library";
++ import { Pagination } from "@boxcustodia/library";
+```
+
+**Props renombradas / cambiadas en `Pagination`:**
+
+- `initialCurrentPage` → `defaultCurrentPage`
+- `onChange` → `onCurrentPageChange` + `onPageSizeChange` (separadas)
+- `optionProps` y `containerProps` eliminadas — para customizar items, usá los primitives (`PaginationLink`, `PaginationPrevious`, `PaginationNext`, etc.)
+- `TABLE_PAGE_SIZES` eliminada — usá `PAGINATION_SIZES`
+
+```diff
+- <Pagination
+-   totalItems={100}
+-   pageSize={10}
+-   initialCurrentPage={1}
+-   onChange={(page) => setPage(page)}
+- />
++ <Pagination
++   totalItems={100}
++   defaultPageSize={10}
++   defaultCurrentPage={1}
++   onCurrentPageChange={(page) => setPage(page)}
++   onPageSizeChange={(size) => setSize(size)}
++ />
+```
+
+**Layout numerado** — reconstruí con primitivos:
+
+```tsx
+import {
+  PaginationRoot,
+  PaginationFirst,
+  PaginationPrevious,
+  PaginationPages,
+  PaginationNext,
+  PaginationLast,
+} from "@boxcustodia/library";
+
+<PaginationRoot totalItems={100} defaultPageSize={10}>
+  <PaginationFirst />
+  <PaginationPrevious />
+  <PaginationPages />
+  <PaginationNext />
+  <PaginationLast />
+</PaginationRoot>;
+```
+
+**Cambió mucho.** Si tu uso es no-trivial, lee la story `Components/Pagination` en Storybook — ahí están todos los modos (composite default, layout numerado, modo URL con `getPageHref` / `linkComponent`, overrides de textos via `texts`).