@boxcustodia/library 2.0.0-alpha.11 → 2.0.0-alpha.12

package/src/__doc__/Migration.mdx

@@ -0,0 +1,475 @@
+import { Meta, Source } from "@storybook/addon-docs/blocks";
+
+<Meta title="Documentation/Migration v1 → v2" />
+
+# Migración v1 → v2
+
+Esta guía te lleva paso a paso desde `@boxcustodia/library@1.x` hasta la versión estable de v2.
+
+---
+
+## 1. Version 2.0.0-alpha.6
+
+### Instalación
+
+```bash
+npm install @boxcustodia/library@2.0.0-alpha.6
+```
+
+### Cambios necesarios
+
+#### Provider
+
+El wrapper `Toaster` fue deprecado. Reemplazalo por `LibraryProvider`.
+
+```tsx
+// Antes
+import { Toaster } from "@boxcustodia/library";
+
+<Toaster />;
+```
+
+```tsx
+// Ahora
+import { LibraryProvider } from "@boxcustodia/library";
+
+<LibraryProvider>
+  <App />
+</LibraryProvider>;
+```
+
+---
+
+#### Avatar
+
+La prop `variant` fue renombrada a `shape`. Los valores no cambian.
+
+```tsx
+// Antes
+<Avatar variant="circle" />
+
+// Ahora
+<Avatar shape="circle" />
+```
+
+---
+
+#### Checkbox
+
+La prop `onChange` fue renombrada a `onCheckedChange`. `checked` y `defaultChecked` no cambian.
+
+```tsx
+// Antes
+<Checkbox onChange={(value) => setValue(value)} />
+
+// Ahora
+<Checkbox onCheckedChange={(value) => setValue(value)} />
+```
+
+Las siguientes props fueron eliminadas: `size`, `containerClassName`, `containerProps`.
+
+---
+
+#### Switch
+
+La prop `onChange` fue renombrada a `onCheckedChange`. `checked` y `defaultChecked` no cambian.
+
+```tsx
+// Antes
+<Switch onChange={(value) => setValue(value)} />
+
+// Ahora
+<Switch onCheckedChange={(value) => setValue(value)} />
+```
+
+Las siguientes props fueron eliminadas: `containerClassName`, `containerProps`. El control de estilos ahora es via `className`.
+
+---
+
+#### Kbd
+
+Las siguientes props fueron eliminadas: `size`, `variant`.
+
+---
+
+#### Skeleton
+
+Las props `width`, `height`, `isCircle` e `isLoading` fueron eliminadas. El control de tamaño y forma ahora es via `className`. Además, ya no acepta `children` — usá un ternario para controlar la visibilidad.
+
+```tsx
+// Antes
+<Skeleton width="200px" height="16px" isLoading={isLoading}>
+  <p>Contenido</p>
+</Skeleton>;
+
+// Ahora
+{
+  isLoading ? <Skeleton className="h-4 w-[200px]" /> : <p>Contenido</p>;
+}
+```
+
+---
+
+#### Dialog
+
+`DialogContent` fue renombrado a `DialogPopup`. La prop `trigger` cambió de `ReactNode` a `ReactElement`.
+
+Las siguientes props fueron eliminadas: `triggerProps`, `contentProps`, `contentClassName`, `headerProps`, `headerClassName`, `titleProps`, `titleClassName`, `descriptionProps`, `descriptionClassName`, `footerProps`, `footerClassName`, `focus`.
+
+---
+
+#### AlertDialog
+
+La prop `asChild` del composite fue eliminada — ya no es necesaria.
+
+---
+
+#### Tooltip
+
+La prop `label` fue renombrada a `content`. La prop `asChild` fue eliminada.
+
+```tsx
+// Antes
+<Tooltip label="Más información" asChild>
+  <button>Hover</button>
+</Tooltip>
+
+// Ahora
+<Tooltip content="Más información">
+  <button>Hover</button>
+</Tooltip>
+```
+
+---
+
+#### Toast
+
+La prop `type` fue renombrada a `variant` en las llamadas directas a `toast`.
+
+```tsx
+// Antes
+toast({ type: "error", description: "Algo salió mal" });
+
+// Ahora
+toast({ variant: "error", description: "Algo salió mal" });
+```
+
+---
+
+La API de `toast.promise` cambió. Ahora cada estado recibe un objeto con las props del toast en lugar de un string directo.
+
+```tsx
+// Antes
+toast.promise(mockSuccessPromise(), {
+  loading: "Guardando...",
+  success: (data) => data.message || "Guardado correctamente",
+  error: (error) => error.message || "Error al guardar",
+});
+```
+
+```tsx
+// Ahora
+toast.promise(saveData(), {
+  loading: { description: "Guardando..." },
+  success: (data) => ({
+    variant: "success",
+    description: data.message || "Guardado correctamente",
+  }),
+  error: (error) => ({
+    variant: "error",
+    description: error.message || "Error al guardar",
+  }),
+});
+```
+
+---
+
+#### Componentes nuevos
+
+Se agregaron los siguientes componentes. No requieren ningún cambio en tu código existente.
+
+- **Alert** — notificaciones y mensajes de estado inline.
+- **CheckboxGroup** — agrupa múltiples checkboxes con manejo de estado unificado.
+- **Progress** — barra de progreso determinada e indeterminada.
+
+---
+
+## 2. Version 2.0.0-alpha.7
+
+### Instalación
+
+```bash
+npm install @boxcustodia/library@2.0.0-alpha.7
+```
+
+### Cambios necesarios
+
+#### Field
+
+Las siguientes props fueron eliminadas: `labelClassName`, `labelProps`, `errorClassName`, `errorProps`.
+
+La prop `error` cambió de `ReactNode` a `string | { message: ReactNode; match: FieldErrorMatch }`.
+
+```tsx
+// Antes
+<Field error={<span>Campo requerido</span>} />
+
+// Ahora
+<Field error="Campo requerido" />
+```
+
+---
+
+#### Input
+
+La integración con `ThemeProvider` fue eliminada. El control de estilos ahora es via `className`.
+
+---
+
+#### Password
+
+La prop `containerClassName` fue eliminada. Usá `className` para estilizar el input directamente, y un wrapper externo para controlar el contenedor.
+
+---
+
+## 3. Version 2.0.0-alpha.8
+
+### Instalación
+
+```bash
+npm install @boxcustodia/library@2.0.0-alpha.8
+```
+
+### Cambios necesarios
+
+#### Form
+
+La API de `Form` cambió completamente. El componente ya no tiene acoplamiento con React Hook Form — ahora es agnóstico a cualquier estrategia de validación (HTML nativo, Zod, server actions, RHF, etc.).
+
+**Si querés migrar a la nueva API**, revisá la story **Components/Form** en Storybook para ver los distintos modos de uso.
+
+**Si no querés migrar todavía**, copiá el código desde la story **Form → WithReactHookForm** (tab "Show code") en un archivo de tu proyecto, por ejemplo `src/components/form/form.tsx`. El snippet ya exporta los helpers con los mismos nombres que usabas — `useForm`, `Form` y `FormField` — así que solo tenés que cambiar los imports:
+
+```tsx
+// Antes
+import { useForm, Form, FormField } from "@boxcustodia/library";
+
+// Ahora
+import { useForm, Form, FormField } from "@/components/form/form";
+```
+
+El resto de tu código no necesita ningún cambio.
+
+---
+
+## 4. Version 2.0.0-alpha.10
+
+### Instalación
+
+```bash
+npm install @boxcustodia/library@2.0.0-alpha.10
+```
+
+### Cambios necesarios
+
+#### Calendar
+
+El componente `Calendar` fue completamente reescrito usando `react-day-picker` en lugar de una implementación custom. La API cambió significativamente:
+
+**Props eliminadas:**
+
+- `initialView` — el calendar ahora solo soporta modo month.
+- `view` / `onChangeView` — no hay control de vista (month/year/decade).
+- `initialDate` — usá las props nativas de `react-day-picker`.
+- `monthViewProps` — usá `classNames` para customizar estilos.
+- `goBackProps`, `goNextProps`, `changeViewProps` — los controles de navegación son internos.
+
+**Props nuevas (de react-day-picker):**
+
+- `mode` — `"single"`, `"multiple"`, `"range"`.
+- `captionLayout` — `"dropdown"` o `"buttons"` para seleccionar mes/año.
+- `classNames` — object con clases para cada parte del calendar.
+- `components` — customizar componentes internos (Dropdown, Chevron).
+- `startMonth` / `endMonth` — rango de meses navegables.
+
+```tsx
+// Antes
+<Calendar
+  initialView="month"
+  disabled={(date) => date.getDay() === 0}
+  goBackProps={{ className: "custom" }}
+/>
+
+// Ahora
+<Calendar
+  mode="single"
+  disabled={(date) => date.getDay() === 0}
+  captionLayout="dropdown"
+  classNames={{ button_previous: "custom" }}
+/>
+```
+
+---
+
+#### Popover
+
+El componente `Popover` fue completamente reescrito usando Base UI en lugar de Radix. La API cambió significativamente:
+
+**Props renombradas:**
+
+- `contentClassName` → `popupClassName`
+- `contentProps` → `popupProps`
+
+**Props eliminadas:**
+
+- `triggerAsChild` — el comportamiento ahora es el predeterminado. Usá `render` en lugar de `asChild`.
+- `triggerClassName` — pasá `className` al elemento dentro del `render`.
+- `offset` — se divide en dos props: `sideOffset` (brecha vertical/horizontal) y `alignOffset` (desplazamiento perpendicular).
+
+**Cambios en el tipo de `trigger`:**
+
+- Antes: `ReactNode`
+- Ahora: `ReactElement` (se pasa directamente, no envuelto).
+
+```tsx
+// Antes
+<Popover trigger={<Button>Open</Button>} contentClassName="w-80">
+  Content
+</Popover>
+
+// Ahora
+<Popover trigger={<Button>Open</Button>} popupClassName="w-80">
+  Content
+</Popover>
+```
+
+**Offset → sideOffset + alignOffset:**
+
+```tsx
+// Antes
+<Popover offset={8}>Content</Popover>
+
+// Ahora
+<Popover sideOffset={8} alignOffset={0}>Content</Popover>
+```
+
+**Primitivas con `render`:**
+
+Si usabas `PopoverTrigger` con `asChild`, reemplazá con `render`:
+
+```tsx
+// Antes
+<PopoverTrigger asChild>
+  <Button>Open</Button>
+</PopoverTrigger>
+
+// Ahora
+<PopoverTrigger render={<Button>Open</Button>} />
+```
+
+---
+
+#### DatePicker
+
+El componente ahora soporta múltiples modos y cambió de API internamente.
+
+**Props eliminadas:**
+
+- `hideFooter` — usá `renderFooter` para controlar completamente el pie.
+
+**Props nuevas:**
+
+- `mode` — `"single"`, `"range"`, `"multiple"` para seleccionar el tipo de picker.
+
+```tsx
+// Antes
+<DatePicker value={date} onChange={setDate} hideFooter />
+
+// Ahora
+<DatePicker mode="single" value={date} onChange={setDate} renderFooter={() => null} />
+```
+
+**Si necesitás un date picker editable:** Usá el nuevo componente `DateInput` que permite escribir la fecha directamente en el input además de seleccionar desde el calendar.
+
+---
+
+## 5. Version 2.0.0-alpha.11
+
+### Instalación
+
+```bash
+npm install @boxcustodia/library@2.0.0-alpha.11
+```
+
+### Cambios necesarios
+
+#### Combobox
+
+El Combobox fue completamente reescrito usando Base UI en lugar de la arquitectura anterior. La API es significativamente diferente. Ahora soporta selección múltiple con chips dinámicos y una arquitectura de primitivas para casos de uso avanzados.
+
+**Props renombradas:**
+
+- `valueKey` → `getValue` (ahora una function `(item) => string`)
+- `labelKey` → `getLabel` (ahora una function `(item) => string`)
+- `renderOption` → `renderItem`
+- `emptyMessage` → `emptyText`
+- `searchPlaceholder` → `placeholder`
+- `triggerProps` → `inputProps` (single) o `chipsProps` (multiple)
+- `contentProps` → `popupProps`
+
+**Props eliminadas:**
+
+- `searchProps` — en modo multiple, el input ahora está en el popup
+- `commandProps` — no necesario con la nueva arquitectura
+- `contentClassName` — usá `popupProps` con `className`
+
+**Props nuevas:**
+
+- `multiple?: boolean` — habilita modo múltiple con chips dinámicos
+- `getLabel: (item: TItem) => string` — extraer label del item
+- `getValue: (item: TItem) => string` — extraer valor del item
+- `renderItem?: (item: TItem) => ReactNode` — customizar contenido de cada item
+- `showClear?: boolean` — mostrar botón clear (default `true`)
+- `listProps?: ComponentProps` — customizar lista
+- `itemProps?: ComponentProps` — customizar items
+
+**Cambios de comportamiento:**
+
+En single select, el input está en el trigger. En multiple select, los chips se renderizan en el trigger y el input para búsqueda va en el popup. Los chips se ajustan dinámicamente al ancho del contenedor — si no caben, muestran "+N más".
+
+```tsx
+// Antes (single select)
+<Combobox
+  items={fruits}
+  valueKey="id"
+  labelKey="name"
+  renderOption={(item) => item.name}
+  value={selected}
+  onChange={(val) => setSelected(val)}
+/>
+
+// Ahora (single select)
+<Combobox
+  items={fruits}
+  getLabel={(item) => item.name}
+  getValue={(item) => item.id}
+  renderItem={(item) => item.name}
+  value={selected}
+  onChange={(item) => setSelected(item)}
+/>
+
+// Ahora (multiple select - NUEVO)
+<Combobox
+  items={fruits}
+  multiple
+  getLabel={(item) => item.name}
+  getValue={(item) => item.id}
+  placeholder="Select fruits…"
+  value={selectedFruits}
+  onChange={setSelectedFruits}
+/>
+```
+
+**Para casos avanzados:** Si los props de escape-hatch no son suficientes, usá las primitivas directamente: `ComboboxRoot`, `ComboboxInput`, `ComboboxChips`, `ComboboxChipsInput`, `ComboboxPopup`, `ComboboxList`, etc.
+
+---

