@usetheo/ui 0.8.0-next.0 → 0.10.0-next.0

package/registry/r/pagination.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "pagination",
+  "type": "registry:ui",
+  "title": "Pagination",
+  "description": "Accessible page-number navigation primitive. Renders <nav aria-label=Pagination> with first/prev/numbers/next/last buttons and visual ellipses when totalPages exceeds the visible range. Active page carries aria-current=page. Keyboard nav: ArrowLeft / ArrowRight / Home / End. Configurable siblingCount + optional jump buttons. Returns null when totalPages <= 1. Exports a pure computePageRange helper for unit testing the range logic in isolation.",
+  "dependencies": [
+    "lucide-react"
+  ],
+  "registryDependencies": [
+    "https://usetheodev.github.io/theo-ui/r/cn.json",
+    "https://usetheodev.github.io/theo-ui/r/tailwind-preset.json"
+  ],
+  "files": [
+    {
+      "path": "components/primitives/pagination/pagination.tsx",
+      "type": "registry:ui",
+      "target": "components/ui/pagination.tsx",
+      "content": "import { ChevronLeft, ChevronRight, ChevronsLeft, ChevronsRight } from \"lucide-react\";\nimport { forwardRef } from \"react\";\nimport type { HTMLAttributes, KeyboardEvent } from \"react\";\nimport { cn } from \"@/lib/cn\";\n\n/**\n * Pagination — accessible page-number navigation primitive.\n *\n * Renders a `<nav aria-label=\"Pagination\">` containing a button group:\n * `[<<] [<] 1 ... 5 6 [7] 8 9 ... 42 [>] [>>]`. The active page carries\n * `aria-current=\"page\"`. Keyboard navigation (ArrowLeft / ArrowRight /\n * Home / End) is wired on the nav. Ellipses are rendered as\n * non-interactive `<span>` elements with `aria-hidden`.\n *\n * Renders nothing when `totalPages <= 1` (the page is the whole list).\n *\n * `siblingCount` controls how many neighbors of the current page are\n * always visible (default 1 → \"5 6 [7] 8 9\"). `showJumpButtons`\n * toggles the first/last `<<` / `>>` buttons.\n *\n * Consumers control state (`currentPage`) and are responsible for any\n * URL routing — the buttons are `<button>`, not `<a>`.\n *\n * @example\n *   <Pagination\n *     currentPage={page}\n *     totalPages={42}\n *     onPageChange={setPage}\n *   />\n */\nexport interface PaginationProps extends Omit<HTMLAttributes<HTMLElement>, \"onChange\"> {\n  currentPage: number;\n  totalPages: number;\n  onPageChange: (page: number) => void;\n  /** Neighbors of current page that stay visible. Default 1. */\n  siblingCount?: number;\n  /** Render `<<` / `>>` first/last buttons. Default true. */\n  showJumpButtons?: boolean;\n  /** Size variant. Default md. */\n  size?: \"sm\" | \"md\";\n}\n\n/**\n * Pure helper: compute the visible page-range with ellipses.\n * Exported for unit testing — most pagination bugs live here.\n */\nexport function computePageRange(\n  currentPage: number,\n  totalPages: number,\n  siblingCount = 1,\n): Array<number | \"ellipsis-start\" | \"ellipsis-end\"> {\n  if (totalPages <= 1) return [];\n\n  // Always keep first + last + siblings around current.\n  // Total \"core\" buttons: 1 + (siblingCount * 2 + 1) + 1 = siblingCount * 2 + 3.\n  // Plus possibly 2 ellipsis placeholders → max visible = siblingCount * 2 + 5.\n  const totalNumbers = siblingCount * 2 + 3;\n  const totalWithEdges = totalNumbers + 2;\n\n  if (totalPages <= totalWithEdges) {\n    return Array.from({ length: totalPages }, (_, i) => i + 1);\n  }\n\n  const leftSibling = Math.max(currentPage - siblingCount, 1);\n  const rightSibling = Math.min(currentPage + siblingCount, totalPages);\n\n  const showLeftEllipsis = leftSibling > 2;\n  const showRightEllipsis = rightSibling < totalPages - 1;\n\n  if (!showLeftEllipsis && showRightEllipsis) {\n    const leftRangeEnd = 1 + (siblingCount * 2 + 2);\n    const leftRange = Array.from({ length: leftRangeEnd }, (_, i) => i + 1);\n    return [...leftRange, \"ellipsis-end\", totalPages];\n  }\n\n  if (showLeftEllipsis && !showRightEllipsis) {\n    const rightStart = totalPages - (siblingCount * 2 + 2);\n    const rightRange = Array.from(\n      { length: totalPages - rightStart + 1 },\n      (_, i) => rightStart + i,\n    );\n    return [1, \"ellipsis-start\", ...rightRange];\n  }\n\n  // Both sides need ellipsis.\n  const middleRange = Array.from(\n    { length: rightSibling - leftSibling + 1 },\n    (_, i) => leftSibling + i,\n  );\n  return [1, \"ellipsis-start\", ...middleRange, \"ellipsis-end\", totalPages];\n}\n\nconst SIZE: Record<NonNullable<PaginationProps[\"size\"]>, string> = {\n  sm: \"size-7 text-label\",\n  md: \"size-8 text-body-sm\",\n};\n\nconst ICON_SIZE: Record<NonNullable<PaginationProps[\"size\"]>, string> = {\n  sm: \"size-3\",\n  md: \"size-3.5\",\n};\n\nconst Pagination = forwardRef<HTMLElement, PaginationProps>(\n  (\n    {\n      className,\n      currentPage,\n      totalPages,\n      onPageChange,\n      siblingCount = 1,\n      showJumpButtons = true,\n      size = \"md\",\n      ...props\n    },\n    ref,\n  ) => {\n    if (totalPages <= 1) {\n      return null;\n    }\n\n    const range = computePageRange(currentPage, totalPages, siblingCount);\n    const prevDisabled = currentPage <= 1;\n    const nextDisabled = currentPage >= totalPages;\n    const sizeClass = SIZE[size];\n    const iconClass = ICON_SIZE[size];\n\n    const buttonBase = cn(\n      \"inline-flex items-center justify-center rounded-md font-mono tabular-nums\",\n      \"transition-colors\",\n      \"focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background\",\n      sizeClass,\n    );\n\n    function go(page: number) {\n      const clamped = Math.max(1, Math.min(totalPages, page));\n      if (clamped !== currentPage) onPageChange(clamped);\n    }\n\n    function handleKeyDown(e: KeyboardEvent<HTMLElement>) {\n      if (e.key === \"ArrowLeft\") {\n        e.preventDefault();\n        go(currentPage - 1);\n      } else if (e.key === \"ArrowRight\") {\n        e.preventDefault();\n        go(currentPage + 1);\n      } else if (e.key === \"Home\") {\n        e.preventDefault();\n        go(1);\n      } else if (e.key === \"End\") {\n        e.preventDefault();\n        go(totalPages);\n      }\n    }\n\n    return (\n      <nav\n        ref={ref}\n        aria-label=\"Pagination\"\n        onKeyDown={handleKeyDown}\n        className={cn(\"flex items-center gap-1\", className)}\n        {...props}\n      >\n        {showJumpButtons ? (\n          <button\n            type=\"button\"\n            onClick={() => go(1)}\n            disabled={prevDisabled}\n            aria-label=\"Go to first page\"\n            aria-disabled={prevDisabled || undefined}\n            className={cn(\n              buttonBase,\n              \"text-foreground hover:bg-muted\",\n              prevDisabled && \"cursor-not-allowed opacity-40 hover:bg-transparent\",\n            )}\n          >\n            <ChevronsLeft aria-hidden=\"true\" className={iconClass} />\n          </button>\n        ) : null}\n        <button\n          type=\"button\"\n          onClick={() => go(currentPage - 1)}\n          disabled={prevDisabled}\n          aria-label=\"Go to previous page\"\n          aria-disabled={prevDisabled || undefined}\n          className={cn(\n            buttonBase,\n            \"text-foreground hover:bg-muted\",\n            prevDisabled && \"cursor-not-allowed opacity-40 hover:bg-transparent\",\n          )}\n        >\n          <ChevronLeft aria-hidden=\"true\" className={iconClass} />\n        </button>\n        {range.map((item) => {\n          if (item === \"ellipsis-start\" || item === \"ellipsis-end\") {\n            return (\n              <span\n                key={item}\n                aria-hidden=\"true\"\n                className={cn(\n                  \"inline-flex items-center justify-center text-muted-foreground\",\n                  sizeClass,\n                )}\n              >\n                …\n              </span>\n            );\n          }\n          const isActive = item === currentPage;\n          return (\n            <button\n              key={item}\n              type=\"button\"\n              onClick={() => go(item)}\n              aria-label={`Go to page ${item}`}\n              aria-current={isActive ? \"page\" : undefined}\n              className={cn(\n                buttonBase,\n                isActive\n                  ? \"bg-primary text-primary-foreground hover:bg-primary\"\n                  : \"text-foreground hover:bg-muted\",\n              )}\n            >\n              {item}\n            </button>\n          );\n        })}\n        <button\n          type=\"button\"\n          onClick={() => go(currentPage + 1)}\n          disabled={nextDisabled}\n          aria-label=\"Go to next page\"\n          aria-disabled={nextDisabled || undefined}\n          className={cn(\n            buttonBase,\n            \"text-foreground hover:bg-muted\",\n            nextDisabled && \"cursor-not-allowed opacity-40 hover:bg-transparent\",\n          )}\n        >\n          <ChevronRight aria-hidden=\"true\" className={iconClass} />\n        </button>\n        {showJumpButtons ? (\n          <button\n            type=\"button\"\n            onClick={() => go(totalPages)}\n            disabled={nextDisabled}\n            aria-label=\"Go to last page\"\n            aria-disabled={nextDisabled || undefined}\n            className={cn(\n              buttonBase,\n              \"text-foreground hover:bg-muted\",\n              nextDisabled && \"cursor-not-allowed opacity-40 hover:bg-transparent\",\n            )}\n          >\n            <ChevronsRight aria-hidden=\"true\" className={iconClass} />\n          </button>\n        ) : null}\n      </nav>\n    );\n  },\n);\nPagination.displayName = \"Pagination\";\n\nexport { Pagination };\n"
+    }
+  ]
+}