ionbase-ui 0.47.0 → 0.51.0

package/dist/meta/Pagination.json

@@ -0,0 +1,200 @@
+{
+  "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"
+    },
+    "className": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    }
+  },
+  "propCounts": {
+    "own": 11,
+    "aria": 0,
+    "dom": 276,
+    "other": 0
+  }
+}