@qijenchen/design-system 0.1.0-beta.10

package/src/lib/drag-visual.ts

@@ -0,0 +1,272 @@
+/**
+ * Drag visual SSOT(2026-05-06 v14.5)
+ *
+ * DS canonical drag visual,3 處 consumer(TreeView / DataTable row drag / DataTable column reorder)
+ * 共用同一組 styling constant — 對齊 TreeView 最早 codified 的 pattern。
+ *
+ * ## Pattern
+ *
+ * - **Source element**(被拖中的 row/column):`opacity-30`(半透,user 仍看得到原位)
+ *   — 不是 `opacity:0` 全隱形,因 user 拖太遠看不到「源頭」會迷失方向。對齊 TreeView 最早 v1 + Notion / Atlassian / Linear。
+ * - **Ghost preview**(浮動 follow cursor):透過 dnd-kit `<DragOverlay>` portal,clone source 的 outerHTML
+ *   strip transform/transition/opacity → render 在 portal 層,visually 跟 cursor 走。
+ * - **Drop indicator**(目標位置藍細線):2px(`h-0.5` / `w-0.5`)`bg-primary` absolute line:
+ *   - **Row context**(TreeView / table row drag):水平線 在 target row 的 top(before)/ bottom(after)
+ *   - **Column context**(table column reorder):垂直線 在 target column 的 left(before)/ right(after)
+ * - **Inside-drop highlight**(nested target,如拖到 TreeView 子層 / Table nested row 內):整 row `bg-primary-subtle`
+ *
+ * ## Why centralize
+ *
+ * 三處 drag 之前各自實作不一致(TreeView opacity:30 + indicator vs DataTable row opacity:0 no indicator
+ * vs Column reorder opacity:0 + indicator)— M23 / M27 violation(DS 內 canonical 沒對齊)。
+ * 抽到此 module 後 3 處 import 同 constants,未來改 1 處全 sync。
+ *
+ * ## Token usage
+ *
+ * - `bg-primary`:semantic state token(`--primary`)— 跟 focus state ring color 同 source(M23 一致)
+ * - `bg-primary-subtle`:semantic primary subtle(`--primary-subtle`)— inside-drop dim background
+ * - `h-0.5` / `w-0.5`:Tailwind size token = 2px(對齊 hairline divider thickness 概念)
+ * - `opacity-30`:Tailwind 30% opacity(半透但仍清楚看到 outline)
+ */
+
+import type * as React from 'react'
+import type { Modifier } from '@dnd-kit/core'
+
+// ── Source element styling(被拖中的 source row/column)─────────────────────
+
+/**
+ * Source element 拖中的 opacity className。
+ *
+ * **Reuse `opacity-disabled` token**(2026-05-06 v14.5.2 對齊 Atlassian Pragmatic):
+ * Atlassian dnd guidelines 也用 `opacity.disabled` token 給 drag source dim(他們值 0.40,
+ * 我們值 0.45,role 一致)。不另開 drag-source 專屬 token — single-role-per-value 哲學
+ * + DS internal SSOT。
+ */
+export const dragSourceClass = 'opacity-disabled' as const
+
+/** Source element 拖中的 inline style(consume DS token `--opacity-disabled`)*/
+export function dragSourceStyle(isDragging: boolean): React.CSSProperties {
+  return isDragging ? { opacity: 'var(--opacity-disabled)' } : {}
+}
+
+/**
+ * DragOverlay ghost 視覺 canonical(2026-05-06 v14.5.2 對齊 dnd-kit / Atlassian / Material):
+ * **不 dim**(opacity:1)+ elevation shadow `shadow-[var(--elevation-200)]` + 顯式 bg
+ * (`bg-surface` 或 `bg-surface-raised`)+ border。Lifted preview pattern,跟 surface 拉開
+ * 視覺距離靠 shadow 不靠 opacity。
+ *
+ * Consumer 自己組 className(因 ghost 結構各自不同 — TreeView 是 icon+label compact pill,
+ * DataTable 是 cloned row HTML wrapper),這裡只 codify 規則 不導出 class string。
+ */
+
+// ── Drop indicator className(target row/column edge 顯藍細線)──────────────
+
+/**
+ * Row drop indicator(水平線,跨 row 全寬)
+ *
+ * - `before`:在 target row top edge,提示「放開後會插入這 row 之前」
+ * - `after`:在 target row bottom edge,提示「放開後會插入這 row 之後」
+ *
+ * **Indent option**:nested context(TreeView / table nested rows)可加 `style={{ left: indentPx }}`
+ * 讓 indicator 隨 depth 縮排,視覺對齊 row content 起始位置。
+ */
+export const dropIndicatorRow = {
+  before: 'absolute top-0 left-0 right-0 h-0.5 bg-primary z-10 pointer-events-none',
+  after: 'absolute bottom-0 left-0 right-0 h-0.5 bg-primary z-10 pointer-events-none',
+} as const
+
+/**
+ * Column drop indicator(垂直線,跨 column header height)
+ *
+ * - `before`:在 target column left edge(-1px outset 對齊 grid line)
+ * - `after`:在 target column right edge(-1px outset 對齊 grid line)
+ *
+ * 兩種變體,視覺一致(2px primary line),只有 DOM mechanism 不同 — consumer 視 use case 選:
+ *
+ * - **`absoluteDiv`**(TreeView pattern):render absolute `<div>` child;
+ *   consumer 必須有 `position: relative` parent。
+ * - **`pseudoBefore` / `pseudoAfter`**:用 Tailwind `before:` / `after:` pseudo-element;
+ *   consumer 不需 child element(適合 cloneElement 等不能加 child 的場景)。
+ *
+ * 兩變體 thickness / color / z-index 完全一致,差別純 implementation 機制。
+ */
+export const dropIndicatorColumn = {
+  // Absolute div 變體(consumer render <div>)
+  before: 'absolute top-0 bottom-0 left-[-1px] w-0.5 bg-primary z-10 pointer-events-none',
+  after: 'absolute top-0 bottom-0 right-[-1px] w-0.5 bg-primary z-10 pointer-events-none',
+  // Pseudo-element 變體(用 Tailwind before:/after:)
+  pseudoBefore: 'before:absolute before:top-0 before:bottom-0 before:left-[-1px] before:w-0.5 before:bg-primary before:z-10 before:pointer-events-none before:content-[""]',
+  pseudoAfter: 'after:absolute after:top-0 after:bottom-0 after:right-[-1px] after:w-0.5 after:bg-primary after:z-10 after:pointer-events-none after:content-[""]',
+} as const
+
+// ── Inside-drop highlight(nested context,target row 整列亮藍 subtle)─────
+
+/**
+ * Nested 拖入 highlight(TreeView / nested rows 拖到子層)。整 row 加 background。
+ */
+export const dropIndicatorInside = 'bg-primary-subtle' as const
+
+// ── Cursor classes ────────────────────────────────────────────────────────
+
+/** Draggable element 拖中時的 cursor(grabbing)*/
+export const dragActiveCursor = 'cursor-grabbing' as const
+/**
+ * Combined drag handle cursor canonical(2026-05-07 v15.7 user directive):
+ * **只 cursor-grab,不變 grabbing**。對齊 Material / Carbon / Polaris canonical —
+ * drag affordance 由 visible button 提供,cursor 變化反而干擾 indicator+ghost 視覺焦點。
+ * Consumer 直接 cn(...)。
+ */
+export const dragHandleCursorClass = 'cursor-grab' as const
+
+// ── Modifier:Ghost 跟 cursor 維持初始相對位置 SSOT(v15.7 user directive) ─
+
+/**
+ * Ghost 跟 cursor 維持「cursor 在 ghost 點下時相對位置」SSOT(對齊 user directive
+ * 「ghost 和 cursor 要確保相對位置是合理的而且有 ssot」)。
+ *
+ * **Why need this**:dnd-kit DragOverlay 預設 ghost.top-left = source rect (`setNodeRef`)
+ * 的 top-left。當 source ≠ activator 位置不同(e.g. activator = portal'd Button 在
+ * table outer 邊緣;source = primary row 在 table 內 column region),cursor 點下
+ * activator → cursor 落在 source rect 的 negative offset → ghost 永遠相對 source rect
+ * 起算 → cursor 跟 ghost 起始就有大 offset(e.g. 100+ px),drag 期間維持錯位。
+ *
+ * **本 modifier**:把 (cursor.initial - source.left, cursor.initial - source.top)
+ * 加進 transform → ghost.top-left 永遠對齊 cursor 位置(cursor 在 ghost 左前角)。
+ * Consumer 套進 DndContext.modifiers array,所有 drag scenario 套用 = SSOT。
+ *
+ * **對齊世界級**:Linear / Notion / Jira / AG Grid 的 row drag ghost 都跟 cursor
+ * 維持初始相對位置(整列拖時 cursor 在 click 點;button 拖時 cursor 在 button 位置)—
+ * 這個 modifier 把「整列拖 + 整列 ghost」UX 在 button-only / 多 region 場景下也達到。
+ */
+export const snapToCursorModifier: Modifier = ({ transform, activatorEvent, draggingNodeRect }) => {
+  if (!activatorEvent || !draggingNodeRect) return transform
+  // **codex P1 fix(2026-05-07 v15.12)**:KeyboardSensor 走 KeyboardEvent,沒
+  // `clientX/clientY` → `offsetX/offsetY = NaN` → ghost transform 變 NaN/NaN →
+  // overlay 定位+collision 全 corrupt → keyboard-initiated drag 直接壞。Guard 條件:
+  // 只 pointer/mouse event 才平移,keyboard 走 dnd-kit 預設(無 modifier 偏移)。
+  if (!('clientX' in activatorEvent) || !('clientY' in activatorEvent)) return transform
+  const ev = activatorEvent as PointerEvent | MouseEvent
+  if (typeof ev.clientX !== 'number' || typeof ev.clientY !== 'number') return transform
+  const offsetX = ev.clientX - draggingNodeRect.left
+  const offsetY = ev.clientY - draggingNodeRect.top
+  return {
+    ...transform,
+    x: transform.x + offsetX,
+    y: transform.y + offsetY,
+  }
+}
+
+// ── Reorder noop helper(SSOT 對齊 row + column reorder canonical) ────────
+
+/**
+ * Drop position 等同 source 原位 → noop。對齊 Linear / Notion / Jira / TreeView SSOT:
+ * user 拉到 source 鄰近(視覺等同原位)應 cancel,不 commit reorder 也不顯 indicator。
+ *
+ * Consumer 在 onDragOver 用此判斷是否畫 indicator;onDragEnd 用同一函數判斷是否
+ * 觸發 reorder callback —— 兩處共享一個 invariant,避免「indicator 顯示但 commit 不 fire」
+ * 或反向 drift。
+ *
+ * 規則:
+ *   - source idx N,drop on idx N (self) → noop
+ *   - source idx N,drop on idx N-1 with side='after'  = N(原位)→ noop
+ *   - source idx N,drop on idx N+1 with side='before' = N(原位)→ noop
+ */
+export function isReorderNoop(activeIdx: number, overIdx: number, side: 'before' | 'after'): boolean {
+  if (activeIdx === overIdx) return true
+  if (side === 'after' && overIdx + 1 === activeIdx) return true
+  if (side === 'before' && overIdx - 1 === activeIdx) return true
+  return false
+}
+
+// ── Ghost reconstruction(跨 region table row → 完整橫跨 ghost) ───────────
+
+/**
+ * 為 dnd-kit DragOverlay 重建跨 region 的完整 row ghost(2026-05-07 v15.9 Bug A+B 修)。
+ *
+ * **Why cross-region**:Pinned column DataTable 結構 = 三 region(left / center / right)
+ * 各 mount 一個 row div(同 `row.id`),listeners 只在 primary(center)。之前 ghost 只
+ * 抓 primary region row → cells 只有 center 欄(missing pinned SKU / Updated)→ user 看
+ * 到 ghost「跟 source 不一樣」(Bug B)。virtualized + 無 pinning 下亦可能因 region 多
+ * 個 mount 衍生不可預期(Bug A)。
+ *
+ * **Algorithm**:
+ *   1. 收集 `[role="row"][data-sortable-row-id="${id}"]` 所有 match(可能 1-3 個 region)
+ *   2. DOM 文檔順序剛好是 left → center → right(因 body region 排列順序)
+ *   3. 從每個 region row 的 children(role=cell)抽出 outerHTML,串成單一 flex row
+ *   4. 總寬 = sum(region offsetWidth)
+ *   5. Wrap 用 primary region 的 className(視覺一致)+ inline `display:flex; width:total`
+ *
+ * **Single-region case**(無 pinning,常見):退化成 single row clone + sanitize,行為跟舊版同。
+ *
+ * **Returns** `{ html, width }` 或 `null`(找不到 row)。
+ */
+export function reconstructFullRowGhost(
+  rowId: string,
+  tableRoot: HTMLElement | null,
+): { html: string; width: number } | null {
+  // **codex P1 fix(2026-05-07 v15.13)**:tableRoot 強制 required(non-optional)。
+  // 之前 fallback document 仍允許多 DataTable 同頁 row.id reuse(default index-based)→
+  // cross-instance ghost 污染。strict-scope canonical:caller 必傳 tableRef.current
+  // (`[data-data-table-outer]`),null 直接 return null(caller 該守 ref 已 mount)。
+  if (!tableRoot) return null
+  const escaped = rowId.replace(/(["\\])/g, '\\$1')
+  const allRows = Array.from(
+    tableRoot.querySelectorAll<HTMLElement>(
+      `[role="row"][data-sortable-row-id="${escaped}"]`,
+    ),
+  )
+  if (allRows.length === 0) return null
+
+  // Single-region:直接 clone 整 row + sanitize(無 pinning 場景,跟舊版一致)
+  if (allRows.length === 1) {
+    const sourceEl = allRows[0]
+    const clone = sourceEl.cloneNode(true) as HTMLElement
+    sanitizeGhostClone(clone, sourceEl.offsetWidth)
+    return { html: clone.outerHTML, width: sourceEl.offsetWidth }
+  }
+
+  // Multi-region:抽 cells 串接。Primary region(`data-row-drag-source="true"`)的
+  // className + role 給 outer wrapper,確保 hover bg / border / row-height token 一致。
+  const primaryRow =
+    allRows.find((r) => r.dataset.rowDragSource === 'true') ?? allRows[0]
+  const cellsHtml: string[] = []
+  let totalWidth = 0
+  for (const regionRow of allRows) {
+    totalWidth += regionRow.offsetWidth
+    for (const cell of Array.from(
+      regionRow.querySelectorAll<HTMLElement>('[role="cell"],[role="gridcell"]'),
+    )) {
+      const cellClone = cell.cloneNode(true) as HTMLElement
+      // Strip drag handle portal(只在 primary region)+ inline transform 殘餘
+      cellClone.querySelectorAll('[data-drag-handle-portal]').forEach((n) => n.remove())
+      cellClone.style.transform = 'none'
+      cellsHtml.push(cellClone.outerHTML)
+    }
+  }
+  // 套 primary row 的 class(cn 結果含 hover/border/sizing token)+ display:flex 顯式
+  // 容納 cells,inline style override transform/position/opacity 避免 stale 殘餘
+  const inlineStyle = `display:flex; width:${totalWidth}px; transform:none; position:static; opacity:1; transition:none;`
+  const html = `<div role="row" class="${primaryRow.className}" style="${inlineStyle}">${cellsHtml.join('')}</div>`
+  return { html, width: totalWidth }
+}
+
+/**
+ * Reset ghost clone inline styles + strip 干擾 attributes(transform/opacity/data-row-index 等)。
+ * Internal helper, not exported.
+ */
+function sanitizeGhostClone(el: HTMLElement, width: number): void {
+  el.style.position = 'static'
+  el.style.transform = 'none'
+  el.style.transition = 'none'
+  el.style.opacity = '1'
+  el.style.zIndex = ''
+  el.style.width = `${width}px`
+  el.removeAttribute('data-row-index')
+  el.removeAttribute('aria-rowindex')
+  el.removeAttribute('data-hovered')
+  el.querySelectorAll('[data-drag-handle-portal]').forEach((n) => n.remove())
+}
+
+// ── Type exports for consumer ─────────────────────────────────────────────
+
+export type DropPosition = 'before' | 'after' | 'inside'

package/src/lib/i18n/README.md

@@ -0,0 +1,60 @@
+# DS i18n(Route B infrastructure)
+
+**Status**: shipped 2026-04-24(additive,backward compatible)
+
+## 什麼
+
+可選的 context-based i18n layer — consumer 在 app root 包 `<I18nProvider labels={...}>` 一次,DS 元件內部 opt-in 用 `useI18n()` hook 讀 labels。沒包 provider 完全不影響既有 prop-based 行為。
+
+## 為什麼(vs Route A prop-only)
+
+Route A(2026-04-24 原 ship)每元件暴露 `dismissAriaLabel` / `closeAriaLabel` 等個別 prop。Consumer 要全 app 多語 → 每 call site 傳 prop = 重複 noise。
+
+Route B provider 一次注入 label catalog,per-call-site override 仍可(prop > context > default fallback chain)。
+
+## Usage
+
+```tsx
+// Consumer app root
+import { I18nProvider } from '@/design-system/lib/i18n/i18n-context'
+
+const enLabels = {
+  notice: { dismiss: 'Dismiss' },
+  'file-viewer': { close: 'Close viewer', download: 'Download' },
+  carousel: { previous: 'Previous slide', next: 'Next slide' },
+  // ... consumer 覆寫需要的項
+}
+
+<I18nProvider labels={enLabels}>
+  <App />
+</I18nProvider>
+```
+
+DS 元件內部(逐步 migration):
+
+```tsx
+import { useI18n } from '@/design-system/lib/i18n/i18n-context'
+
+const { t } = useI18n()
+<Button aria-label={propLabel ?? t('notice', 'dismiss', '關閉通知')} />
+```
+
+## Fallback chain
+
+1. **Consumer prop**(call-site,最優先)
+2. **Context labels**(`labels[componentKey][labelKey]`)
+3. **DS default**(fallback 參數,i18n-allow 的 CJK)
+
+## Migration status
+
+- **infrastructure**:✅ shipped(`i18n-context.tsx`)
+- **元件逐步 adopt**:Notice / FileViewer labels object / etc 已 Route A prop-based;Route B 可並存,未來有需要再逐元件 opt-in 換成 context reader
+
+## 世界級對照
+
+- **Material MUI**:`createTheme({ locale })` — monolithic locale
+- **Ant Design**:`<ConfigProvider locale={zhCN}>` — context inject locale
+- **Carbon**:`<PrefixContext>` + locale 分離 — modular
+- **Radix Primitives**:無 i18n layer,留給 consumer
+
+本 DS 選「additive optional context」對齊 Ant / Carbon 彈性路徑:consumer 想要時包一次,不想要保持 prop API。

package/src/lib/i18n/i18n-context.tsx

@@ -0,0 +1,129 @@
+import * as React from 'react'
+
+/**
+ * DS i18n Route B — additive I18nProvider + useI18n hook
+ *
+ * ── 背景 ──
+ * Route A(2026-04-24 shipped)= individual prop override(Notice dismissAriaLabel /
+ * FileViewer labels / etc)+ `// i18n-allow` marker。
+ *
+ * Route B(本 module)= opt-in context provider,consumer 傳 labels catalog 一次性
+ * 注入全 DS,個別 prop 不需每個 call site 傳。**完全 backward compatible** — 沒
+ * 包 provider 不影響既有 prop-based 行為。
+ *
+ * ── Fallback chain(每個 label resolution)──
+ *   1. Consumer 傳的 prop(e.g. `<Notice dismissAriaLabel="X" />`)
+ *   2. Context labels(useI18n().t('notice', 'dismiss', default))
+ *   3. DS default(CJK `i18n-allow` rationale)
+ *
+ * ── Usage ──
+ *
+ * ```tsx
+ * // Consumer app root
+ * import { I18nProvider } from '@/design-system/lib/i18n/i18n-context'
+ *
+ * const labels = {
+ *   notice: { dismiss: 'Dismiss' },
+ *   fileViewer: { close: 'Close viewer', download: 'Download' },
+ *   // ... 覆寫需要的項
+ * }
+ *
+ * <I18nProvider labels={labels}>
+ *   <App />
+ * </I18nProvider>
+ * ```
+ *
+ * ```tsx
+ * // DS component internal(opt-in migration)
+ * import { useI18n } from '@/design-system/lib/i18n/i18n-context'
+ *
+ * const { t } = useI18n()
+ * <button aria-label={props.dismissAriaLabel ?? t('notice', 'dismiss', '關閉通知')}>
+ * ```
+ *
+ * ── 為什麼 opt-in(不強制)──
+ * DS 目前大半 component 都走 prop override,強制 all-or-nothing migration 需要
+ * 17 files × multi-location refactor 的協調成本。Route B 讓既有 prop API 繼續
+ * 工作,同時開放 context-based i18n 給想統一管理的 consumer。
+ *
+ * ── 為什麼 hierarchical key(component, label)而非 flat key ──
+ * Flat key(e.g. 'notice.dismiss')需要命名 convention + grep-based validation;
+ * hierarchical object 天然分 namespace + TypeScript 可做 discriminated union。
+ */
+
+/**
+ * Labels catalog 結構:`{ [componentKey]: { [labelKey]: translatedString } }`
+ *
+ * Consumer 可透過 module augmentation 擴充 type safety:
+ *
+ * ```ts
+ * declare module '@/design-system/lib/i18n/i18n-context' {
+ *   interface I18nLabels {
+ *     notice?: { dismiss?: string }
+ *     fileViewer?: { close?: string; download?: string }
+ *   }
+ * }
+ * ```
+ */
+// code-quality-allow: dead-export — public API surface — consumer-exposed for future use
+export interface I18nLabels {
+  [componentKey: string]: Record<string, string | undefined> | undefined
+}
+
+const I18nContext = React.createContext<I18nLabels | null>(null)
+
+export interface I18nProviderProps {
+  /** Labels catalog。空 object OK(代表用 all defaults)。Partial 覆寫 OK(只填需要翻的)。 */
+  labels: I18nLabels
+  children: React.ReactNode
+}
+
+/**
+ * I18nProvider — consumer-optional wrapper 注入 labels catalog。
+ *
+ * 沒包 → `useI18n().t()` 每次返 fallback(= DS CJK defaults)。
+ * 包 → 該 labels 取代對應 DS defaults;未填的 key 仍 fallback。
+ */
+// code-quality-allow: dead-export — public API surface — consumer-exposed for future use
+export function I18nProvider({ labels, children }: I18nProviderProps) {
+  // Memoize context value to avoid triggering consumer re-renders when parent re-renders
+  const value = React.useMemo(() => labels, [labels])
+  return <I18nContext.Provider value={value}>{children}</I18nContext.Provider>
+}
+
+// code-quality-allow: dead-export — public API surface — consumer-exposed for future use
+export interface I18nHookResult {
+  /**
+   * Translate:return labels[componentKey]?.[labelKey] ?? fallback。
+   *
+   * @param componentKey - 元件 namespace(kebab-case,e.g. 'notice' / 'file-viewer')
+   * @param labelKey - 該元件內的 label 名(camelCase,e.g. 'dismiss' / 'close')
+   * @param fallback - DS default(無 context / no key 時用)
+   */
+  t: (componentKey: string, labelKey: string, fallback: string) => string
+  /** 當前 labels catalog(null = 無 provider)。Debug / advanced use */
+  labels: I18nLabels | null
+}
+
+/**
+ * useI18n — DS 元件內消費 labels catalog。
+ *
+ * **Fallback chain**(每 label resolution):
+ *   1. Consumer 傳的 prop(call site 最優先)
+ *   2. Context `labels[componentKey][labelKey]`
+ *   3. DS default(fallback 參數,i18n-allow 的 CJK)
+ *
+ * 無 I18nProvider 環境:`labels` = null,`t()` 每次直接返 fallback。**不拋 error**
+ *(跟 Field context 等 DS 其他 optional context 同 pattern)。
+ */
+// code-quality-allow: dead-export — public API surface — consumer-exposed for future use
+export function useI18n(): I18nHookResult {
+  const labels = React.useContext(I18nContext)
+  const t = React.useCallback<I18nHookResult['t']>(
+    (componentKey, labelKey, fallback) => {
+      return labels?.[componentKey]?.[labelKey] ?? fallback
+    },
+    [labels],
+  )
+  return { t, labels }
+}

package/src/lib/multi-select-ordering.ts

@@ -0,0 +1,61 @@
+/**
+ * multi-select-ordering — SSOT primitive for "Select All" / bulk-select value ordering
+ *
+ * **Canonical**:Path A(preserve existing user click order + append unselected options
+ * in source/canonical order,with dedup)。
+ *
+ * **Source basis(Layer A + Codex M31 Round 4 共識,2026-05-16 user verbatim approve「就照
+ * 你們的共識做到完美確保有 SSOT」)**:
+ *
+ * Ant Design 跨元件「Select All」 bulk-select canonical 證據:
+ * - **Transfer**(`components/transfer/index.tsx`): `Array.from(new Set([...prevKeys, ...keys]))`
+ *   — preserve previous selection order + append new bulk keys with dedup
+ * - **Table rowSelection selectAll**(`components/table/hooks/useSelection.tsx`): existing keySet
+ *   + flattened source-order append via `Array.from(keySet)`
+ * - **Checkbox.Group**(`components/checkbox/Group.tsx`): 強制 sort source order(更嚴格 B 變體,
+ *   但只用於 onChange callback,非 bulk-select 動作)
+ *
+ * **PeoplePicker / SelectMenu「全部」 footer 場景對應**:
+ * - 動作語意 = Transfer / Table rowSelection 的「Select All」(bulk 選 remaining items)
+ * - 跟 Checkbox.Group 不同(後者沒 Select All button,只是 onChange 回 sort)
+ * - **採 path A**(preserve+append)為 ordering canonical
+ *
+ * **為何 SSOT(per user「以後遇到此類設計都有相同邏輯不會偏移」)**:
+ * 1. 集中 ordering logic 一處,future 改 ordering policy 只改本檔
+ * 2. Future consumers(e.g. DataTable filter checkAll / 任何新 multi-select 元件 with Select All
+ *    footer)必 import 本 primitive,hook `check_select_all_canonical.sh` 機械強制
+ * 3. 對齊 mindset #2「優先消費既有」+ M17「SSOT 必可傳播」+ M23「DS internal canonical 優先」
+ *
+ * **世界級對照**:Ant Transfer + Table rowSelection canonical(2026-05-16 Round 4 grep verify)。
+ * 非「跟世界級對齊」一句空話 — 直接 codify Ant 兩個 bulk-select 元件的 implementation 行為。
+ */
+
+/**
+ * Apply "Select All" canonical:preserve existing selection order + append unselected options
+ * in source order(with dedup)。
+ *
+ * @param existing — 既有 selection array(user click 累積順序)
+ * @param all — 所有可選 options 值 array(source / canonical order — 通常 = `options.filter(!disabled).map(v)`)
+ * @returns 新 selection array,既有部分維持原順序在前,新加入部分按 source order append 在後
+ *
+ * @example
+ * ```ts
+ * applySelectAll(['c', 'a'], ['a', 'b', 'c', 'd'])  // => ['c', 'a', 'b', 'd']
+ * applySelectAll([], ['a', 'b', 'c'])               // => ['a', 'b', 'c']
+ * applySelectAll(['a', 'b', 'c'], ['a', 'b', 'c'])  // => ['a', 'b', 'c']
+ * ```
+ */
+export function applySelectAll<T>(existing: readonly T[], all: readonly T[]): T[] {
+  const existingSet = new Set(existing)
+  const unselected = all.filter((v) => !existingSet.has(v))
+  return [...existing, ...unselected]
+}
+
+/**
+ * Companion:clear all selection。
+ * Trivial wrapper for symmetry(consumer 用 `applySelectAll` ↔ `clearSelection` pair 達成
+ * 「全選 → 取消全選」 toggle canonical)。
+ */
+export function clearSelection<T>(): T[] {
+  return []
+}

package/src/lib/utils.ts

@@ -0,0 +1,93 @@
+import { clsx, type ClassValue } from 'clsx'
+import { extendTailwindMerge } from 'tailwind-merge'
+
+/**
+ * 擴充 tailwind-merge,讓它認識設計系統的自訂 typography 與 text-color utilities。
+ *
+ * 預設 tailwind-merge 看到 `text-{xxx}` 自訂 class 會用 heuristic 猜它是 font-size
+ * 還是 color——猜錯就會把不該放在同一組的 class 誤判為衝突,然後 strip 掉其中一個。
+ *
+ * 實際發生過的 bug:`text-body`(font-size 14px)和 `text-fg-secondary`(color)
+ * 被同時放進 font-size group,tailwind-merge 把 `text-body` 吃掉,導致元件
+ * inherit 父層 16px,description 永遠跟 label 同字級。
+ *
+ * 修法:**font-size group 和 text-color group 都明確列舉**,不留猜測空間。
+ */
+const twMerge = extendTailwindMerge({
+  extend: {
+    classGroups: {
+      'font-size': [
+        'text-h1', 'text-h2', 'text-h3', 'text-h4', 'text-h5', 'text-h6',
+        'text-body-lg', 'text-body', 'text-caption', 'text-footnote',
+      ],
+      // 自訂 text-color utilities(對應 semantic.css 的 `@theme inline --color-*` bridge)。
+      //
+      // 任何新增的 text-{semantic-name} color utility 都必須在這裡登記,否則
+      // tailwind-merge 會誤判成 font-size 與 typography 衝突(歷史 bug:
+      // text-body + text-fg-secondary 被 strip)。
+      //
+      // 完整家族對齊 semantic.css: 5 狀態色(primary/error/success/warning/info)
+      // × 3 互動階(base/hover/active)+ text(on-subtle-bg)+ subtle(含 primary)
+      // + notification(紅 badge)+ neutral foreground 四階。
+      'text-color': [
+        // Neutral foreground 家族
+        'text-foreground',
+        'text-fg-secondary',
+        'text-fg-muted',
+        'text-fg-disabled',
+        'text-inverse-fg',
+        'text-on-emphasis',  // 白字於飽和色底(Avatar color variants / Steps filled indicator)
+
+        // Status 基色(base)
+        'text-primary',
+        'text-error',
+        'text-success',
+        'text-warning',
+        'text-info',
+        'text-notification',
+
+        // Status 互動階(hover / active)
+        'text-primary-hover',
+        'text-primary-active',
+        'text-error-hover',
+        'text-error-active',
+        'text-success-hover',
+        'text-success-active',
+        'text-warning-hover',
+        'text-warning-active',
+        'text-info-hover',
+        'text-info-active',
+
+        // on-subtle-bg 版本(深色文字配淺色底)
+        'text-primary-text',
+        'text-error-text',
+        'text-success-text',
+        'text-warning-text',
+        'text-info-text',
+
+        // Subtle 文字(少用,保持完整家族一致)
+        'text-primary-subtle',
+        'text-error-subtle',
+        'text-success-subtle',
+        'text-warning-subtle',
+        'text-info-subtle',
+      ],
+      // Custom opacity utility(對應 tokens/opacity/opacity.css `@utility opacity-disabled`)。
+      // 不註冊 group → tailwind-merge 用 default opacity-N heuristic,可能誤判 class 衝突。
+      'opacity': ['opacity-disabled'],
+    },
+  },
+})
+
+/**
+ * cn() — Tailwind class 合併工具
+ *
+ * 用法：
+ *   cn("px-4 py-2", isActive && "bg-primary", className)
+ *
+ * 原理：clsx 處理條件式 class，twMerge 解決 Tailwind class 衝突
+ * 例如 cn("px-4", "px-2") → "px-2"（後者優先）
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}