{
  "schemaVersion": 1,
  "target": "react",
  "name": "pagination",
  "version": "0.1.0",
  "category": "navigation",
  "title": "Pagination",
  "description": "Page controls with previous and next, page numbers that collapse into ellipses, and a compact \"Page 3 of 12\" variant, as links or buttons.",
  "tags": [
    "navigation",
    "pagination",
    "pager",
    "table"
  ],
  "requires": {
    "projectTypes": [
      "next",
      "vite-react"
    ],
    "styling": "tailwind-v4"
  },
  "npmDependencies": {
    "@base-ui/react": "^1.9.0"
  },
  "registryDependencies": [],
  "docsPath": "/components/pagination",
  "props": [
    {
      "name": "paginationRange(page, pageCount, siblings?)",
      "type": "(number, number, number) => (number | \"ellipsis\")[]",
      "description": "Pages to render: first, last, the current page with siblings on each side, and ellipses for skipped runs. The length stays constant once there are enough pages, so controls do not jump."
    },
    {
      "name": "PaginationLink href",
      "type": "string",
      "description": "Renders an <a>. Without href (and without render) the control is a <button> for onClick paging."
    },
    {
      "name": "PaginationLink isActive",
      "type": "boolean",
      "default": "false",
      "description": "Marks the current page with aria-current=\"page\", a selected tint, and a hairline ring."
    },
    {
      "name": "PaginationLink disabled",
      "type": "boolean",
      "default": "false",
      "description": "Keeps the control in place but inert. Links drop their href and set aria-disabled; buttons are disabled."
    },
    {
      "name": "PaginationLink render",
      "type": "ReactElement",
      "description": "Your router's link, for example render={<Link href=\"?page=4\" />}."
    },
    {
      "name": "PaginationPrevious / PaginationNext label",
      "type": "string",
      "default": "\"Previous\" / \"Next\"",
      "description": "Visible text beside the arrow. Below 480px only the arrow shows; the text stays as the accessible name."
    },
    {
      "name": "PaginationEllipsis",
      "type": "ComponentProps<\"span\">",
      "description": "Marks skipped pages. Hidden from assistive technology."
    },
    {
      "name": "PaginationCompact page / pageCount",
      "type": "number",
      "description": "Current page (from 1) and total pages for the compact variant."
    },
    {
      "name": "PaginationCompact onPageChange / getHref",
      "type": "(page) => void / (page) => string",
      "description": "Button paging, or link paging when getHref is set. renderLink wraps links in your router component."
    }
  ],
  "accessibility": [
    "Pagination renders a nav landmark named \"Pagination\"; rename it with aria-label when there is more than one.",
    "The current page has aria-current=\"page\" and reads without color: a tint plus a hairline ring and stronger text.",
    "Page numbers rendered as buttons get an aria-label such as \"Page 4\" in the example, so the control is not announced as a bare number.",
    "Previous and Next keep their text as the accessible name when it is visually hidden on narrow screens.",
    "Disabled link controls have no href and set aria-disabled, so they stay in reading order but cannot be followed; disabled buttons use the disabled attribute.",
    "The compact variant's \"Page 3 of 12\" is a polite live region, so the new page is announced after an arrow is pressed.",
    "Controls have a visible focus ring and change only colors (150ms, removed with reduced motion)."
  ],
  "states": [
    "default",
    "current",
    "disabled",
    "compact"
  ],
  "files": [
    {
      "path": "ui/pagination.tsx",
      "content": "\"use client\";\n\nimport { mergeProps } from \"@base-ui/react/merge-props\";\nimport { useRender } from \"@base-ui/react/use-render\";\nimport type { ComponentProps, MouseEvent, ReactElement } from \"react\";\n\nfunction cx(...classes: (string | false | null | undefined)[]) {\n  return classes.filter(Boolean).join(\" \");\n}\n\n/**\n * The pages to show for `page` out of `pageCount`: always the first and last page, `siblings`\n * pages on each side of the current one, and `\"ellipsis\"` where a run of pages is skipped.\n * The result has a constant length once there are enough pages, so the controls never jump in width.\n */\nexport function paginationRange(page: number, pageCount: number, siblings = 1): (number | \"ellipsis\")[] {\n  const total = Math.max(1, Math.floor(pageCount));\n  const current = Math.min(Math.max(1, Math.floor(page)), total);\n  // first + last + current + siblings on each side + two ellipses\n  const slots = siblings * 2 + 5;\n  if (total <= slots) return Array.from({ length: total }, (_, index) => index + 1);\n\n  const range = (from: number, to: number) => Array.from({ length: to - from + 1 }, (_, index) => from + index);\n  const edgeCount = siblings * 2 + 3;\n  const showStartGap = current - siblings > 3;\n  const showEndGap = current + siblings < total - 2;\n  if (!showStartGap) return [...range(1, edgeCount), \"ellipsis\", total];\n  if (!showEndGap) return [1, \"ellipsis\", ...range(total - edgeCount + 1, total)];\n  return [1, \"ellipsis\", ...range(current - siblings, current + siblings), \"ellipsis\", total];\n}\n\nexport interface PaginationProps extends ComponentProps<\"nav\"> {\n  /** Accessible name of the landmark. */\n  \"aria-label\"?: string;\n}\n\n/** The pagination landmark. Holds a `PaginationList`, or a `PaginationCompact`. */\nexport function Pagination({ \"aria-label\": label = \"Pagination\", className, ...props }: PaginationProps) {\n  return <nav aria-label={label} className={cx(\"flex\", className)} {...props} />;\n}\n\n/** The row of page controls. */\nexport function PaginationList({ className, ...props }: ComponentProps<\"ul\">) {\n  return <ul className={cx(\"m-0 flex list-none items-center gap-1 p-0\", className)} {...props} />;\n}\n\n/** Wraps one control in the list. */\nexport function PaginationItem({ className, ...props }: ComponentProps<\"li\">) {\n  return <li className={cx(\"flex\", className)} {...props} />;\n}\n\nconst control = cx(\n  \"inline-flex h-8 min-w-8 items-center justify-center gap-1 rounded-lg px-2 text-sm font-medium tabular-nums no-underline select-none\",\n  \"text-zinc-600 dark:text-zinc-400\",\n  \"transition-[background-color,color,box-shadow] duration-150 ease-out motion-reduce:transition-none\",\n  \"hover:bg-zinc-950/[0.04] hover:text-zinc-950 dark:hover:bg-white/[0.06] dark:hover:text-white\",\n  \"focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-sky-500\",\n  // The current page: selected tint plus a hairline ring, so it reads without color.\n  \"aria-[current=page]:bg-zinc-950/[0.06] aria-[current=page]:text-zinc-950 aria-[current=page]:shadow-[inset_0_0_0_1px_rgb(9_9_11/0.1)]\",\n  \"dark:aria-[current=page]:bg-white/[0.09] dark:aria-[current=page]:text-white dark:aria-[current=page]:shadow-[inset_0_0_0_1px_rgb(255_255_255/0.14)]\",\n  \"aria-disabled:pointer-events-none aria-disabled:opacity-40 disabled:pointer-events-none disabled:opacity-40\",\n  \"[&_svg]:size-4 [&_svg]:shrink-0\",\n);\n\nexport interface PaginationLinkProps extends Omit<useRender.ComponentProps<\"a\">, \"href\"> {\n  /** Destination of the control. Without it the control renders a `<button>` for `onClick` paging. */\n  href?: string;\n  /** Marks the current page with `aria-current=\"page\"`. */\n  isActive?: boolean;\n  /** Keeps the control in place but inert, for example Previous on the first page. */\n  disabled?: boolean;\n}\n\n/**\n * A page number or arrow control. Renders an `<a>` when `href` is set and a `<button>` otherwise;\n * pass `render={<Link href=\"…\" />}` for your router. Disabled links drop their `href` and set\n * `aria-disabled`, so they stay in the reading order without being followable.\n */\nexport function PaginationLink({ href, isActive = false, disabled = false, render, className, onClick, ...props }: PaginationLinkProps) {\n  const asLink = href !== undefined || render !== undefined;\n  const handleClick = (event: MouseEvent<HTMLAnchorElement>) => {\n    if (disabled) {\n      event.preventDefault();\n      return;\n    }\n    onClick?.(event);\n  };\n\n  return useRender({\n    defaultTagName: asLink ? \"a\" : \"button\",\n    render,\n    props: mergeProps<\"a\">(\n      {\n        className: cx(control, className),\n        \"aria-current\": isActive ? \"page\" : undefined,\n        ...(asLink\n          ? { href: disabled ? undefined : href, \"aria-disabled\": disabled || undefined, role: disabled ? \"link\" : undefined }\n          : ({ type: \"button\", disabled } as Record<string, unknown>)),\n      },\n      { ...props, onClick: handleClick },\n    ),\n  });\n}\n\nconst chevronLeft = (\n  <svg aria-hidden=\"true\" viewBox=\"0 0 16 16\" fill=\"none\">\n    <path d=\"M9.75 4.25 6 8l3.75 3.75\" stroke=\"currentColor\" strokeWidth=\"1.5\" strokeLinecap=\"round\" strokeLinejoin=\"round\" />\n  </svg>\n);\nconst chevronRight = (\n  <svg aria-hidden=\"true\" viewBox=\"0 0 16 16\" fill=\"none\">\n    <path d=\"M6.25 4.25 10 8l-3.75 3.75\" stroke=\"currentColor\" strokeWidth=\"1.5\" strokeLinecap=\"round\" strokeLinejoin=\"round\" />\n  </svg>\n);\n\nexport interface PaginationStepProps extends PaginationLinkProps {\n  /** Visible text. Hidden below 480px wide, where only the arrow shows; it stays the accessible name. */\n  label?: string;\n}\n\n/** The control that goes back one page. */\nexport function PaginationPrevious({ label = \"Previous\", className, ...props }: PaginationStepProps) {\n  return (\n    <PaginationLink className={cx(\"pr-2.5 pl-1.5\", className)} {...props}>\n      {chevronLeft}\n      <span className=\"max-[480px]:sr-only\">{label}</span>\n    </PaginationLink>\n  );\n}\n\n/** The control that goes forward one page. */\nexport function PaginationNext({ label = \"Next\", className, ...props }: PaginationStepProps) {\n  return (\n    <PaginationLink className={cx(\"pr-1.5 pl-2.5\", className)} {...props}>\n      <span className=\"max-[480px]:sr-only\">{label}</span>\n      {chevronRight}\n    </PaginationLink>\n  );\n}\n\n/** Marks skipped pages. Hidden from assistive technology; the page numbers around it carry the meaning. */\nexport function PaginationEllipsis({ className, ...props }: ComponentProps<\"span\">) {\n  return (\n    <span\n      aria-hidden=\"true\"\n      className={cx(\"inline-flex h-8 w-6 items-center justify-center pt-1.5 text-zinc-400 dark:text-zinc-600\", className)}\n      {...props}\n    >\n      <svg viewBox=\"0 0 16 4\" fill=\"currentColor\" className=\"h-1 w-4\">\n        <circle cx=\"2.5\" cy=\"2\" r=\"1.1\" />\n        <circle cx=\"8\" cy=\"2\" r=\"1.1\" />\n        <circle cx=\"13.5\" cy=\"2\" r=\"1.1\" />\n      </svg>\n    </span>\n  );\n}\n\nexport interface PaginationCompactProps extends Omit<ComponentProps<\"div\">, \"children\"> {\n  /** The current page, starting at 1. */\n  page: number;\n  /** Total number of pages. */\n  pageCount: number;\n  /** Called with the next page when an arrow is pressed. Use it for button paging. */\n  onPageChange?: (page: number) => void;\n  /** Builds a URL for a page. When set, the arrows render as links. */\n  getHref?: (page: number) => string;\n  /** Wraps each arrow link, for example `(href) => <Link href={href} />`. */\n  renderLink?: (href: string) => ReactElement;\n  /** Accessible names of the arrows. */\n  previousLabel?: string;\n  nextLabel?: string;\n}\n\n/**\n * A compact pager for tight spaces: two arrows around \"Page 3 of 12\". The count is a polite live\n * region, so screen readers hear the new page after an arrow is pressed.\n */\nexport function PaginationCompact({\n  page,\n  pageCount,\n  onPageChange,\n  getHref,\n  renderLink,\n  previousLabel = \"Previous page\",\n  nextLabel = \"Next page\",\n  className,\n  ...props\n}: PaginationCompactProps) {\n  const total = Math.max(1, pageCount);\n  const current = Math.min(Math.max(1, page), total);\n  const linkProps = (target: number) => {\n    const href = getHref?.(target);\n    return {\n      href,\n      render: href !== undefined && renderLink ? renderLink(href) : undefined,\n      onClick: onPageChange ? () => onPageChange(target) : undefined,\n    };\n  };\n\n  return (\n    <div className={cx(\"inline-flex items-center gap-1\", className)} {...props}>\n      <PaginationLink aria-label={previousLabel} disabled={current <= 1} className=\"px-0\" {...linkProps(current - 1)}>\n        {chevronLeft}\n      </PaginationLink>\n      <span aria-live=\"polite\" className=\"min-w-[7.5rem] px-1 text-center text-sm text-zinc-500 tabular-nums dark:text-zinc-400\">\n        Page <span className=\"font-medium text-zinc-950 dark:text-white\">{current}</span> of {total}\n      </span>\n      <PaginationLink aria-label={nextLabel} disabled={current >= total} className=\"px-0\" {...linkProps(current + 1)}>\n        {chevronRight}\n      </PaginationLink>\n    </div>\n  );\n}\n"
    }
  ],
  "example": {
    "content": "\"use client\";\n\nimport { useState } from \"react\";\nimport {\n  Pagination,\n  PaginationCompact,\n  PaginationEllipsis,\n  PaginationItem,\n  PaginationLink,\n  PaginationList,\n  PaginationNext,\n  PaginationPrevious,\n  paginationRange,\n} from \"@/components/shaken/ui/pagination\";\n\nconst pageSize = 25;\nconst runCount = 293;\nconst pageCount = Math.ceil(runCount / pageSize);\n\nexport default function PaginationExample() {\n  const [page, setPage] = useState(4);\n  const [logPage, setLogPage] = useState(3);\n  const first = (page - 1) * pageSize + 1;\n  const last = Math.min(page * pageSize, runCount);\n\n  return (\n    <div className=\"flex w-full max-w-xl flex-col gap-8\">\n      <div className=\"flex flex-col items-center gap-3\">\n        <Pagination aria-label=\"Agent runs pages\">\n          <PaginationList>\n            <PaginationItem>\n              <PaginationPrevious disabled={page === 1} onClick={() => setPage(page - 1)} />\n            </PaginationItem>\n            {paginationRange(page, pageCount).map((entry, index) =>\n              entry === \"ellipsis\" ? (\n                <PaginationItem key={`gap-${index}`}>\n                  <PaginationEllipsis />\n                </PaginationItem>\n              ) : (\n                <PaginationItem key={entry}>\n                  <PaginationLink isActive={entry === page} aria-label={`Page ${entry}`} onClick={() => setPage(entry)}>\n                    {entry}\n                  </PaginationLink>\n                </PaginationItem>\n              ),\n            )}\n            <PaginationItem>\n              <PaginationNext disabled={page === pageCount} onClick={() => setPage(page + 1)} />\n            </PaginationItem>\n          </PaginationList>\n        </Pagination>\n        <p className=\"text-xs text-zinc-500 tabular-nums\">\n          Showing runs {first} to {last} of {runCount}\n        </p>\n      </div>\n\n      <div className=\"flex items-center justify-between gap-4 border-t border-zinc-950/[0.07] pt-4 dark:border-white/[0.08]\">\n        <span className=\"font-mono text-xs text-zinc-500\">deploy.log</span>\n        <Pagination aria-label=\"Log pages\">\n          <PaginationCompact page={logPage} pageCount={12} onPageChange={setLogPage} />\n        </Pagination>\n      </div>\n    </div>\n  );\n}\n"
  }
}
