@justeattakeaway/pie-pagination 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,137 @@
-# Temporary Holding Version
+# @justeattakeaway/pie-pagination
+[Source Code](https://github.com/justeattakeaway/pie/tree/main/packages/components/pie-pagination) | [Design Documentation](https://pie.design/components/pagination) | [NPM](https://www.npmjs.com/package/@justeattakeaway/pie-pagination)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p>
+  <a href="https://www.npmjs.com/@justeattakeaway/pie-pagination">
+    <img alt="GitHub Workflow Status" src="https://img.shields.io/npm/v/@justeattakeaway/pie-pagination.svg">
+  </a>
+</p>
+
+`@justeattakeaway/pie-pagination` is a Web Component built using the Lit library. It offers a simple and accessible `pagination` component for web applications.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Documentation](#documentation)
+  - [Properties](#properties)
+  - [Slots](#slots)
+  - [CSS Variables](#css-variables)
+  - [Events](#events)
+- [Usage Examples](#usage-examples)
+- [Questions and Support](#questions-and-support)
+- [Contributing](#contributing)
+
+## Installation
+
+> To install any of our web components in your application, we would suggest following the [getting started guide](https://webc.pie.design/?path=/docs/introduction-getting-started--docs) to set up your project.
+
+Ideally, you should install the component using the **`@justeattakeaway/pie-webc`** package, which includes all of the components. Or you can install the individual component package.
+
+## Documentation
+
+### Properties
+| Prop          | Options | Description                                                                                                                                                                                                    | Default |
+|---------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|
+| `currentPage` | `number`| The currently active page (1-based). This component is fully controlled, so it never updates this value itself; the consumer is responsible for updating it in response to the `pie-pagination-page-change` event. | `1`     |
+| `totalPages`  | `number`| The total number of pages to render.                                                                                                                                                                            | `1`     |
+| `disabled`    | `boolean`| When true, all pagination controls are disabled.                                                                                                                                                               | `false` |
+| `aria`        | `object`| The ARIA attributes for the pagination landmark. Offers a `label` used for the `aria-label` of the wrapping `<nav>` element.                                                                                      | `undefined` |
+
+### Slots
+This component does not use any slots.
+
+### CSS Variables
+This component does not expose any CSS variables.
+
+### Events
+| Event                         | Type          | Description                                                                                                                                                            |
+|-------------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `pie-pagination-page-change`  | `CustomEvent` | Fired when the user interacts with any pagination control. The event detail contains `{ currentPage }`, the page the user wants to navigate to. |
+| `pie-pagination-prev`         | `CustomEvent` | Fired when the user clicks the "previous" control. The event detail contains `{ currentPage }`. This event fires **in addition to** `pie-pagination-page-change`. |
+| `pie-pagination-next`         | `CustomEvent` | Fired when the user clicks the "next" control. The event detail contains `{ currentPage }`. This event fires **in addition to** `pie-pagination-page-change`. |
+
+## Usage Examples
+
+**For HTML:**
+
+```js
+// import as module into a js file e.g. main.js
+import '@justeattakeaway/pie-webc/components/pagination.js'
+```
+
+```html
+<!-- pass js file into <script> tag -->
+
+<script type="module" src="/main.js"></script>
+```
+
+```html
+<pie-pagination currentPage="2" totalPages="10"></pie-pagination>
+
+<script>
+  const pagination = document.querySelector('pie-pagination');
+
+  pagination.addEventListener('pie-pagination-page-change', (event) => {
+    // The component is controlled — update the prop yourself
+    pagination.currentPage = event.detail.currentPage;
+  });
+</script>
+```
+
+The `pie-pagination-prev` and `pie-pagination-next` events let you hook into the previous/next controls specifically. They fire in addition to `pie-pagination-page-change`, so you can use either one:
+
+```html
+<pie-pagination currentPage="2" totalPages="10"></pie-pagination>
+
+<script>
+  const pagination = document.querySelector('pie-pagination');
+
+  pagination.addEventListener('pie-pagination-prev', (event) => {
+    console.log('previous clicked, requested page:', event.detail.currentPage);
+    pagination.currentPage = event.detail.currentPage;
+  });
+
+  pagination.addEventListener('pie-pagination-next', (event) => {
+    console.log('next clicked, requested page:', event.detail.currentPage);
+    pagination.currentPage = event.detail.currentPage;
+  });
+</script>
+```
+
+**For Native JS Applications, Vue, Angular, Svelte etc.:**
+
+```js
+// Vue templates (using Nuxt 3)
+import '@justeattakeaway/pie-webc/components/pagination.js'
+```
+
+**For React Applications:**
+
+```jsx
+import { PiePagination } from '@justeattakeaway/pie-webc/react/pagination.js';
+
+<PiePagination
+  currentPage={currentPage}
+  totalPages={totalPages}
+  onPiePaginationPageChange={(event) => setCurrentPage(event.detail.currentPage)}
+/>
+```
+
+The `pie-pagination-prev` and `pie-pagination-next` events are exposed as `onPiePaginationPrev` and `onPiePaginationNext`:
+
+```jsx
+<PiePagination
+  currentPage={currentPage}
+  totalPages={totalPages}
+  onPiePaginationPrev={(event) => setCurrentPage(event.detail.currentPage)}
+  onPiePaginationNext={(event) => setCurrentPage(event.detail.currentPage)}
+/>
+```
+
+## Questions and Support
+
+If you work at Just Eat Takeaway.com, please contact us on **#help-designsystem**. Otherwise, please raise an issue on [Github](https://github.com/justeattakeaway/pie/issues).
+
+## Contributing
+
+Check out our [contributing guide](https://github.com/justeattakeaway/pie/wiki/Contributing-Guide) for more information on [local development](https://github.com/justeattakeaway/pie/wiki/Contributing-Guide#local-development) and how to run specific [component tests](https://github.com/justeattakeaway/pie/wiki/Contributing-Guide#testing).

package/custom-elements.json

@@ -0,0 +1,255 @@
+{
+  "schemaVersion": "1.0.0",
+  "readme": "",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "src/defs-react.js",
+      "declarations": [],
+      "exports": []
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/defs.js",
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "ON_PAGE_CHANGE_EVENT",
+          "type": {
+            "text": "string"
+          },
+          "default": "'pie-pagination-page-change'",
+          "description": "The event name dispatched when the user interacts with a pagination control.\nThe component is fully controlled: it never changes `currentPage` itself, it\nonly tells the consumer which page the user wants to navigate to."
+        },
+        {
+          "kind": "variable",
+          "name": "ON_PREV_EVENT",
+          "type": {
+            "text": "string"
+          },
+          "default": "'pie-pagination-prev'",
+          "description": "The event name dispatched when the user clicks the \"previous\" control."
+        },
+        {
+          "kind": "variable",
+          "name": "ON_NEXT_EVENT",
+          "type": {
+            "text": "string"
+          },
+          "default": "'pie-pagination-next'",
+          "description": "The event name dispatched when the user clicks the \"next\" control."
+        },
+        {
+          "kind": "variable",
+          "name": "defaultProps",
+          "type": {
+            "text": "DefaultProps"
+          },
+          "default": "{ currentPage: 1, totalPages: 1, disabled: false, }"
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "ON_PAGE_CHANGE_EVENT",
+          "declaration": {
+            "name": "ON_PAGE_CHANGE_EVENT",
+            "module": "src/defs.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ON_PREV_EVENT",
+          "declaration": {
+            "name": "ON_PREV_EVENT",
+            "module": "src/defs.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ON_NEXT_EVENT",
+          "declaration": {
+            "name": "ON_NEXT_EVENT",
+            "module": "src/defs.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "defaultProps",
+          "declaration": {
+            "name": "defaultProps",
+            "module": "src/defs.js"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/index.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "",
+          "name": "PiePagination",
+          "members": [
+            {
+              "kind": "field",
+              "name": "aria",
+              "type": {
+                "text": "PaginationProps['aria']"
+              },
+              "privacy": "public",
+              "attribute": "aria"
+            },
+            {
+              "kind": "field",
+              "name": "currentPage",
+              "privacy": "public",
+              "attribute": "currentPage"
+            },
+            {
+              "kind": "field",
+              "name": "totalPages",
+              "privacy": "public",
+              "attribute": "totalPages"
+            },
+            {
+              "kind": "field",
+              "name": "disabled",
+              "privacy": "public",
+              "attribute": "disabled"
+            },
+            {
+              "kind": "method",
+              "name": "_emitPageChange",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "currentPage",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "Emits the page change event with the page the user wants to navigate to.\nThe component never updates `currentPage` itself."
+            },
+            {
+              "kind": "method",
+              "name": "_handlePreviousClick",
+              "privacy": "private",
+              "description": "Handles a click on the \"previous\" control."
+            },
+            {
+              "kind": "method",
+              "name": "_handleNextClick",
+              "privacy": "private",
+              "description": "Handles a click on the \"next\" control."
+            },
+            {
+              "kind": "method",
+              "name": "_handlePageClick",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "page",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "Handles a click on a page number control."
+            },
+            {
+              "kind": "method",
+              "name": "_renderChevronIcon",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "direction",
+                  "type": {
+                    "text": "'previous' | 'next'"
+                  }
+                }
+              ],
+              "description": "Renders the chevron icon for the previous/next controls, mirroring it for RTL."
+            }
+          ],
+          "events": [
+            {
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "when the user interacts with a pagination control.",
+              "name": "pie-pagination-page-change"
+            },
+            {
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "when the user clicks the \"previous\" control.",
+              "name": "pie-pagination-prev"
+            },
+            {
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "when the user clicks the \"next\" control.",
+              "name": "pie-pagination-next"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "aria",
+              "type": {
+                "text": "PaginationProps['aria']"
+              },
+              "fieldName": "aria"
+            },
+            {
+              "name": "currentPage",
+              "fieldName": "currentPage"
+            },
+            {
+              "name": "totalPages",
+              "fieldName": "totalPages"
+            },
+            {
+              "name": "disabled",
+              "fieldName": "disabled"
+            }
+          ],
+          "mixins": [
+            {
+              "name": "RtlMixin",
+              "package": "@justeattakeaway/pie-webc-core"
+            }
+          ],
+          "superclass": {
+            "name": "PieElement",
+            "package": "@justeattakeaway/pie-webc-core/src/internals/PieElement"
+          },
+          "tagName": "pie-pagination",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "module": "src/defs"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "PiePagination",
+          "declaration": {
+            "name": "PiePagination",
+            "module": "src/index.js"
+          }
+        }
+      ]
+    }
+  ]
+}

package/dist/index.d.ts

@@ -0,0 +1,111 @@
+import { ComponentDefaultProps } from '@justeattakeaway/pie-webc-core';
+import { CSSResult } from 'lit';
+import { GenericConstructor } from '@justeattakeaway/pie-webc-core';
+import { PieElement } from '@justeattakeaway/pie-webc-core/src/internals/PieElement';
+import { PropertyValues } from 'lit';
+import { RTLInterface } from '@justeattakeaway/pie-webc-core';
+import { TemplateResult } from 'lit-html';
+
+declare type AriaProps = {
+    label?: string;
+};
+
+export declare type DefaultProps = ComponentDefaultProps<PaginationProps, 'currentPage' | 'totalPages' | 'disabled'>;
+
+export declare const defaultProps: DefaultProps;
+
+/**
+ * The event name dispatched when the user clicks the "next" control.
+ * @constant
+ */
+export declare const ON_NEXT_EVENT = "pie-pagination-next";
+
+/**
+ * The event name dispatched when the user interacts with a pagination control.
+ * The component is fully controlled: it never changes `currentPage` itself, it
+ * only tells the consumer which page the user wants to navigate to.
+ * @constant
+ */
+export declare const ON_PAGE_CHANGE_EVENT = "pie-pagination-page-change";
+
+/**
+ * The event name dispatched when the user clicks the "previous" control.
+ * @constant
+ */
+export declare const ON_PREV_EVENT = "pie-pagination-prev";
+
+export declare interface PaginationProps {
+    /**
+     * The ARIA attributes for the pagination landmark. Offers a `label` used for
+     * the `aria-label` of the wrapping `<nav>` element.
+     */
+    aria?: AriaProps;
+    /**
+     * The currently active page (1-based). This component is fully controlled, so
+     * it never updates this value itself; the consumer is responsible for updating
+     * it in response to the `pie-pagination-page-change` event.
+     * @default 1
+     */
+    currentPage?: number;
+    /**
+     * The total number of pages to render.
+     * @default 1
+     */
+    totalPages?: number;
+    /**
+     * When true, all pagination controls are disabled.
+     * @default false
+     */
+    disabled?: boolean;
+}
+
+/**
+ * @tagname pie-pagination
+ * @event {CustomEvent} pie-pagination-page-change - when the user interacts with a pagination control.
+ * @event {CustomEvent} pie-pagination-prev - when the user clicks the "previous" control.
+ * @event {CustomEvent} pie-pagination-next - when the user clicks the "next" control.
+ */
+export declare class PiePagination extends PiePagination_base implements PaginationProps {
+    aria: PaginationProps['aria'];
+    currentPage: number;
+    totalPages: number;
+    disabled: boolean;
+    protected updated(changedProperties: PropertyValues<this>): void;
+    /**
+     * Emits the page change event with the page the user wants to navigate to.
+     * The component never updates `currentPage` itself.
+     *
+     * @private
+     */
+    private _emitPageChange;
+    /**
+     * Handles a click on the "previous" control.
+     *
+     * @private
+     */
+    private _handlePreviousClick;
+    /**
+     * Handles a click on the "next" control.
+     *
+     * @private
+     */
+    private _handleNextClick;
+    /**
+     * Handles a click on a page number control.
+     *
+     * @private
+     */
+    private _handlePageClick;
+    /**
+     * Renders the chevron icon for the previous/next controls, mirroring it for RTL.
+     *
+     * @private
+     */
+    private _renderChevronIcon;
+    render(): TemplateResult<1>;
+    static styles: CSSResult;
+}
+
+declare const PiePagination_base: GenericConstructor<RTLInterface> & typeof PieElement;
+
+export { }

package/dist/index.js

@@ -0,0 +1,160 @@
+import { LitElement as u, html as p, unsafeCSS as x } from "lit";
+import { property as g } from "lit/decorators.js";
+import { classMap as f } from "lit/directives/class-map.js";
+import { ifDefined as P } from "lit/directives/if-defined.js";
+import { RtlMixin as y, dispatchCustomEvent as b, safeCustomElement as z } from "@justeattakeaway/pie-webc-core";
+import "@justeattakeaway/pie-icon-button";
+import "@justeattakeaway/pie-icons-webc/dist/IconChevronLeft.js";
+import "@justeattakeaway/pie-icons-webc/dist/IconChevronRight.js";
+const v = class v extends u {
+  willUpdate() {
+    this.getAttribute("v") || this.setAttribute("v", v.v);
+  }
+};
+v.v = "0.1.0";
+let m = v;
+const _ = "*,*:after,*:before{box-sizing:inherit}:host{display:inline-block}.c-pagination{display:inline-block}.c-pagination-list{display:flex;align-items:center;gap:var(--dt-spacing-b);margin:0;padding:0;list-style:none}.c-pagination-item{display:flex;align-items:center}.c-pagination-control{--btn-border-radius: var(--dt-radius-rounded-e);--btn-font-family: var(--dt-font-interactive-l-family);--btn-font-weight: var(--dt-font-interactive-l-weight);--int-states-mixin-bg-color: var(--dt-color-interactive-brand);--btn-text-color: var(--dt-color-content-interactive-light-solid);--btn-padding-vertical-xsmall: 6px;--btn-padding-vertical-small-expressive: 8px;--btn-padding-vertical-small-productive: 10px;--btn-padding-vertical-medium: 12px;--btn-padding-vertical-large: 16px;--btn-padding-horizontal-small: var(--dt-spacing-b);--btn-padding-horizontal-medium: var(--dt-spacing-d);--btn-padding-horizontal-large: var(--dt-spacing-e);position:relative;display:inline-flex;gap:var(--dt-spacing-b);align-items:center;justify-content:center;border:none;border-radius:var(--btn-border-radius);outline:none;background-color:var(--int-states-mixin-bg-color);cursor:pointer;-webkit-user-select:none;user-select:none;text-decoration:none;font-family:var(--btn-font-family);font-size:var(--btn-font-size);font-weight:var(--btn-font-weight);color:var(--btn-text-color);line-height:var(--btn-line-height);inline-size:var(--btn-inline-size)}.c-pagination-control:focus-visible{box-shadow:0 0 0 2px var(--dt-color-focus-inner),0 0 0 4px var(--dt-color-focus-outer);outline:none}.c-pagination-control{--btn-font-size: calc(var(--dt-font-interactive-xs-size) * 1px);--btn-line-height: calc(var(--dt-font-interactive-xs-line-height) * 1px);--btn-icon-size: 16px;--icon-size-override: 16px;padding:var(--btn-padding-vertical-xsmall) var(--btn-padding-horizontal-small)}@media(min-width:769px){.c-pagination-control.c-button--responsive{--btn-font-size: calc(var(--dt-font-interactive-s-size) * 1px);--btn-line-height: calc(var(--dt-font-interactive-s-line-height) * 1px);--btn-icon-size: 20px;--icon-size-override: 20px;padding:var(--btn-padding-vertical-small-productive) var(--btn-padding-horizontal-medium)}.c-pagination-control.c-button--responsive.c-button--expressive{--btn-font-size: calc(var(--dt-font-interactive-l-size) * 1px);--btn-line-height: calc(var(--dt-font-interactive-l-line-height) * 1px);--btn-icon-size: 20px;--icon-size-override: 20px;padding:var(--btn-padding-vertical-small-expressive) var(--btn-padding-horizontal-medium)}}.c-pagination-control.c-button--outline,.c-pagination-control.c-button--outline-inverse{padding:calc(var(--btn-padding-vertical-xsmall) - 1px) var(--btn-padding-horizontal-small)}@media(min-width:769px){.c-pagination-control.c-button--outline.c-button--responsive,.c-pagination-control.c-button--outline-inverse.c-button--responsive{padding:calc(var(--btn-padding-vertical-small-productive) - 1px) var(--btn-padding-horizontal-medium)}.c-pagination-control.c-button--outline.c-button--responsive.c-button--expressive,.c-pagination-control.c-button--outline-inverse.c-button--responsive.c-button--expressive{padding:calc(var(--btn-padding-vertical-small-expressive) - 1px) var(--btn-padding-horizontal-medium)}}.c-pagination-control{--int-states-mixin-bg-color: transparent;--btn-text-color: var(--dt-color-content-interactive-secondary-solid)}@media(hover:hover){.c-pagination-control:hover:not(:disabled,.is-disabled,.is-dismissible){--hover-modifier: calc(-1 * var(--dt-color-hover-01));--hover-modifier: var(--dt-color-hover-01);--int-states-mixin-bg-color: hsl(var(--dt-color-black-h), var(--dt-color-black-s), var(--dt-color-black-l), var(--hover-modifier));--int-states-mixin-bg-color: hsl(var(--dt-color-transparent-h), var(--dt-color-transparent-s), calc(var(--dt-color-transparent-l) + var(--hover-modifier)))}}.c-pagination-control:active:not(:disabled,.is-disabled,.is-dismissible),.c-pagination-control.is-loading:not(:disabled,.is-disabled){--active-modifier: calc(-1 * var(--dt-color-active-01));--active-modifier: var(--dt-color-active-01);--int-states-mixin-bg-color: hsl(var(--dt-color-black-h), var(--dt-color-black-s), var(--dt-color-black-l), var(--active-modifier));--int-states-mixin-bg-color: hsl(var(--dt-color-transparent-h), var(--dt-color-transparent-s), calc(var(--dt-color-transparent-l) + var(--active-modifier)))}@supports (background-color: color-mix(in srgb,black,white)){@media(hover:hover){.c-pagination-control:hover:not(:disabled,.is-disabled,.is-dismissible){--int-states-mixin-bg-color: color-mix(in srgb, var(--dt-color-hover-01-bg) var(--dt-color-hover-01), var(--dt-color-transparent))}}.c-pagination-control:active:not(:disabled,.is-disabled,.is-dismissible),.c-pagination-control.is-loading:not(:disabled,.is-disabled){--int-states-mixin-bg-color: color-mix(in srgb, var(--dt-color-active-01-bg) var(--dt-color-active-01), var(--dt-color-transparent))}}.c-pagination-control{inline-size:32px;block-size:32px;padding:0;--btn-font-weight: var(--dt-font-body-s-weight)}.c-pagination-control.c-pagination-control--current{--int-states-mixin-bg-color: var(--dt-color-interactive-primary);--btn-text-color: var(--dt-color-content-interactive-primary)}@media(hover:hover){.c-pagination-control.c-pagination-control--current:hover:not(:disabled,.is-disabled,.is-dismissible){--hover-modifier: var(--dt-color-hover-02);--int-states-mixin-bg-color: hsl(var(--dt-color-interactive-primary-h), var(--dt-color-interactive-primary-s), calc(var(--dt-color-interactive-primary-l) + var(--hover-modifier)))}}.c-pagination-control.c-pagination-control--current:active:not(:disabled,.is-disabled,.is-dismissible),.c-pagination-control.c-pagination-control--current.is-loading:not(:disabled,.is-disabled){--active-modifier: var(--dt-color-active-02);--int-states-mixin-bg-color: hsl(var(--dt-color-interactive-primary-h), var(--dt-color-interactive-primary-s), calc(var(--dt-color-interactive-primary-l) + var(--active-modifier)))}@supports (background-color: color-mix(in srgb,black,white)){@media(hover:hover){.c-pagination-control.c-pagination-control--current:hover:not(:disabled,.is-disabled,.is-dismissible){--int-states-mixin-bg-color: color-mix(in srgb, var(--dt-color-hover-02-bg) var(--dt-color-hover-02), var(--dt-color-interactive-primary))}}.c-pagination-control.c-pagination-control--current:active:not(:disabled,.is-disabled,.is-dismissible),.c-pagination-control.c-pagination-control--current.is-loading:not(:disabled,.is-disabled){--int-states-mixin-bg-color: color-mix(in srgb, var(--dt-color-active-02-bg) var(--dt-color-active-02), var(--dt-color-interactive-primary))}}.c-pagination-control.c-pagination-control--current{--btn-font-weight: var(--dt-font-body-strong-s-weight)}.c-pagination-control:disabled{--int-states-mixin-bg-color: transparent;--btn-text-color: var(--dt-color-content-disabled-solid);cursor:not-allowed}", w = "pie-pagination-page-change", $ = "pie-pagination-prev", k = "pie-pagination-next", h = {
+  currentPage: 1,
+  totalPages: 1,
+  disabled: !1
+};
+var C = Object.defineProperty, N = Object.getOwnPropertyDescriptor, l = (t, i, n, e) => {
+  for (var a = e > 1 ? void 0 : e ? N(i, n) : i, r = t.length - 1, s; r >= 0; r--)
+    (s = t[r]) && (a = (e ? s(i, n, a) : s(a)) || a);
+  return e && a && C(i, n, a), a;
+};
+let o = class extends y(m) {
+  constructor() {
+    super(...arguments), this.currentPage = h.currentPage, this.totalPages = h.totalPages, this.disabled = h.disabled;
+  }
+  updated(t) {
+    t.has("totalPages") && this.totalPages < 1 && console.warn(`pie-pagination: "totalPages" must be at least 1, received "${this.totalPages}".`), t.has("currentPage") && this.currentPage < 1 && console.warn(`pie-pagination: "currentPage" must be at least 1, received "${this.currentPage}".`), t.has("currentPage") && this.currentPage > this.totalPages && console.warn(`pie-pagination: "currentPage" (${this.currentPage}) cannot be greater than "totalPages" (${this.totalPages}).`);
+  }
+  /**
+   * Emits the page change event with the page the user wants to navigate to.
+   * The component never updates `currentPage` itself.
+   *
+   * @private
+   */
+  _emitPageChange(t) {
+    b(this, w, { currentPage: t });
+  }
+  /**
+   * Handles a click on the "previous" control.
+   *
+   * @private
+   */
+  _handlePreviousClick() {
+    if (this.disabled || this.currentPage <= 1) return;
+    const t = this.currentPage - 1;
+    b(this, $, { currentPage: t }), this._emitPageChange(t);
+  }
+  /**
+   * Handles a click on the "next" control.
+   *
+   * @private
+   */
+  _handleNextClick() {
+    if (this.disabled || this.currentPage >= this.totalPages) return;
+    const t = this.currentPage + 1;
+    b(this, k, { currentPage: t }), this._emitPageChange(t);
+  }
+  /**
+   * Handles a click on a page number control.
+   *
+   * @private
+   */
+  _handlePageClick(t) {
+    this.disabled || t === this.currentPage || this._emitPageChange(t);
+  }
+  /**
+   * Renders the chevron icon for the previous/next controls, mirroring it for RTL.
+   *
+   * @private
+   */
+  _renderChevronIcon(t) {
+    return (t === "previous" ? !this.isRTL : this.isRTL) ? p`<icon-chevron-left></icon-chevron-left>` : p`<icon-chevron-right></icon-chevron-right>`;
+  }
+  render() {
+    const {
+      aria: t,
+      currentPage: i,
+      disabled: n,
+      totalPages: e
+    } = this, a = Array.from({ length: Math.max(e, 0) }, (c, d) => d + 1), r = n || i <= 1, s = n || i >= e;
+    return p`
+            <nav
+                class="c-pagination"
+                aria-label="${(t == null ? void 0 : t.label) ?? "Pagination"}"
+                data-test-id="pie-pagination">
+                <ol class="c-pagination-list" data-test-id="pie-pagination-list">
+                    <li class="c-pagination-item">
+                        <pie-icon-button
+                            data-test-id="pie-pagination-previous"
+                            size="xsmall"
+                            variant="ghost-secondary"
+                            ?disabled="${r}"
+                            .aria="${{ label: "Previous page" }}"
+                            @click="${this._handlePreviousClick}">
+                            ${this._renderChevronIcon("previous")}
+                        </pie-icon-button>
+                    </li>
+
+                    ${a.map((c) => {
+      const d = c === i;
+      return p`
+                            <li class="c-pagination-item">
+                                <button
+                                    type="button"
+                                    class="${f({
+        "c-pagination-control": !0,
+        "c-pagination-control--current": d
+      })}"
+                                    data-test-id="pie-pagination-page"
+                                    ?disabled="${n}"
+                                    aria-current="${P(d ? "page" : void 0)}"
+                                    aria-label="Page ${c}"
+                                    @click="${() => this._handlePageClick(c)}">
+                                    ${c}
+                                </button>
+                            </li>`;
+    })}
+
+                    <li class="c-pagination-item">
+                        <pie-icon-button
+                            data-test-id="pie-pagination-next"
+                            size="xsmall"
+                            variant="ghost-secondary"
+                            ?disabled="${s}"
+                            .aria="${{ label: "Next page" }}"
+                            @click="${this._handleNextClick}">
+                            ${this._renderChevronIcon("next")}
+                        </pie-icon-button>
+                    </li>
+                </ol>
+            </nav>`;
+  }
+};
+o.styles = x(_);
+l([
+  g({ type: Object })
+], o.prototype, "aria", 2);
+l([
+  g({ type: Number })
+], o.prototype, "currentPage", 2);
+l([
+  g({ type: Number })
+], o.prototype, "totalPages", 2);
+l([
+  g({ type: Boolean })
+], o.prototype, "disabled", 2);
+o = l([
+  z("pie-pagination")
+], o);
+export {
+  k as ON_NEXT_EVENT,
+  w as ON_PAGE_CHANGE_EVENT,
+  $ as ON_PREV_EVENT,
+  o as PiePagination,
+  h as defaultProps
+};

package/dist/react.d.ts

@@ -0,0 +1,122 @@
+import { ComponentDefaultProps } from '@justeattakeaway/pie-webc-core';
+import { CSSResult } from 'lit';
+import { GenericConstructor } from '@justeattakeaway/pie-webc-core';
+import { PieElement } from '@justeattakeaway/pie-webc-core/src/internals/PieElement';
+import { PropertyValues } from 'lit';
+import * as React_2 from 'react';
+import { RTLInterface } from '@justeattakeaway/pie-webc-core';
+import { TemplateResult } from 'lit-html';
+
+declare type AriaProps = {
+    label?: string;
+};
+
+export declare type DefaultProps = ComponentDefaultProps<PaginationProps, 'currentPage' | 'totalPages' | 'disabled'>;
+
+export declare const defaultProps: DefaultProps;
+
+/**
+ * The event name dispatched when the user clicks the "next" control.
+ * @constant
+ */
+export declare const ON_NEXT_EVENT = "pie-pagination-next";
+
+/**
+ * The event name dispatched when the user interacts with a pagination control.
+ * The component is fully controlled: it never changes `currentPage` itself, it
+ * only tells the consumer which page the user wants to navigate to.
+ * @constant
+ */
+export declare const ON_PAGE_CHANGE_EVENT = "pie-pagination-page-change";
+
+/**
+ * The event name dispatched when the user clicks the "previous" control.
+ * @constant
+ */
+export declare const ON_PREV_EVENT = "pie-pagination-prev";
+
+export declare interface PaginationProps {
+    /**
+     * The ARIA attributes for the pagination landmark. Offers a `label` used for
+     * the `aria-label` of the wrapping `<nav>` element.
+     */
+    aria?: AriaProps;
+    /**
+     * The currently active page (1-based). This component is fully controlled, so
+     * it never updates this value itself; the consumer is responsible for updating
+     * it in response to the `pie-pagination-page-change` event.
+     * @default 1
+     */
+    currentPage?: number;
+    /**
+     * The total number of pages to render.
+     * @default 1
+     */
+    totalPages?: number;
+    /**
+     * When true, all pagination controls are disabled.
+     * @default false
+     */
+    disabled?: boolean;
+}
+
+export declare const PiePagination: React_2.ForwardRefExoticComponent<React_2.PropsWithChildren<Omit<React_2.PropsWithoutRef<PaginationProps>, "children">> & React_2.RefAttributes<PiePagination_2> & PiePaginationEvents & ReactBaseType>;
+
+/**
+ * @tagname pie-pagination
+ * @event {CustomEvent} pie-pagination-page-change - when the user interacts with a pagination control.
+ * @event {CustomEvent} pie-pagination-prev - when the user clicks the "previous" control.
+ * @event {CustomEvent} pie-pagination-next - when the user clicks the "next" control.
+ */
+declare class PiePagination_2 extends PiePagination_base implements PaginationProps {
+    aria: PaginationProps['aria'];
+    currentPage: number;
+    totalPages: number;
+    disabled: boolean;
+    protected updated(changedProperties: PropertyValues<this>): void;
+    /**
+     * Emits the page change event with the page the user wants to navigate to.
+     * The component never updates `currentPage` itself.
+     *
+     * @private
+     */
+    private _emitPageChange;
+    /**
+     * Handles a click on the "previous" control.
+     *
+     * @private
+     */
+    private _handlePreviousClick;
+    /**
+     * Handles a click on the "next" control.
+     *
+     * @private
+     */
+    private _handleNextClick;
+    /**
+     * Handles a click on a page number control.
+     *
+     * @private
+     */
+    private _handlePageClick;
+    /**
+     * Renders the chevron icon for the previous/next controls, mirroring it for RTL.
+     *
+     * @private
+     */
+    private _renderChevronIcon;
+    render(): TemplateResult<1>;
+    static styles: CSSResult;
+}
+
+declare const PiePagination_base: GenericConstructor<RTLInterface> & typeof PieElement;
+
+declare type PiePaginationEvents = {
+    onPiePaginationPageChange?: (event: CustomEvent) => void;
+    onPiePaginationPrev?: (event: CustomEvent) => void;
+    onPiePaginationNext?: (event: CustomEvent) => void;
+};
+
+declare type ReactBaseType = React_2.HTMLAttributes<HTMLElement>;
+
+export { }

package/dist/react.js

@@ -0,0 +1,25 @@
+import * as a from "react";
+import { createComponent as i } from "@lit/react";
+import { PiePagination as e } from "./index.js";
+import { ON_NEXT_EVENT as r, ON_PAGE_CHANGE_EVENT as m, ON_PREV_EVENT as N, defaultProps as E } from "./index.js";
+const n = i({
+  displayName: "PiePagination",
+  elementClass: e,
+  react: a,
+  tagName: "pie-pagination",
+  events: {
+    onPiePaginationPageChange: "pie-pagination-page-change",
+    // when the user interacts with a pagination control.
+    onPiePaginationPrev: "pie-pagination-prev",
+    // when the user clicks the "previous" control.
+    onPiePaginationNext: "pie-pagination-next"
+    // when the user clicks the "next" control.
+  }
+}), P = n;
+export {
+  r as ON_NEXT_EVENT,
+  m as ON_PAGE_CHANGE_EVENT,
+  N as ON_PREV_EVENT,
+  P as PiePagination,
+  E as defaultProps
+};

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@justeattakeaway/pie-pagination",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "PIE design system pagination built using web components",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/justeattakeaway/pie",
+    "directory": "packages/components/pie-pagination"
+  },
+  "homepage": "https://webc.pie.design/?path=/docs/components-pagination--overview",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "custom-elements.json",
+    "src",
+    "dist",
+    "**/*.d.ts"
+  ],
+  "pieMetadata": {
+    "componentStatus": "alpha",
+    "replaces": {
+      "snacks": []
+    }
+  },
+  "scripts": {
+    "build": "run -T vite build",
+    "build:react-wrapper": "run -T build-react-wrapper",
+    "create:manifest": "run -T cem analyze --litelement",
+    "lint:scripts": "run -T eslint .",
+    "lint:scripts:fix": "yarn lint:scripts --fix",
+    "lint:style": "run -T stylelint ./src/**/*.{css,scss}",
+    "lint:style:fix": "yarn lint:style --fix",
+    "watch": "run -T vite build --watch",
+    "test:browsers": "run -T playwright test -c ./playwright-lit.config.ts",
+    "test:browsers:ci": "yarn test:browsers",
+    "test:visual": "run -T cross-env-shell PERCY_TOKEN=${PERCY_TOKEN_PIE_PAGINATION} percy exec --allowed-hostname cloudfront.net -- run -T playwright test -c ./playwright-lit-visual.config.ts",
+    "test:visual:ci": "yarn test:visual"
+  },
+  "author": "Just Eat Takeaway.com - Design System Team",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@justeattakeaway/pie-components-config": "0.21.5",
+    "@justeattakeaway/pie-css": "1.9.1",
+    "@justeattakeaway/pie-monorepo-utils": "0.9.12",
+    "@justeattakeaway/pie-wrapper-react": "0.14.5"
+  },
+  "customElements": "custom-elements.json",
+  "sideEffects": [
+    "dist/*.js"
+  ],
+  "dependencies": {
+    "@justeattakeaway/pie-button": "1.15.1",
+    "@justeattakeaway/pie-icon-button": "2.8.1",
+    "@justeattakeaway/pie-icons-webc": "1.29.5",
+    "@justeattakeaway/pie-webc-core": "22.0.1"
+  }
+}

package/src/defs-react.ts

@@ -0,0 +1,3 @@
+import type React from 'react';
+
+export type ReactBaseType = React.HTMLAttributes<HTMLElement>;

package/src/defs.ts

@@ -0,0 +1,61 @@
+import { type ComponentDefaultProps } from '@justeattakeaway/pie-webc-core';
+
+/**
+ * The event name dispatched when the user interacts with a pagination control.
+ * The component is fully controlled: it never changes `currentPage` itself, it
+ * only tells the consumer which page the user wants to navigate to.
+ * @constant
+ */
+export const ON_PAGE_CHANGE_EVENT = 'pie-pagination-page-change';
+
+/**
+ * The event name dispatched when the user clicks the "previous" control.
+ * @constant
+ */
+export const ON_PREV_EVENT = 'pie-pagination-prev';
+
+/**
+ * The event name dispatched when the user clicks the "next" control.
+ * @constant
+ */
+export const ON_NEXT_EVENT = 'pie-pagination-next';
+
+type AriaProps = {
+    label?: string;
+};
+
+export interface PaginationProps {
+    /**
+     * The ARIA attributes for the pagination landmark. Offers a `label` used for
+     * the `aria-label` of the wrapping `<nav>` element.
+     */
+    aria?: AriaProps;
+
+    /**
+     * The currently active page (1-based). This component is fully controlled, so
+     * it never updates this value itself; the consumer is responsible for updating
+     * it in response to the `pie-pagination-page-change` event.
+     * @default 1
+     */
+    currentPage?: number;
+
+    /**
+     * The total number of pages to render.
+     * @default 1
+     */
+    totalPages?: number;
+
+    /**
+     * When true, all pagination controls are disabled.
+     * @default false
+     */
+    disabled?: boolean;
+}
+
+export type DefaultProps = ComponentDefaultProps<PaginationProps, 'currentPage' | 'totalPages' | 'disabled'>;
+
+export const defaultProps: DefaultProps = {
+    currentPage: 1,
+    totalPages: 1,
+    disabled: false,
+};

package/src/index.ts

@@ -0,0 +1,200 @@
+import {
+    html, unsafeCSS, type PropertyValues,
+} from 'lit';
+import { property } from 'lit/decorators.js';
+import { classMap } from 'lit/directives/class-map.js';
+import { ifDefined } from 'lit/directives/if-defined.js';
+
+import { PieElement } from '@justeattakeaway/pie-webc-core/src/internals/PieElement';
+import {
+    dispatchCustomEvent,
+    RtlMixin,
+    safeCustomElement,
+} from '@justeattakeaway/pie-webc-core';
+
+import '@justeattakeaway/pie-icon-button';
+import '@justeattakeaway/pie-icons-webc/dist/IconChevronLeft.js';
+import '@justeattakeaway/pie-icons-webc/dist/IconChevronRight.js';
+
+import styles from './pagination.scss?inline';
+import {
+    type PaginationProps,
+    defaultProps,
+    ON_PAGE_CHANGE_EVENT,
+    ON_PREV_EVENT,
+    ON_NEXT_EVENT,
+} from './defs';
+
+// Valid values available to consumers
+export * from './defs';
+
+const componentSelector = 'pie-pagination';
+
+/**
+ * @tagname pie-pagination
+ * @event {CustomEvent} pie-pagination-page-change - when the user interacts with a pagination control.
+ * @event {CustomEvent} pie-pagination-prev - when the user clicks the "previous" control.
+ * @event {CustomEvent} pie-pagination-next - when the user clicks the "next" control.
+ */
+@safeCustomElement('pie-pagination')
+export class PiePagination extends RtlMixin(PieElement) implements PaginationProps {
+    @property({ type: Object })
+    public aria: PaginationProps['aria'];
+
+    @property({ type: Number })
+    public currentPage = defaultProps.currentPage;
+
+    @property({ type: Number })
+    public totalPages = defaultProps.totalPages;
+
+    @property({ type: Boolean })
+    public disabled = defaultProps.disabled;
+
+    protected updated (changedProperties: PropertyValues<this>): void {
+        if (changedProperties.has('totalPages') && this.totalPages < 1) {
+            console.warn(`pie-pagination: "totalPages" must be at least 1, received "${this.totalPages}".`);
+        }
+
+        if (changedProperties.has('currentPage') && this.currentPage < 1) {
+            console.warn(`pie-pagination: "currentPage" must be at least 1, received "${this.currentPage}".`);
+        }
+
+        if (changedProperties.has('currentPage') && this.currentPage > this.totalPages) {
+            console.warn(`pie-pagination: "currentPage" (${this.currentPage}) cannot be greater than "totalPages" (${this.totalPages}).`);
+        }
+    }
+
+    /**
+     * Emits the page change event with the page the user wants to navigate to.
+     * The component never updates `currentPage` itself.
+     *
+     * @private
+     */
+    private _emitPageChange (currentPage: number) {
+        dispatchCustomEvent(this, ON_PAGE_CHANGE_EVENT, { currentPage });
+    }
+
+    /**
+     * Handles a click on the "previous" control.
+     *
+     * @private
+     */
+    private _handlePreviousClick () {
+        if (this.disabled || this.currentPage <= 1) return;
+
+        const requestedPage = this.currentPage - 1;
+
+        dispatchCustomEvent(this, ON_PREV_EVENT, { currentPage: requestedPage });
+        this._emitPageChange(requestedPage);
+    }
+
+    /**
+     * Handles a click on the "next" control.
+     *
+     * @private
+     */
+    private _handleNextClick () {
+        if (this.disabled || this.currentPage >= this.totalPages) return;
+
+        const requestedPage = this.currentPage + 1;
+
+        dispatchCustomEvent(this, ON_NEXT_EVENT, { currentPage: requestedPage });
+        this._emitPageChange(requestedPage);
+    }
+
+    /**
+     * Handles a click on a page number control.
+     *
+     * @private
+     */
+    private _handlePageClick (page: number) {
+        if (this.disabled || page === this.currentPage) return;
+        this._emitPageChange(page);
+    }
+
+    /**
+     * Renders the chevron icon for the previous/next controls, mirroring it for RTL.
+     *
+     * @private
+     */
+    private _renderChevronIcon (direction: 'previous' | 'next') {
+        const pointsLeft = direction === 'previous' ? !this.isRTL : this.isRTL;
+
+        return pointsLeft
+            ? html`<icon-chevron-left></icon-chevron-left>`
+            : html`<icon-chevron-right></icon-chevron-right>`;
+    }
+
+    render () {
+        const {
+            aria, currentPage, disabled, totalPages,
+        } = this;
+
+        const pages = Array.from({ length: Math.max(totalPages, 0) }, (_, index) => index + 1);
+        const isPreviousDisabled = disabled || currentPage <= 1;
+        const isNextDisabled = disabled || currentPage >= totalPages;
+
+        return html`
+            <nav
+                class="c-pagination"
+                aria-label="${aria?.label ?? 'Pagination'}"
+                data-test-id="pie-pagination">
+                <ol class="c-pagination-list" data-test-id="pie-pagination-list">
+                    <li class="c-pagination-item">
+                        <pie-icon-button
+                            data-test-id="pie-pagination-previous"
+                            size="xsmall"
+                            variant="ghost-secondary"
+                            ?disabled="${isPreviousDisabled}"
+                            .aria="${{ label: 'Previous page' }}"
+                            @click="${this._handlePreviousClick}">
+                            ${this._renderChevronIcon('previous')}
+                        </pie-icon-button>
+                    </li>
+
+                    ${pages.map((page) => {
+            const isCurrent = page === currentPage;
+            const classes = {
+                'c-pagination-control': true,
+                'c-pagination-control--current': isCurrent,
+            };
+
+            return html`
+                            <li class="c-pagination-item">
+                                <button
+                                    type="button"
+                                    class="${classMap(classes)}"
+                                    data-test-id="pie-pagination-page"
+                                    ?disabled="${disabled}"
+                                    aria-current="${ifDefined(isCurrent ? 'page' : undefined)}"
+                                    aria-label="Page ${page}"
+                                    @click="${() => this._handlePageClick(page)}">
+                                    ${page}
+                                </button>
+                            </li>`;
+        })}
+
+                    <li class="c-pagination-item">
+                        <pie-icon-button
+                            data-test-id="pie-pagination-next"
+                            size="xsmall"
+                            variant="ghost-secondary"
+                            ?disabled="${isNextDisabled}"
+                            .aria="${{ label: 'Next page' }}"
+                            @click="${this._handleNextClick}">
+                            ${this._renderChevronIcon('next')}
+                        </pie-icon-button>
+                    </li>
+                </ol>
+            </nav>`;
+    }
+
+    // Renders a `CSSResult` generated from SCSS by Vite
+    static styles = unsafeCSS(styles);
+}
+
+declare global {
+    interface HTMLElementTagNameMap {
+        [componentSelector]: PiePagination;
+    }
+}

package/src/pagination.scss

@@ -0,0 +1,53 @@
+@use '@justeattakeaway/pie-css/scss' as p;
+@use '@justeattakeaway/pie-css/scss/mixins/components/button' as btn;
+
+:host {
+    display: inline-block;
+}
+
+.c-pagination {
+    display: inline-block;
+}
+
+.c-pagination-list {
+    display: flex;
+    align-items: center;
+    gap: var(--dt-spacing-b);
+    margin: 0;
+    padding: 0;
+    list-style: none;
+}
+
+.c-pagination-item {
+    display: flex;
+    align-items: center;
+}
+
+// Page number control.
+// Built from the shared PIE button mixins so it inherits the same typography,
+// interactive states and focus ring as pie-button, but sized as a fixed
+// 32x32 circular control to match the Figma specification.
+.c-pagination-control {
+    @include btn.button-base($include-icon-selector: false);
+    @include btn.button-size('xsmall');
+    @include btn.button-variant('ghost');
+
+    inline-size: 32px;
+    block-size: 32px;
+    padding: 0;
+
+    --btn-font-weight: var(--dt-font-body-s-weight);
+
+    &.c-pagination-control--current {
+        @include btn.button-variant('primary-alternative');
+
+        --btn-font-weight: var(--dt-font-body-strong-s-weight);
+    }
+
+    &:disabled {
+        --int-states-mixin-bg-color: transparent;
+        --btn-text-color: var(--dt-color-content-disabled-solid);
+
+        cursor: not-allowed;
+    }
+}

package/src/react.ts

@@ -0,0 +1,29 @@
+import * as React from 'react';
+import { createComponent, type EventName } from '@lit/react';
+import { PiePagination as PiePaginationLit } from './index';
+import { type PaginationProps } from './defs';
+
+export * from './defs';
+
+const PiePaginationReact = createComponent({
+    displayName: 'PiePagination',
+    elementClass: PiePaginationLit,
+    react: React,
+    tagName: 'pie-pagination',
+    events: {
+        onPiePaginationPageChange: 'pie-pagination-page-change' as EventName<CustomEvent>, // when the user interacts with a pagination control.
+        onPiePaginationPrev: 'pie-pagination-prev' as EventName<CustomEvent>, // when the user clicks the "previous" control.
+        onPiePaginationNext: 'pie-pagination-next' as EventName<CustomEvent>, // when the user clicks the "next" control.
+    },
+});
+
+type ReactBaseType = React.HTMLAttributes<HTMLElement>;
+
+type PiePaginationEvents = {
+    onPiePaginationPageChange?: (event: CustomEvent) => void;
+    onPiePaginationPrev?: (event: CustomEvent) => void;
+    onPiePaginationNext?: (event: CustomEvent) => void;
+};
+
+export const PiePagination = PiePaginationReact as React.ForwardRefExoticComponent<React.PropsWithChildren<Omit<React.PropsWithoutRef<PaginationProps>, 'children'>>
+    & React.RefAttributes<PiePaginationLit> & PiePaginationEvents & ReactBaseType>;