@commercetools/nimbus-mcp 0.1.0 → 2.11.0

package/data/docs/routes/components-navigation-pagination.json

@@ -0,0 +1,502 @@
+{
+  "meta": {
+    "id": "Components-Pagination",
+    "title": "Pagination",
+    "exportName": "Pagination",
+    "description": "Pagination is a component that divides a large set of content or data into sequential pages, providing navigation controls to move between them.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/pagination/pagination.mdx",
+    "menu": [
+      "Components",
+      "Navigation",
+      "Pagination"
+    ],
+    "route": "components/navigation/pagination",
+    "tags": [
+      "component",
+      "pagination",
+      "paging",
+      "navigation",
+      "pages"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Resources",
+        "href": "#resources",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variables",
+        "href": "#variables",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Visuals",
+        "href": "#visuals",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      }
+    ],
+    "figmaLink": "https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system",
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "guidelines",
+        "title": "Guidelines",
+        "order": 2
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      },
+      {
+        "key": "a11y",
+        "title": "Accessibility",
+        "order": 4
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nPagination contains controls for navigating with dedicated buttons for moving to the next and previous pages, visible page numbering for direct access, and clear feedback indicating the user's current page position within the total set of results.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system)\n\n## Variables\n\nGet familiar with the features.\n\n### Visuals\n\n**Page size selection paired with jump to page**\n\nUse this combination for the most control over viewing and jumping to pages. This is best suited for navigating pagination with a lot of resources. Allowing users to jump to different pages as needed. \n\n\n```jsx live\nconst App = () => {\n  const [currentPage, setCurrentPage] = React.useState(1);\n  const [pageSize, setPageSize] = React.useState(20);\n  \n  return (\n    <Pagination\n      totalItems={150}\n      currentPage={currentPage}\n      pageSize={pageSize}\n      onPageChange={setCurrentPage}\n      onPageSizeChange={setPageSize}\n    />\n  );\n};\n```\n**Simplified paging without page input**\n\nThis combination allows users to select how many items appear on the page and tab through other existing pages. It simplifies paging but restricts users from jumping pages. This is better suited for content that is 20 pages or less. \n\n```jsx live\nconst App = () => {\n  const [currentPage, setCurrentPage] = React.useState(1);\n  const [pageSize, setPageSize] = React.useState(20);\n  \n  return (\n    <Pagination\n      totalItems={150}\n      currentPage={currentPage}\n      pageSize={pageSize}\n      onPageChange={setCurrentPage}\n      onPageSizeChange={setPageSize}\n      enablePageInput={false}\n    />\n  );\n};\n```\n\n**Without page size selector**\n\nThe simplest solution, and mainly for uses with minimal data or processes that have multiple steps. This won't allow users to select how much information is viewed on the page, but only to navigate through via tapping through the arrows.\n\n```jsx live\nconst App = () => {\n  const [currentPage, setCurrentPage] = React.useState(1);\n  \n  return (\n    <Box display=\"flex\" justifyContent=\"flex-start\">\n      <Pagination\n        totalItems={75}\n        currentPage={currentPage}\n        pageSize={15}\n        onPageChange={setCurrentPage}\n        enablePageInput={false}\n        enablePageSizeSelector={false}\n      />\n    </Box>\n  );\n};\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nPagination contains controls for navigating with dedicated buttons for moving to the next and previous pages, visible page numbering for direct access, and clear feedback indicating the user's current page position within the total set of results.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system)\n\n## Variables\n\nGet familiar with the features.\n\n### Visuals\n\n**Page size selection paired with jump to page**\n\nUse this combination for the most control over viewing and jumping to pages. This is best suited for navigating pagination with a lot of resources. Allowing users to jump to different pages as needed. \n\n\n```jsx live\nconst App = () => {\n  const [currentPage, setCurrentPage] = React.useState(1);\n  const [pageSize, setPageSize] = React.useState(20);\n  \n  return (\n    <Pagination\n      totalItems={150}\n      currentPage={currentPage}\n      pageSize={pageSize}\n      onPageChange={setCurrentPage}\n      onPageSizeChange={setPageSize}\n    />\n  );\n};\n```\n**Simplified paging without page input**\n\nThis combination allows users to select how many items appear on the page and tab through other existing pages. It simplifies paging but restricts users from jumping pages. This is better suited for content that is 20 pages or less. \n\n```jsx live\nconst App = () => {\n  const [currentPage, setCurrentPage] = React.useState(1);\n  const [pageSize, setPageSize] = React.useState(20);\n  \n  return (\n    <Pagination\n      totalItems={150}\n      currentPage={currentPage}\n      pageSize={pageSize}\n      onPageChange={setCurrentPage}\n      onPageSizeChange={setPageSize}\n      enablePageInput={false}\n    />\n  );\n};\n```\n\n**Without page size selector**\n\nThe simplest solution, and mainly for uses with minimal data or processes that have multiple steps. This won't allow users to select how much information is viewed on the page, but only to navigate through via tapping through the arrows.\n\n```jsx live\nconst App = () => {\n  const [currentPage, setCurrentPage] = React.useState(1);\n  \n  return (\n    <Box display=\"flex\" justifyContent=\"flex-start\">\n      <Pagination\n        totalItems={75}\n        currentPage={currentPage}\n        pageSize={15}\n        onPageChange={setCurrentPage}\n        enablePageInput={false}\n        enablePageSizeSelector={false}\n      />\n    </Box>\n  );\n};\n```\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variables",
+          "href": "#variables",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Visuals",
+          "href": "#visuals",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\nAccessibility ensures that digital content and functionality are usable by\neveryone, including people with disabilities, by addressing visual, auditory,\ncognitive, and physical limitations.\n\n```jsx live\nconst App = () => {\n  const [currentPage, setCurrentPage] = React.useState(1);\n  const [pageSize, setPageSize] = React.useState(20);\n\n  return (\n    <Pagination\n      totalItems={150}\n      currentPage={currentPage}\n      pageSize={pageSize}\n      onPageChange={setCurrentPage}\n      onPageSizeChange={setPageSize}\n    />\n  );\n};\n```\n\n### Accessibility standards\n\n- **ARIA Roles:** Use `role=\"navigation\"` to identify the component as a\n  navigation block. Use `aria-current=\"page\"` on the active page link/button to\n  signal the user's location to screen readers.\n- **Keyboard Navigation:** Ensure the entire component is navigable using the\n  Tab key and that all links/buttons are operable with the Enter key.\n- **Descriptive Text:** Use `aria-label` on the navigation buttons (\"Previous\n  page,\" \"Next page\") to provide screen readers with unambiguous information,\n  even if the visual text is just an arrow.\n- **Focus Indication:** Provide a strong, clear focus indicator on the currently\n  active navigation item when using keyboard control.\n",
+      "toc": [
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility standards",
+          "href": "#accessibility-standards",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Pagination, type PaginationProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe simplest implementation requires managing the pagination state:\n\n```jsx live-dev\nconst App = () => {\n  const [currentPage, setCurrentPage] = useState<PaginationProps[\"currentPage\"]>(1);\n  const [pageSize, setPageSize] = useState<PaginationProps[\"pageSize\"]>(10);\n\n  const totalItems = 100;\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Text>Total items: {totalItems}</Text>\n      <Pagination\n        totalItems={totalItems}\n        currentPage={currentPage}\n        pageSize={pageSize}\n        onPageChange={setCurrentPage}\n        onPageSizeChange={setPageSize}\n      />\n    </Stack>\n  );\n};\n```\n\n## Usage examples\n\n### Displaying current state\n\nDisplay the current pagination state to provide context to users:\n\n```jsx live-dev\nconst App = () => {\n  const [currentPage, setCurrentPage] = useState<PaginationProps[\"currentPage\"]>(1);\n  const [pageSize, setPageSize] = useState<PaginationProps[\"pageSize\"]>(10);\n\n  const totalItems = 247;\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Stack direction=\"row\" gap=\"200\" align=\"center\">\n        <Text fontWeight=\"semibold\">Current state:</Text>\n        <Text>Page {currentPage} of {Math.ceil(totalItems / (pageSize || 10))}</Text>\n        <Text>•</Text>\n        <Text>{pageSize} items per page</Text>\n      </Stack>\n\n      <Pagination\n        totalItems={totalItems}\n        currentPage={currentPage}\n        pageSize={pageSize}\n        onPageChange={setCurrentPage}\n        onPageSizeChange={setPageSize}\n      />\n    </Stack>\n  );\n};\n```\n\n### Page size selector\n\nEnable the page size selector to allow users to change how many items are displayed per page:\n\n```jsx live-dev\nconst App = () => {\n  const [currentPage, setCurrentPage] = useState<PaginationProps[\"currentPage\"]>(1);\n  const [pageSize, setPageSize] = useState<PaginationProps[\"pageSize\"]>(20);\n\n  const totalItems = 1000;\n  const startItem = ((currentPage || 1) - 1) * (pageSize || 20) + 1;\n  const endItem = Math.min((currentPage || 1) * (pageSize || 20), totalItems);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Text>\n        Showing items {startItem}-{endItem} of {totalItems}\n      </Text>\n\n      <Pagination\n        totalItems={totalItems}\n        currentPage={currentPage}\n        pageSize={pageSize}\n        onPageChange={setCurrentPage}\n        onPageSizeChange={setPageSize}\n        enablePageSizeSelector={true}\n      />\n    </Stack>\n  );\n};\n```\n\n### Direct page input\n\nThe page input field allows users to jump directly to a specific page by typing the page number:\n\n```jsx live-dev\nconst App = () => {\n  const [currentPage, setCurrentPage] = useState<PaginationProps[\"currentPage\"]>(1);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Text>\n        Try typing a page number directly in the input field\n      </Text>\n\n      <Pagination\n        totalItems={500}\n        currentPage={currentPage}\n        onPageChange={setCurrentPage}\n        enablePageInput={true}\n      />\n    </Stack>\n  );\n};\n```\n\n### Configuration options\n\nCustomize which controls are displayed by enabling or disabling the page input and page size selector:\n\n```jsx live-dev\nconst App = () => {\n  const [currentPage, setCurrentPage] = useState<PaginationProps[\"currentPage\"]>(1);\n  const [pageSize, setPageSize] = useState<PaginationProps[\"pageSize\"]>(10);\n  const [showInput, setShowInput] = useState(true);\n  const [showSelector, setShowSelector] = useState(true);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Stack direction=\"row\" gap=\"400\">\n        <Checkbox\n          isSelected={showInput}\n          onChange={setShowInput}\n        >\n          Enable page input\n        </Checkbox>\n        <Checkbox\n          isSelected={showSelector}\n          onChange={setShowSelector}\n        >\n          Enable page size selector\n        </Checkbox>\n      </Stack>\n\n      <Pagination\n        totalItems={200}\n        currentPage={currentPage}\n        pageSize={pageSize}\n        onPageChange={setCurrentPage}\n        onPageSizeChange={setPageSize}\n        enablePageInput={showInput}\n        enablePageSizeSelector={showSelector}\n      />\n    </Stack>\n  );\n};\n```\n\n### Custom page size options\n\nProvide custom page size options to match your application's needs:\n\n```jsx live-dev\nconst App = () => {\n  const [currentPage, setCurrentPage] = useState<PaginationProps[\"currentPage\"]>(1);\n  const [pageSize, setPageSize] = useState<PaginationProps[\"pageSize\"]>(25);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Text>\n        Custom page sizes: 25, 50, 75, 100\n      </Text>\n\n      <Pagination\n        totalItems={300}\n        currentPage={currentPage}\n        pageSize={pageSize}\n        pageSizeOptions={[25, 50, 75, 100]}\n        onPageChange={setCurrentPage}\n        onPageSizeChange={setPageSize}\n        enablePageSizeSelector={true}\n      />\n    </Stack>\n  );\n};\n```\n\n### With data rendering\n\nComplete example showing pagination with actual data rendering:\n\n```jsx live-dev\nconst App = () => {\n  const [currentPage, setCurrentPage] = useState<PaginationProps[\"currentPage\"]>(1);\n  const [pageSize, setPageSize] = useState<PaginationProps[\"pageSize\"]>(5);\n\n  // Generate sample data\n  const allItems = Array.from({ length: 50 }, (_, i) => ({\n    id: i + 1,\n    name: `Item ${i + 1}`,\n    category: ['Electronics', 'Clothing', 'Food'][i % 3],\n  }));\n\n  // Calculate which items to display\n  const startIndex = ((currentPage || 1) - 1) * (pageSize || 5);\n  const endIndex = startIndex + (pageSize || 5);\n  const displayedItems = allItems.slice(startIndex, endIndex);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Stack direction=\"column\" gap=\"200\" padding=\"400\" borderWidth=\"1px\" borderRadius=\"200\">\n        {displayedItems.map((item) => (\n          <Stack key={item.id} direction=\"row\" gap=\"200\" justify=\"space-between\">\n            <Text fontWeight=\"semibold\">{item.name}</Text>\n            <Text color=\"neutral.11\">{item.category}</Text>\n          </Stack>\n        ))}\n      </Stack>\n\n      <Pagination\n        totalItems={allItems.length}\n        currentPage={currentPage}\n        pageSize={pageSize}\n        pageSizeOptions={[5, 10, 25]}\n        onPageChange={setCurrentPage}\n        onPageSizeChange={setPageSize}\n        enablePageSizeSelector={true}\n      />\n    </Stack>\n  );\n};\n```\n\n## Component requirements\n\n## Accessibility\n\nThe Pagination component follows WCAG 2.1 AA guidelines and provides comprehensive keyboard navigation and screen reader support.\n\n#### Role\n\n- Navigation element uses `role=\"navigation\"` with descriptive `aria-label`\n\n#### Labeling\n\n- Previous/next buttons have clear `aria-label` attributes\n- Page input field has `aria-label` and `aria-current=\"page\"` attributes\n- Page size selector has descriptive `aria-label`\n- All labels are internationalized using `@internationalized/string`\n\n#### Keyboard navigation\n\n| Key | Action |\n|-----|--------|\n| `Tab` | Move focus between pagination controls |\n| `Enter` / `Space` | Activate focused button (previous/next) |\n| `Arrow Up` / `Arrow Down` | Increment/decrement page number in input field |\n| Type number | Directly enter page number in input field |\n\nIf your use case requires tracking and analytics for this component, it is good practice to add a **persistent**, **unique** id to the component:\n\n```tsx\nconst PERSISTENT_ID = \"product-list-pagination\";\n\nexport const ProductList = () => {\n  const [currentPage, setCurrentPage] = useState(1);\n  const [pageSize, setPageSize] = useState(20);\n\n  return (\n    <Pagination\n      id={PERSISTENT_ID}\n      totalItems={500}\n      currentPage={currentPage}\n      pageSize={pageSize}\n      onPageChange={setCurrentPage}\n      onPageSizeChange={setPageSize}\n    />\n  );\n};\n```\n\n## API reference\n\n<PropsTable id=\"Pagination\" />\n\n## Common patterns\n\n### Resetting to page 1 on filter changes\n\nWhen filters or search criteria change, reset pagination to the first page:\n\n```tsx\nconst ProductList = () => {\n  const [currentPage, setCurrentPage] = useState(1);\n  const [searchQuery, setSearchQuery] = useState('');\n  const [filteredItems, setFilteredItems] = useState([]);\n\n  // Reset to page 1 when search changes\n  useEffect(() => {\n    setCurrentPage(1);\n  }, [searchQuery]);\n\n  return (\n    <>\n      <TextInput\n        value={searchQuery}\n        onChange={(e) => setSearchQuery(e.target.value)}\n        placeholder=\"Search...\"\n      />\n\n      <Pagination\n        totalItems={filteredItems.length}\n        currentPage={currentPage}\n        onPageChange={setCurrentPage}\n      />\n    </>\n  );\n};\n```\n\n### Persisting pagination state\n\nStore pagination state in URL query parameters for shareable links:\n\n```tsx\nconst ProductList = () => {\n  const [searchParams, setSearchParams] = useSearchParams();\n\n  const currentPage = parseInt(searchParams.get('page') || '1', 10);\n  const pageSize = parseInt(searchParams.get('size') || '20', 10);\n\n  const handlePageChange = (page: number) => {\n    setSearchParams({ page: page.toString(), size: pageSize.toString() });\n  };\n\n  const handlePageSizeChange = (size: number) => {\n    setSearchParams({ page: '1', size: size.toString() });\n  };\n\n  return (\n    <Pagination\n      totalItems={500}\n      currentPage={currentPage}\n      pageSize={pageSize}\n      onPageChange={handlePageChange}\n      onPageSizeChange={handlePageSizeChange}\n      enablePageSizeSelector\n    />\n  );\n};\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Pagination within your application. As the component's internal functionality is already tested by Nimbus, these patterns help you verify your integration and application-specific logic.\n\n### Basic Rendering Tests\n\nVerify the pagination component renders with expected controls and labels\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Pagination, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Pagination - Basic rendering\", () => {\n  it(\"renders pagination navigation with accessible controls\", () => {\n    render(\n      <NimbusProvider>\n        <Pagination totalItems={100} />\n      </NimbusProvider>\n    );\n\n    // Verify navigation element exists\n    const nav = screen.getByRole(\"navigation\", { name: /pagination/i });\n    expect(nav).toBeInTheDocument();\n\n    // Verify previous/next buttons\n    expect(\n      screen.getByRole(\"button\", { name: /go to previous page/i })\n    ).toBeInTheDocument();\n    expect(\n      screen.getByRole(\"button\", { name: /go to next page/i })\n    ).toBeInTheDocument();\n\n    // Verify page input exists\n    expect(screen.getByLabelText(/current page/i)).toBeInTheDocument();\n  });\n\n  it(\"renders page size selector when enabled\", () => {\n    render(\n      <NimbusProvider>\n        <Pagination totalItems={100} enablePageSizeSelector={true} />\n      </NimbusProvider>\n    );\n\n    // Verify page size selector is present\n    expect(screen.getByLabelText(/items per page/i)).toBeInTheDocument();\n    expect(screen.getByText(/items per page/i)).toBeInTheDocument();\n  });\n\n  it(\"hides page input when disabled\", () => {\n    render(\n      <NimbusProvider>\n        <Pagination totalItems={100} enablePageInput={false} />\n      </NimbusProvider>\n    );\n\n    // Page input should not exist\n    expect(screen.queryByLabelText(/current page/i)).not.toBeInTheDocument();\n\n    // But current page number should still be displayed as text\n    expect(screen.getByText(\"1\")).toBeInTheDocument();\n  });\n});\n```\n\n### Controlled Mode Tests\n\nTest controlled pagination state management\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Pagination, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Pagination - Controlled mode\", () => {\n  it(\"respects controlled currentPage prop\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <Pagination totalItems={100} currentPage={1} pageSize={10} />\n      </NimbusProvider>\n    );\n\n    // Verify initial page\n    const pageInput = screen.getByLabelText(/current page/i);\n    expect(pageInput).toHaveValue(\"1\");\n\n    // Update to page 5\n    rerender(\n      <NimbusProvider>\n        <Pagination totalItems={100} currentPage={5} pageSize={10} />\n      </NimbusProvider>\n    );\n\n    expect(pageInput).toHaveValue(\"5\");\n  });\n\n  it(\"calls onPageChange callback when navigating\", async () => {\n    const user = userEvent.setup();\n    const handlePageChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Pagination\n          totalItems={100}\n          currentPage={1}\n          pageSize={10}\n          onPageChange={handlePageChange}\n        />\n      </NimbusProvider>\n    );\n\n    // Click next button\n    const nextButton = screen.getByRole(\"button\", {\n      name: /go to next page/i,\n    });\n    await user.click(nextButton);\n\n    expect(handlePageChange).toHaveBeenCalledWith(2);\n  });\n\n  it(\"calls onPageSizeChange callback when changing page size\", async () => {\n    const user = userEvent.setup();\n    const handlePageSizeChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Pagination\n          totalItems={100}\n          pageSize={10}\n          pageSizeOptions={[10, 20, 50]}\n          enablePageSizeSelector={true}\n          onPageSizeChange={handlePageSizeChange}\n        />\n      </NimbusProvider>\n    );\n\n    // Open the page size selector\n    const selector = screen.getByLabelText(/items per page/i);\n    await user.click(selector);\n\n    // Select a different page size\n    const option20 = screen.getByRole(\"option\", { name: \"20\" });\n    await user.click(option20);\n\n    expect(handlePageSizeChange).toHaveBeenCalledWith(20);\n  });\n});\n```\n\n### Page Navigation Tests\n\nTest previous/next navigation and direct page input\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Pagination, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Pagination - Page navigation\", () => {\n  it(\"disables previous button on first page\", () => {\n    render(\n      <NimbusProvider>\n        <Pagination totalItems={100} currentPage={1} pageSize={10} />\n      </NimbusProvider>\n    );\n\n    const prevButton = screen.getByRole(\"button\", {\n      name: /go to previous page/i,\n    });\n    expect(prevButton).toBeDisabled();\n  });\n\n  it(\"disables next button on last page\", () => {\n    render(\n      <NimbusProvider>\n        <Pagination totalItems={100} currentPage={10} pageSize={10} />\n      </NimbusProvider>\n    );\n\n    const nextButton = screen.getByRole(\"button\", {\n      name: /go to next page/i,\n    });\n    expect(nextButton).toBeDisabled();\n  });\n\n  it(\"allows direct page number input\", async () => {\n    const user = userEvent.setup();\n    const handlePageChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Pagination\n          totalItems={100}\n          currentPage={1}\n          pageSize={10}\n          onPageChange={handlePageChange}\n          enablePageInput={true}\n        />\n      </NimbusProvider>\n    );\n\n    const pageInput = screen.getByLabelText(/current page/i);\n\n    // Clear and type new page number, then blur to commit\n    await user.clear(pageInput);\n    await user.type(pageInput, \"5\");\n    await user.tab(); // Blur the input to commit the value\n\n    expect(handlePageChange).toHaveBeenCalledWith(5);\n  });\n\n  it(\"validates page input within bounds\", async () => {\n    const user = userEvent.setup();\n    const handlePageChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Pagination\n          totalItems={100}\n          currentPage={1}\n          pageSize={10}\n          onPageChange={handlePageChange}\n          enablePageInput={true}\n        />\n      </NimbusProvider>\n    );\n\n    const pageInput = screen.getByLabelText(/current page/i);\n\n    // Try to enter page number beyond total pages (max is 10), then blur to commit\n    await user.clear(pageInput);\n    await user.type(pageInput, \"999\");\n    await user.tab(); // Blur the input to commit the value\n\n    // Should clamp to max page (10)\n    expect(handlePageChange).toHaveBeenCalledWith(10);\n  });\n});\n```\n\n### Page Size Selector Tests\n\nTest page size selection and option configuration\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Pagination, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Pagination - Page size selector\", () => {\n  it(\"renders custom page size options\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <Pagination\n          totalItems={100}\n          pageSize={25}\n          pageSizeOptions={[25, 50, 75, 100]}\n          enablePageSizeSelector={true}\n        />\n      </NimbusProvider>\n    );\n\n    // Open the selector\n    const selector = screen.getByLabelText(/items per page/i);\n    await user.click(selector);\n\n    // Verify custom options are present\n    expect(screen.getByRole(\"option\", { name: \"25\" })).toBeInTheDocument();\n    expect(screen.getByRole(\"option\", { name: \"50\" })).toBeInTheDocument();\n    expect(screen.getByRole(\"option\", { name: \"75\" })).toBeInTheDocument();\n    expect(screen.getByRole(\"option\", { name: \"100\" })).toBeInTheDocument();\n  });\n\n  it(\"shows correct selected page size\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <Pagination\n          totalItems={100}\n          pageSize={50}\n          pageSizeOptions={[10, 20, 50, 100]}\n          enablePageSizeSelector={true}\n        />\n      </NimbusProvider>\n    );\n\n    // Open selector to verify selected option\n    const selector = screen.getByLabelText(/items per page/i);\n    await user.click(selector);\n\n    const option50 = screen.getByRole(\"option\", { name: \"50\" });\n    expect(option50).toHaveAttribute(\"aria-selected\", \"true\");\n  });\n});\n```\n\n### Integration Tests\n\nTest pagination with data rendering and realistic scenarios\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Pagination, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Pagination - Integration scenarios\", () => {\n  it(\"calculates correct page ranges for data slicing\", () => {\n    const totalItems = 47;\n    const pageSize = 10;\n    const currentPage = 3;\n\n    // Calculate start and end indices for data slicing\n    const startIndex = (currentPage - 1) * pageSize;\n    const endIndex = startIndex + pageSize;\n\n    expect(startIndex).toBe(20);\n    expect(endIndex).toBe(30);\n\n    // For display: start item is 1-based\n    const startItem = startIndex + 1;\n    const endItem = Math.min(endIndex, totalItems);\n\n    expect(startItem).toBe(21);\n    expect(endItem).toBe(30);\n  });\n\n  it(\"handles page size changes by resetting to valid page\", async () => {\n    const user = userEvent.setup();\n    const handlePageChange = vi.fn();\n    const handlePageSizeChange = vi.fn();\n\n    const { rerender } = render(\n      <NimbusProvider>\n        <Pagination\n          totalItems={100}\n          currentPage={10}\n          pageSize={10}\n          pageSizeOptions={[10, 50]}\n          onPageChange={handlePageChange}\n          onPageSizeChange={handlePageSizeChange}\n          enablePageSizeSelector={true}\n        />\n      </NimbusProvider>\n    );\n\n    // Currently on page 10 of 10 (100 items / 10 per page)\n    const nextButton = screen.getByRole(\"button\", { name: /go to next page/i });\n    expect(nextButton).toBeDisabled();\n\n    // Change page size to 50\n    const selector = screen.getByLabelText(/items per page/i);\n    await user.click(selector);\n\n    const option50 = screen.getByRole(\"option\", { name: \"50\" });\n    await user.click(option50);\n\n    expect(handlePageSizeChange).toHaveBeenCalledWith(50);\n\n    // With 100 items and 50 per page, we now have 2 total pages\n    // Current page 10 is invalid, should adjust to page 2\n    rerender(\n      <NimbusProvider>\n        <Pagination\n          totalItems={100}\n          currentPage={2}\n          pageSize={50}\n          pageSizeOptions={[10, 50]}\n          onPageChange={handlePageChange}\n          onPageSizeChange={handlePageSizeChange}\n          enablePageSizeSelector={true}\n        />\n      </NimbusProvider>\n    );\n\n    const pageInput = screen.getByLabelText(/current page/i);\n    expect(pageInput).toHaveValue(\"2\");\n  });\n\n  it(\"works with zero items\", () => {\n    render(\n      <NimbusProvider>\n        <Pagination totalItems={0} pageSize={10} />\n      </NimbusProvider>\n    );\n\n    // Should show page 1 of 1\n    const pageInput = screen.getByLabelText(/current page/i);\n    expect(pageInput).toHaveValue(\"1\");\n\n    // Both navigation buttons should be disabled\n    expect(\n      screen.getByRole(\"button\", { name: /go to previous page/i })\n    ).toBeDisabled();\n    expect(\n      screen.getByRole(\"button\", { name: /go to next page/i })\n    ).toBeDisabled();\n  });\n});\n```\n\n\n## Resources\n\n- [Pagination Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-pagination--docs)\n",
+      "toc": [
+        {
+          "value": "Getting started",
+          "href": "#getting-started",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Import",
+          "href": "#import",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Displaying current state",
+          "href": "#displaying-current-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Page size selector",
+          "href": "#page-size-selector",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Direct page input",
+          "href": "#direct-page-input",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Configuration options",
+          "href": "#configuration-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom page size options",
+          "href": "#custom-page-size-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With data rendering",
+          "href": "#with-data-rendering",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Role",
+          "href": "#role",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Labeling",
+          "href": "#labeling",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Common patterns",
+          "href": "#common-patterns",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resetting to page 1 on filter changes",
+          "href": "#resetting-to-page-1-on-filter-changes",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Persisting pagination state",
+          "href": "#persisting-pagination-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Rendering Tests",
+          "href": "#basic-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled Mode Tests",
+          "href": "#controlled-mode-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Page Navigation Tests",
+          "href": "#page-navigation-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Page Size Selector Tests",
+          "href": "#page-size-selector-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Integration Tests",
+          "href": "#integration-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nPagination guidelines aim to support similar and consistent experiences for\nusers seeking to navigate their data or processes.\n\n### Best practices\n\n- **Provide clear feedback:** always highlight the current active page clearly.\n- **Keep navigation minimal:** limit the visible page numbers shown to a\n  manageable amount (e.g., show 5-7 pages).\n- **Show total context:** display the total number of items or total pages\n  available (e.g., \"Showing 1-20 of 150 results\").\n- **Disable end controls:** clearly disable the \"Previous\" button on the first\n  page and the \"Next\" button on the last page.\n\n### Usage\n\n> [!TIP]\\\n> When to use\n\n- **Control is essential:** When the user needs control over where they are and\n  how many items they see.\n- **Predictable data sets:** For data tables, structured search results, or\n  catalogs where items have a known order and consistent size.\n- **User needs to bookmark/reference:** When users need to easily save or share\n  a specific page number, or refer back to a particular screen of results.\n\n> [!CAUTION]\\\n> When not to use\n\n- **Unstructured or image-heavy content:** For image galleries or highly\n  dynamic, unstructured content where infinite scrolling provides a smoother,\n  faster visual experience.\n- **Mobile experience:** Infinite scroll is often preferred on mobile devices to\n  reduce the effort of tapping small pagination controls\n\n### Pagination in use\n\n> [!TIP]\\\n> **Do**\n>\n> - Do allow direct input to jump to a specific page number (if the set is very\n>   large).\n> - Do place pagination controls consistently at the top, bottom, or both, of\n>   the content being paginated.\n\n```jsx live\nconst App = () => {\n  const [currentPage, setCurrentPage] = useState(1);\n  const [pageSize, setPageSize] = useState(4);\n\n  return (\n    <Pagination\n      totalItems={10240}\n      currentPage={currentPage}\n      pageSize={pageSize}\n      pageSizeOptions={[4, 10, 20, 50]}\n      enablePageSizeSelector\n      enablePageInput\n      onPageChange={setCurrentPage}\n      onPageSizeChange={setPageSize}\n    />\n  );\n};\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Don't reset the pagination every time a filter or sort option is applied;\n>   try to maintain the user's current page if possible.\n> - Don't overload the component with too many page numbers that visually\n>   clutter the interface.\n> - Don't hide or neglect to disable the 'Previous' or 'Next' buttons when they\n>   are no longer functional.\n\n```jsx live\nconst App = () => {\n  const [currentPage, setCurrentPage] = useState(1483271);\n  const [pageSize, setPageSize] = useState(4);\n\n  return (\n    <Pagination\n      totalItems={9007199254740991}\n      currentPage={currentPage}\n      pageSize={pageSize}\n      pageSizeOptions={[4, 10, 20, 50]}\n      enablePageSizeSelector\n      enablePageInput\n      onPageChange={setCurrentPage}\n      onPageSizeChange={setPageSize}\n    />\n  );\n};\n```\n",
+      "toc": [
+        {
+          "value": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Best practices",
+          "href": "#best-practices",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage",
+          "href": "#usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Pagination in use",
+          "href": "#pagination-in-use",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}