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

package/src/utils/form.tsx

@@ -1,55 +1,78 @@
-// @ts-nocheck
-// biome-ignore-all lint: utility wrappers require flexible typings
 import { zodResolver } from "@hookform/resolvers/zod";
 import type { ComponentProps, ReactNode } from "react";
 import {
+  Controller,
   type ControllerRenderProps,
+  type FieldPath,
   type FieldValues,
   FormProvider,
-  type Path,
   type RegisterOptions,
   useForm as rhfUseForm,
   type SubmitHandler,
   type UseFormProps,
   type UseFormReturn,
-  useController,
+  useFormContext,
 } from "react-hook-form";
-import type { z } from "zod";
+import { z } from "zod";
+import { Field, type FieldProps, Form as LibraryForm } from "../components";
 
-import { Field, type FieldProps } from "../components/field";
-import { Form as LibraryForm } from "../components/form";
-
-// ── useForm ───────────────────────────────────────────────────────────────────
+/**
+ * Validates `formValues` from `Form.onFormSubmit` against a Zod schema and
+ * returns `{ data, errors }` ready to wire back into `Form`'s `errors` prop.
+ *
+ * - `data` is the typed, parsed value, or `null` when validation fails.
+ * - `errors` is the flattened `fieldErrors` object (empty on success).
+ */
+export function parseFormValues<T extends z.ZodType>(
+  schema: T,
+  values: Record<string, unknown>,
+): { data: z.infer<T> | null; errors: Record<string, string[]> } {
+  const result = schema.safeParse(values);
+  if (result.success) {
+    return { data: result.data, errors: {} };
+  }
+  return {
+    data: null,
+    errors: z.flattenError(result.error).fieldErrors as Record<
+      string,
+      string[]
+    >,
+  };
+}
 
-export function useForm<T extends FieldValues = FieldValues>(
+export function useHookForm<T extends FieldValues = FieldValues>(
   schema: z.ZodType<T>,
   options?: Partial<UseFormProps<T>>,
 ): UseFormReturn<T> {
+  // @ts-expect-error RHF's UseFormReturn has 3 generics; narrowing to <T> is safe here.
   return rhfUseForm<T>({
     ...options,
-    resolver: zodResolver(schema),
+    // @ts-expect-error zodResolver returns Resolver<any, any, any>; incompatible with Resolver<T, any, T>.
+    resolver: zodResolver(schema as any),
   });
 }
 
-// ── Form ──────────────────────────────────────────────────────────────────────
-
-type FormProps<T extends FieldValues> = {
+type HookFormProps<T extends FieldValues> = Omit<
+  ComponentProps<typeof LibraryForm>,
+  "onSubmit" | "onFormSubmit" | "children"
+> & {
   form: UseFormReturn<T>;
-  onSubmit: SubmitHandler<T>;
+  onFormSubmit: SubmitHandler<T>;
   children: ReactNode;
-} & Omit<ComponentProps<typeof LibraryForm>, "onSubmit" | "onFormSubmit">;
+};
 
-export function Form<T extends FieldValues>({
+export function HookForm<T extends FieldValues>({
   form,
-  onSubmit,
+  onFormSubmit,
   children,
   ...props
-}: FormProps<T>) {
+}: HookFormProps<T>) {
   return (
     <FormProvider {...form}>
       <LibraryForm
-        onFormSubmit={(event) => {
-          form.handleSubmit(onSubmit)(event);
+        onSubmit={(event) => {
+          event.preventDefault();
+          form.handleSubmit(onFormSubmit)();
         }}
         {...props}
       >
@@ -59,33 +82,42 @@ export function Form<T extends FieldValues>({
   );
 }
 
-// ── FormField ─────────────────────────────────────────────────────────────────
-
-export type FormFieldRenderProps<
+export type HookFieldRenderProps<
   T extends FieldValues = FieldValues,
-  TName extends Path<T> = Path<T>,
+  TName extends FieldPath<T> = FieldPath<T>,
 > = ControllerRenderProps<T, TName> & {
   invalid: boolean;
 };
 
-type FormFieldProps<
+type HookFieldProps<
   T extends FieldValues = FieldValues,
-  TName extends Path<T> = Path<T>,
-> = Omit<FieldProps, "children" | "error"> & {
+  TName extends FieldPath<T> = FieldPath<T>,
+> = Omit<FieldProps, "children" | "error" | "render" | "name"> & {
   name: TName;
-  rules?: RegisterOptions;
-  render: (field: FormFieldRenderProps<T, TName>) => ReactNode;
+  rules?: RegisterOptions<T, TName>;
+  render: (field: HookFieldRenderProps<T, TName>) => ReactNode;
 };
 
-export function FormField<
+export function HookField<
   T extends FieldValues = FieldValues,
-  TName extends Path<T> = Path<T>,
->({ name, rules, render, ...fieldProps }: FormFieldProps<T, TName>) {
-  const { field, fieldState } = useController<T, TName>({ name, rules });
+  TName extends FieldPath<T> = FieldPath<T>,
+>({ name, rules, render, ...fieldProps }: HookFieldProps<T, TName>) {
+  const { control } = useFormContext<T>();
 
   return (
-    <Field {...fieldProps} error={fieldState.error?.message}>
-      {render({ ...field, invalid: fieldState.invalid })}
-    </Field>
+    <Controller<T, TName>
+      name={name}
+      control={control}
+      rules={rules}
+      render={({ field, fieldState }) => (
+        <Field
+          {...fieldProps}
+          invalid={fieldState.invalid}
+          error={fieldState.error?.message}
+        >
+          {render({ ...field, invalid: fieldState.invalid })}
+        </Field>
+      )}
+    />
   );
 }

package/src/utils/index.ts

@@ -1,3 +1,3 @@
+export * from "./form";
 export * from "./functions";
 export * from "./strings";
-export * from "./tests";

package/src/__doc__/Migration.mdx

@@ -1,451 +0,0 @@
-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.
-
----
-
-## 4. Version 2.0.0-alpha.11
-
-### Instalación
-
-```bash
-npm install @boxcustodia/library@2.0.0-alpha.11
-```
-
-### 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.
-
-#### 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.
-
-#### 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.
-
----