@qijenchen/design-system 0.1.0-beta.13 → 0.1.0-beta.131

package/src/components/Pagination/pagination.principles.stories.tsx

@@ -0,0 +1,81 @@
+import React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Pagination } from './pagination'
+import { SegmentedControl, SegmentedControlItem } from '@/design-system/components/SegmentedControl/segmented-control'
+import { Button } from '@/design-system/components/Button/button'
+
+const meta: Meta = {
+  title: 'Design System/Components/Pagination/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// ── Helpers(同 Breadcrumb principles idiom) ──────────────────────────────────
+
+const Rule = ({
+  title, note, children,
+}: {
+  title: string; note?: string; children: React.ReactNode
+}) => (
+  <div className="mb-14">
+    <h3 className="text-body font-bold text-foreground mb-1">{title}</h3>
+    {note && <p className="text-caption text-fg-muted mb-5 max-w-[720px] leading-relaxed">{note}</p>}
+    <div className="flex flex-col gap-3">{children}</div>
+  </div>
+)
+
+const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }) => (
+  <p className={`text-footnote leading-normal ${warn ? 'text-error font-medium' : 'text-fg-muted'}`}>{children}</p>
+)
+
+// ── UsageGuidance — 整合何時用 / 何時不用 / vs 近親(v3 canonical,Polaris/Material/Ant 共識)──
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => {
+    const [page, setPage] = React.useState(2)
+    const [view, setView] = React.useState('list')
+    return (
+      <div>
+        <Rule
+          title="何時用:大量資料切頁後的位置導覽"
+          note="使用者需要知道總頁數、且可能直接跳到某頁的順序瀏覽 —— 訂單列表、搜尋結果、SKU 目錄。表格情境優先用 <DataTable pagination> 內建(內部就是消費本元件),standalone 留給非 DataTable 的列表頁。"
+        >
+          <Pagination total={128} page={page} onPageChange={setPage} />
+          <Label>✓ 訂單管理列表底部:128 筆訂單 / 每頁 20 筆,置於列表下方、間距 tight</Label>
+        </Rule>
+
+        <Rule
+          title="何時不用:無盡瀏覽 feed → load-more / 虛擬滾動"
+          note="activity stream、通知列表這類「往下讀」的流,頁碼是錯的心智模型 —— 使用者不在乎第幾頁,只在乎更多內容。與虛擬滾動互斥:兩者是互斥的大資料策略(TanStack 官方定位),同一份資料不可同時用。"
+        >
+          <Button variant="secondary">載入更多通知</Button>
+          <Label>✓ feed 尾端用 load-more;超大資料集在 DataTable 內建虛擬滾動</Label>
+          <Label warn>✗ 給 activity feed 加頁碼 —— 讀流被切斷,回頭找內容也記不住頁碼</Label>
+        </Rule>
+
+        <Rule
+          title="vs SegmentedControl:位置導覽 ≠ 互斥選值"
+          note="兩者都是「多顆亮一顆」,語意完全不同:SegmentedControl 選項固定 2-5 個、每顆有語意(清單/看板/時間軸),恆有一值;Pagination 頁數動態、可摺疊、數字本身無語意,當前頁是「你在哪」不是「你選了什麼」。"
+        >
+          <SegmentedControl value={view} onValueChange={(v) => v && setView(v)} aria-label="檢視切換">
+            <SegmentedControlItem value="list">清單</SegmentedControlItem>
+            <SegmentedControlItem value="board">看板</SegmentedControlItem>
+            <SegmentedControlItem value="timeline">時間軸</SegmentedControlItem>
+          </SegmentedControl>
+          <Label>✓ 檢視切換用 SegmentedControl(互斥選值)</Label>
+          <Label warn>✗ 用 Pagination 做檢視切換,或用 SegmentedControl 排頁碼</Label>
+        </Rule>
+
+        <Rule
+          title="流程推進不是翻頁"
+          note="精靈流程「上一步 / 下一步」走 Steps(進度指示)+ Button(推進),不是頁碼 —— 頁碼可任意跳,流程有順序依賴;混用會讓使用者以為可以跳過必填步驟。"
+        >
+          <Label>✓ 註冊精靈 / 建立專案引導 → Steps + Button</Label>
+          <Label warn>✗ 精靈底部放 1 2 3 4 頁碼</Label>
+        </Rule>
+      </div>
+    )
+  },
+}

package/src/components/Pagination/pagination.spec.md