package/src/__doc__/Theme.mdx

@@ -0,0 +1,132 @@
+import {
+  Canvas,
+  ColorItem,
+  ColorPalette,
+  Meta,
+  Source,
+} from "@storybook/addon-docs/blocks";
+import { BorderRadius } from "./Examples";
+
+<Meta title="Documentation/Theme" />
+
+# Theme
+
+La librería permite la customización de los estilos mediante variables CSS y la personalización detallada de cada componente usando slots.
+
+## Personalización mediante Slots
+
+Cada componente de la librería está construido con una arquitectura basada en slots, lo que permite una personalización detallada de cada parte del componente a nivel global. Los slots son identificados mediante el atributo `data-slot` en los elementos HTML subyacentes.
+
+### Cómo personalizar usando Slots
+
+Puedes sobrescribir los estilos de cualquier slot utilizando selectores CSS que apunten al atributo `data-slot`. Esta personalización se puede aplicar globalmente en tu archivo CSS principal o dentro de un módulo CSS.
+
+#### Ejemplo: Personalizando un Dialog
+
+```css
+/* En tu archivo index.css */
+[data-slot="input"] {
+  @apply h-12 rounded-xl border-primary; /* Aplica estilos a todos los inputs */
+}
+
+[data-slot="dialog-content"] {
+  @apply rounded-3xl;  /* Aplica bordes más redondeados a todos los dialog */
+}
+```
+
+## Border Radius
+
+Estos son los bordes redondeados por defecto. Se puede customizar `--radius`. La clase `rounded` es equivalente a la mitad del valor de `--radius`
+
+<BorderRadius />
+
+## Paleta de colores
+
+Colores por defecto de la librería. Se puede customizar con las variables css
+
+<ColorPalette>
+  <ColorItem
+    title="color.primary"
+    subtitle="Primary Colors"
+    colors={{
+      Primary: "var(--color-primary)",
+      PrimaryForeground: "var(--color-primary-foreground)",
+    }}
+  />
+  <ColorItem
+    title="color.secondary"
+    subtitle="Secondary Colors"
+    colors={{
+      Secondary: "var(--color-secondary)",
+      SecondaryForeground: "var(--color-secondary-foreground)",
+    }}
+  />
+  <ColorItem
+    title="color.error"
+    subtitle="Error Colors"
+    colors={{
+      error: "var(--color-error)",
+      errorForeground: "var(--color-error-foreground)",
+    }}
+  />
+  <ColorItem
+    title="color.success"
+    subtitle="Success Colors"
+    colors={{
+      Success: "var(--color-success)",
+      SuccessForeground: "var(--color-success-foreground)",
+    }}
+  />
+  <ColorItem
+    title="color.muted"
+    subtitle="Muted Colors"
+    colors={{
+      Muted: "var(--color-muted)",
+      MutedForeground: "var(--color-muted-foreground)",
+    }}
+  />
+  <ColorItem
+    title="color.accent"
+    subtitle="Accent Colors"
+    colors={{
+      Accent: "var(--color-accent)",
+      AccentForeground: "var(--color-accent-foreground)",
+    }}
+  />
+  <ColorItem
+    title="color.popover"
+    subtitle="Popover Colors"
+    colors={{
+      Popover: "var(--color-popover)",
+      PopoverForeground: "var(--color-popover-foreground)",
+    }}
+  />
+  <ColorItem
+    title="color.background"
+    subtitle="Background Colors"
+    colors={{
+      Background: "var(--color-background)",
+    }}
+  />
+  <ColorItem
+    title="color.foreground"
+    subtitle="Foreground Colors"
+    colors={{
+      Foreground: "var(--color-foreground)",
+    }}
+  />
+  <ColorItem
+    title="color.input"
+    subtitle="Input Colors"
+    colors={{
+      Input: "var(--color-input)",
+    }}
+  />
+  <ColorItem
+    title="color.ring"
+    subtitle="Ring Colors"
+    colors={{
+      Ring: "var(--color-ring)",
+    }}
+  />
+</ColorPalette>