fix(pagination): new pagination component

packages/components/pagination/.npmignore

@@ -0,0 +1,2 @@
+src
+**/*.stories.*

packages/components/pagination/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Adevinta ASA.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/components/pagination/README.md

@@ -0,0 +1,13 @@
+# Pagination
+> @spark-ui/pagination
+
+[![storybook](https://img.shields.io/badge/storybook-black?logo=storybook)](https://sparkui.vercel.app/?path=/docs/components-pagination--docs)
+[![documentation](https://img.shields.io/badge/documentation-black?logo=googledocs)](https://sparkui-adv.vercel.app/docs/components/pagination)
+[![issue](https://img.shields.io/badge/report%20a%20bug-black?logo=openbugbounty&logoColor=red)](https://github.com/adevinta/spark/issues/new?&projects=4&template=bug-report.yml&assignees=&labels=Component,Component%3A%20pagination)
+[![npm](https://img.shields.io/npm/dt/%40spark-ui/pagination?logo=npm&labelColor=black)](https://www.npmjs.com/package/@spark-ui/pagination)
+
+
+This package is part of the [`@spark-ui`](https://github.com/adevinta/spark) react-js user interface component library project.
+
+[![Issues open](https://img.shields.io/github/issues-search/adevinta/spark?query=is%3Aopen%20label%3A%22Component%3A%20pagination%22&logo=openbugbounty&logoColor=red&label=issues%20open&color=red)](https://github.com/adevinta/spark/issues?q=is%3Aopen+label%3AComponent%3A%20pagination)
+[![NPM](https://img.shields.io/npm/l/%40spark-ui%2Fpagination)](https://github.com/adevinta/spark/blob/main/packages/components/pagination/LICENSE.md)

packages/components/pagination/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@spark-ui/pagination",
+  "version": "0.0.0",
+  "description": "interface that allows navigating between pages that contain split information, instead of being shown on a single page",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "@spark-ui",
+    "react",
+    "component",
+    "accessible",
+    "accessibility",
+    "wai-aria",
+    "aria",
+    "a11y",
+    "pagination"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "vite build"
+  },
+  "peerDependencies": {
+    "@spark-ui/tailwind-plugins": "latest",
+    "@spark-ui/theme-utils": "latest",
+    "react": "^18.0 || ^19.0",
+    "react-dom": "^18.0 || ^19.0",
+    "tailwindcss": "^3.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/adevinta/spark.git",
+    "directory": "packages/components/pagination"
+  },
+  "config": {
+    "title": "pagination",
+    "category": "components"
+  },
+  "bugs": {
+    "url": "https://github.com/adevinta/spark/issues?q=is%3Aopen+label%3A%22Component%3A+pagination%22"
+  },
+  "homepage": "https://sparkui.vercel.app",
+  "license": "MIT",
+  "dependencies": {
+    "@zag-js/pagination": "0.65.0",
+    "@zag-js/react": "0.65.0",
+    "@spark-ui/icon": "^5.3.0",
+    "@spark-ui/icons": "^5.3.0"
+  }
+}

packages/components/pagination/src/Pagination.doc.mdx

@@ -0,0 +1,102 @@
+import { Meta, Canvas } from '@storybook/blocks'
+import { ArgTypes } from '@docs/helpers/ArgTypes'
+import { Kbd } from '@spark-ui/kbd'
+
+import { Pagination } from '.'
+
+import * as stories from './Pagination.stories'
+
+<Meta of={stories} />
+
+# Pagination
+
+Displays rich content in a portal, triggered by a button.
+
+## Install
+
+```sh
+npm install @spark-ui/pagination
+```
+
+## Import
+
+```tsx
+import { Pagination } from '@spark-ui/pagination'
+```
+
+## Props
+
+<ArgTypes
+  of={Pagination}
+  description="Contains all the parts of a pagination."
+  subcomponents={{
+    'Pagination.FirstPageTrigger': {
+      of: Pagination.FirstPageTrigger,
+      description: 'A button to go to the first page, no matter which page is currently selected.',
+    },
+    'Pagination.PrevTrigger': {
+      of: Pagination.PrevTrigger,
+      description:
+        'A button to go to the previous page, no matter which page is currently selected.',
+    },
+    'Pagination.NextTrigger': {
+      of: Pagination.NextTrigger,
+      description: 'A button to go to the next page, no matter which page is currently selected.',
+    },
+    'Pagination.LastPageTrigger': {
+      of: Pagination.LastPageTrigger,
+      description: 'A button to go to the last page, no matter which page is currently selected.',
+    },
+    'Pagination.Pages': {
+      of: Pagination.Pages,
+      description:
+        'This component exposes the internal api of the pagination to render individual page elements by yourself.',
+    },
+    'Pagination.Item': {
+      of: Pagination.Item,
+      description: 'A numbered page item. Can be a link or a button.',
+    },
+    'Pagination.Ellipsis': {
+      of: Pagination.Ellipsis,
+      description: 'Indicates a jump between visible page elements.',
+    },
+  }}
+/>
+
+## Usage
+
+### Default
+
+A basic example combining all parts of the component: a "previous page" button, "last page" button, and a list of pages items/ellipsis.
+
+<Canvas of={stories.Default} />
+
+### Controlled
+
+Use `page` and `onPageChange` to control the pagination.
+
+<Canvas of={stories.Controlled} />
+
+### No Ellipsis
+
+In this setting, ellipsis logic is disabled. This is practical if you have limited space, on smaller screens, to render more numbered pages than ellipsis elements.
+
+<Canvas of={stories.NoEllipsis} />
+
+### Pagination length
+
+Use `length` to define how many items are displayed between the previous and next buttons (includes ellipsis items). Must be an odd number to keep the active page centered.
+
+Minimum is `5`.
+
+<Canvas of={stories.PaginationLength} />
+
+## Accessibility
+
+There is no official WAI-ARIA design pattern for a pagination. Instead, we followed the guidelines of a [suggested implementation](https://design-system.w3.org/components/pagination.html).
+
+### Keyboard Interactions
+
+- <Kbd>Enter</Kbd>: Triggers the selected item (can be either a link or a button)
+- <Kbd>Tab</Kbd>: Moves focus to the next focusable element.
+- <Kbd>Shift</Kbd> + <Kbd>Tab</Kbd>: Moves focus to the previous focusable element.

packages/components/pagination/src/Pagination.stories.tsx

@@ -0,0 +1,167 @@
+import { FormField } from '@spark-ui/form-field'
+import { RadioGroup } from '@spark-ui/radio-group'
+import { Meta, StoryFn } from '@storybook/react'
+import { useState } from 'react'
+
+import { Pagination } from '.'
+
+const meta: Meta<typeof Pagination> = {
+  title: 'Components/Pagination',
+  component: Pagination,
+}
+
+export default meta
+
+export const Default: StoryFn = () => {
+  return (
+    <Pagination
+      count={100}
+      pageSize={10}
+      translations={{
+        rootLabel: 'Pagination',
+        prevTriggerLabel: 'Previous page',
+        nextTriggerLabel: 'Next page',
+        itemLabel: details =>
+          details.page === details.totalPages
+            ? `Last page, page ${details.page}`
+            : `Page ${details.page}`,
+      }}
+    >
+      <Pagination.PrevTrigger />
+      <Pagination.Pages>
+        {({ pages }) =>
+          pages.map((page, index) =>
+            page.type === 'page' ? (
+              <Pagination.Item key={page.value} value={page.value} />
+            ) : (
+              <Pagination.Ellipsis key={`${index}-ellipsis`} index={index} />
+            )
+          )
+        }
+      </Pagination.Pages>
+      <Pagination.NextTrigger />
+    </Pagination>
+  )
+}
+
+export const NoEllipsis: StoryFn = () => {
+  return (
+    <Pagination
+      count={10}
+      pageSize={1}
+      length={5}
+      noEllipsis
+      translations={{
+        rootLabel: 'Pagination',
+        firstPageTriggerLabel: 'First page',
+        prevTriggerLabel: 'Previous page',
+        nextTriggerLabel: 'Next page',
+        lastPageTriggerLabel: 'Last page',
+        itemLabel: details =>
+          details.page === details.totalPages
+            ? `Last page, page ${details.page}`
+            : `Page ${details.page}`,
+      }}
+    >
+      <Pagination.FirstPageTrigger />
+      <Pagination.PrevTrigger />
+      <Pagination.Pages>
+        {({ pages }) => {
+          return pages.map(page =>
+            page.type === 'page' ? (
+              <Pagination.Item key={page.value} value={page.value}>
+                {page.value}
+              </Pagination.Item>
+            ) : null
+          )
+        }}
+      </Pagination.Pages>
+      <Pagination.NextTrigger />
+      <Pagination.LastPageTrigger />
+    </Pagination>
+  )
+}
+
+export const PaginationLength: StoryFn = () => {
+  const [paginationLength, setPaginationLength] = useState(5)
+
+  return (
+    <div>
+      <FormField name="email" className="mb-xl">
+        <FormField.Label>Length:</FormField.Label>
+
+        <RadioGroup
+          value={`${paginationLength}`}
+          onValueChange={v => setPaginationLength(+v)}
+          orientation="horizontal"
+        >
+          <RadioGroup.Radio value="5">5</RadioGroup.Radio>
+          <RadioGroup.Radio value="7">7</RadioGroup.Radio>
+          <RadioGroup.Radio value="9">9</RadioGroup.Radio>
+        </RadioGroup>
+      </FormField>
+
+      <Pagination
+        count={1000}
+        pageSize={10}
+        length={paginationLength}
+        translations={{
+          rootLabel: 'Pagination',
+          prevTriggerLabel: 'Previous page',
+          nextTriggerLabel: 'Next page',
+          itemLabel: details =>
+            details.page === details.totalPages
+              ? `Last page, page ${details.page}`
+              : `Page ${details.page}`,
+        }}
+      >
+        <Pagination.PrevTrigger />
+        <Pagination.Pages>
+          {({ pages }) =>
+            pages.map((page, index) =>
+              page.type === 'page' ? (
+                <Pagination.Item key={page.value} value={page.value}>
+                  {page.value}
+                </Pagination.Item>
+              ) : (
+                <Pagination.Ellipsis key={`${index}-ellipsis`} index={index} />
+              )
+            )
+          }
+        </Pagination.Pages>
+        <Pagination.NextTrigger />
+      </Pagination>
+    </div>
+  )
+}
+
+export const Controlled: StoryFn = () => {
+  const [currentPage, setCurrentPage] = useState(1)
+
+  return (
+    <>
+      <Pagination
+        count={100}
+        pageSize={10}
+        page={currentPage}
+        onPageChange={details => setCurrentPage(details.page)}
+      >
+        <Pagination.PrevTrigger />
+        <Pagination.Pages>
+          {({ pages }) =>
+            pages.map((page, index) =>
+              page.type === 'page' ? (
+                <Pagination.Item key={page.value} value={page.value}>
+                  {page.value}
+                </Pagination.Item>
+              ) : (
+                <Pagination.Ellipsis key={`${index}-ellipsis`} index={index} />
+              )
+            )
+          }
+        </Pagination.Pages>
+        <Pagination.NextTrigger />
+      </Pagination>
+    </>
+  )
+}