@@ -0,0 +1,150 @@
+---
+component: Pagination
+family: composite
+variants: {}
+sizes: {}
+traits:
+  - hasInteractiveStates
+  - isStructural
+benchmark:
+  - Ant Design Pagination: github.com/ant-design/ant-design/tree/master/components/pagination
+  - MUI Pagination: github.com/mui/material-ui/tree/master/packages/mui-material/src/Pagination
+  - Atlassian Pagination: atlassian.design/components/pagination
+  - shadcn Pagination: ui.shadcn.com/docs/components/pagination
+  - TanStack Table Pagination: tanstack.com/table/latest/docs/guide/pagination
+  - Carbon Pagination: github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Pagination
+  - Polaris Pagination: polaris-react.shopify.com/components/navigation/pagination
+---
+
+# Pagination 設計原則
+
+## 定位
+
+Pagination 是「大量資料切成多頁後的位置導覽」——顯示當前頁、允許直接跳到任一頁。
+
+基於 shadcn/ui Pagination 的 DOM 骨架(`nav >(操作群 div)> ul > li` + 當前頁 `aria-current="page"`),但**按鈕消費 DS `Button`、事件驅動、資料模型 = `total`(總筆數)+ `pageSize`(Ant Pagination 同款,總頁數內部推導),非 shadcn 原生的 `<a href>` 連結型**——本 DS 服務 app 產品場景;需要 URL 同步時由 consumer 在 `onPageChange` 接 router,不是把按鈕換成連結。`page` / `pageSize` 皆 dual-mode(傳值 = controlled,不傳 = uncontrolled)。
+
+**本元件是分頁的完整功能 SSOT**(2026-07-06 user 拍板):頁碼、總筆數資訊(`showTotal`)、每頁筆數選單(`pageSizeOptions`)全部 own 在此——Ant(showTotal / showSizeChanger 內建於 Pagination)/ Carbon(page-size select 內建)/ MUI TablePagination(rows-per-page + range 內建)同派。DataTable 等 consumer **轉發 config 消費本元件**,不自拼分頁列。
+
+**Layout Family**:非 4-family — self-contained composite(nav 橫排 control row);個別按鈕消費 Family 3(Button Pill)。
+
+**樣式派系**(2026-07-05 user 拍板):本系統採數字頁碼列(上下頁箭頭 + 數字 + ellipsis 摺疊)，使用者可同時看見目前位置、鄰近頁與頭尾邊界。純上下頁或 page Select 是不同導覽模式，不在此元件內並存。
+
+---
+
+## 何時用
+
+- 資料表翻頁(**優先用 `<DataTable pagination>` 內建**,見下方分界)
+- server 分批載入的列表頁 / 搜尋結果頁(消費端自行 slice 或 server 端分頁)
+- 任何「使用者需要知道總頁數、且可能想直接跳到某頁」的順序瀏覽
+
+## 何時不用
+
+| 情境 | 改用 |
+|------|------|
+| 無盡瀏覽 feed(activity stream / 通知列表) | 虛擬滾動或 load-more,不是頁碼 |
+| 資料表且已用 `<DataTable>` | `<DataTable pagination>` 內建(不要自己在表格下手排 standalone Pagination) |
+| 精靈流程「上一步 / 下一步」 | `Steps`(流程進度)+ Button——頁碼是**位置導覽**,不是流程推進 |
+| 檢視切換(清單 / 看板 / 時間軸) | `SegmentedControl`(互斥選值) |
+| 資料不足 2 頁且未來也不會成長 | 不放 Pagination(元件本身單頁仍照常渲染;`total <= 0` 才不渲染——見邊界案例) |
+
+## 近親分界
+
+- **vs `SegmentedControl`**:兩者都是「多顆中亮一顆」,但語意不同——SegmentedControl 是**互斥選值**(選項固定 2-5 個、每個選項有語意),Pagination 是**位置導覽**(頁數動態、可摺疊、數字本身無語意)。SegmentedControl 恆有一值且不可空;Pagination 的當前頁是「你在哪」不是「你選了什麼」。
+- **vs `<DataTable pagination>`**:DataTable 把 TanStack 分頁模型(`getPaginationRowModel`)封裝在內部並消費本元件 render 分頁列(Ant Table 消費 Pagination / Atlassian DynamicTable `rowsPerPage` 同模式)。表格場景一律走內建;standalone Pagination 留給非 DataTable 的列表 / 搜尋結果頁。
+- **vs 虛擬滾動**:兩者是互斥的大資料策略(TanStack 官方定位為 alternative strategies)——分頁 = 使用者主動換頁、每頁固定筆數;虛擬滾動 = 連續滾動、只渲染可視列。同一份資料不可同時用兩者。
+- **vs `Button secondary`(語意分界)**:當前頁「視覺上」= secondary 一比一(直接消費),但**語意兩條線**——secondary 是「次要動作」(action emphasis),當前頁是「持續選中」(selection state,由 `aria-current="page"` 承載)。在一般 UI 不得反過來拿 secondary 冒充「選中」表達(選中語意元件走 Chip / SegmentedControl / Pagination);此處是 selection 元件消費 action variant 當視覺 host,方向合法。
+
+---
+
+## 內部結構與摺疊規則
+
+```
+◀ 上一頁   1   …   4  [5]  6   …   12   下一頁 ▶
+```
+
+- **格位配置**:boundary 1 + sibling 1(內部常數,v1 不開 props)。最大格位 = 首尾各 1 + 當前頁左右各 1 + 當前頁 + 2 顆 ellipsis = **7 格**,超過即摺疊。若未來有多個消費者需要不同視窗，再將 boundary / sibling 設定開為受控 API。
+- **Ellipsis 非互動**:純指示符號(`MoreHorizontal` icon + `aria-hidden`),不可點——對齊 MUI / shadcn(非互動 ellipsis)。**Ant 為可點 jump-5 派**(rc-pagination 預設把省略格渲染成 `jump-prev` / `jump-next`:hover 顯 «/»、click 跳 5 頁,`https://github.com/react-component/pagination`);本 DS 選非互動,快速跳頁留給未來 `showQuickJumper`。Breadcrumb 的可點 ellipsis 是 collapse dropdown 場景,語意不同。
+- **上下頁按鈕**:iconOnly(`ChevronLeft` / `ChevronRight`),在第一頁 / 最後一頁時 `disabled`。
+- 頁碼格位由內部演算法產生;兩顆省略號各自身分穩定,翻頁時不互相 remount(演算法簽名與 React key 等實作細節由 `pagination.tsx` 檔內註解單一持有,spec 不重述——職責分離)。
+
+## 視覺
+
+- **全部按鈕 = Button variant 純組裝,零視覺客製**(2026-07-06 user 抓出後精煉):上下頁 = `text` iconOnly、未選數字 = `text`、**當前頁 = `secondary`**——secondary 的 rest(primary 描邊+染字+不染底)/ hover(升 hover 階)/ active(深一階)與 `semantic.css`「選中狀態」canonical 完全同拼寫,直接消費不手寫平行副本(M17/M23)。唯一的 className = 等寬幾何(min-width 方形節奏對齊 Ant,屬 bundled family 合法)。
+- **語意與視覺分工**:「選中」語意由 `aria-current="page"` 承載;Button secondary 僅為視覺 host(action 元件本身無選中語意,見近親分界)。與 Chip / SegmentedControl 選中同一套 token 語言(它們非 Button、自建 element 鏡射同拼寫);同時正是 Ant 當前頁做法(`colorPrimary` 描邊+字+不染底、hover `colorPrimaryHover`)。
+- **間距兩層**:頁碼列內部(數字鈕之間)屬 bundled family(`tokens/layoutSpace/layoutSpace.spec.md` 已明文「Pagination 內部」元件自管),元件固定;完整形態的「資訊 ↔ 操作群」與「頁碼 ↔ 每頁選單」群組間距消費 `--layout-space-tight`(density-aware,與 DataTable 表格→分頁列同 token)。
+
+## 完整形態(showTotal / pageSizeOptions)
+
+**Layout =「資訊左、操作右」**(對齊 Ant 源碼結構:total 文字是最左元素、size changer 是最右元素——資訊「你在哪」與操作「換頁/換每頁筆數」分離):
+
+```
+第 1–20 筆,共 85 筆                    ◀ [1] 2 3 4 5 ▶  [20 筆/頁 ▾]
+```
+
+- `showTotal`(opt-in):左側 range 格式「第 x–y 筆,共 N 筆」——Ant「1-20 of 85 items」/ MUI「1–5 of 13」/ Carbon「1–10 of 128 items」三家共識,非單純總數。
+- `pageSizeOptions`(opt-in):頁碼右側顯示「N 筆/頁」選單，並消費既有 `Select size="sm"`。變更每頁筆數時自動回第 1 頁，避免換大 pageSize 後停在超界頁而出現 clamp 歧義。
+- 兩者皆未開 = 純頁碼 inline 形態(consumer layout 決定對齊;表格情境靠右由 DataTable 處理)。
+
+---
+
+## 邊界案例
+
+| 情境 | 行為 |
+|------|------|
+| `total <= 0` | 不渲染(回傳 null)——沒有資料可導覽 |
+| 單頁(`total <= pageSize`) | **照常渲染**(單顆當前頁 + disabled 上下頁)——對齊 Ant `hideOnSinglePage` 預設 false + MUI;保留版面穩定,避免資料量在 1 頁邊界抖動時整條列出現消失 |
+| `page` 越界(< 1 或 > 總頁數) | 防禦性 clamp 後渲染(顯示層不炸);糾正責任在 consumer / DataTable(接資料變動時同步 clamp) |
+| `pageSize <= 0`(consumer contract violation) | 防禦 clamp 至 1(不渲染垃圾格位、totalPages 不會變 Infinity/NaN) |
+| 極大總頁數(500+) | 摺疊規則不變(恆 ≤ 7 格);數字鈕寬度容納 3-4 位數自然撐開 |
+| 邊界頁 disabled 時 focus 落點 | 接受 focus 掉落(對齊 Ant / MUI 行為);不做 focus 轉移 |
+
+## Loading / 空值
+
+本元件無 loading 態——換頁中的資料 loading 由列表 / DataTable 層表達(skeleton / CircularProgress),頁碼列維持可互動或由 consumer disable。無資料(`total <= 0`)即不渲染,空狀態由 `Empty` 表達。
+
+---
+
+## 與 DataTable 的關係
+
+分頁列本體(頁碼、showTotal、每頁筆數選單、資訊左操作右 layout)**SSOT 在本元件**;DataTable 只做:轉發 config(`pagination` prop → 本元件 props)、own TanStack state(controlled 消費)、表格→分頁列 tight 間距、純頁碼形態靠右、與虛擬滾動互斥——這些表格側規則 → `../DataTable/data-table.spec.md`「L5:分頁」段。
+
+## 禁止事項
+
+- ❌ **手刻當前頁選中樣式**——必消費選中 canonical(semantic.css SSOT);選中態不得用 primary-hover(那是瞬時 hover 專用階)
+- ❌ **把按鈕換成 `<a href>`**——URL 同步由 consumer 在 `onPageChange` 接 router;連結型會破壞 controlled 契約與 Button 消費
+- ❌ **與虛擬滾動並用**(同一份資料同時分頁 + 虛擬化)
+- ❌ **把 ellipsis 做成可點按鈕**(快速跳頁需求走未來 `showQuickJumper` 類擴充,不是 ellipsis)
+- ❌ **用 Pagination 做檢視切換 / 流程推進**(見何時不用)
+- ❌ **在 DataTable 下方自行手排 standalone Pagination**(走 `<DataTable pagination>` 內建)
+
+## A11y 預設
+
+**ARIA / Pattern**:WAI-ARIA 無專門 pagination pattern,公認做法(shadcn / MUI / Atlassian 一致)= landmark + current 標記:
+
+- root `<nav aria-label="Pagination">`(landmark;label 用英文 pattern 名,follow Breadcrumb `aria-label="Breadcrumb"` 慣例;consumer 可覆寫)
+- 當前頁按鈕 `aria-current="page"`(**不用** `aria-pressed`——pressed 是可取消的 toggle 語意,當前頁不可「取消」)
+- ellipsis `aria-hidden`(純視覺指示)
+- 上下頁 iconOnly 按鈕帶 `aria-label`(預設「上一頁」/「下一頁」,`prevAriaLabel` / `nextAriaLabel` props 可覆寫)
+
+**鍵盤**:Tab 逐鈕聚焦(原生 button 序)、Enter / Space 觸發——全部繼承 Button 原生語意,無自訂 key handler;不做 roving tabindex(頁碼是 nav landmark 內的獨立按鈕群,非 composite widget,對齊 shadcn / Ant / MUI)。
+
+**驗證**:Storybook a11y 面板 0 critical violation;純鍵盤可完成翻頁與跳頁。
+
+**SizeMatrix N/A rationale**:本元件無 size 軸(單一尺寸,按鈕固定 `size="sm"`)——頁碼列是 chrome 級導覽,不隨 Field 密度縮放。本 DS 表格密度由 DataTable size 控制，分頁列保持穩定高度與命中區，不連動。
+
+## 相關
+
+- `../Button/button.spec.md` — 按鈕消費(text variant / iconOnly / disabled)
+- `../Chip/chip.spec.md` — 「持續選中」視覺 canonical 同族(描邊+染字、不染底)
+- `../SegmentedControl/segmented-control.spec.md` — 近親分界(互斥選值 vs 位置導覽)
+- `../DataTable/data-table.spec.md` — 表格內建分頁(L5 段,SSOT)
+- `../Steps/steps.spec.md` — 流程進度 vs 位置導覽分界
+- `../../tokens/color/semantic.css` — 選中狀態 token SSOT
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `data-table.spec.md`
+- `segmented-control.spec.md`

