{
  "name": "Pagination",
  "source": "src/components/Pagination.tsx",
  "propsType": "PaginationProps",
  "description": "Page navigation for a table or list.\n\nGeometry from the Figma `Pagination` (1291:503) and `Pagination Item`\n(1283:289) components. The Figma item set is not exported — a caller places a\nPagination, never a cell.",
  "import": "import { Pagination } from 'ionbase-ui';",
  "status": "stable",
  "summary": "Page navigation for a table or list. Renders prev/next arrows, a truncated run of page numbers, and an optional rows-per-page Select.",
  "useWhen": [
    "a result set is split into pages and the user needs to move between them",
    "the total number of pages is known — the numbered run needs a last page to anchor to"
  ],
  "useInstead": [
    {
      "when": "the total is unknown or unbounded, as with a cursor-based or infinite feed",
      "use": "Button",
      "why": "a numbered pager has to draw a last page; with no total there is nothing to draw, and a bare Load more button is honest about that"
    },
    {
      "when": "the user is moving between peer views rather than through one long list",
      "use": "Tabs",
      "why": "pagination implies a sequence with a position; tabs are peers in any order"
    },
    {
      "when": "it is navigation between pages of the app rather than pages of data",
      "use": "NavItem"
    }
  ],
  "variants": {
    "type": {
      "numbered": {
        "use": "the default — prev, the page numbers, next. Use wherever the numbers fit"
      },
      "simple": {
        "use": "prev, \"Page N of M\", next. For drawers, narrow columns and mobile, where a numbered run would wrap or truncate to uselessness"
      }
    },
    "size": {
      "sm": {
        "use": "dense tables, and toolbars"
      },
      "md": {
        "use": "the default"
      },
      "lg": {
        "use": "roomy layouts, and touch targets on tablet"
      }
    }
  },
  "a11y": {
    "role": "navigation / list",
    "guarantees": [
      "the whole control is a landmark — a `nav` with an accessible name, defaulting to \"Pagination\"",
      "the current page carries `aria-current=\"page\"`, not `aria-pressed`: this is a position in a set, not a toggle",
      "every cell has an explicit label — \"Go to page 4\", \"Go to previous page\" — so a screen reader never announces a bare digit",
      "the ellipsis is `aria-hidden` and not focusable: it marks absent pages, and a tab stop that does nothing when activated is worse than no tab stop",
      "in `simple`, the \"Page N of M\" text is an `aria-live=\"polite\"` region, because the page can change without anything else on screen announcing it",
      "prev and next are genuinely `disabled` at the ends rather than styled to look it",
      "the focus ring shows for keyboard focus only, and hover does not latch on touch"
    ],
    "requires": [
      "`aria-label` when more than one Pagination is on a page — two identically named landmarks are two indistinguishable landmarks",
      "`pageSize` when `showPageSize` is set, or the rows-per-page Select renders with nothing selected"
    ]
  },
  "antiPatterns": [
    {
      "avoid": "passing `pageCount={0}` for an empty result set",
      "instead": "render EmptyState and no pager — the component clamps to a single page, which draws a lone disabled `1` that says a page exists when none does"
    },
    {
      "avoid": "raising `siblingCount` to avoid truncation",
      "instead": "switch to `type=\"simple\"`. Widening the run past the container is the problem truncation exists to solve, and it reappears one breakpoint down"
    },
    {
      "avoid": "treating `page` as 0-based",
      "instead": "it is 1-based, matching what the numbers say. An off-by-one here is silent — the pager looks right and fetches the wrong rows"
    }
  ],
  "stylesheet": "src/styles/pagination.css",
  "tokens": [
    "--border-focus",
    "--border-width-thick",
    "--font-family-sans",
    "--font-weight-medium",
    "--font-weight-regular",
    "--icon-size-lg",
    "--icon-size-md",
    "--icon-size-xs",
    "--ion-duration-base",
    "--ion-ease-out",
    "--ion-pagination-box",
    "--ion-pagination-font-size",
    "--ion-pagination-icon",
    "--ion-pagination-line-height",
    "--radius-md",
    "--spacing-16",
    "--spacing-2",
    "--spacing-32",
    "--spacing-4",
    "--spacing-40",
    "--spacing-48",
    "--spacing-6",
    "--spacing-8",
    "--surface-hover",
    "--surface-selected",
    "--surface-selected-hover",
    "--text-default",
    "--text-disabled",
    "--text-secondary",
    "--text-tertiary",
    "--type-body",
    "--type-body-lg",
    "--type-body-lg-line-height",
    "--type-body-line-height",
    "--type-body-sm",
    "--type-body-sm-line-height"
  ],
  "props": {
    "page": {
      "type": "number",
      "required": true,
      "origin": "own",
      "description": "The current page, 1-based."
    },
    "pageCount": {
      "type": "number",
      "required": true,
      "origin": "own",
      "description": "Total number of pages. One or more."
    },
    "onPageChange": {
      "type": "((page: number) => void) | undefined",
      "required": false,
      "origin": "own",
      "description": "Called with the requested page. Not called for the current page."
    },
    "type": {
      "type": "PaginationType | undefined",
      "required": false,
      "origin": "own",
      "description": "Matches the Figma `Type` variant.",
      "values": [
        "numbered",
        "simple"
      ]
    },
    "size": {
      "type": "PaginationSize | undefined",
      "required": false,
      "origin": "own",
      "description": "Matches the Figma `Size` variant.",
      "values": [
        "sm",
        "md",
        "lg"
      ]
    },
    "siblingCount": {
      "type": "number | undefined",
      "required": false,
      "origin": "own",
      "description": "How many pages to show either side of the current one. The first and last\nare always shown, so the widest run is `siblingCount * 2 + 5`."
    },
    "showPageSize": {
      "type": "boolean | undefined",
      "required": false,
      "origin": "own",
      "description": "Renders the rows-per-page control. Matches the Figma `Show Page Size`."
    },
    "pageSize": {
      "type": "number | undefined",
      "required": false,
      "origin": "own",
      "description": "Current rows-per-page value. Required when `showPageSize`."
    },
    "pageSizeOptions": {
      "type": "number[] | undefined",
      "required": false,
      "origin": "own",
      "description": "Options offered by the rows-per-page control."
    },
    "onPageSizeChange": {
      "type": "((pageSize: number) => void) | undefined",
      "required": false,
      "origin": "own"
    },
    "labels": {
      "type": "PaginationLabels | undefined",
      "required": false,
      "origin": "own",
      "description": "Every string the pager renders, for translation. English by default. The\nlandmark's name is `aria-label` — \"Pagination\" when it is left out."
    },
    "className": {
      "type": "string | undefined",
      "required": false,
      "origin": "own"
    }
  },
  "propCounts": {
    "own": 12,
    "aria": 0,
    "dom": 276,
    "other": 0
  }
}