@boxcustodia/library 2.0.0-alpha.3 → 2.0.0-alpha.30

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

@@ -0,0 +1,174 @@
+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: "Components/Pagination",
+  component: Pagination,
+  subcomponents: {
+    PaginationRoot,
+    PaginationFirst,
+    PaginationPrevious,
+    PaginationNext,
+    PaginationLast,
+    PaginationLink,
+    PaginationPages,
+    PaginationEllipsis,
+    PaginationTotal,
+    PaginationPageInfo,
+    PaginationRange,
+    PaginationSizeSelect,
+  },
+  argTypes: {
+    onCurrentPageChange: { action: "onCurrentPageChange" },
+    onPageSizeChange: { action: "onPageSizeChange" },
+  },
+  args: {
+    totalItems: 100,
+    defaultPageSize: 10,
+  },
+  parameters: {
+    layout: "centered",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+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 (
+      <Pagination {...args} currentPage={page} onCurrentPageChange={setPage} />
+    );
+  },
+};
+
+/**
+ * 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

@@ -0,0 +1,201 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import {
+  Pagination,
+  PaginationFirst,
+  PaginationLast,
+  PaginationNext,
+  PaginationPageInfo,
+  PaginationPages,
+  PaginationPrevious,
+  PaginationRange,
+  PaginationRoot,
+  PaginationSizeSelect,
+  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("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("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("disables prev on first page", () => {
+    render(<Pagination defaultPageSize={10} totalItems={30} />);
+    expect(screen.getByRole("button", { name: /anterior/i })).toBeDisabled();
+  });
+
+  it("disables next on last page", () => {
+    render(
+      <Pagination
+        defaultCurrentPage={3}
+        defaultPageSize={10}
+        totalItems={30}
+      />,
+    );
+    expect(screen.getByRole("button", { name: /próxima/i })).toBeDisabled();
+  });
+
+  it("hides size selector when sizes is false", () => {
+    render(<Pagination defaultPageSize={10} totalItems={30} sizes={false} />);
+    expect(screen.queryByRole("combobox")).not.toBeInTheDocument();
+  });
+
+  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);
+  });
+});
+
+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();
+  });
+
+  it("renders DOTS when range overflows", () => {
+    render(
+      <PaginationRoot defaultPageSize={10} totalItems={200}>
+        <PaginationPages />
+      </PaginationRoot>,
+    );
+    expect(screen.getAllByText(/Más páginas/).length).toBeGreaterThan(0);
+  });
+
+  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("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");
+  });
+
+  it("throws when used outside Root", () => {
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    expect(() => render(<PaginationNext />)).toThrow(
+      /must be used inside <PaginationRoot>/,
+    );
+    consoleError.mockRestore();
+  });
+
+  it("PaginationFirst navigates to page 1 from non-first page", () => {
+    render(
+      <PaginationRoot
+        defaultCurrentPage={3}
+        defaultPageSize={10}
+        totalItems={30}
+      >
+        <PaginationFirst />
+        <PaginationPageInfo />
+      </PaginationRoot>,
+    );
+    click(screen.getByRole("button", { name: /primera página/i }));
+    expect(screen.getByText(/Página 1 de 3/)).toBeInTheDocument();
+  });
+
+  it("PaginationLast navigates to last page", () => {
+    render(
+      <PaginationRoot
+        defaultCurrentPage={1}
+        defaultPageSize={10}
+        totalItems={30}
+      >
+        <PaginationLast />
+        <PaginationPageInfo />
+      </PaginationRoot>,
+    );
+    click(screen.getByRole("button", { name: /última página/i }));
+    expect(screen.getByText(/Página 3 de 3/)).toBeInTheDocument();
+  });
+
+  it("PaginationSizeSelect changes page size and resets to page 1", () => {
+    render(
+      <PaginationRoot defaultPageSize={10} totalItems={50}>
+        <PaginationSizeSelect />
+        <PaginationRange />
+      </PaginationRoot>,
+    );
+    expect(screen.getByText(/1 - 10 de 50/)).toBeInTheDocument();
+    fireEvent.change(screen.getByRole("combobox"), {
+      target: { value: "25" },
+    });
+    expect(screen.getByText(/1 - 25 de 50/)).toBeInTheDocument();
+  });
+
+  it("PaginationRange renders data-slot and range text", () => {
+    render(
+      <PaginationRoot defaultPageSize={10} totalItems={30}>
+        <PaginationRange />
+      </PaginationRoot>,
+    );
+    expect(
+      document.querySelector('[data-slot="pagination-range"]'),
+    ).toBeInTheDocument();
+    expect(screen.getByText(/1 - 10 de 30/)).toBeInTheDocument();
+  });
+});