# Pagination

여러 페이지로 나뉜 목록에서 볼 페이지를 고르는 컨트롤입니다.

> 원본: `03_ASSET_GUIDE/catalog/pagination.js` · CSS: `03_ASSET_GUIDE/styles/elements/pagination.css`
> kind `component` · category `navigation` · status `stable` · specSource `measured`

> [!NOTE]
> **Grid Footer 에서 분리한 컴포넌트입니다**
> 원래 정의는 `GRID_기능정의.pptx` (`WG2 작업폴더/디벨럭스/김유진/GRID_기능정의.pptx`,
> 2026-08-25) 의 GRID 기능 **② PAGINATION** 이고, 동작 규칙(처음 / 이전 / 번호 최대 10 /
> 다음 / 마지막)은 원본 그대로입니다. 치수·토큰은 `styles/elements/pagination.css` 에서
> 실측했습니다. 표가 아닌 목록에도 필요해 Grid 에서 분리했으며,
> [Grid](./grid.md) 의 Footer 도 이 컴포넌트를 씁니다.

---

## 1. 구성

가로 한 줄입니다. 양 끝에 이동 버튼 넷, 가운데에 페이지 번호가 놓입니다.

```
┌──────────────────────────────────────────┐
│ [|<] [<]   6  [7]  8   [>] [>|]          │
└──────────────────────────────────────────┘
  ①    ②    ③   ④       ⑤   ⑥
```

| # | 요소 | 필수 | 클래스 | 설명 |
|---|---|---|---|---|
| — | Container | 필수 | `atom-pagination` | `<nav aria-label="페이지">`. 블록 자체는 여백을 갖지 않습니다. |
| ① | 처음으로 | 필수 | `atom-pagination__btn` | 왼쪽 끝. 아이콘만 있으므로 `aria-label` 을 답니다. |
| ② | 이전으로 | 필수 | `atom-pagination__btn` | 왼쪽 끝 두 번째. 아이콘만 있으므로 `aria-label` 을 답니다. |
| ③ | 페이지 번호 | 필수 | `atom-pagination__page` | 지금 고를 수 있는 번호입니다. 한 번에 최대 10개입니다. |
| ④ | 현재 페이지 | 필수 | `atom-pagination__page[aria-current="page"]` | `aria-current="page"` 인 번호 하나. 채워진 배경으로 표시합니다. |
| ⑤ | 다음으로 | 필수 | `atom-pagination__btn` | 오른쪽 끝 두 개 중 첫 번째입니다. |
| ⑥ | 마지막으로 | 필수 | `atom-pagination__btn` | 오른쪽 끝입니다. |

생략 기호(`…`)는 두지 않습니다. 번호 창이 10개를 넘지 않으므로 필요하지 않습니다.

---

## 2. 종류 / 크기

### 구성

다섯 부분이며, 모두 페이지 인덱스를 바꿉니다.

| 컨트롤 | 동작 | 비활성 조건 |
| --- | --- | --- |
| `처음으로` | INDEX = 0 | 첫 페이지 |
| `이전으로` | INDEX - 1 | 첫 페이지 |
| `페이지 NUM` | 해당 INDEX 로 이동 | 현재 페이지 |
| `다음으로` | INDEX + 1 | 마지막 페이지 |
| `마지막으로` | INDEX = 마지막 | 마지막 페이지 |

### 번호 창

번호는 **한 번에 최대 10개**이며, 10개 묶음 단위로 넘어갑니다. 10페이지에서 다음으로를 누르면 창이 11~20 으로 바뀝니다.

| 상황 | 번호 | 가장자리 버튼 |
| --- | --- | --- |
| 첫 페이지 | 1~10 | 처음 · 이전 비활성 |
| 중간 | 해당 묶음 10개 | 넷 다 활성 |
| 마지막 묶음 | 남은 개수만 | 다음 · 마지막 비활성 |

> [!NOTE]
> **번호 창은 묶음 단위로 넘어갑니다**
> 현재 페이지를 늘 가운데 두면 번호를 누를 때마다 나머지 번호의 위치가 바뀝니다. 묶음
> 단위로 넘기면 같은 묶음 안에서는 번호 위치가 고정됩니다.

