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

package/src/components/otp/otp.tsx

@@ -0,0 +1,100 @@
+import { OTPFieldPreview as OTPPrimitive } from "@base-ui/react/otp-field";
+import type React from "react";
+import { Fragment } from "react";
+
+import { cn } from "../../lib";
+import { Divider } from "../divider/divider";
+
+export function OTPRoot({
+  className,
+  size = "default",
+  ...props
+}: OTPPrimitive.Root.Props & {
+  size?: "default" | "lg";
+}): React.ReactElement {
+  return (
+    <OTPPrimitive.Root
+      className={cn(
+        "flex items-center gap-2 has-disabled:opacity-64 has-disabled:**:data-[slot=otp-input]:shadow-none has-disabled:**:data-[slot=otp-input]:before:shadow-none!",
+        className,
+      )}
+      data-size={size}
+      data-slot="otp"
+      {...props}
+    />
+  );
+}
+
+export function OTPInput({
+  className,
+  ...props
+}: OTPPrimitive.Input.Props): React.ReactElement {
+  return (
+    <OTPPrimitive.Input
+      className={cn(
+        "in-[[data-slot=otp][data-size=lg]]:size-10 size-9 min-w-0 rounded-lg border border-input bg-background text-center in-[[data-slot=otp][data-size=lg]]:text-lg text-base text-foreground in-[[data-slot=otp][data-size=lg]]:leading-10 leading-9 outline-none transition-shadow focus-visible:z-10 focus-visible:border-ring aria-invalid:border-error focus-visible:aria-invalid:border-error focus-visible:aria-invalid:ring-error/20 in-[[data-slot=field][data-invalid]]:border-error in-[[data-slot=field][data-invalid]]:focus-visible:border-error in-[[data-slot=field][data-invalid]]:focus-visible:ring-error/20 sm:in-[[data-slot=otp][data-size=lg]]:size-9 sm:size-8 sm:in-[[data-slot=otp][data-size=lg]]:text-base sm:text-sm sm:in-[[data-slot=otp][data-size=lg]]:leading-9 sm:leading-8",
+        className,
+      )}
+      data-slot="otp-input"
+      spellCheck={false}
+      {...props}
+    />
+  );
+}
+
+export function OTPSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof Divider>): React.ReactElement {
+  return (
+    <OTPPrimitive.Separator
+      render={
+        <Divider
+          className={cn(
+            "rounded-full bg-input data-[orientation=horizontal]:h-0.5 data-[orientation=horizontal]:w-3",
+            className,
+          )}
+          orientation="horizontal"
+          {...props}
+        />
+      }
+    />
+  );
+}
+
+interface OTPProps extends Omit<OTPPrimitive.Root.Props, "children"> {
+  size?: "default" | "lg";
+  /** Insert a separator after this slot (1-indexed). */
+  split?: number;
+  inputProps?: OTPPrimitive.Input.Props;
+}
+
+export function OTP({
+  split,
+  inputProps,
+  size,
+  length,
+  "aria-invalid": ariaInvalid,
+  ...props
+}: OTPProps): React.ReactElement {
+  const slotProps: OTPPrimitive.Input.Props = {
+    ...(ariaInvalid ? { "aria-invalid": true } : {}),
+    ...inputProps,
+  };
+
+  return (
+    <OTPRoot size={size} length={length} aria-invalid={ariaInvalid} {...props}>
+      {Array.from({ length }, (_, i) => (
+        <Fragment key={i}>
+          <OTPInput
+            aria-label={`Character ${i + 1} of ${length}`}
+            {...slotProps}
+          />
+          {split === i + 1 && <OTPSeparator />}
+        </Fragment>
+      ))}
+    </OTPRoot>
+  );
+}
+
+export { OTPPrimitive };

package/src/components/pagination/index.ts

@@ -1 +1,2 @@
 export * from "./pagination";
+export * from "./pagination.model";

package/src/components/pagination/pagination.model.ts

@@ -0,0 +1,2 @@
+export const PAGINATION_SIZES = [10, 25, 50] as const;
+export type PageSize = (typeof PAGINATION_SIZES)[number] | number;

package/src/components/pagination/pagination.stories.tsx

@@ -1,20 +1,57 @@
-import { Meta, StoryObj } from "@storybook/react-vite";
-import { ComponentProps } from "react";
-import { action } from "storybook/actions";
-import { Pagination } from "../../components";
-import { cn } from "../../lib";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import {
+  Pagination,
+  PaginationEllipsis,
+  PaginationFirst,
+  PaginationLast,
+  PaginationLink,
+  PaginationNext,
+  PaginationPageInfo,
+  PaginationPages,
+  PaginationPrevious,
+  PaginationRange,
+  PaginationRoot,
+  PaginationSizeSelect,
+  PaginationTotal,
+} from "../../components";
 
