Merge pull request #2419 from adevinta/canary

feat: add Pagination and Stepper components

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.71.0",
+    "@zag-js/react": "0.71.0",
+    "@spark-ui/icon": "^5.3.0",
+    "@spark-ui/icons": "^5.3.0"
+  }
+}

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

@@ -0,0 +1,109 @@
+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
+
+interface that allows navigating between pages that contain split information, instead of being shown on a single page.
+
+## 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} />
+
+### Visible page items
+
+Use `visiblePageItems` 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` in ellipsis mode (default), `3` otherwise.
+
+<Canvas of={stories.VisiblePageItems} />
+
+## 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).
+
+### Guidelines
+
+When setting **aria-labels**:
+- Use descriptive labels: Indicate purpose (e.g., "Go to first page")
+- Include current page info: "page X of Y"
+- Specify first/last pages: "First page, page 1 of 10"
+
+### 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,195 @@
+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 type="button" aria-label="Pagination" count={100} pageSize={10}>
+      <Pagination.PrevTrigger aria-label="Previous page" />
+      <Pagination.Pages>
+        {({ pages, totalPages }) =>
+          pages.map((page, index) =>
+            page.type === 'page' ? (
+              <Pagination.Item
+                key={page.value}
+                value={page.value}
+                aria-label={
+                  page.value === totalPages ? `Last page, page ${page.value}` : `Page ${page.value}`
+                }
+              />
+            ) : (
+              <Pagination.Ellipsis key={`${index}-ellipsis`} index={index} />
+            )
+          )
+        }
+      </Pagination.Pages>
+      <Pagination.NextTrigger aria-label="Next page" />
+    </Pagination>
+  )
+}
+
+export const NoEllipsis: StoryFn = () => {
+  return (
+    <Pagination
+      type="button"
+      aria-label="Pagination"
+      count={10}
+      pageSize={1}
+      visiblePageItems={5}
+      noEllipsis
+    >
+      <Pagination.FirstPageTrigger aria-label="First page" />
+      <Pagination.PrevTrigger aria-label="Previous page" />
+      <Pagination.Pages>
+        {({ pages, totalPages }) => {
+          return pages.map(page =>
+            page.type === 'page' ? (
+              <Pagination.Item
+                key={page.value}
+                value={page.value}
+                aria-label={
+                  page.value === totalPages ? `Last page, page ${page.value}` : `Page ${page.value}`
+                }
+              >
+                {page.value}
+              </Pagination.Item>
+            ) : null
+          )
+        }}
+      </Pagination.Pages>
+      <Pagination.NextTrigger aria-label="Next page" />
+      <Pagination.LastPageTrigger aria-label="Last page" />
+    </Pagination>
+  )
+}
+
+export const VisiblePageItems: StoryFn = () => {
+  const [visiblePageItems, setVisiblePageItems] = useState(5)
+
+  return (
+    <div>
+      <FormField name="email" className="mb-xl">
+        <FormField.Label>
+          Visible page items (these are just example value, you can go above):
+        </FormField.Label>
+
+        <RadioGroup
+          value={`${visiblePageItems}`}
+          onValueChange={v => setVisiblePageItems(+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
+        type="button"
+        aria-label="Pagination"
+        count={1000}
+        pageSize={10}
+        visiblePageItems={visiblePageItems}
+      >
+        <Pagination.PrevTrigger aria-label="Previous page" />
+        <Pagination.Pages>
+          {({ pages, totalPages }) =>
+            pages.map((page, index) =>
+              page.type === 'page' ? (
+                <Pagination.Item
+                  key={page.value}
+                  value={page.value}
+                  aria-label={
+                    page.value === totalPages
+                      ? `Last page, page ${page.value}`
+                      : `Page ${page.value}`
+                  }
+                >
+                  {page.value}
+                </Pagination.Item>
+              ) : (
+                <Pagination.Ellipsis key={`${index}-ellipsis`} index={index} />
+              )
+            )
+          }
+        </Pagination.Pages>
+        <Pagination.NextTrigger aria-label="Next page" />
+      </Pagination>
+    </div>
+  )
+}
+
+export const Controlled: StoryFn = () => {
+  const [currentPage, setCurrentPage] = useState(1)
+  const [items] = useState(
+    Array.from({ length: 48 }, (_, i) => ({
+      id: i + 1,
+      name: `Article ${i + 1}`,
+    }))
+  )
+
+  const pageSize = 5
+
+  const currentPageItems = items.slice(
+    (currentPage - 1) * pageSize,
+    (currentPage - 1) * pageSize + pageSize
+  )
+
+  return (
+    <div className="flex flex-col items-center justify-center gap-xl">
+      <div className="flex w-full flex-col gap-md">
+        {currentPageItems.map(item => {
+          return (
+            <div key={item.id} className="bg-basic-container p-lg">
+              <p>{item.name}</p>
+            </div>
+          )
+        })}
+      </div>
+      <Pagination
+        type="button"
+        aria-label="Pagination"
+        count={items.length}
+        pageSize={pageSize}
+        page={currentPage}
+        onPageChange={details => {
+          setCurrentPage(details.page)
+        }}
+      >
+        <Pagination.PrevTrigger aria-label="Previous page" />
+        <Pagination.Pages>
+          {({ pages, totalPages }) =>
+            pages.map((page, index) =>
+              page.type === 'page' ? (
+                <Pagination.Item
+                  key={page.value}
+                  value={page.value}
+                  aria-label={
+                    page.value === totalPages
+                      ? `Last page, page ${page.value}`
+                      : `Page ${page.value}`
+                  }
+                >
+                  {page.value}
+                </Pagination.Item>
+              ) : (
+                <Pagination.Ellipsis key={`${index}-ellipsis`} index={index} />
+              )
+            )
+          }
+        </Pagination.Pages>
+        <Pagination.NextTrigger aria-label="Next page" />
+      </Pagination>
+    </div>
+  )
+}