(구현: `implement/src/lib/pagination-window.ts` 의 `getPageWindow` — 창 시작 = `floor(pageIndex / maxPageButtons) × maxPageButtons`.
공용 `lib/pagination.ts` 의 `getPageItems` 는 가운데 정렬 + 생략 기호 규칙이라 이 컴포넌트에는 쓰지 않습니다.)

### Size

`medium` 이 기본입니다. Grid Footer 처럼 컨트롤이 나란히 놓이는 자리는 `medium`,
카드 안의 짧은 목록처럼 밀도가 높은 자리는 `small` 을 씁니다.

> [!NOTE]
> **이 절은 등급이 둘입니다**
> `medium` 은 `styles/elements/pagination.css` 의 실측값이고, `small` 은 이번에 함께 정의한
> 제안값입니다. Grid 에서는 `medium` 하나만 쓰이므로 `small` 은 아직 실사용 사례가 없습니다.

| Size | 높이 · 최소 너비 | 폰트 | 아이콘 |
| --- | --- | --- | --- |
| `medium` | 30px | 13px | 14px |
| `small` | 26px | 12px | 12px |

### Grid Footer 안에서

주로 쓰이는 위치입니다. [Grid](./grid.md) Footer 는 총 건수(좌) · Pagination(중앙) ·
Page size(우) 를 한 줄에 담고, 가운데 정렬은 Grid 쪽에서 겁니다.

```html
<div class="atom-grid__footer">
  <span class="atom-grid__count">총 건수 : <span class="atom-grid__count-value">1,284</span></span>
  <nav class="atom-pagination" aria-label="페이지">…</nav>
  <div class="atom-grid__page-size">
    <div class="atom-select atom-select--size_small" data-state="closed">…</div>
  </div>
</div>
```

> [!WARNING]
> **블록 자체는 여백을 갖지 않습니다**
> 가운데 정렬은 `grid.css` 의 `.atom-grid__footer .atom-pagination { margin-inline: auto }`
> 가 담당합니다. `.atom-pagination` 에 `margin` 을 직접 넣으면 Footer 밖에서 쓸 때마다 그
> 여백을 다시 지워야 합니다.

### 클래스 계약

`styles/elements/pagination.css` 헤더와 원본 `registry.json` `css.blocks` 기준입니다. 클래스가 없는 값(—)은 기본 스타일 그대로입니다.

| Prop | 값 | 클래스 |
|---|---|---|
| `size` | `small` · `medium` | `--size_small` · — |

상태 선택자: `:hover` · `[data-hover]` · `:focus-visible` · `[aria-current="page"]` · `[aria-disabled="true"]`

---

## 3. 상태

네 가지입니다. 현재 페이지만 채워진 배경을 갖고, 나머지는 전부 배경 없이 시작합니다.

| State | 표현 | 선택자 |
| --- | --- | --- |
| 기본 | `--atom-fg-neutral-muted`, 배경 없음 | — |
| hover | `--atom-bg-neutral-weak` 배경 + `--atom-fg-neutral` | `:hover` · `[data-hover]` |
| 현재 페이지 | `--atom-bg-neutral-solid` 배경 + `--atom-fg-on-solid`, 600 굵기 | `[aria-current="page"]` |
| 비활성 | 35% 투명도, 포인터 무시 | `[aria-disabled="true"]` |

> [!NOTE]
> **현재 페이지에는 hover 를 얹지 않습니다**
> 현재 페이지는 누를 필요가 없으므로 hover 규칙을 `:not([aria-current="page"])` 로
> 제외했습니다.

---

## 4. Props

| Prop | Type | Default | 필수 | 설명 |
|---|---|---|---|---|
| `pageIndex` | `number` | `0` | | 현재 페이지 인덱스입니다. 0부터 시작합니다. |
| `pageCount` | `number` | | ● | 전체 페이지 수입니다. 0이면 1로 봅니다. |
| `maxPageButtons` | `number` | `10` | | 한 번에 노출할 번호 개수입니다. |
| `size` | `"small" \| "medium"` | `"medium"` | | 컨트롤 높이와 폰트 크기를 결정합니다. |
| `label` | `string` | `"페이지"` | | `<nav>` 의 `aria-label` 입니다. |
| `onPageChange` | `(pageIndex: number) => void` | | | 페이지가 바뀔 때 호출됩니다. |

구현에서는 `pageIndex` 를 주면 controlled, 생략하면 `defaultPageIndex`(기본 `0`)에서 시작하는 uncontrolled 입니다.

