@zentauri-ui/zentauri-components 1.3.0 → 1.4.0

package/src/ui/pagination/pagination.test.tsx

@@ -0,0 +1,165 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+
+import { buildPaginationItems } from "../../hooks/usePagination";
+import { clampPage } from "../../lib/utils";
+import { Pagination } from "./pagination";
+
+const PAGINATION_SLOT = '[data-slot="pagination"]';
+
+function getPaginationRoot(container: HTMLElement = document.body) {
+  const elements = container.querySelectorAll(PAGINATION_SLOT);
+  expect(
+    elements.length,
+    `Expected exactly one element matching ${PAGINATION_SLOT}, found ${elements.length}`,
+  ).toBe(1);
+  return elements[0] as HTMLElement;
+}
+
+describe("buildPaginationItems", () => {
+  it("should return an empty list when pageCount is zero", () => {
+    expect(
+      buildPaginationItems({
+        pageCount: 0,
+        currentPage: 1,
+        siblingCount: 1,
+        boundaryCount: 1,
+      }),
+    ).toEqual([]);
+  });
+
+  it("should enumerate all pages when pageCount is within the compact threshold", () => {
+    const items = buildPaginationItems({
+      pageCount: 5,
+      currentPage: 3,
+      siblingCount: 1,
+      boundaryCount: 1,
+    });
+    expect(items).toEqual([
+      { type: "page", value: 1 },
+      { type: "page", value: 2 },
+      { type: "page", value: 3 },
+      { type: "page", value: 4 },
+      { type: "page", value: 5 },
+    ]);
+  });
+
+  it("should insert ellipses when the current page sits between boundary windows", () => {
+    const items = buildPaginationItems({
+      pageCount: 20,
+      currentPage: 10,
+      siblingCount: 1,
+      boundaryCount: 1,
+    });
+    expect(items).toEqual([
+      { type: "page", value: 1 },
+      { type: "ellipsis", key: "gap-1-9" },
+      { type: "page", value: 9 },
+      { type: "page", value: 10 },
+      { type: "page", value: 11 },
+      { type: "ellipsis", key: "gap-11-20" },
+      { type: "page", value: 20 },
+    ]);
+  });
+
+  it("should widen the middle window when siblingCount is larger", () => {
+    const items = buildPaginationItems({
+      pageCount: 30,
+      currentPage: 15,
+      siblingCount: 2,
+      boundaryCount: 1,
+    });
+    const pageValues = items
+      .filter(
+        (item): item is { type: "page"; value: number } => item.type === "page",
+      )
+      .map((item) => item.value);
+    expect(pageValues).toContain(1);
+    expect(pageValues).toContain(30);
+    expect(pageValues).toContain(13);
+    expect(pageValues).toContain(14);
+    expect(pageValues).toContain(15);
+    expect(pageValues).toContain(16);
+    expect(pageValues).toContain(17);
+  });
+});
+
+describe("clampPage", () => {
+  it("should clampPage values into the inclusive page range", () => {
+    expect(clampPage(0, 5)).toBe(1);
+    expect(clampPage(100, 5)).toBe(5);
+    expect(clampPage(3, 5)).toBe(3);
+  });
+
+  it("should return 1 when pageCount is zero", () => {
+    expect(clampPage(5, 0)).toBe(1);
+  });
+});
+
+describe("Pagination (component library)", () => {
+  it("should expose a stable displayName", () => {
+    expect(Pagination.displayName).toBe("Pagination");
+  });
+
+  it("should stamp data-slot on the root nav element", () => {
+    render(<Pagination pageCount={3} defaultPage={1} />);
+    expect(getPaginationRoot().getAttribute("data-slot")).toBe("pagination");
+  });
+
+  it("should render navigation with an accessible name", () => {
+    render(<Pagination pageCount={3} defaultPage={1} />);
+    expect(
+      screen.getByRole("navigation", { name: "Pagination" }),
+    ).toBeVisible();
+  });
+
+  it("should mark the active page with aria-current", () => {
+    render(<Pagination pageCount={5} page={3} />);
+    expect(screen.getByRole("button", { name: "Page 3" })).toHaveAttribute(
+      "aria-current",
+      "page",
+    );
+  });
+
+  it("should call onPageChange when a different page is activated", async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(
+      <Pagination pageCount={5} defaultPage={1} onPageChange={handleChange} />,
+    );
+    await user.click(screen.getByRole("button", { name: "Page 4" }));
+    expect(handleChange).toHaveBeenCalledWith(4);
+  });
+
+  it("should disable the previous control on the first page", () => {
+    render(<Pagination pageCount={4} page={1} />);
+    expect(
+      screen.getByRole("button", { name: "Previous page" }),
+    ).toBeDisabled();
+  });
+
+  it("should disable the next control on the last page", () => {
+    render(<Pagination pageCount={4} page={4} />);
+    expect(screen.getByRole("button", { name: "Next page" })).toBeDisabled();
+  });
+
+  it("should apply list variant classes for the selected appearance", () => {
+    render(<Pagination pageCount={3} page={1} appearance="emerald" />);
+    const list = document.querySelector('[data-slot="pagination-list"]');
+    expect(list?.className).toMatch(/border-emerald-500/);
+  });
+
+  it("should render anchors for page controls when getPageHref is provided", () => {
+    render(
+      <Pagination
+        pageCount={3}
+        page={2}
+        getPageHref={(p) => `/items?page=${p}`}
+      />,
+    );
+    const page2 = screen.getByRole("link", { name: "Page 2" });
+    expect(page2.getAttribute("href")).toBe("/items?page=2");
+    expect(page2).toHaveAttribute("aria-current", "page");
+  });
+});