package/src/components/Pagination/pagination.stories.tsx

@@ -0,0 +1,97 @@
+import React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Pagination } from './pagination'
+
+const meta: Meta<typeof Pagination> = {
+  title: 'Design System/Components/Pagination/展示',
+  component: Pagination,
+  tags: ['autodocs'],
+  parameters: {
+    docs: { description: { component: '讓使用者在離散資料頁之間前後移動或直接跳頁，並保留目前頁位置。資料量需要分頁載入或 URL 可定位頁碼時使用；連續探索內容可改用載入更多。' } },
+  },
+}
+export default meta
+type Story = StoryObj<typeof Pagination>
+
+/* ── 預設 ── */
+export const Default: Story = {
+  name: '預設',
+  render: () => {
+    const [page, setPage] = React.useState(3)
+    return (
+      <div className="flex flex-col gap-3">
+        <p className="text-caption text-fg-muted">
+          客服工單佇列:共 128 筆、每頁 20 筆 → 7 頁。
+        </p>
+        <Pagination total={128} page={page} onPageChange={setPage} />
+      </div>
+    )
+  },
+}
+
+/* ── 完整形態(資訊左、操作右) ── */
+export const FullBar: Story = {
+  name: '完整形態',
+  render: () => {
+    const [page, setPage] = React.useState(1)
+    return (
+      <div className="flex flex-col gap-3">
+        <p className="text-caption text-fg-muted">
+          搜尋結果頁:顯示總筆數 + 每頁筆數選單,左資訊右操作;換每頁筆數會自動回第 1 頁。
+        </p>
+        <Pagination
+          total={85}
+          page={page}
+          onPageChange={setPage}
+          showTotal
+          pageSizeOptions={[10, 20, 50]}
+        />
+      </div>
+    )
+  },
+}
+
+/* ── 大量頁數摺疊 ── */
+export const ManyPages: Story = {
+  name: '大量頁數摺疊',
+  render: () => {
+    const [page, setPage] = React.useState(42)
+    return (
+      <div className="flex flex-col gap-3">
+        <p className="text-caption text-fg-muted">
+          商品 SKU 目錄 10,000 筆 / 每頁 20 = 500 頁:恆 ≤ 7 格位、雙側 … 摺疊(boundary/sibling
+          = 1/1,MUI 預設同款);… 為純指示不可點。翻到頭尾附近時摺疊自動變單側。
+        </p>
+        <Pagination total={10000} page={page} onPageChange={setPage} />
+      </div>
+    )
+  },
+}
+
+/* ── 邊界狀態(R3 hasInteractiveStates) ── */
+export const States: Story = {
+  name: '邊界狀態',
+  render: () => {
+    const [first, setFirst] = React.useState(1)
+    const [last, setLast] = React.useState(7)
+    return (
+      <div className="flex flex-col gap-6">
+        <div>
+          <p className="text-caption text-fg-muted mb-2">第一頁 — 上一頁按鈕 disabled</p>
+          <Pagination total={128} page={first} onPageChange={setFirst} />
+        </div>
+        <div>
+          <p className="text-caption text-fg-muted mb-2">最後一頁 — 下一頁按鈕 disabled</p>
+          <Pagination total={128} page={last} onPageChange={setLast} />
+        </div>
+        <div>
+          <p className="text-caption text-fg-muted mb-2">
+            單頁(total ≤ pageSize)— 照常渲染保持版面穩定(Ant hideOnSinglePage=false + MUI 同);
+            total=0 則整個不渲染
+          </p>
+          <Pagination total={15} page={1} onPageChange={() => {}} />
+        </div>
+      </div>
+    )
+  },
+}

