# Pagination

> Moves through a script page by page, each page on its revision paper, A-pages included. A plainer form steps through long lists of records.

Source: https://kwark.space/designSystem/components/pagination

## Usage

### What it is
A row of page tabs for moving through something that really is in pages: the screenplay in page view, the printed call sheet set, a PDF of the shooting script. For long lists of records (shots, cast, locations) there is a plainer form: a range and two words.

### The Kwark idea: pages on their revision paper
On a shooting script, the colour of the paper says which issue a page is from, in an order every crew reads the same way (white, blue, pink, yellow, green, goldenrod…; `EditorModule/utils/revision.ts`). Locked scripts never renumber, so a page added after 26 is **26A**. Kwark's pagination draws each page tab with a 6px band of its paper colour and keeps A-pages as their own tabs. A script supervisor can see at a glance that pages 26 and 27 changed on blue and 26A arrived on pink, without opening them. A key under the pager names each colour with its date, because colour alone never carries meaning.

### When to use
- The screenplay's page view, the PDF preview, a stack of issued call sheets.
- A list of more than about 100 records where people need a stable place to return to: the range form.

### When not to use
- For a script in its continuous, scrolling view: use the [scene navigator](https://kwark.space/designSystem/components/script-timeline.md) and the page breaks ([divider](https://kwark.space/designSystem/components/divider.md)).
- For a list under about 100 records: show them all and let people filter ([search and filter](https://kwark.space/designSystem/patterns/search-and-filter.md)).
- Infinite scroll for the screenplay: never. A page is an address people say out loud on set.

### Behaviour
- Always shows first, last, the current page and its neighbours; gaps are an ellipsis.
- **Go to page** takes *26*, *26A* or *p26*; an unknown page says *This draft has 112 pages and A-pages 26A and 61A*.
- The status line says the page, the total, its revision and date, and the scenes on it.
- The range form keeps sort and filters across pages and never applies an edit by row position.

## Style

### Anatomy

1. **Page tab**: at least 34 × 42px (current 46px tall, so it stands up like the top sheet), 1px `--k-line`, corners 3px at the top and 6px at the foot, `--k-surface`, Poppins 500 12px tabular in `--k-text-2`.
2. **Revision band**: 6px tall across the top of the tab in the page's `--k-revision-*` colour, with a 1px edge at 14% `--k-strip-ink` so white paper still shows on white.
3. **Current**: 46px tall, 1px `--k-text` border, `--k-text`, weight 600, `aria-current="page"`.
4. **Steps**: 36 × 42px icon buttons with 16px chevrons (44px on phones); disabled at 35%.
5. **Go to page**: a 56px tabular field labelled *Page*.
6. **Status**: 12px `--k-text-2`, the page and total in `--k-text`.
7. **Key**: 14 × 10px paper swatches with names and dates.
8. **Range form**: *51–100 of 312 shots* and quiet *Previous* / *Next* buttons, a line above.
9. **Phone (under 520px)**: far pages and gaps drop; steps, neighbours and Go to page stay.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-focus` | #0f172a | #f4f4f5 |
| `--k-revision-white` | #ffffff |  |
| `--k-revision-blue` | #d6e4f0 |  |
| `--k-revision-pink` | #f7d9e3 |  |
| `--k-revision-yellow` | #f7f0c0 |  |
| `--k-revision-green` | #d3e8d3 |  |
| `--k-revision-goldenrod` | #f0dfa0 |  |
| `--k-strip-ink` | #1f2427 |  |
| `--k-radius-control` | 6px |  |
| `--k-control-md` | 36px |  |
| `--k-tap` | 44px |  |
| `--k-fs-meta` | 12px |  |
| `--k-fs-dense` | 11px |  |

## Code

### React

Use the HTML below with `kwark.css`. The example shows the markup and styling. Supply any application behavior described on this page.

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<nav class="kw-pager" aria-label="Screenplay pages">
  <button class="kw-pager__step" type="button" aria-label="Previous page, 25"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m15 18-6-6 6-6"/></svg></button>
  <div class="kw-pager__pages">
    <a class="kw-pager__page kw-pager__far" href="#p1" aria-label="Page 1, white">1</a>
    <span class="kw-pager__gap" aria-hidden="true">…</span>
    <a class="kw-pager__page kw-pager__far" href="#p24" aria-label="Page 24, white">24</a>
    <a class="kw-pager__page" href="#p25" aria-label="Page 25, white">25</a>
    <a class="kw-pager__page" href="#p26" data-rev="blue" aria-current="page" aria-label="Page 26, blue revision">26</a>
    <a class="kw-pager__page" href="#p26a" data-rev="pink" aria-label="Page 26A, pink revision">26A</a>
    <a class="kw-pager__page" href="#p27" data-rev="blue" aria-label="Page 27, blue revision">27</a>
    <span class="kw-pager__gap" aria-hidden="true">…</span>
    <a class="kw-pager__page kw-pager__far" href="#p112" aria-label="Page 112, white">112</a>
  </div>
  <button class="kw-pager__step" type="button" aria-label="Next page, 26A"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m9 18 6-6-6-6"/></svg></button>
  <label class="kw-pager__jump">Page <input type="text" inputmode="numeric" value="26" aria-label="Go to page"></label>
  <p class="kw-pager__status"><strong>Page 26 of 112</strong> · Blue revision, 12 Nov · Scenes 12 and 12A</p>
</nav>
<ul class="kw-revkey" aria-label="Revision colours in this script">
  <li><i style="--kw-rev:var(--k-revision-white)"></i>White · first issue</li>
  <li><i style="--kw-rev:var(--k-revision-blue)"></i>Blue · 12 Nov</li>
  <li><i style="--kw-rev:var(--k-revision-pink)"></i>Pink · 15 Nov</li>
</ul>
<nav class="kw-pager kw-pager--list" aria-label="Shot list pages">
  <span class="kw-pager__range"><strong>51–100</strong> of 312 shots</span>
  <span style="display:inline-flex;gap:4px"><a class="kw-button kw-button--quiet" href="#shots-1"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m15 18-6-6 6-6"/></svg>Previous</a><a class="kw-button kw-button--quiet" href="#shots-3">Next<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m9 18 6-6-6-6"/></svg></a></span>
</nav>
```

## Accessibility

### Keyboard
| Key | Does |
|---|---|
| Tab | Previous, each page, Next, Go to page. |
| Enter | Opens the page. Focus moves to the top of the new page, not back to the pager. |
| Page Up / Page Down | Previous and next page while the page view has focus (as in every PDF reader). |
| Enter in Go to page | Goes there; an unknown page shows the error under the field and keeps the typed value. |

### ARIA
- A `<nav>` with `aria-label="Screenplay pages"`; the current tab has `aria-current="page"`.
- Each tab's name says its revision in words: *Page 26, blue revision*. The band is never the only signal.
- Step buttons say where they go: *Next page, 26A*.
- The range form's live region says *Shots 51 to 100 of 312* after the list updates.

## For agents

### Rules

- **Must** draw each script page with its revision colour band and give its revision in words in the accessible name and the key.
- **Must** keep A-pages (26A) as their own pages and never renumber a locked script.
- **Always** show first, last, current and neighbours, plus a Go to page field that accepts 26, 26A and p26.
- **Never** use infinite scroll for pages of a script, and never apply an edit by row position in a paged list.
- **Must** move focus to the top of the new page after navigating.

### AI readiness test

**Task:** Add page navigation to the PDF preview of the shooting script.

**Give the agent:** This page, Screenplay page, Print and export, revision.ts colour order.

**Constraint:** The script has white, blue and pink pages and A-pages 26A and 61A.

**A reliable answer:**
- Tabs with revision bands in the industry order
- 26A and 61A as their own tabs
- Accessible names say the revision in words
- A key lists each colour with its date
- Go to page accepts "61A"