+/**
+ * Composite + primitives for pagination UI. The composite renders the default table layout
+ * (size selector + range + prev/next). Use primitives via `PaginationRoot` to compose any
+ * layout — numbered pages, page info, total only, etc. State is controllable through
+ * `currentPage` / `defaultCurrentPage` and `pageSize` / `defaultPageSize`. Pass `getPageHref`
+ * (and optionally `linkComponent`) to render navigation as anchors instead of buttons.
+ */
 const meta: Meta<typeof Pagination> = {
-  title: "Data display/Pagination",
+  title: "Components/Pagination",
   component: Pagination,
-  tags: ["autodocs"],
+  subcomponents: {
+    PaginationRoot,
+    PaginationFirst,
+    PaginationPrevious,
+    PaginationNext,
+    PaginationLast,
+    PaginationLink,
+    PaginationPages,
+    PaginationEllipsis,
+    PaginationTotal,
+    PaginationPageInfo,
+    PaginationRange,
+    PaginationSizeSelect,
+  },
+  argTypes: {
+    onCurrentPageChange: { action: "onCurrentPageChange" },
+    onPageSizeChange: { action: "onPageSizeChange" },
+  },
   args: {
-    siblingCount: 1,
     totalItems: 100,
-    pageSize: 10,
-    initialCurrentPage: 1,
-    onChange: action("onChange"),
+    defaultPageSize: 10,
   },
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["beta"],
 };
 
 export default meta;
@@ -22,59 +59,117 @@ type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {};
 
