# Pagination

Pagination is a navigation component that allows users to browse through large sets of content by dividing it into discrete pages. Also known as pager, page navigator, or page selector.

## Installation

Install the pagination, the theme package, and **the font package matching your
project's brand**:

**Leroy Merlin projects**

```bash
npm install @ptlm-azulejo/pagination @ptlm-azulejo/themes @ptlm-azulejo/fonts-leroy-merlin
# or
yarn add @ptlm-azulejo/pagination @ptlm-azulejo/themes @ptlm-azulejo/fonts-leroy-merlin
```

**Adeo projects**

```bash
npm install @ptlm-azulejo/pagination @ptlm-azulejo/themes @ptlm-azulejo/fonts-adeo
# or
yarn add @ptlm-azulejo/pagination @ptlm-azulejo/themes @ptlm-azulejo/fonts-adeo
```

`@ptlm-azulejo/icons` comes along as a dependency — the component imports its
stylesheet itself, so there is nothing extra to wire up.

## Styles & theming

The component ships no colors or typeface of its own — it reads design tokens from
CSS variables at runtime. Those tokens come from `@ptlm-azulejo/themes`, and **the
brand is selected by a class on your app's `<html>` element**, so switching brand
never touches component code.

| Project      | Preset stylesheet                               | Root class    | Typeface        | Font package                       |
| ------------ | ----------------------------------------------- | ------------- | --------------- | ---------------------------------- |
| Leroy Merlin | `@ptlm-azulejo/themes/presets/leroy-merlin.css` | `preset-lm`   | LeroyMerlinSans | `@ptlm-azulejo/fonts-leroy-merlin` |
| Adeo         | `@ptlm-azulejo/themes/presets/adeo.css`         | `preset-adeo` | Roboto          | `@ptlm-azulejo/fonts-adeo`         |

**Leroy Merlin projects**

```js
import '@ptlm-azulejo/themes/presets/leroy-merlin.css'
import '@ptlm-azulejo/fonts-leroy-merlin'
import '@ptlm-azulejo/pagination/style.css'
```

```html
<html lang="pt" class="preset-lm"></html>
```

**Adeo projects**

```js
import '@ptlm-azulejo/themes/presets/adeo.css'
import '@ptlm-azulejo/fonts-adeo'
import '@ptlm-azulejo/pagination/style.css'
```

```html
<html lang="pt" class="preset-adeo"></html>
```

> The preset class is what resolves the brand at runtime. Without it — even with
> the stylesheets imported — the component renders uncolored and in a fallback
> typeface. See the [themes package](../themes/README.md) for brand switching,
> dark mode, and custom brands.

### Light and dark mode

Add `data-theme` alongside the brand class to pin the color scheme. Leave it off
and the preset follows the OS `prefers-color-scheme`:

```html
<html lang="pt" class="preset-lm" data-theme="dark"></html>
```

### Why the font package is separate

The preset only _names_ its typeface in `--font-family` and ships no font files.
[Loading them is your app's job](../themes/README.md#fonts), as with upstream
Mozaic, so you keep control of hosting, subsetting and preload. Without the
matching font package, `font-sans` falls back to a generic sans-serif. A
multi-brand app can install both and switch by swapping the `.preset-*` class:
only the active brand's file is ever downloaded.

## Props

| Name          | Type                 | Default         | Description                                         |
| ------------- | -------------------- | --------------- | --------------------------------------------------- |
| `id`          | `string`             | —               | Unique identifier for the pagination                |
| `modelValue`  | `number`             | —               | Selected page value (`v-model`)                     |
| `options`     | `PaginationOption[]` | —               | Available pages with `text`, `value`, optional `id` |
| `ariaLabel`   | `string`             | `'pagination'`  | Accessible name for the navigation landmark         |
| `selectLabel` | `string`             | `'Select page'` | Accessible label for the page select                |
| `compact`     | `boolean`            | `false`         | Circular previous/next buttons, no select           |
| `ui`          | `PaginationUi`       | `{}`            | Per-part Tailwind class overrides                   |

## Events

| Name                | Payload    | Description                                        |
| ------------------- | ---------- | -------------------------------------------------- |
| `update:modelValue` | `[number]` | Emitted when the selected page changes (`v-model`) |

## Basic usage

```vue
<script setup>
import { ref } from 'vue'
import { AzPagination } from '@ptlm-azulejo/pagination'

const page = ref(10)
</script>

<template>
  <AzPagination
    id="results-pagination"
    v-model="page"
    aria-label="pagination"
    select-label="Select page"
    :options="[
      { text: 'Page 1 of 99', value: 1 },
      { text: 'Page 2 of 99', value: 2 },
      { text: 'Page 3 of 99', value: 3 },
      { text: 'Page 10 of 99', value: 10 },
      { text: 'Page 99 of 99', value: 99 },
    ]"
  />
</template>
```