### Parts (compound)

| Part | 요소 | 설명 |
|---|---|---|
| `Pagination` | `<nav class="atom-pagination">` | 위 Props 를 받습니다. 처음 · 이전 · 번호 창 · 다음 · 마지막 버튼을 모두 렌더합니다. 파트는 없습니다. |

---

## 5. Component tokens

| 대상 | 속성 | Token | Value |
| --- | --- | --- | --- |
| 컨트롤 | radius | `{radius.r1}` | 4px |
| 컨트롤 | color | `{color.fg.neutral-muted}` | |
| 컨트롤 | transition | `{duration.fast}` | |
| hover | background | `{color.bg.neutral-weak}` | + `{color.fg.neutral}` |
| 현재 페이지 | background | `{color.bg.neutral-solid}` | + `{color.fg.on-solid}`, 600 굵기 |
| Focus | outline | `{color.fg.brand}` | 2px · offset -2px |

높이(30 · 26px), 폰트(13 · 12px), 컨트롤 사이 간격 2px, 비활성 투명도 0.35 는 토큰이 아닙니다.

> [!NOTE]
> **현재 페이지 표시는 중립색입니다**
> [Grid](./grid.md) 에서 쓰던 `--atom-bg-neutral-solid` 를 그대로 가져왔습니다. Color 의
> "브랜드 색은 아껴 쓴다" 원칙에 따라 브랜드 색은 포커스 링에만 씁니다.

```json
{
  "pagination": {
    "radius":     { "$type": "dimension", "$value": "{radius.r1}" },
    "transition": { "$type": "duration", "$value": "{duration.fast}" },
    "control":    { "$type": "color", "fg": { "$value": "{color.fg.neutral-muted}" } },
    "hover":      { "$type": "color", "bg": { "$value": "{color.bg.neutral-weak}" }, "fg": { "$value": "{color.fg.neutral}" } },
    "current":    { "$type": "color", "bg": { "$value": "{color.bg.neutral-solid}" }, "fg": { "$value": "{color.fg.on-solid}" } },
    "focus":      { "$type": "color", "outline": { "$value": "{color.fg.brand}" } }
  }
}
```

---

## 6. 접근성

- **역할** — `<nav>` 로 감싸고 `aria-label` 로 무엇의 페이지인지 밝힙니다. 한 화면에 목록이
  둘이면 `aria-label` 도 둘이어야 합니다 ("검색 결과 페이지" · "첨부파일 페이지").
- **현재 위치** — 현재 페이지 버튼에 `aria-current="page"` 를 답니다. 채워진 배경만으로는
  스크린리더 사용자에게 전달되지 않습니다.
- **아이콘 버튼** — 처음 · 이전 · 다음 · 마지막은 글자가 없으므로 `aria-label` 이 필수입니다.
  `svg` 에는 `aria-hidden="true"` 를 답니다.
- **번호 버튼** — 텍스트 `3` 이 그대로 이름이 됩니다. 맥락이 약하면 `aria-label="3 페이지"`
  로 보강합니다.
- **비활성** — `disabled` 대신 `aria-disabled="true"` 를 씁니다. 초점은 받되 동작하지
  않으므로, 첫 페이지에서 `Tab` 으로 온 사용자가 "처음으로, 사용할 수 없음" 을 듣습니다.
  `disabled` 를 쓰면 버튼이 탭 순서에서 빠져 버튼의 존재를 알 수 없습니다.
- **키보드** — `Tab` 으로 컨트롤 사이를 이동하고 `Enter` · `Space` 로 누릅니다. 화살표 키는
  쓰지 않습니다. 각 버튼이 독립된 링크에 가까우므로 roving tabindex 를 걸지 않습니다.
- **전환 알림** — 페이지가 바뀌면 목록 영역에서 `aria-live="polite"` 로 "3 페이지, 100건"
  처럼 알립니다. 목록 변경은 화면에만 보이고 스크린리더에는 전달되지 않기 때문입니다.
- **대비** — 기본 상태의 `--atom-fg-neutral-muted` 는 흰 배경 대비 6.99:1 입니다. 비활성은
  35% 투명도라 대비를 만족하지 못하지만, WCAG 는 비활성 컨트롤을 대비 요건에서 제외합니다.
