@boxcustodia/library 2.0.0-alpha.18 → 2.0.0-alpha.19

package/src/__doc__/V2.mdx

@@ -1,1281 +0,0 @@
-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>
-```
-
-**Props `icon` y `iconPosition` eliminadas.** Los íconos se componen directamente como `children` y la posición la define el orden en el JSX. Sin atributos extra ni configuración:
-
-```diff
-- <Button icon={<TrashIcon />}>Borrar</Button>
-+ <Button><TrashIcon />Borrar</Button>
-
-- <Button icon={<TrashIcon />} iconPosition="inline-end">Borrar</Button>
-+ <Button>Borrar<TrashIcon /></Button>
-```
-
-**`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 — la posición la define el orden en el JSX:
-
-```diff
-- <Tag icon={<Check />}>Approved</Tag>
-+ <Tag><Check /> Approved</Tag>
-```
-
-**`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 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>;
-```
-
----
-
-## Hooks
-
-### 1. useClipboard
-
-**API rediseñada de tupla a objeto.** En v1 el hook devolvía `[copiedText, copy]` — un string con el último valor copiado y la función de copia. En v2 devuelve un objeto con estado completo: `copied` (booleano que se resetea solo), `error` (Error si falla), `copy` y `reset`.
-
-**Cambios:**
-
-- Retorno: `[string | null, (text) => Promise<boolean>]` → `{ copy, reset, copied, error }`.
-- `copy` ya no es `async` ni devuelve `Promise<boolean>` — es fire-and-forget; inspeccioná `error` para detectar fallos.
-- `copied` se resetea automáticamente después de `timeout` ms (default `2000`). Configurable vía `useClipboard({ timeout })`.
-- Se agrega `reset()` para limpiar `copied` y `error` manualmente.
-
-```diff
-- const [copiedText, copy] = useClipboard();
-+ const { copy, copied, error, reset } = useClipboard({ timeout: 2000 });
-
-- <Button onClick={() => copy("hello")}>
--   {copiedText === "hello" ? "Copied!" : "Copy"}
-- </Button>
-+ <Button onClick={() => copy("hello")}>
-+   {copied ? "Copied!" : "Copy"}
-+ </Button>
-```
-
----
-
-### 2. useHover
-
-**`isHovering` → `hovered`.** Find-and-replace. Los callbacks `onHoverStart` / `onHoverEnd` siguen funcionando igual.
-
-```diff
-- const { ref, isHovering } = useHover<HTMLDivElement>();
-+ const { ref, hovered } = useHover<HTMLDivElement>();
-```