-export const DotsVariants: Story = {
-  argTypes: {
-    totalItems: { control: false },
-    pageSize: { control: false },
-    initialCurrentPage: { control: false },
-  },
+export const NoSizes: Story = {
+  args: { sizes: false },
+};
+
+export const CustomSizes: Story = {
+  args: { sizes: [5, 20, 100, 1000] },
+};
+
+/**
+ * Controlled `currentPage` via React state. The component never owns the page —
+ * useful when the page lives in a parent, URL params, or Zustand store.
+ */
+export const Controlled: Story = {
   render: (args) => {
+    const [page, setPage] = useState(1);
     return (
-      <div className="space-y-2">
-        <h2>No hay suficientes elementos para mostrar puntos</h2>
-        <Pagination
-          {...(args as ComponentProps<typeof Pagination>)}
-          pageSize={20}
-        />
-        <h2>Puntos a la derecha</h2>
-        <Pagination
-          {...(args as ComponentProps<typeof Pagination>)}
-          initialCurrentPage={1}
-        />
-        <h2>Puntos de ambos lados</h2>
-        <Pagination
-          {...(args as ComponentProps<typeof Pagination>)}
-          initialCurrentPage={5}
-        />
-        <h2>Puntos a la izquierda</h2>
-        <Pagination
-          {...(args as ComponentProps<typeof Pagination>)}
-          initialCurrentPage={10}
-        />
-      </div>
+      <Pagination {...args} currentPage={page} onCurrentPageChange={setPage} />
     );
   },
 };
 
 /**
- * Se exponen los siguientes atributos:
- *
- * | Atributo | Descripción |
- * | --- | --- |
- * | `data-active` | si el elemento es el activo |
- * | `data-dots` | si el elemento son puntos|
- **/
-export const Custom: Story = {
-  args: {
-    className: "gap-x-4",
-    optionProps: {
-      className: cn(
-        "p-0 w-9 h-9 rounded-full flex justify-center items-center",
-        "data-[active=true]:bg-error data-[active=true]:text-error-foreground data-[active=true]:hover:bg-error/90",
-        "data-[dots=true]:border-none data-[dots=true]:bg-transparent",
-        "[&:nth-child(-n+2)]:border-none [&:nth-child(-n+2)]:bg-background",
-        "[&:nth-last-child(-n+2)]:border-none [&:nth-last-child(-n+2)]:bg-background",
-      ),
-    },
-  },
+ * Compose freely with primitives. Example: numbered pagination with first/last buttons
+ * and a DOTS-aware page list (the legacy `Pagination` numbered API).
+ */
+export const WithPageNumbers: Story = {
+  args: { totalItems: 200, defaultPageSize: 10 },
+  render: (args) => (
+    <PaginationRoot {...args}>
+      <PaginationFirst />
+      <PaginationPrevious />
+      <PaginationPages />
+      <PaginationNext />
+      <PaginationLast />
+    </PaginationRoot>
+  ),
+};
+
+/**
+ * Compact layout showing total + page info between prev/next, e.g. "25 resultados < Página 1 de 3 >".
+ */
+export const WithTotalAndPageInfo: Story = {
+  args: { totalItems: 25, defaultPageSize: 10 },
+  render: (args) => (
+    <PaginationRoot {...args}>
+      <PaginationTotal />
+      <PaginationPrevious />
+      <PaginationPageInfo />
+      <PaginationNext />
+    </PaginationRoot>
+  ),
+};
+
+/**
+ * Custom display content via render-prop children. `Total`, `Range`, and `PageInfo` accept
+ * either ReactNode or a function returning ReactNode.
+ */
+export const CustomDisplays: Story = {
+  args: { totalItems: 47, defaultPageSize: 5 },
+  render: (args) => (
+    <PaginationRoot {...args}>
+      <PaginationTotal>{(n) => <strong>{n} elementos</strong>}</PaginationTotal>
+      <PaginationRange>
+        {({ start, end, total }) => (
+          <em>
+            Mostrando {start}–{end} de {total}
+          </em>
+        )}
+      </PaginationRange>
+      <PaginationPrevious />
+      <PaginationPageInfo>
+        {({ page, max }) => (
+          <span>
+            {page}/{max}
+          </span>
+        )}
+      </PaginationPageInfo>
+      <PaginationNext />
+    </PaginationRoot>
+  ),
+};
+
+/**
+ * URL-driven mode. Passing `getPageHref` makes Previous/Next/Pages/First/Last render as
+ * anchors. Default `linkComponent` is `<a>`; pass `linkComponent={Link}` for React Router /
+ * Next.js wrapping a component that accepts `href`. The `onCurrentPageChange` callback
+ * still fires on click, so you can sync your router state imperatively.
+ */
+export const WithUrl: Story = {
+  args: { totalItems: 100, defaultPageSize: 10 },
+  render: (args) => (
+    <PaginationRoot
+      {...args}
+      getPageHref={({ page, pageSize }) => `?page=${page}&size=${pageSize}`}
+    >
+      <PaginationPrevious />
+      <PaginationPages />
+      <PaginationNext />
+    </PaginationRoot>
+  ),
+};
+
+/**
+ * Standalone `PaginationSizeSelect` outside the composite — wire it however you want.
+ */
+export const SizeSelectOnly: Story = {
+  args: { totalItems: 100 },
+  render: (args) => (
+    <PaginationRoot {...args}>
+      <PaginationSizeSelect />
+      <PaginationRange />
+    </PaginationRoot>
+  ),
 };

package/src/components/pagination/pagination.test.tsx

@@ -1,76 +1,141 @@
-import { render, screen, waitFor } from "@testing-library/react";
-import { describe, expect, it } from "vitest";
-import { Pagination } from "../../components";
-import { DOTS } from "../../hooks";
-import { click } from "../../utils";
-
-describe("Pagination component", () => {
-  it("should render correctly", () => {
-    render(<Pagination pageSize={10} totalItems={100} />);
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import {
+  Pagination,
+  PaginationNext,
+  PaginationPageInfo,
+  PaginationPages,
+  PaginationPrevious,
+  PaginationRoot,
+  PaginationTotal,
+} from "../../components";
+import { click } from "../../utils/tests";
+
+describe("Pagination composite", () => {
+  it("renders default range text", () => {
+    render(<Pagination defaultPageSize={10} totalItems={30} />);
+    expect(screen.getByText(/1 - 10 de 30/)).toBeInTheDocument();
   });
 
-  it("should navigate to page", async () => {
-    render(<Pagination pageSize={10} totalItems={100} />);
-
-    const page = screen.getByText(/Ir a la página 3/i).parentElement!;
-    click(page);
-
-    waitFor(() => {
-      expect(page).toHaveAttribute("active", "true");
-    });
+  it("navigates to next page", () => {
+    render(<Pagination defaultPageSize={10} totalItems={30} />);
+    click(screen.getByRole("button", { name: /próxima página/i }));
+    expect(screen.getByText(/11 - 20 de 30/)).toBeInTheDocument();
   });
 
-  it("should navigate to first page", async () => {
-    render(<Pagination pageSize={10} totalItems={100} />);
-
-    const page = screen.getByText(/Ir a primera página/i);
-    click(page);
-
-    waitFor(() => {
-      expect(page).toHaveAttribute("active", "true");
-    });
+  it("navigates to previous page", () => {
+    render(
+      <Pagination
+        defaultCurrentPage={2}
+        defaultPageSize={10}
+        totalItems={30}
+      />,
+    );
+    click(screen.getByRole("button", { name: /anterior/i }));
+    expect(screen.getByText(/1 - 10 de 30/)).toBeInTheDocument();
   });
 
-  it("should navigate to previous page", async () => {
-    render(<Pagination pageSize={10} totalItems={100} />);
-
-    const page = screen.getByText(/Ir a página anterior/i);
-    click(page);
-
-    waitFor(() => {
-      expect(page).toHaveAttribute("active", "true");
-    });
+  it("disables prev on first page", () => {
+    render(<Pagination defaultPageSize={10} totalItems={30} />);
+    expect(screen.getByRole("button", { name: /anterior/i })).toBeDisabled();
   });
 
-  it("should navigate to next page", async () => {
-    render(<Pagination pageSize={10} totalItems={100} />);
+  it("disables next on last page", () => {
+    render(
+      <Pagination
+        defaultCurrentPage={3}
+        defaultPageSize={10}
+        totalItems={30}
+      />,
+    );
+    expect(screen.getByRole("button", { name: /próxima/i })).toBeDisabled();
+  });
 
-    const page = screen.getByText(/Ir a próxima página/i);
-    click(page);
+  it("hides size selector when sizes is false", () => {
+    render(<Pagination defaultPageSize={10} totalItems={30} sizes={false} />);
+    expect(screen.queryByRole("combobox")).not.toBeInTheDocument();
+  });
 
-    waitFor(() => {
-      expect(page).toHaveAttribute("active", "true");
-    });
+  it("calls onCurrentPageChange controlled", () => {
+    const onChange = vi.fn();
+    render(
+      <Pagination
+        currentPage={1}
+        defaultPageSize={10}
+        totalItems={30}
+        onCurrentPageChange={onChange}
+      />,
+    );
+    click(screen.getByRole("button", { name: /próxima/i }));
+    expect(onChange).toHaveBeenCalledWith(2);
   });
+});
 
-  it("should navigate to last page", async () => {
-    render(<Pagination pageSize={10} totalItems={100} />);
+describe("Pagination primitives", () => {
+  it("renders page numbers via PaginationPages", () => {
+    render(
+      <PaginationRoot defaultPageSize={10} totalItems={30}>
+        <PaginationPages />
+      </PaginationRoot>,
+    );
+    expect(
+      screen.getByRole("button", { name: /Ir a la página 1/i }),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole("button", { name: /Ir a la página 2/i }),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole("button", { name: /Ir a la página 3/i }),
+    ).toBeInTheDocument();
+  });
 
-    const page = screen.getByText(/Ir a última página/i);
-    click(page);
+  it("renders DOTS when range overflows", () => {
+    render(
+      <PaginationRoot defaultPageSize={10} totalItems={200}>
+        <PaginationPages />
+      </PaginationRoot>,
+    );
+    expect(screen.getAllByText(/Más páginas/).length).toBeGreaterThan(0);
+  });
 
-    waitFor(() => {
-      expect(page).toHaveAttribute("active", "true");
-    });
+  it("renders total + pageInfo + prev/next layout", () => {
+    render(
+      <PaginationRoot defaultPageSize={10} totalItems={25}>
+        <PaginationTotal />
+        <PaginationPrevious />
+        <PaginationPageInfo />
+        <PaginationNext />
+      </PaginationRoot>,
+    );
+    expect(screen.getByText(/25 resultados/)).toBeInTheDocument();
+    expect(screen.getByText(/Página 1 de 3/)).toBeInTheDocument();
   });
 
-  it("should render dots", async () => {
-    render(<Pagination pageSize={10} totalItems={100} />);
-    const dots = screen.getByText(DOTS);
+  it("renders anchors when getPageHref is provided", () => {
+    const { container } = render(
+      <PaginationRoot
+        defaultPageSize={10}
+        defaultCurrentPage={2}
+        totalItems={30}
+        getPageHref={({ page }) => `/users?page=${page}`}
+      >
+        <PaginationPrevious />
+        <PaginationNext />
+      </PaginationRoot>,
+    );
+    const anchors = container.querySelectorAll("a[href]");
+    expect(anchors.length).toBe(2);
+    expect(anchors[0]).toHaveAttribute("href", "/users?page=1");
+    expect(anchors[1]).toHaveAttribute("href", "/users?page=3");
+  });
 
-    waitFor(() => {
-      expect(dots).toBeInTheDocument();
-      expect(dots).toHaveAttribute("dots", "true");
-    });
+  it("throws when used outside Root", () => {
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    expect(() => render(<PaginationNext />)).toThrow(
+      /must be used inside <PaginationRoot>/,
+    );
+    consoleError.mockRestore();
   });
 });