package/src/ui/pagination/pagination.tsx

@@ -0,0 +1,237 @@
+"use client";
+
+import { forwardRef, useCallback, useId, type KeyboardEvent } from "react";
+
+import { cn, clampPage } from "../../lib/utils";
+import { buttonVariants } from "../buttons/variants";
+
+import type { PaginationProps } from "./types";
+import { usePagination } from "../../hooks/usePagination";
+import { paginationEllipsisVariants, paginationListVariants } from "./variants";
+
+const defaultPrevLabel = "Previous page";
+const defaultNextLabel = "Next page";
+const defaultEllipsisLabel = "More pages";
+
+export const Pagination = forwardRef<HTMLElement, PaginationProps>(
+  function Pagination(
+    {
+      className,
+      appearance = "default",
+      size = "md",
+      pageCount,
+      page,
+      defaultPage = 1,
+      onPageChange,
+      siblingCount = 1,
+      boundaryCount = 1,
+      showPrevNext = true,
+      prevLabel = defaultPrevLabel,
+      nextLabel = defaultNextLabel,
+      ellipsisLabel = defaultEllipsisLabel,
+      getPageHref,
+      "aria-label": ariaLabel = "Pagination",
+      ...rest
+    },
+    ref,
+  ) {
+    const id = useId();
+    const listId = `${id}-list`;
+
+    const {
+      currentPage,
+      items,
+      setPage,
+      goPrev,
+      goNext,
+      canGoPrev,
+      canGoNext,
+    } = usePagination({
+      pageCount,
+      page,
+      defaultPage,
+      siblingCount,
+      boundaryCount,
+      onPageChange,
+    });
+
+    const handleKeyDown = useCallback(
+      (event: KeyboardEvent<HTMLElement>) => {
+        if (pageCount <= 0) {
+          return;
+        }
+        if (event.key === "ArrowRight" || event.key === "ArrowDown") {
+          event.preventDefault();
+          if (canGoNext) {
+            setPage(currentPage + 1);
+          }
+        } else if (event.key === "ArrowLeft" || event.key === "ArrowUp") {
+          event.preventDefault();
+          if (canGoPrev) {
+            setPage(currentPage - 1);
+          }
+        } else if (event.key === "Home") {
+          event.preventDefault();
+          setPage(1);
+        } else if (event.key === "End") {
+          event.preventDefault();
+          setPage(pageCount);
+        }
+      },
+      [canGoNext, canGoPrev, currentPage, pageCount, setPage],
+    );
+
+    if (pageCount <= 0) {
+      return null;
+    }
+
+    const inactiveTriggerClass = cn(
+      buttonVariants({ appearance: "ghost", size }),
+      "bg-white/[0.04] text-slate-200 hover:bg-white/10",
+    );
+
+    const currentTriggerClass = buttonVariants({ appearance, size });
+
+    const triggerFocusRing =
+      "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-slate-300 focus-visible:ring-offset-2 focus-visible:ring-offset-slate-950";
+
+    const renderPageControl = (pageNumber: number) => {
+      const isCurrent = pageNumber === currentPage;
+      const href = getPageHref?.(pageNumber);
+      const shared = cn(
+        isCurrent ? currentTriggerClass : inactiveTriggerClass,
+        "min-w-[2.25ch] shrink-0",
+        triggerFocusRing,
+      );
+
+      if (href) {
+        return (
+          <a
+            data-slot="pagination-trigger"
+            href={href}
+            aria-label={`Page ${pageNumber}`}
+            aria-current={isCurrent ? "page" : undefined}
+            className={shared}
+          >
+            {pageNumber}
+          </a>
+        );
+      }
+
+      return (
+        <button
+          type="button"
+          data-slot="pagination-trigger"
+          aria-label={`Page ${pageNumber}`}
+          aria-current={isCurrent ? "page" : undefined}
+          className={shared}
+          onClick={() => {
+            if (!isCurrent) {
+              setPage(pageNumber);
+            }
+          }}
+        >
+          {pageNumber}
+        </button>
+      );
+    };
+
+    const prevHref = getPageHref?.(clampPage(currentPage - 1, pageCount));
+    const nextHref = getPageHref?.(clampPage(currentPage + 1, pageCount));
+
+    const navTriggerClass = cn(
+      buttonVariants({ appearance: "outline", size }),
+      "shrink-0 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-slate-300 focus-visible:ring-offset-2 focus-visible:ring-offset-slate-950",
+    );
+
+    return (
+      <nav
+        ref={ref}
+        data-slot="pagination"
+        aria-label={ariaLabel}
+        className={cn("w-full", className)}
+        onKeyDown={handleKeyDown}
+        {...rest}
+      >
+        <div className="flex flex-wrap items-center gap-2">
+          {showPrevNext ? (
+            getPageHref && prevHref && canGoPrev ? (
+              <a
+                data-slot="pagination-prev"
+                aria-label={prevLabel}
+                href={prevHref}
+                className={navTriggerClass}
+              >
+                Prev
+              </a>
+            ) : (
+              <button
+                type="button"
+                data-slot="pagination-prev"
+                aria-label={prevLabel}
+                disabled={!canGoPrev}
+                className={navTriggerClass}
+                onClick={goPrev}
+              >
+                Prev
+              </button>
+            )
+          ) : null}
+
+          <ul
+            id={listId}
+            data-slot="pagination-list"
+            className={paginationListVariants({ appearance, size })}
+          >
+            {items.map((item) => (
+              <li
+                key={item.type === "page" ? `page-${item.value}` : item.key}
+                data-slot="pagination-item"
+                className="inline-flex items-center"
+              >
+                {item.type === "ellipsis" ? (
+                  <span
+                    data-slot="pagination-ellipsis"
+                    aria-hidden="true"
+                    title={ellipsisLabel}
+                    className={paginationEllipsisVariants({ size })}
+                  >
+                    …
+                  </span>
+                ) : (
+                  renderPageControl(item.value)
+                )}
+              </li>
+            ))}
+          </ul>
+
+          {showPrevNext ? (
+            getPageHref && nextHref && canGoNext ? (
+              <a
+                data-slot="pagination-next"
+                aria-label={nextLabel}
+                href={nextHref}
+                className={navTriggerClass}
+              >
+                Next
+              </a>
+            ) : (
+              <button
+                type="button"
+                data-slot="pagination-next"
+                aria-label={nextLabel}
+                disabled={!canGoNext}
+                className={navTriggerClass}
+                onClick={goNext}
+              >
+                Next
+              </button>
+            )
+          ) : null}
+        </div>
+      </nav>
+    );
+  },
+);
+
+Pagination.displayName = "Pagination";

