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

package/src/patterns/horizontal-overflow/horizontal-overflow.spec.md

@@ -1,10 +1,10 @@
 ---
 pattern: horizontal-overflow
 internal: true
-scope: utility primitives module (useOverflowItems hook + fade-mask + scroll-arrow helper components) — DS-internal consumer only(Tabs / ChipGroup wrap)
+scope: utility primitives module (use-overflow-items hooks: useScrollEdges + useOverflowIndices + fade-mask + scroll-arrow helper components) — DS-internal consumer only(Tabs / ChipGroup / FileViewer filmstrip wrap)
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+<!-- @benchmark-unverified-blanket: 對齊 horizontal-overflow.tsx:5 的 file-level retraction(M22(d))——本檔 benchmark claim 均未逐條 URL cite,視為未驗證的視覺/用法陳述,除非後續 retrofit per-claim。 -->
 
 # Horizontal Overflow 設計原則
 
@@ -22,7 +22,7 @@ scope: utility primitives module (useOverflowItems hook + fade-mask + scroll-arr
 
 `ScrollArrow` 元件在 `Tabs/tabs.tsx` 和 `Chip/chip.tsx` **逐行 copy-paste**,`buildFadeMask` / `ARROW_BUTTON_WIDTH` / `SCROLL_PAGE_RATIO` 常數也是複製的。任何修改都要手動改兩處,是漂移溫床——實際上已經造成了一個 bug:
 
-**Chip 的 menu trigger 曾用 chip variant 的視覺語言(與可選 chip 同形狀),讓 menu trigger 與可選 chip 在 mental model 上無法區分——使用者預期點擊是選中,實際是打開選單。同期 Tabs 的 menu trigger 用 text button 正確表達「這是 overflow 工具」,兩個元件 overflow affordance 自相矛盾。**
+**Chip 的 menu trigger 曾漂移成可選 chip 的視覺語言,使用者無法區分「點擊 = 選中」與「點擊 = 打開選單」;同期 Tabs 正確用 text button 表達工具層——同一個 overflow affordance 在兩元件自相矛盾。**
 
 ### Canonical 規則
 
@@ -30,12 +30,21 @@ scope: utility primitives module (useOverflowItems hook + fade-mask + scroll-arr
 
 - 左右 scroll arrow → text button,ChevronLeft / ChevronRight
 - Menu trigger → text button,ChevronDown
-- **禁止**用 item 自身的視覺語言(chip 形狀、tab 底線等)來渲染 overflow trigger——overflow affordance 是「工具層」,不是「業務層」,不該跟內容爭視覺重量(對齊 `CLAUDE.md` 的「工具層必須是視覺重量最低的一層」原則)。
+- **禁止**用 item 自身的視覺語言(chip 形狀、tab 底線等)來渲染 overflow trigger——overflow affordance 是「工具層」,不是「業務層」,不該跟內容爭視覺重量(「工具層必須是視覺重量最低的一層」— 本 spec codify 此原則,owner SSOT 在此)。
 
 這條規則讓使用者看到向下 chevron 或向右 arrow 時,心智是一致的:「這是 overflow 的工具,不是可選內容」,不論這排 items 是什麼類型。
 
 ---
 
+## 何時用 / 近親分界 / 常見誤解 / A11y
+
+- **何時用**:任何「一排水平 items 可能塞不下容器」的 DS 元件要加 overflow affordance 時 import 本 module。scroll vs menu 模式的抉擇 SSOT 在 `tabs.spec.md`「Overflow 模式」表(none / scroll / menu 三策略 + 何時用),此處不重複
+- **何時不用 / 近親分界**:設計上拒絕 overflow 的元件不消費——SegmentedControl / Steps(見「消費者清單 Non-consumers」,各自 spec 明文)
+- **常見誤解**:「在新元件自刻 ScrollArrow / fade mask 比較快」——禁止(見「禁止事項」),copy-paste 漂移正是本 module 存在的歷史教訓
+- **A11y**:arrow / trigger 內建 `aria-label`(arrow 預設繁中、trigger 必填)+ iconOnly Button 自動 tooltip(見「元件保證行為」);menu 開啟後的 a11y 由消費者的 DropdownMenu(Radix)承擔
+
+---
+
 ## 提供的 primitive
 
 ### 常數
@@ -49,7 +58,7 @@ scope: utility primitives module (useOverflowItems hook + fade-mask + scroll-arr
 ### Helpers
 
 - `buildFadeMask({ canScroll, atStart, atEnd, reserveArrowWidth })`
-  回傳 `linear-gradient` 字串。`reserveArrowWidth` > 0 時 fade 會延伸到 arrow button 底下(Material 3 scrim 原理);= 0 時直接從邊緣 fade。
+  回傳 `linear-gradient` 字串。`reserveArrowWidth` > 0 時 fade 會延伸到 arrow button 底下(Material 3 scrim 原理);= 0 時直接從邊緣 fade。 <!-- @benchmark-unverified -->
 - `useScrollByPage(scrollRef)` → `(direction: 'left' | 'right') => void`
   點一次滑動 `clientWidth × SCROLL_PAGE_RATIO`,含 `behavior: 'smooth'`。
 
@@ -60,16 +69,20 @@ scope: utility primitives module (useOverflowItems hook + fade-mask + scroll-arr
   - Icon: `ChevronLeft` / `ChevronRight`
   - aria-label 內建繁中(「向左捲動」/「向右捲動」)
   - **絕對定位**在容器 `left-0` / `right-0`,`pointer-events-none` 外層 + `pointer-events-auto` 內層(讓 mask 下方仍可滑動)
-- `<OverflowMenuTriggerButton label>` (forwardRef)
+- `<OverflowMenuTriggerButton aria-label>` (forwardRef)
   - Root: `<Button variant="text" size="sm" iconOnly>`
   - Icon: `ChevronDown`
-  - 接收 `label` 當 `aria-label`(由消費者決定,例如「頁籤選單(共 5 個)」)
+  - 必填 `aria-label`(直接傳給 Button 的 `aria-label`,無 `label` alias;由消費者決定,例如「頁籤選單(共 5 個)」)
   - `forwardRef` + `...props` spread 讓 Radix `DropdownMenuTrigger asChild` 可以接管
 
+> **元件保證行為:auto-Tooltip**——`OverflowScrollArrow` 與 `OverflowMenuTriggerButton` 都是 `iconOnly` + string `aria-label` + 非 `asChild`,因此都會觸發 Button 內建的 auto-Tooltip wrap(`button.tsx` iconOnly auto-Tooltip wrap)。亦即 hover 時 arrow / trigger 會自動冒出對應 `aria-label` 的 tooltip(「向左捲動」/「向右捲動」/「頁籤選單(共 N 個)」),共享全域 `Tooltip` 的 delay 與 warm-up。`DropdownMenuTrigger asChild` 仍正常運作:Radix 的 `asChild` 由 Trigger 自身消費(套到 `OverflowMenuTriggerButton` 的 forwardRef),不會傳成 Button 的 `asChild` prop,所以 tooltip wrap 與 trigger 接管互不衝突。
+
 ### Hook re-export
 
 為了消費者只 import 一處,本 module re-export `useScrollEdges` / `useOverflowIndices` from `hooks/use-overflow-items.ts`。
 
+> **`useOverflowIndices` 目前 0 consumer(reserved primitive)**:DS 內 menu 模式(Tabs / Chip)走「show-all navigator」派(dropdown 永遠列全部 items,不需動態 overflow 計算),刻意不用此 hook(見 `tabs.tsx` / `chip.tsx` 註解)。本 hook 保留給未來真正需「collapse-overflow」的 consumer;其 a11y(roving tabindex)由 consumer 渲染決定,非 hook 保證(詳 `hooks/use-overflow-items.ts` jsDoc)。`useScrollEdges` 則由 Tabs / Chip scroll 模式實際消費。
+
 ---
 
 ## 消費者架構
@@ -78,12 +91,12 @@ scope: utility primitives module (useOverflowItems hook + fade-mask + scroll-arr
 
 ### 為什麼不做成封閉的 `<HorizontalOverflowContainer>`?
 
-- Tabs 的 underline border owner 在 **list 內部**(`TABS_LIST_BASE` 套 `border-b border-divider`),outer 不畫;Chip outer 是 pill border `rounded-full border border-border`,亦不需 outer `border-b`。Owner 升 list 是 2026-05-19 fix:outer `border-b` + inner `overflow-x-auto` → browser y auto-promote(CSS overflow-3 spec:一軸 auto 時另軸 visible compute auto)→ active underline `after:bottom:-1px` 1px clip + 1px 垂直可捲 bug
+- Tabs 的 separator owner 是 **list**，Chip 的 boundary owner 是**各 item**；兩者的 outer container 都只負責 overflow orchestration。責任歸屬不同，不能藏進同一個封閉 container prop。確切 utility、DOM 結構與歷史瀏覽器修復由 `tabs.tsx` / `chip.tsx` source comments 與 regression checks 擁有。
 - Tabs 用 `TabsPrimitive.List` 作為 inner list;Chip 用 `ToggleGroupPrimitive.Root`
 - Tabs 用 `DropdownMenuItem + selected`(單選);Chip 用 `DropdownMenuCheckboxItem`(多選)
 - Tabs 有 `gap-[var(--layout-space-loose)]`;Chip 有 `gap-2`
 
-把這些差異塞進一個 container prop 只會讓 API 變成 bag of flags。**讓 consumer 組裝,但強制消費 canonical primitive**,是更乾淨的做法——跟 `item-layout` module 提供 `ItemPrefix` / `ItemLabel` / `ItemIcon` 但不做「ItemRow 容器」是同一個設計哲學。
+把這些差異塞進一個 container prop 只會讓 API 變成 bag of flags。**讓 consumer 組裝,但強制消費 canonical primitive**,是更乾淨的做法——跟 `item-anatomy` module(`patterns/element-anatomy/item-anatomy.tsx`)提供 `ItemPrefix` / `ItemLabel` / `ItemIcon` 但不做「ItemRow 容器」是同一個設計哲學。
 
 ### 典型 scroll 模式組裝
 
@@ -118,7 +131,7 @@ return (
 )
 ```
 
-> **Why `overflow-y-hidden`(2026-05-19 codify)**:CSS overflow-3 spec 強制「一軸 auto/scroll/hidden 時另軸 visible compute auto」。`overflow-x-auto` 單獨設 + active underline `after:bottom:-1px` 落在 box 外 → y auto-promote → 1px 垂直可捲 + underline 初始 1px clip bug。明示 `overflow-y-hidden` 阻 promote。對齊 Primer UnderlineNav `overflow-x:auto; overflow-y:hidden` 公開實作。
+> **雙軸 overflow contract(2026-05-19 codify)**:啟用水平捲動時必同時抑制垂直捲動，避免 CSS overflow 軸計算讓 active indicator 進入非預期的垂直 scroll range。確切 utility 由各 consumer source 擁有；Primer UnderlineNav 採同一雙軸約束。
 
 ### 典型 menu 模式組裝
 
@@ -141,7 +154,7 @@ return (
     {canScroll && (
       <DropdownMenu>
         <DropdownMenuTrigger asChild>
-          <OverflowMenuTriggerButton label={`頁籤選單(共 ${items.length} 個)`} />
+          <OverflowMenuTriggerButton aria-label={`頁籤選單(共 ${items.length} 個)`} />
         </DropdownMenuTrigger>
         <DropdownMenuContent align="end">
           {/* menu button container 自帶 border-b border-divider 對齊 list border */}
@@ -154,6 +167,13 @@ return (
 
 ---
 
+## 邊界案例
+
+- **內容塞得下(`canScroll=false`)**:`buildFadeMask` 回傳 `undefined`(無 mask),消費者依 `canScroll` 條件不渲染 arrows / menu trigger(Tabs / Chip 組裝範例皆如此)——items 為 0 或恰好全部塞進容器同理,overflow affordance 完全不出現
+- **鍵盤操作**:arrow / trigger 都是標準 `<Button>`(Tab 聚焦、Enter / Space 觸發);menu 開啟後的 Escape / 方向鍵由消費者的 `DropdownMenu`(Radix)own,本 module 無自訂 keyboard handler
+
+---
+
 ## 禁止事項
 
 ❌ **禁止** copy `ScrollArrow` 到其他元件。要在新元件加 overflow → import 本 module 的 `<OverflowScrollArrow>`。
@@ -163,14 +183,15 @@ return (
 
 ---
 
-## 消費者清單(跟 item-layout 同步維護)
+## 消費者清單(跟 item-anatomy 同步維護)
 
 - `components/Tabs/tabs.tsx` — `overflow="scroll" | "menu"`
 - `components/Chip/chip.tsx` — `layout="scroll" | "menu"`
+- `components/FileViewer/file-viewer.tsx` — Filmstrip(直接組裝 `useScrollEdges` / `useScrollByPage` / `buildFadeMask` / `OverflowScrollArrow`)
 
 **Non-consumers**(2026-05-10 retire from「未來」清單 — prior prediction stale,spec 已明文不消費):
-- ~~`components/Steps/steps.tsx`~~ — `steps.spec.md:326`「水平空間不夠塞 content 區,強塞會破壞 stepper 的掃視節奏」+ L337「步驟 ≤ 5、水平空間充足」→ 設計上不 overflow
-- ~~`components/SegmentedControl/*`~~ — `segmented-control.spec.md:223`「**不支援 overflow / scroll**——若選項可能超出容器寬度,代表選錯元件了」+ L162「最多 5 個 item」→ 設計上拒絕 overflow
+- ~~`components/Steps/steps.tsx`~~ — `steps.spec.md:347`「水平空間不夠塞 content 區,強塞會破壞 stepper 的掃視節奏」+ L358「步驟 ≤ 5、水平空間充足」→ 設計上不 overflow
+- ~~`components/SegmentedControl/*`~~ — `segmented-control.spec.md`「規模限制與邊界案例」段「**不支援 overflow / scroll**——若選項可能超出容器寬度,代表選錯元件了」+「最多 5 個 item」→ 設計上拒絕 overflow
 
 新消費者必須加到這個清單,並且**只從本 module import** overflow 相關的 primitive,不允許自己複製。
 
@@ -179,7 +200,6 @@ return (
 ## 反向引用
 
 - `hooks/use-overflow-items.ts` — 底層 scroll / overflow 計算 hooks(本 module re-export)
-- `CLAUDE.md`「選擇 / 狀態視覺」規則 — 為什麼 overflow trigger 不該用 selection-like 視覺
 - `components/Button/button.tsx` — text variant 的 canonical 樣式
 - `components/DropdownMenu/dropdown-menu.spec.md` — menu item 的 selection 指示器規則
 
@@ -187,5 +207,6 @@ return (
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `chip.spec.md`
 - `file-viewer.spec.md`
 - `overflow-indicator.spec.md`

package/src/patterns/horizontal-overflow/horizontal-overflow.stories.tsx

@@ -0,0 +1,139 @@
+// @story-baseline: components/Tabs/tabs.stories.tsx#OverflowScroll + #OverflowMenu — scroll / menu 兩模式的正式 consumer 視覺基準;本頁組裝結構抄 horizontal-overflow.spec.md「典型 scroll / menu 模式組裝」
+//
+// Internal Pattern 參照 story。本 module 是「樂高」utility primitives(非組裝好的 UI 元件):
+// Tabs / ChipGroup / FileViewer filmstrip 等 consumer 自組 outer wrapper,
+// overflow affordance(scroll arrows / menu trigger / fade mask)一律從這裡取用。
+// 本頁給 DS contributor 看 primitive 的組裝方式與 canonical 規則。
+import type { Meta, StoryObj } from '@storybook/react'
+import {
+  useScrollEdges,
+  useScrollByPage,
+  buildFadeMask,
+  ARROW_BUTTON_WIDTH,
+  OverflowScrollArrow,
+  OverflowMenuTriggerButton,
+} from './horizontal-overflow'
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+} from '@/design-system/components/DropdownMenu/dropdown-menu'
+
+const meta: Meta = {
+  title: 'Design System/Internal Patterns/Horizontal Overflow',
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: `
+**@internal** — 水平 overflow 的 canonical primitives + helpers(fade mask / scroll arrow / menu trigger / \`useScrollEdges\`),給任何「一排水平 items 可能塞不下容器」的 DS 元件共用。
+
+**Canonical 規則**:所有 overflow affordance 一律 \`<Button variant="text" size="sm" iconOnly>\`——overflow trigger 是「工具層」,不用 item 自身的視覺語言(chip 形狀 / tab 底線),不跟內容爭視覺重量。
+
+end-user 不直接 import——由 Tabs(\`overflow\` prop)/ Chip(\`layout\` prop)/ FileViewer filmstrip 消費;本頁是 DS contributor 的組裝參照。
+
+完整規則:\`packages/design-system/src/patterns/horizontal-overflow/horizontal-overflow.spec.md\`
+        `,
+      },
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj
+
+/** 簡報頁面縮圖(對標 FileViewer filmstrip consumer 場景) */
+const SLIDE_TITLES = [
+  '封面', '議程', '年度目標回顧', 'Q2 營收摘要', '客戶成長曲線',
+  '產品線更新', '競品分析', '人力規劃', '風險與對策', '下一步行動',
+]
+
+/** 典型 scroll 模式組裝(抄 spec「典型 scroll 模式組裝」):
+ *  useScrollEdges 偵測邊緣 → buildFadeMask 算漸變 → OverflowScrollArrow 疊在容器兩端。 */
+function FilmstripScrollDemo() {
+  const { scrollRef, atStart, atEnd, canScroll } = useScrollEdges<HTMLDivElement>()
+  const scrollByPage = useScrollByPage(scrollRef)
+  const maskImage = buildFadeMask({
+    canScroll,
+    atStart,
+    atEnd,
+    reserveArrowWidth: ARROW_BUTTON_WIDTH,
+  })
+
+  return (
+    <div className="relative w-[480px]">
+      <div
+        ref={scrollRef}
+        tabIndex={0}
+        aria-label="簡報頁面縮圖"
+        className="overflow-x-auto overflow-y-hidden [scrollbar-width:none] [&::-webkit-scrollbar]:hidden"
+        style={{ maskImage, WebkitMaskImage: maskImage }}
+      >
+        <div className="flex w-fit gap-2 py-1">
+          {SLIDE_TITLES.map((title, i) => (
+            <div
+              key={title}
+              className="flex h-16 w-24 shrink-0 flex-col justify-between rounded-md border border-border bg-surface p-2"
+            >
+              <span className="truncate text-caption text-foreground">{title}</span>
+              <span className="text-footnote text-fg-muted">第 {i + 1} 頁</span>
+            </div>
+          ))}
+        </div>
+      </div>
+      {!atStart && canScroll && (
+        <OverflowScrollArrow direction="left" onClick={() => scrollByPage('left')} />
+      )}
+      {!atEnd && canScroll && (
+        <OverflowScrollArrow direction="right" onClick={() => scrollByPage('right')} />
+      )}
+    </div>
+  )
+}
+
+export const ScrollMode: Story = {
+  name: '捲動模式',
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <FilmstripScrollDemo />
+      <p className="max-w-[480px] text-caption text-fg-muted">
+        簡報縮圖列(對標 FileViewer filmstrip)。fade mask 提示還有內容,arrow 一次捲 80% 容器寬;
+        到達邊緣時該側 arrow 與 fade 自動消失。fade 延伸到 arrow 底下(Material 3 scrim 原理
+        {/* @benchmark-unverified: 對齊 horizontal-overflow.spec.md 已顯式撤回之同句 marker */}),
+        避免透明按鈕 icon 跟 item 文字視覺打架。
+      </p>
+    </div>
+  ),
+}
+
+/** 典型 menu 模式組裝(抄 spec「典型 menu 模式組裝」):
+ *  trigger 只提供按鈕,DropdownMenu 內容由 consumer 依資料結構自組
+ *  (Tabs 用 DropdownMenuItem 單選 / Chip 用 DropdownMenuCheckboxItem 多選)。 */
+const PROJECT_TABS = ['概覽', '活動', '檔案', '權限', '整合', '帳單']
+
+export const MenuMode: Story = {
+  name: '選單模式',
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <div>
+        <DropdownMenu defaultOpen>
+          <DropdownMenuTrigger asChild>
+            <OverflowMenuTriggerButton aria-label={`頁籤選單(共 ${PROJECT_TABS.length} 個)`} />
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="start">
+            {PROJECT_TABS.map((tab) => (
+              <DropdownMenuItem key={tab}>{tab}</DropdownMenuItem>
+            ))}
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </div>
+      <p className="max-w-[480px] text-caption text-fg-muted">
+        專案設定頁籤塞不下時的 ⌄ 導覽選單(對標 Tabs overflow=&quot;menu&quot;)。trigger 是
+        forwardRef Button,Radix DropdownMenuTrigger asChild 接管 aria-expanded / data-state;
+        aria-label 必填且帶語境,hover 會自動冒出同名 tooltip。此處 defaultOpen 讓選單內容
+        直接可見(視覺快照覆蓋);正式 consumer 組裝見檔頭 baseline 兩個 story。
+      </p>
+    </div>
+  ),
+}

package/src/patterns/horizontal-overflow/horizontal-overflow.tsx

@@ -1,5 +1,5 @@
 /**
- * @internal — DS-internal primitive module(2026-05-23 per `.claude/rules/ui-development.md` Public vs Internal canonical)。
+ * @internal — DS-internal primitive module(2026-05-23 per `packages/design-system/ds-canonical/rules/ui-development.md` Public vs Internal canonical)。
  * end-user app 直接 import 無 functioning UI;由 Tabs / ChipGroup 等 DS 元件 wrap 消費 hook + helper components。
  */
 // @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.

package/src/patterns/horizontal-overflow/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 './horizontal-overflow'

package/src/patterns/overlay-surface/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 './overlay-surface'