@justeattakeaway/pie-pagination 0.0.0 → 0.1.0

package/README.md

@@ -30,24 +30,25 @@ Ideally, you should install the component using the **`@justeattakeaway/pie-webc
 ## Documentation
 
 ### Properties
-| Prop             | Options                                                                                                                                                                  | Description                                                                                                                                                                                                         | Default        |
-|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------|
-| | | | |
+| 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
-| Slot     | Description                                                                                                                                                                                                                                                                         |
-|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-|  | |
+This component does not use any slots.
 
 ### CSS Variables
-| Variable | Description                                                                                                                                                                                                                 | Default |
-|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|
-| | | |
+This component does not expose any CSS variables.
 
 ### Events
-| Event | Type                                                                                                                                                                                                                 | Description |
-|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
-| | | |
+| 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
 
@@ -64,12 +65,44 @@ import '@justeattakeaway/pie-webc/components/pagination.js'
 <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:**
@@ -77,6 +110,22 @@ import '@justeattakeaway/pie-webc/components/pagination.js'
 ```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

package/custom-elements.json

@@ -11,8 +11,77 @@
     {
       "kind": "javascript-module",
       "path": "src/defs.js",
-      "declarations": [],
-      "exports": []
+      "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",
@@ -22,7 +91,133 @@
           "kind": "class",
           "description": "",
           "name": "PiePagination",
-          "members": [],
+          "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/dist/index.d.ts

@@ -1,16 +1,107 @@
+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;
 }

package/dist/index.js

@@ -1,27 +1,160 @@
-import { LitElement as f, html as h, unsafeCSS as v } from "lit";
-import { RtlMixin as c, safeCustomElement as d } from "@justeattakeaway/pie-webc-core";
-const e = class e extends f {
+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", e.v);
+    this.getAttribute("v") || this.setAttribute("v", v.v);
   }
 };
-e.v = "0.0.0";
-let i = e;
-const g = "*,*:after,*:before{box-sizing:inherit}:host{display:block}";
-var u = Object.getOwnPropertyDescriptor, b = (a, n, p, o) => {
-  for (var t = o > 1 ? void 0 : o ? u(n, p) : n, s = a.length - 1, l; s >= 0; s--)
-    (l = a[s]) && (t = l(t) || t);
-  return t;
+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
 };
-let r = class extends c(i) {
+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() {
-    return h`<h1 data-test-id="pie-pagination">Hello world!</h1>`;
+    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>`;
   }
 };
-r.styles = v(g);
-r = b([
-  d("pie-pagination")
-], r);
+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 {
-  r as PiePagination
+  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

@@ -1,25 +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> & ReactBaseType>;
+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

@@ -1,13 +1,25 @@
 import * as a from "react";
 import { createComponent as i } from "@lit/react";
 import { PiePagination as e } from "./index.js";
-const t = i({
+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: {}
-}), m = t;
+  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 {
-  m as PiePagination
+  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,7 +1,13 @@
 {
   "name": "@justeattakeaway/pie-pagination",
-  "description": "PIE Design System Pagination built using Web Components",
-  "version": "0.0.0",
+  "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",
@@ -37,13 +43,17 @@
   "devDependencies": {
     "@justeattakeaway/pie-components-config": "0.21.5",
     "@justeattakeaway/pie-css": "1.9.1",
-    "@justeattakeaway/pie-monorepo-utils": "0.9.12"
-  },
-  "dependencies": {
-    "@justeattakeaway/pie-webc-core": "22.0.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

@@ -1,8 +1,3 @@
 import type React from 'react';
-/**
- * TODO: Verify if ReactBaseType can be set as a more specific React interface
- * Use the React IntrinsicElements interface to find how to map standard HTML elements to existing React Interfaces
- * Example: an HTML button maps to `React.ButtonHTMLAttributes<HTMLButtonElement>`
- * https://github.com/DefinitelyTyped/DefinitelyTyped/blob/0bb210867d16170c4a08d9ce5d132817651a0f80/types/react/index.d.ts#L2829
- */
-export type ReactBaseType = React.HTMLAttributes<HTMLElement>
+
+export type ReactBaseType = React.HTMLAttributes<HTMLElement>;

package/src/defs.ts

@@ -1,3 +1,61 @@
-// TODO - please remove the eslint disable comment below when you add props to this interface
-// eslint-disable-next-line @typescript-eslint/no-empty-interface
-export interface PaginationProps {}
+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

@@ -1,12 +1,29 @@
+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 { html, unsafeCSS } from 'lit';
 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 } from './defs';
+import {
+    type PaginationProps,
+    defaultProps,
+    ON_PAGE_CHANGE_EVENT,
+    ON_PREV_EVENT,
+    ON_NEXT_EVENT,
+} from './defs';
 
 // Valid values available to consumers
 export * from './defs';
@@ -15,11 +32,161 @@ 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 () {
-        return html`<h1 data-test-id="pie-pagination">Hello world!</h1>`;
+        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

package/src/pagination.scss

@@ -1,7 +1,53 @@
 @use '@justeattakeaway/pie-css/scss' as p;
+@use '@justeattakeaway/pie-css/scss/mixins/components/button' as btn;
 
 :host {
-    // Note: For consistency sake, the recommended display should be either
-    // "block" or "inline-block", otherwise it can be ommited for floating elements
-    display: block;
+    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

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { createComponent } from '@lit/react';
+import { createComponent, type EventName } from '@lit/react';
 import { PiePagination as PiePaginationLit } from './index';
 import { type PaginationProps } from './defs';
 
@@ -10,10 +10,20 @@ const PiePaginationReact = createComponent({
     elementClass: PiePaginationLit,
     react: React,
     tagName: 'pie-pagination',
-    events: {},
+    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 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> & ReactBaseType>;
+    & React.RefAttributes<PiePaginationLit> & PiePaginationEvents & ReactBaseType>;