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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boxcustodia/library",
-  "version": "2.0.0-alpha.16",
+  "version": "2.0.0-alpha.18",
   "type": "module",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",

package/src/__doc__/V2.mdx

@@ -1242,4 +1242,40 @@ import {
 </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`).
+---
+
+## 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>();
+```

package/src/components/accordion/accordion.test.tsx

@@ -0,0 +1,117 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import {
+  Accordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionRoot,
+  AccordionTrigger,
+} from "../../components";
+import { click } from "../../utils/tests";
+
+const items = [
+  { value: "item-1", trigger: "First question", content: "First answer" },
+  { value: "item-2", trigger: "Second question", content: "Second answer" },
+];
+
+describe("Accordion component", () => {
+  it("should render correctly", () => {
+    render(<Accordion data-testid="Accordion" items={items} />);
+    const component = screen.getByTestId("Accordion");
+    expect(component).toBeInTheDocument();
+  });
+
+  it("should show all triggers", () => {
+    render(<Accordion items={items} />);
+
+    expect(screen.getByText(/first question/i)).toBeInTheDocument();
+    expect(screen.getByText(/second question/i)).toBeInTheDocument();
+  });
+
+  it("should open a panel when its trigger is clicked", () => {
+    render(<Accordion items={items} />);
+
+    const trigger = screen.getByRole("button", { name: /first question/i });
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+
+    click(trigger);
+
+    waitFor(() => {
+      expect(trigger).toHaveAttribute("aria-expanded", "true");
+      expect(screen.getByText("First answer")).toBeVisible();
+    });
+  });
+
+  it("should render disabled items as disabled", () => {
+    render(
+      <Accordion
+        items={[
+          { value: "item-1", trigger: "Available", content: "Open me" },
+          {
+            value: "item-2",
+            trigger: "Disabled",
+            content: "Cannot open",
+            disabled: true,
+          },
+        ]}
+      />,
+    );
+
+    const disabledTrigger = screen.getByRole("button", { name: /disabled/i });
+    expect(disabledTrigger).toBeDisabled();
+  });
+
+  it("should be controlled", () => {
+    const mock = vi.fn();
+    render(<Accordion items={items} value={["item-1"]} onValueChange={mock} />);
+
+    const secondTrigger = screen.getByRole("button", {
+      name: /second question/i,
+    });
+    click(secondTrigger);
+
+    waitFor(() => {
+      expect(mock).toHaveBeenCalled();
+    });
+  });
+
+  it("should apply classNames to each slot", () => {
+    render(
+      <Accordion
+        items={items}
+        className="root-class"
+        classNames={{
+          item: "item-class",
+          trigger: "trigger-class",
+          content: "content-class",
+        }}
+      />,
+    );
+
+    expect(document.querySelector('[data-slot="accordion"]')).toHaveClass(
+      "root-class",
+    );
+    expect(document.querySelector('[data-slot="accordion-item"]')).toHaveClass(
+      "item-class",
+    );
+    expect(
+      document.querySelector('[data-slot="accordion-trigger"]'),
+    ).toHaveClass("trigger-class");
+  });
+
+  it("should render correctly using primitives", () => {
+    render(
+      <AccordionRoot defaultValue={["item-1"]}>
+        <AccordionItem value="item-1">
+          <AccordionTrigger>Primitive trigger</AccordionTrigger>
+          <AccordionContent>Primitive content</AccordionContent>
+        </AccordionItem>
+      </AccordionRoot>,
+    );
+
+    expect(screen.getByText(/primitive trigger/i)).toBeInTheDocument();
+    expect(
+      screen.getByRole("button", { name: /primitive trigger/i }),
+    ).toHaveAttribute("aria-expanded", "true");
+  });
+});

package/src/components/alert-dialog/alert-dialog.test.tsx

@@ -1,49 +1,235 @@
-import { render, screen } from "@testing-library/react";
+import { render, screen, waitFor } from "@testing-library/react";
 import { describe, expect, it, vi } from "vitest";
-import { AlertDialog } from "../../components";
+import {
+  AlertDialog,
+  AlertDialogClose,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogPopup,
+  AlertDialogPrimitive,
+  AlertDialogRoot,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+  Button,
+} from "../../components";
 import { click } from "../../utils/tests";
 
-describe("AlertDialog component", () => {
-  it("should show custom title and description", () => {
+describe("AlertDialog composite", () => {
+  it("renders title and description when open", () => {
     render(
-      <AlertDialog
-        open
-        title="Custom title"
-        description="Custom description"
-      />,
+      <AlertDialog open title="Custom title" description="Custom description" />,
     );
 
     expect(screen.getByText("Custom title")).toBeInTheDocument();
     expect(screen.getByText("Custom description")).toBeInTheDocument();
   });
 
-  it("should cancel action", () => {
-    const onCancel = vi.fn();
+  it("uses Spanish defaults for cancel and action buttons", () => {
+    render(<AlertDialog open title="Title" />);
+
+    expect(
+      screen.getByRole("button", { name: "Cancelar" }),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole("button", { name: "Confirmar" }),
+    ).toBeInTheDocument();
+  });
+
+  it("renders custom closeText and actionText", () => {
     render(
       <AlertDialog
         open
-        title="Custom title"
-        description="Custom description"
-        onClose={onCancel}
+        title="Delete"
+        closeText="Mantener"
+        actionText="Eliminar"
       />,
     );
 
+    expect(screen.getByRole("button", { name: "Mantener" })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Eliminar" })).toBeInTheDocument();
+  });
+
+  it("calls onClose when cancel button is clicked", () => {
+    const onClose = vi.fn();
+    render(<AlertDialog open title="Title" onClose={onClose} />);
+
     click(screen.getByRole("button", { name: "Cancelar" }));
-    expect(onCancel).toHaveBeenCalled();
+
+    expect(onClose).toHaveBeenCalledOnce();
+  });
+
+  it("calls onAction when action button is clicked", () => {
+    const onAction = vi.fn();
+    render(<AlertDialog open title="Title" onAction={onAction} />);
+
+    click(screen.getByRole("button", { name: "Confirmar" }));
+
+    expect(onAction).toHaveBeenCalledOnce();
+  });
+
+  it("opens on trigger click", async () => {
+    render(
+      <AlertDialog
+        trigger={<Button>Abrir</Button>}
+        title="Title"
+        description="Description"
+      />,
+    );
+
+    expect(screen.queryByText("Title")).not.toBeInTheDocument();
+
+    click(screen.getByRole("button", { name: "Abrir" }));
+
+    await waitFor(() => {
+      expect(screen.getByText("Title")).toBeInTheDocument();
+      expect(screen.getByText("Description")).toBeInTheDocument();
+    });
   });
 
-  it("should confirm action", () => {
-    const onConfirm = vi.fn();
+  it("closes after clicking the action button", async () => {
+    render(
+      <AlertDialog
+        trigger={<Button>Abrir</Button>}
+        title="Title"
+        actionText="Confirmar"
+      />,
+    );
+
+    click(screen.getByRole("button", { name: "Abrir" }));
+    await waitFor(() =>
+      expect(screen.getByText("Title")).toBeInTheDocument(),
+    );
+
+    click(screen.getByRole("button", { name: "Confirmar" }));
+
+    await waitFor(() =>
+      expect(screen.queryByText("Title")).not.toBeInTheDocument(),
+    );
+  });
+
+  it("renders children between description and footer", () => {
+    render(
+      <AlertDialog open title="Title" description="Description">
+        <div data-testid="custom-body">Extra content</div>
+      </AlertDialog>,
+    );
+
+    expect(screen.getByTestId("custom-body")).toBeInTheDocument();
+  });
+
+  it("omits the header when no title or description is provided", () => {
+    render(<AlertDialog open />);
+
+    expect(
+      document.querySelector('[data-slot="alert-dialog-header"]'),
+    ).toBeNull();
+    expect(
+      screen.getByRole("button", { name: "Cancelar" }),
+    ).toBeInTheDocument();
+  });
+
+  it("applies className to the popup and classNames to internal slots", () => {
     render(
       <AlertDialog
         open
-        title="Custom title"
-        description="Custom description"
-        onAction={onConfirm}
+        title="Title"
+        description="Description"
+        className="popup-class"
+        classNames={{
+          backdrop: "backdrop-class",
+          header: "header-class",
+          title: "title-class",
+          description: "description-class",
+          footer: "footer-class",
+          closeButton: "close-class",
+          actionButton: "action-class",
+        }}
       />,
     );
 
-    click(screen.getByRole("button", { name: "Aceptar" }));
-    expect(onConfirm).toHaveBeenCalled();
+    expect(
+      document.querySelector('[data-slot="alert-dialog-popup"]'),
+    ).toHaveClass("popup-class");
+    expect(
+      document.querySelector('[data-slot="alert-dialog-backdrop"]'),
+    ).toHaveClass("backdrop-class");
+    expect(
+      document.querySelector('[data-slot="alert-dialog-header"]'),
+    ).toHaveClass("header-class");
+    expect(screen.getByText("Title")).toHaveClass("title-class");
+    expect(screen.getByText("Description")).toHaveClass("description-class");
+    expect(
+      document.querySelector('[data-slot="alert-dialog-footer"]'),
+    ).toHaveClass("footer-class");
+    expect(screen.getByRole("button", { name: "Cancelar" })).toHaveClass(
+      "close-class",
+    );
+    expect(screen.getByRole("button", { name: "Confirmar" })).toHaveClass(
+      "action-class",
+    );
+  });
+});
+
+describe("AlertDialog primitives", () => {
+  const setup = () =>
+    render(
+      <AlertDialogRoot>
+        <AlertDialogTrigger render={<Button>Abrir</Button>} />
+        <AlertDialogPopup>
+          <AlertDialogHeader>
+            <AlertDialogTitle>Title</AlertDialogTitle>
+            <AlertDialogDescription>Description</AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogClose render={<Button>Cancelar</Button>} />
+            <AlertDialogClose render={<Button>Confirmar</Button>} />
+          </AlertDialogFooter>
+        </AlertDialogPopup>
+      </AlertDialogRoot>,
+    );
+
+  it("opens on trigger click", async () => {
+    setup();
+
+    click(screen.getByRole("button", { name: "Abrir" }));
+
+    await waitFor(() => {
+      expect(screen.getByText("Title")).toBeInTheDocument();
+      expect(screen.getByText("Description")).toBeInTheDocument();
+    });
+  });
+
+  it("closes when AlertDialogClose is clicked", async () => {
+    setup();
+
+    click(screen.getByRole("button", { name: "Abrir" }));
+    await waitFor(() =>
+      expect(screen.getByText("Title")).toBeInTheDocument(),
+    );
+
+    click(screen.getByRole("button", { name: "Cancelar" }));
+
+    await waitFor(() =>
+      expect(screen.queryByText("Title")).not.toBeInTheDocument(),
+    );
+  });
+
+  it("is controlled by the open prop on the Root", () => {
+    render(
+      <AlertDialogRoot open>
+        <AlertDialogPopup>
+          <AlertDialogTitle>Controlled title</AlertDialogTitle>
+        </AlertDialogPopup>
+      </AlertDialogRoot>,
+    );
+
+    expect(screen.getByText("Controlled title")).toBeInTheDocument();
+  });
+
+  it("exposes the Base UI namespace via AlertDialogPrimitive", () => {
+    expect(AlertDialogPrimitive).toBeDefined();
+    expect(AlertDialogPrimitive.Root).toBeDefined();
+    expect(AlertDialogPrimitive.Popup).toBeDefined();
   });
 });

package/src/components/alert-dialog/alert-dialog.tsx

@@ -198,9 +198,9 @@ export type AlertDialogProps = Omit<AlertDialogBase.Root.Props, "children"> & {
   onAction?: () => void;
   /** Visual variant for the action button. @default "default" */
   variant?: VariantProps<typeof buttonVariants>["variant"];
-  /** Label for the cancel button. @default "Cancel" */
+  /** Label for the cancel button. @default "Cancelar" */
   closeText?: ReactNode;
-  /** Label for the action button. @default "Confirm" */
+  /** Label for the action button. @default "Confirmar" */
   actionText?: ReactNode;
   /** Styles the dialog popup panel. */
   className?: string;
@@ -254,8 +254,8 @@ export function AlertDialog({
   onClose,
   onAction,
   variant = "default",
-  closeText = "Cancel",
-  actionText = "Confirm",
+  closeText = "Cancelar",
+  actionText = "Confirmar",
   className,
   classNames,
   ...props

package/src/components/avatar/avatar.test.tsx

@@ -1,61 +1,198 @@
 import { render, screen } from "@testing-library/react";
-import { describe, expect, it } from "vitest";
-import { Avatar } from "../../components";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import {
+  Avatar,
+  AvatarBadge,
+  AvatarFallback,
+  AvatarGroup,
+  AvatarGroupCount,
+  AvatarImage,
+  AvatarPrimitive,
+  AvatarRoot,
+} from "../../components";
 import { extractInitials } from "../../utils";
 
-describe("Avatar component", () => {
+// Base UI's Avatar uses `new window.Image()` to detect loading state, which
+// never resolves in jsdom. Mock it so a non-empty src completes synchronously
+// and Base UI's fast path (`image.complete && naturalWidth > 0`) renders the
+// underlying `<img>` immediately.
+const OriginalImage = globalThis.Image;
+beforeAll(() => {
+  class MockImage {
+    onload: (() => void) | null = null;
+    onerror: (() => void) | null = null;
+    referrerPolicy = "";
+    crossOrigin: string | null = null;
+    naturalWidth = 0;
+    complete = false;
+    set src(value: string) {
+      if (value) {
+        this.naturalWidth = 1;
+        this.complete = true;
+      }
+    }
+  }
+  vi.stubGlobal("Image", MockImage);
+});
+afterAll(() => {
+  vi.stubGlobal("Image", OriginalImage);
+});
+
+describe("Avatar composite", () => {
   const personName = "lorem ipsum";
   const imageSrc = "https://i.pravatar.cc/300";
 
-  it("renders correctly", () => {
+  it("renders the image with src and alt", () => {
     render(<Avatar alt={personName} src={imageSrc} />);
-    const image = screen.getByRole("img");
 
-    expect(image).toBeInTheDocument();
+    const image = screen.getByRole("img");
     expect(image).toHaveAttribute("alt", personName);
     expect(image).toHaveAttribute("src", imageSrc);
   });
 
-  it("renders correctly without src", () => {
+  it("falls back to the alt initials when no src is provided", () => {
     render(<Avatar alt={personName} src="" />);
-    const nameInitials = extractInitials(personName);
 
-    const image = screen.queryByRole("img");
-    const fallbackText = screen.getByText(nameInitials);
+    expect(screen.queryByRole("img")).not.toBeInTheDocument();
+    expect(screen.getByText(extractInitials(personName))).toBeInTheDocument();
+  });
 
-    expect(image).not.toBeInTheDocument();
-    expect(fallbackText).toBeInTheDocument();
+  it("renders a custom fallback node when provided", () => {
+    render(
+      <Avatar alt={personName} src="" fallback={<span>Custom</span>} />,
+    );
+
+    expect(screen.getByText("Custom")).toBeInTheDocument();
+    expect(
+      screen.queryByText(extractInitials(personName)),
+    ).not.toBeInTheDocument();
   });
 
-  it("renders correctly with onError", () => {
-    render(<Avatar alt={personName} src="" />);
+  it("renders a badge when provided", () => {
+    render(
+      <Avatar alt={personName} src={imageSrc} badge={<span>3</span>} />,
+    );
 
-    const nameInitials = extractInitials(personName);
-    const image = screen.queryByRole("img");
-    const fallbackText = screen.getByText(nameInitials);
+    const badge = document.querySelector('[data-slot="avatar-badge"]');
+    expect(badge).not.toBeNull();
+    expect(badge).toHaveTextContent("3");
+  });
 
-    expect(image).not.toBeInTheDocument();
-    expect(fallbackText).toBeInTheDocument();
+  it("omits the badge slot when no badge is provided", () => {
+    render(<Avatar alt={personName} src={imageSrc} />);
+
+    expect(
+      document.querySelector('[data-slot="avatar-badge"]'),
+    ).toBeNull();
+  });
+
+  it("applies the size variant via data-size and class", () => {
+    render(<Avatar alt={personName} src={imageSrc} size="sm" />);
+
+    const root = document.querySelector('[data-slot="avatar"]');
+    expect(root).toHaveAttribute("data-size", "sm");
+    expect(root).toHaveClass("size-8");
   });
 
-  it("renders correctly with imageProps", () => {
-    const testClassName = "test-class";
+  it("defaults size to md when omitted", () => {
+    render(<Avatar alt={personName} src={imageSrc} />);
+
+    const root = document.querySelector('[data-slot="avatar"]');
+    expect(root).toHaveAttribute("data-size", "md");
+    expect(root).toHaveClass("size-10");
+  });
+
+  it("applies className to the root and classNames to each slot", () => {
     render(
       <Avatar
         alt={personName}
-        src={imageSrc}
-        imageProps={{ className: testClassName }}
+        src=""
+        badge={<span>!</span>}
+        className="root-class"
+        classNames={{
+          image: "image-class",
+          fallback: "fallback-class",
+          badge: "badge-class",
+        }}
       />,
     );
 
-    const image = screen.getByRole("img");
-    expect(image).toHaveClass(testClassName);
+    expect(document.querySelector('[data-slot="avatar"]')).toHaveClass(
+      "root-class",
+    );
+    expect(
+      document.querySelector('[data-slot="avatar-fallback"]'),
+    ).toHaveClass("fallback-class");
+    expect(document.querySelector('[data-slot="avatar-badge"]')).toHaveClass(
+      "badge-class",
+    );
   });
+});
 
-  it("renders correctly with size variants", () => {
-    render(<Avatar alt={personName} src={imageSrc} size="sm" />);
-    const avatar = screen.getByRole("img").parentElement;
+describe("Avatar primitives", () => {
+  it("composes Root, Image, and Fallback directly", () => {
+    render(
+      <AvatarRoot>
+        <AvatarImage src="https://i.pravatar.cc/300" alt="user" />
+        <AvatarFallback>U</AvatarFallback>
+      </AvatarRoot>,
+    );
+
+    expect(screen.getByRole("img")).toHaveAttribute("alt", "user");
+  });
+
+  it("renders the Fallback when no Image is provided", () => {
+    render(
+      <AvatarRoot>
+        <AvatarFallback>FB</AvatarFallback>
+      </AvatarRoot>,
+    );
+
+    expect(screen.getByText("FB")).toBeInTheDocument();
+  });
+
+  it("renders AvatarBadge as an absolutely positioned slot", () => {
+    render(
+      <AvatarRoot>
+        <AvatarFallback>U</AvatarFallback>
+        <AvatarBadge>1</AvatarBadge>
+      </AvatarRoot>,
+    );
+
+    const badge = document.querySelector('[data-slot="avatar-badge"]');
+    expect(badge).toHaveTextContent("1");
+    expect(badge).toHaveClass("absolute");
+  });
+
+  it("renders AvatarGroup wrapping multiple avatars", () => {
+    render(
+      <AvatarGroup data-testid="group">
+        <AvatarRoot>
+          <AvatarFallback>A</AvatarFallback>
+        </AvatarRoot>
+        <AvatarRoot>
+          <AvatarFallback>B</AvatarFallback>
+        </AvatarRoot>
+      </AvatarGroup>,
+    );
+
+    const group = screen.getByTestId("group");
+    expect(group).toHaveAttribute("data-slot", "avatar-group");
+    expect(group.querySelectorAll('[data-slot="avatar"]')).toHaveLength(2);
+  });
+
+  it("renders AvatarGroupCount with the chosen size", () => {
+    render(<AvatarGroupCount size="lg">+3</AvatarGroupCount>);
+
+    const count = document.querySelector('[data-slot="avatar-group-count"]');
+    expect(count).toHaveTextContent("+3");
+    expect(count).toHaveClass("size-14");
+  });
 
-    expect(avatar).toHaveClass("w-8 h-8");
+  it("exposes the Base UI namespace via AvatarPrimitive", () => {
+    expect(AvatarPrimitive).toBeDefined();
+    expect(AvatarPrimitive.Root).toBeDefined();
+    expect(AvatarPrimitive.Image).toBeDefined();
+    expect(AvatarPrimitive.Fallback).toBeDefined();
   });
 });

package/src/components/combobox/combobox.tsx

@@ -545,7 +545,7 @@ export function ComboboxChipRemove(
 ): React.ReactElement {
   return (
     <ComboboxPrimitive.ChipRemove
-      aria-label="Remove"
+      aria-label="Quitar"
       className="h-full shrink-0 cursor-pointer px-1 opacity-80 hover:opacity-100 [&_svg:not([class*='size-'])]:size-4 sm:[&_svg:not([class*='size-'])]:size-3.5"
       data-slot="combobox-chip-remove"
       {...props}