- **타깃 크기** — 30px 는 포인터 기준입니다. 터치가 주 입력인 화면에 얹을 때는 컨트롤 주위
  여백을 더해 44px 를 확보하세요. 컨트롤 간격이 2px 이므로 잘못 누르기 쉽습니다.

---

## 7. 사용 가이드

### 끝에서는 버튼을 비활성으로 둡니다

첫 페이지에서 처음 · 이전을 지우면 번호가 왼쪽으로 밀립니다. 버튼 자리는 유지하고 비활성으로
표시합니다.

- ✅ **Do** 쓸 수 없는 버튼도 자리를 지키고 `aria-disabled="true"` 로 표시합니다.
- ❌ **Don't** 끝에서 버튼을 DOM 에서 빼지 않습니다. 나머지 버튼 위치가 바뀝니다.

### 한 페이지뿐이어도 줄을 지우지 않습니다

결과가 0건이거나 한 페이지에 다 들어가도 `1` 하나를 비활성으로 남깁니다. 컨트롤이 사라지면
페이지가 하나뿐인지 오류인지 구분할 수 없습니다. [Grid](./grid.md) 의 총 건수가 `0` 일
때도 같은 규칙입니다.

- ✅ **Do** `1` 만 남기고 비활성으로 둡니다.
- ❌ **Don't** 컨트롤을 통째로 감추지 않습니다.

### 화면에는 1부터, 코드에는 0부터

`pageIndex` 는 0부터 세고, 사용자에게 보이는 번호는 1부터입니다. 변환은 컴포넌트 안에서 한
번만 합니다. 변환을 여러 곳에서 하면 "0페이지" 표시나 마지막 페이지 계산 오류가 생기기
쉽습니다.

### 페이지가 바뀌면 스크롤을 위로

페이지가 바뀌면 목록 영역의 스크롤을 처음으로 되돌립니다. 그대로 두면 새 페이지를 중간부터
보게 됩니다. Grid 처럼 스크롤이 컴포넌트 안에서
끝나는 경우에는 그 스크롤 컨테이너가 대상입니다.

Page size 가 바뀌면 페이지 인덱스를 0으로 되돌립니다. 100 을 1000 으로 바꾸면 기존
3페이지의 행 범위가 달라지기 때문입니다.

### 관련 컴포넌트

- [Grid](./grid.md) — Footer 가운데에서 이 컴포넌트를 그대로 씁니다.
- [Select](./select.md) — 같은 Footer 오른쪽의 Page size 컨트롤.
- [Tabs](./tabs.md) — 페이지가 아니라 서로 다른 내용 사이를 오갈 때.

---

## 8. 예시

```tsx
const [page, setPage] = useState(0);

<Pagination pageCount={24} pageIndex={page} onPageChange={setPage} />

<Pagination pageCount={5} size="small" label="첨부파일 페이지" />
```

```html
<nav class="atom-pagination" aria-label="페이지">
  <button class="atom-pagination__btn" type="button"
          aria-label="처음으로" aria-disabled="true">
    <svg viewBox="0 0 16 16" aria-hidden="true">…</svg>
  </button>
  <button class="atom-pagination__btn" type="button"
          aria-label="이전으로" aria-disabled="true">
    <svg viewBox="0 0 16 16" aria-hidden="true">…</svg>
  </button>

  <button class="atom-pagination__page" type="button" aria-current="page">1</button>
  <button class="atom-pagination__page" type="button">2</button>
  <button class="atom-pagination__page" type="button">3</button>

  <button class="atom-pagination__btn" type="button" aria-label="다음으로">
    <svg viewBox="0 0 16 16" aria-hidden="true">…</svg>
  </button>
  <button class="atom-pagination__btn" type="button" aria-label="마지막으로">
    <svg viewBox="0 0 16 16" aria-hidden="true">…</svg>
  </button>
</nav>
```

> [!WARNING]
> **`<span>` 으로 쓰지 않습니다**
> 이전 Grid Footer 에서는 `<span>` 이라 `Tab` 으로 이동할 수 없었습니다. 페이지를 바꾸는
> 컨트롤은 `<button type="button">` 이어야 초점과 `Enter` · `Space` 를 받습니다.

`data-hover` 는 문서용 훅입니다. 포인터 없이 hover 표현을 그려야 하는 데모와
스크린샷에서만 씁니다.