package/src/ui/pagination/types.ts

@@ -0,0 +1,66 @@
+import type { VariantProps } from "class-variance-authority";
+import type { ComponentPropsWithoutRef } from "react";
+
+import type { buttonVariants } from "../buttons/variants";
+
+export type PaginationAppearance = NonNullable<
+  VariantProps<typeof buttonVariants>["appearance"]
+>;
+
+export type PaginationSize = NonNullable<
+  VariantProps<typeof buttonVariants>["size"]
+>;
+
+export type PaginationPageItem =
+  | { type: "page"; value: number }
+  | { type: "ellipsis"; key: string };
+
+export type UsePaginationParams = {
+  pageCount: number;
+  page?: number;
+  defaultPage?: number;
+  siblingCount?: number;
+  boundaryCount?: number;
+  onPageChange?: (page: number) => void;
+};
+
+export type UsePaginationResult = {
+  /** 1-based active page, clamped to `[1, pageCount]`. */
+  currentPage: number;
+  pageCount: number;
+  items: PaginationPageItem[];
+  setPage: (page: number) => void;
+  goPrev: () => void;
+  goNext: () => void;
+  canGoPrev: boolean;
+  canGoNext: boolean;
+};
+
+export type PaginationProps = Omit<
+  ComponentPropsWithoutRef<"nav">,
+  "onChange"
+> &
+  VariantProps<typeof buttonVariants> & {
+    pageCount: number;
+    page?: number;
+    defaultPage?: number;
+    onPageChange?: (page: number) => void;
+    /**
+     * Number of page buttons to show on each side of the current page (the “middle” window).
+     * @defaultValue 1
+     */
+    siblingCount?: number;
+    /**
+     * Number of pages to keep visible at the start and end of the range.
+     * @defaultValue 1
+     */
+    boundaryCount?: number;
+    showPrevNext?: boolean;
+    prevLabel?: string;
+    nextLabel?: string;
+    ellipsisLabel?: string;
+    /**
+     * When set, page controls render as anchors suitable for URL-based pagination.
+     */
+    getPageHref?: (page: number) => string | undefined;
+  };