package/src/components/Pagination/pagination.tsx

@@ -0,0 +1,263 @@
+// ────────────────────────────── 消費的 SSOT ──────────────────────────────
+// - Button:../Button/button.tsx —— 全部按鈕純 variant 組裝零視覺客製(2026-07-06 user 抓出):
+//   上下頁 = text iconOnly / 未選數字 = text / 當前頁 = secondary(rest primary 描邊染字不染底、
+//   hover 升 hover 階、active 深一階 —— 與 semantic.css「選中」canonical + 拍板 #8 完全同拼寫);
+//   選中「語意」由 aria-current="page" 承載(非 pressed —— pressed 是可取消 toggle,當前頁不可取消)
+// - Select(size="sm"):../Select/select.tsx —— 完整形態的「N 筆/頁」選單
+// - Ellipsis icon:MoreHorizontal(packages/design-system/ds-canonical/rules/ui-development.md「Icon canonical」)
+// - DOM 骨架:shadcn Pagination(nav > ul > li + aria-current="page");
+//   controlled 事件驅動 + total/pageSize 資料模型對齊 Ant Pagination(2026-07-06 user 拍板:
+//   Pagination 本體 = 完整功能 SSOT —— showTotal / 每頁筆數皆本元件 own,Table 轉發 config 消費)
+// 設計規則:./pagination.spec.md
+import * as React from 'react'
+import { ChevronLeft, ChevronRight, MoreHorizontal } from 'lucide-react'
+import { cn } from '@/lib/utils'
+import { Button } from '@/design-system/components/Button/button'
+import { Select } from '@/design-system/components/Select/select'
+import { useControllable } from '@/design-system/hooks/use-controllable'
+
+// MUI usePagination 預設同款(boundaryCount/siblingCount = 1/1)。內部常數不開 props(M21
+// 最小 API);未來若開放,命名必沿用 MUI siblingCount / boundaryCount。
+// 最大格位 = 首尾各 1 + 當前頁左右各 1 + 當前頁 + 2 顆 ellipsis = 7,超過即摺疊。
+const BOUNDARY_COUNT = 1
+const SIBLING_COUNT = 1
+
+type PaginationSlot = number | 'ellipsis-start' | 'ellipsis-end'
+
+// 摺疊演算法照 MUI usePagination(1/1 配置);兩顆 ellipsis 用 distinct 穩定 key
+// (Breadcrumb Math.random key remount 前車之鑑,breadcrumb.tsx:208-210)。
+function getPaginationRange(page: number, totalPages: number): PaginationSlot[] {
+  const range = (start: number, end: number) =>
+    Array.from({ length: end - start + 1 }, (_, i) => start + i)
+
+  // 全部放得下(≤ 7 頁)→ 不摺疊
+  if (totalPages <= BOUNDARY_COUNT * 2 + SIBLING_COUNT * 2 + 3) return range(1, totalPages)
+
+  const startPages = range(1, BOUNDARY_COUNT)
+  const endPages = range(totalPages - BOUNDARY_COUNT + 1, totalPages)
+  const siblingsStart = Math.max(
+    Math.min(page - SIBLING_COUNT, totalPages - BOUNDARY_COUNT - SIBLING_COUNT * 2 - 1),
+    BOUNDARY_COUNT + 2,
+  )
+  const siblingsEnd = Math.min(
+    Math.max(page + SIBLING_COUNT, BOUNDARY_COUNT + SIBLING_COUNT * 2 + 2),
+    totalPages - BOUNDARY_COUNT - 1,
+  )
+
+  return [
+    ...startPages,
+    ...(siblingsStart > BOUNDARY_COUNT + 2
+      ? (['ellipsis-start'] as const)
+      : [BOUNDARY_COUNT + 1]),
+    ...range(siblingsStart, siblingsEnd),
+    ...(siblingsEnd < totalPages - BOUNDARY_COUNT - 1
+      ? (['ellipsis-end'] as const)
+      : [totalPages - BOUNDARY_COUNT]),
+    ...endPages,
+  ]
+}
+
+export interface PaginationProps extends React.ComponentPropsWithoutRef<'nav'> {
+  /** 資料總筆數(Ant `total` 同款資料模型;<= 0 不渲染)。總頁數 = ceil(total / pageSize) 內部推導。 */
+  total: number
+  /** 每頁筆數(controlled;搭配 onPageSizeChange)。不傳 = uncontrolled(defaultPageSize 起始)。 */
+  pageSize?: number
+  /** uncontrolled 每頁筆數初始值(預設 20)。 */
+  defaultPageSize?: number
+  /** 當前頁(1-based,controlled)。不傳 = uncontrolled(defaultPage 起始)。越界防禦性 clamp。 */
+  page?: number
+  /** uncontrolled 初始頁(1-based,預設 1)。 */
+  defaultPage?: number
+  /** 換頁 callback(1-based)。URL 同步在此接 router,不把按鈕換 <a>。每頁筆數變更時自動回第 1 頁並 fire。 */
+  onPageChange?: (page: number) => void
+  /** 每頁筆數變更 callback。 */
+  onPageSizeChange?: (pageSize: number) => void
+  /** 完整形態:左側顯示「第 x–y 筆,共 N 筆」range 資訊(Ant showTotal / MUI / Carbon 同款,opt-in)。 */
+  showTotal?: boolean
+  /** 完整形態:頁碼右側渲染「N 筆/頁」選單(消費 Select sm;Ant showSizeChanger 同款,opt-in)。 */
+  pageSizeOptions?: number[]
+  /** 上一頁按鈕 aria-label(iconOnly 必有名)。 */
+  prevAriaLabel?: string
+  /** 下一頁按鈕 aria-label。 */
+  nextAriaLabel?: string
+}
+
+/**
+ * Pagination —— 大量資料切頁後的位置導覽(數字頁碼派,2026-07-05 user 拍板)。
+ *
+ * 本元件是分頁的**完整功能 SSOT**(2026-07-06 user 拍板):頁碼 + 總筆數資訊(showTotal)
+ * + 每頁筆數選單(pageSizeOptions)全部 own 在此;完整形態 layout =「資訊左、操作右」
+ * (Ant 源碼結構同款:total 文字最左、size changer 最右)。DataTable 等 consumer 轉發
+ * config 消費本元件,不自拼分頁列。與虛擬滾動互斥。詳 ./pagination.spec.md。
+ */
+const Pagination = React.forwardRef<HTMLElement, PaginationProps>(
+  (
+    {
+      total,
+      pageSize: pageSizeProp,
+      defaultPageSize = 20,
+      page: pageProp,
+      defaultPage = 1,
+      onPageChange,
+      onPageSizeChange,
+      showTotal = false,
+      pageSizeOptions,
+      prevAriaLabel = '上一頁', // i18n-allow: DS default; consumer override via prop(precedent calendar.tsx)
+      nextAriaLabel = '下一頁', // i18n-allow: DS default; consumer override via prop
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    // Hooks 必在 early return 之前(React #310 canonical,select.tsx:503 同慣例)
+    const [pageSize, setPageSize] = useControllable<number>({
+      value: pageSizeProp,
+      defaultValue: defaultPageSize,
+      onChange: onPageSizeChange,
+    })
+    const [page, setPage] = useControllable<number>({
+      value: pageProp,
+      defaultValue: defaultPage,
+      onChange: onPageChange,
+    })
+
+    // 無資料 → 不渲染(空狀態由 Empty / 列表層表達,詳 spec 邊界案例)
+    if (total <= 0) return null
+
+    // pageSize <= 0 防禦 clamp(consumer contract violation)——防 totalPages 變 Infinity/NaN
+    // 渲染垃圾格位(spec 邊界案例表有對應 row)
+    const safePageSize = Math.max(1, Math.floor(pageSize))
+    const totalPages = Math.max(1, Math.ceil(total / safePageSize))
+    const current = Math.min(Math.max(page, 1), totalPages)
+    const slots = getPaginationRange(current, totalPages)
+    const hasSizeChanger = !!pageSizeOptions && pageSizeOptions.length > 0
+    const hasExtras = showTotal || hasSizeChanger
+    const rangeStart = (current - 1) * safePageSize + 1
+    const rangeEnd = Math.min(current * safePageSize, total)
+    // 當前 pageSize 不在 options 內時補進清單頭(否則 Select trigger 顯示裸值失去「N 筆/頁」文案)
+    const sizeOptions = hasSizeChanger
+      ? (pageSizeOptions!.includes(safePageSize) ? pageSizeOptions! : [safePageSize, ...pageSizeOptions!])
+      : []
+
+    const pageList = (
+      <ul className="flex items-center gap-1">
+        <li>
+          <Button
+            variant="text"
+            size="sm"
+            iconOnly
+            startIcon={ChevronLeft}
+            aria-label={prevAriaLabel}
+            disabled={current <= 1}
+            onClick={() => setPage(current - 1)}
+          />
+        </li>
+        {slots.map((slot) =>
+          typeof slot === 'number' ? (
+            <li key={slot}>
+              {/* 當前頁 = <Button variant="secondary"> 一比一零客製(2026-07-06 user 抓出可純組裝):
+                  secondary 的 rest(primary 描邊+染字+不染底)/ hover(升 hover 階)/ active(深一階)
+                  與 semantic.css「選中」canonical + 拍板 #8 完全同拼寫,且無 neutral 灰底 hover —
+                  消費既有 variant 取代手寫平行拼寫(M17/M23 SSOT)。選中「語意」由 aria-current="page"
+                  承載,Button 僅為視覺 host;未選 = text variant。className 只剩等寬幾何
+                  (蓋掉 size sm 的 min-w-14/px-3,方形 item 對齊 Ant;兩 variant 同 border 寬零位移)。 */}
+              <Button
+                variant={slot === current ? 'secondary' : 'text'}
+                size="sm"
+                aria-current={slot === current ? 'page' : undefined}
+                className="min-w-[var(--field-height-sm)] px-1 justify-center tabular-nums"
+                onClick={() => setPage(slot)}
+              >
+                {slot}
+              </Button>
+            </li>
+          ) : (
+            // Ellipsis 純指示不可點(MUI / shadcn 同;Ant 為可點 jump-5 派,見 spec);寬度對齊數字鈕保持節奏
+            <li
+              key={slot}
+              aria-hidden
+              className="flex min-w-[var(--field-height-sm)] items-center justify-center"
+            >
+              <MoreHorizontal size={16} className="text-fg-muted" />
+            </li>
+          ),
+        )}
+        <li>
+          <Button
+            variant="text"
+            size="sm"
+            iconOnly
+            startIcon={ChevronRight}
+            aria-label={nextAriaLabel}
+            disabled={current >= totalPages}
+            onClick={() => setPage(current + 1)}
+          />
+        </li>
+      </ul>
+    )
+
+    return (
+      <nav
+        ref={ref}
+        aria-label="Pagination"
+        className={cn(
+          'flex items-center',
+          // 完整形態 =「資訊左、操作右」(Ant 源碼結構:total 文字最左 li、size changer 最右 li)
+          hasExtras && 'w-full justify-between gap-[var(--layout-space-tight)]',
+          className,
+        )}
+        {...props}
+      >
+        {hasExtras && (
+          // i18n-allow: DS default(range 格式 = Ant/MUI/Carbon 共識);showTotal=false 時渲染
+          // 空 span 佔 justify-between 左位,不含 stray 文字節點
+          <span className="text-body text-fg-secondary">
+            {showTotal ? `第 ${rangeStart}–${rangeEnd} 筆,共 ${total} 筆` : null}
+          </span>
+        )}
+        <div className="flex items-center gap-[var(--layout-space-tight)]">
+          {pageList}
+          {hasSizeChanger && (
+            <Select
+              size="sm"
+              aria-label="每頁筆數" // i18n-allow: DS default
+              className="w-28"
+              value={String(safePageSize)}
+              onChange={(v) => {
+                const next = Number(v)
+                // 同值重選 / 非法值不動作——防「重選 20 筆/頁」誤把頁碼重置回第 1 頁
+                if (!Number.isFinite(next) || next <= 0 || next === safePageSize) return
+                setPageSize(next)
+                // 換每頁筆數回第 1 頁——MUI TablePagination / TanStack autoResetPageIndex 派;
+                // Ant 為 preserve-position(clamp)派,本 DS 採 reset-to-1(spec「完整形態」段有註記)
+                setPage(1)
+              }}
+              options={sizeOptions.map((n) => ({ value: String(n), label: `${n} 筆/頁` }))} // i18n-allow: DS default(Ant「20 / page」內嵌同款)
+            />
+          )}
+        </div>
+      </nav>
+    )
+  },
+)
+Pagination.displayName = 'Pagination'
+
+export const paginationMeta = {
+  component: 'Pagination',
+  family: null, // non-family composite(nav 橫排 control row;按鈕消費 Family 3 Button Pill)
+  variants: {},
+  // 單一尺寸(按鈕固定 Button sm;無 size 軸)—— 頁碼列是 chrome 級導覽不隨 Field 密度縮放,
+  // spec「SizeMatrix N/A rationale」段有完整理由
+  sizes: {},
+  // 'selected' = 當前頁(語意由 aria-current="page" 承載;2026-07-07 meta 詞彙統一:持續選中一律 'selected')
+  states: ['default', 'hover', 'active', 'selected', 'focus-visible', 'disabled'],
+  tokens: {
+    // bg:未選/上下頁(Button text)hover 灰底 + active 深一階;當前頁(secondary)bg-surface
+    bg: ['bg-surface', 'bg-neutral-hover', 'bg-neutral-active'],
+    fg: ['text-foreground', 'text-primary', 'text-primary-hover', 'text-primary-active', 'text-fg-muted', 'text-fg-secondary', 'text-fg-disabled'],
+    border: ['border-primary', 'border-primary-hover', 'border-primary-active'],
+    ring: ['ring-ring'],
+  },
+} as const
+
+export { Pagination }

package/src/components/PeoplePicker/avatar-stack-overflow.ts

@@ -10,7 +10,7 @@
  *   4. **架構違反**:`MultiPersonDisplay` display path 用 canvas-based 算 / Combobox edit path 用 DOM offsetWidth
  *      → 同 cell width 兩 path 不同結果 → user verbatim「同寬 cell overflow 時間不一樣」SSOT 根本被違反
  *
- * **Fix**(per codex Q3 consensus):抽 pure formula + React hook,display + edit 兩 path **共用**。
+ * **Fix**(per codex Q3 consensus):抽 pure formula + React hook,view + edit 兩 path **共用**。
  *
  * **Deterministic formula**:
  * ```

package/src/components/PeoplePicker/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './people-picker'

package/src/components/PeoplePicker/people-picker-helpers.ts

@@ -11,7 +11,7 @@
 // 在主檔 SSOT-bearing API 邊界處,本檔屬機械搬移。
 import { nakedCellRowModeAlign } from '@/design-system/components/Field/field-wrapper'
 import type { SelectOption } from '@/design-system/components/Select/select'
-import { buildPersonNameCard, resolvePerson, type PersonValue } from './person-display'
+import { buildPersonProfileCard, resolvePerson, type PersonValue } from './person-display'
 
 // ── Tag wrapper className SSOT ──────────────────────────────────────────────
 //
@@ -26,7 +26,7 @@ import { buildPersonNameCard, resolvePerson, type PersonValue } from './person-d
 // 必經此 helper(hook `check_peoplepicker_ssot_drift.sh` 攔接 wrapper class literal in tsx)。
 //
 // **2026-05-15 SSOT alignment**(user verbatim「單選 people picker 沒壞,難道沒有 SSOT?」):
-// 單選 picker wrapper(`select.tsx:229`)= `flex-1 min-w-0 inline-flex items-center +
+// 單選 picker wrapper(`select.tsx:244` selectedItemRenderer wrapper)= `flex-1 min-w-0 inline-flex items-center +
 // nakedCellRowModeAlign` — proven working,canonical SSOT。本 helper 對齊 single SSOT,
 // **不**自定一套(spec.md §C row 1 +「length=1 視覺 = 跟單人 closed 一致」+ §E「PersonDisplay
 // 共享 renderer」)。
@@ -46,7 +46,7 @@ export const PEOPLE_PICKER_LENGTH1_WRAPPER_CLASS = `flex-1 min-w-0 inline-flex i
 // code-quality-allow: dead-export — paired helper for SSOT primitive(同上 hook + future use rationale)
 export function getPeoplePickerTagWrapperClass(selectedCount: number): string {
   return selectedCount === 1
-    ? PEOPLE_PICKER_LENGTH1_WRAPPER_CLASS  // SSOT aligned to single picker wrapper(select.tsx:229)
+    ? PEOPLE_PICKER_LENGTH1_WRAPPER_CLASS  // SSOT aligned to single picker wrapper(select.tsx:244 selectedItemRenderer wrapper)
     // length>=2 stack 視覺(spec.md §D row 1):圓形 avatar overlap + group/avatar selector for dismiss overlay
     : '-ml-0.5 first:ml-0 relative inline-flex group/avatar'
 }
@@ -58,7 +58,7 @@ export function getPeoplePickerTagWrapperClass(selectedCount: number): string {
 // menu 時 dropdown row 只顯純文字 name(資訊弱)— 現透過 wrapper schema unify 直接帶 avatar /
 // description 給 SelectMenu primitive 渲。
 //
-// 2026-05-18 fix(per user directive「所有 avatar hover 都要 NameCard」+ avatar.spec.md
+// 2026-05-18 fix(per user directive「所有 avatar hover 都要 ProfileCard」+ avatar.spec.md
 // DS-wide canonical):dropdown menu items Avatar 必帶 hoverCard,跟 PersonDisplay / Tag
 // avatar 對齊。漏掉 = user 抓「PeoplePicker 選單內 avatar 沒有 namecard」。
 export function personToSelectOption(person: PersonValue): SelectOption {
@@ -66,7 +66,7 @@ export function personToSelectOption(person: PersonValue): SelectOption {
   return {
     value: p.name,
     label: p.name,
-    avatar: { src: p.avatarUrl, alt: p.name, hoverCard: buildPersonNameCard(p) },
+    avatar: { src: p.avatarUrl, alt: p.name, hoverCard: buildPersonProfileCard(p) },
     description: p.description,
   }
 }