package/src/ui/pagination/variants.ts

@@ -0,0 +1,97 @@
+import { cva } from "class-variance-authority";
+
+/**
+ * Layout and chrome for the page list cluster. Appearance and size keys align with
+ * `components/ui/buttons/variants.ts` for consistent design-system tokens.
+ */
+export const paginationListVariants = cva(
+  "inline-flex flex-wrap items-center rounded-xl border p-1 ring-offset-slate-950",
+  {
+    variants: {
+      appearance: {
+        default: "border-white/10 bg-white/[0.03]",
+        secondary: "border-white/10 bg-slate-900/40",
+        destructive: "border-rose-500/25 bg-rose-950/20",
+        outline: "border-white/15 bg-transparent",
+        ghost: "border-transparent bg-transparent",
+        link: "border-transparent bg-transparent",
+        glass: "border-white/15 bg-white/5 backdrop-blur-md",
+        emerald: "border-emerald-500/25 bg-emerald-950/20",
+        indigo: "border-indigo-500/25 bg-indigo-950/20",
+        purple: "border-purple-500/25 bg-purple-950/20",
+        pink: "border-pink-500/25 bg-pink-950/20",
+        rose: "border-rose-500/25 bg-rose-950/20",
+        sky: "border-sky-500/25 bg-sky-950/20",
+        teal: "border-teal-500/25 bg-teal-950/20",
+        yellow: "border-yellow-500/25 bg-yellow-950/20",
+        orange: "border-orange-500/25 bg-orange-950/20",
+        gray: "border-gray-500/25 bg-gray-950/20",
+        amber: "border-amber-500/25 bg-amber-950/20",
+        violet: "border-violet-500/25 bg-violet-950/20",
+        "gradient-blue":
+          "border-blue-500/30 bg-gradient-to-r from-blue-950/30 to-purple-950/30",
+        "gradient-green":
+          "border-lime-500/30 bg-gradient-to-r from-green-950/30 to-lime-950/30",
+        "gradient-red":
+          "border-pink-500/30 bg-gradient-to-r from-red-950/30 to-pink-950/30",
+        "gradient-yellow":
+          "border-orange-500/30 bg-gradient-to-r from-yellow-950/30 to-orange-950/30",
+        "gradient-purple":
+          "border-pink-500/30 bg-gradient-to-r from-purple-950/30 to-pink-950/30",
+        "gradient-teal":
+          "border-cyan-500/30 bg-gradient-to-r from-teal-950/30 to-cyan-950/30",
+        "gradient-indigo":
+          "border-purple-500/30 bg-gradient-to-r from-indigo-950/30 to-purple-950/30",
+        "gradient-pink":
+          "border-rose-500/30 bg-gradient-to-r from-pink-950/30 to-rose-950/30",
+        "gradient-orange":
+          "border-orange-500/30 bg-gradient-to-r from-orange-950/30 to-red-950/30",
+      },
+      size: {
+        sm: "gap-0.5",
+        md: "gap-1",
+        lg: "gap-1",
+        xl: "gap-1.5",
+        "2xl": "gap-1.5",
+        "3xl": "gap-2",
+        "4xl": "gap-2",
+        "5xl": "gap-2",
+        "6xl": "gap-2",
+        "7xl": "gap-2.5",
+        "8xl": "gap-2.5",
+        "9xl": "gap-2.5",
+        "10xl": "gap-3",
+        icon: "gap-1",
+      },
+    },
+    defaultVariants: {
+      appearance: "default",
+      size: "md",
+    },
+  },
+);
+
+export const paginationEllipsisVariants = cva(
+  "inline-flex min-w-[2ch] select-none items-center justify-center px-1 font-medium text-slate-400",
+  {
+    variants: {
+      size: {
+        sm: "text-xs",
+        md: "text-sm",
+        lg: "text-base",
+        xl: "text-base",
+        "2xl": "text-lg",
+        "3xl": "text-lg",
+        "4xl": "text-xl",
+        "5xl": "text-xl",
+        "6xl": "text-xl",
+        "7xl": "text-2xl",
+        "8xl": "text-2xl",
+        "9xl": "text-2xl",
+        "10xl": "text-2xl",
+        icon: "text-sm",
+      },
+    },
+    defaultVariants: { size: "md" },
+  },
+);

package/src/ui/progress/animated/animations.ts

@@ -0,0 +1,9 @@
+import { ProgressAnimationPresets } from "./types";
+
+export const progressAnimationPresets: ProgressAnimationPresets = {
+  none: {},
+  shimmer: {
+    animate: { backgroundPosition: ["0% 0%", "100% 0%"] },
+    transition: { repeat: Infinity, duration: 1.2, ease: "linear" },
+  },
+};

package/src/ui/progress/animated/index.ts

@@ -0,0 +1,17 @@
+"use client";
+
+export {
+  ProgressAnimated,
+  ProgressBarAnimated,
+  ProgressLabel,
+  ProgressValue,
+} from "./progress-animated";
+export type {
+  ProgressAnimatedProps,
+  ProgressAnimation,
+  ProgressAnimationPresets,
+  ProgressPresetMotionProps,
+  ProgressVariantProps,
+  ProgressBarAnimatedProps,
+} from "./types";
+export { progressAnimationPresets } from "./animations";