@qijenchen/design-system 0.1.0-beta.3

package/src/hooks/use-controllable.ts

@@ -0,0 +1,40 @@
+import { useCallback, useRef, useState } from 'react'
+
+/**
+ * Controlled / Uncontrolled dual-mode state hook。
+ *
+ * 對齊 Radix `useControllableState` 慣例:
+ * - 提供 `value` → controlled,setter 純 callback,內部不存 state
+ * - 不提供 `value`(or undefined)→ uncontrolled,內部 state + callback 同步
+ *
+ * 使用情境:Field / Switch / Checkbox / DataTable selection / DropdownMenu open 等
+ * 雙模式 prop。
+ */
+export function useControllable<T>({
+  value,
+  defaultValue,
+  onChange,
+}: {
+  value?: T
+  defaultValue: T
+  onChange?: (next: T) => void
+}): [T, (next: T | ((prev: T) => T)) => void] {
+  const isControlled = value !== undefined
+  const [internal, setInternal] = useState<T>(defaultValue)
+  const onChangeRef = useRef(onChange)
+  onChangeRef.current = onChange
+
+  const current = isControlled ? (value as T) : internal
+
+  const setValue = useCallback(
+    (next: T | ((prev: T) => T)) => {
+      const computed =
+        typeof next === 'function' ? (next as (prev: T) => T)(current) : next
+      if (!isControlled) setInternal(computed)
+      onChangeRef.current?.(computed)
+    },
+    [isControlled, current]
+  )
+
+  return [current, setValue]
+}

package/src/hooks/use-is-narrow-viewport.ts

@@ -0,0 +1,19 @@
+import * as React from "react"
+
+const MOBILE_BREAKPOINT = 768
+
+export function useIsNarrowViewport() {
+  const [isNarrow, setIsNarrow] = React.useState<boolean | undefined>(undefined)
+
+  React.useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
+    const onChange = () => {
+      setIsNarrow(window.innerWidth < MOBILE_BREAKPOINT)
+    }
+    mql.addEventListener("change", onChange)
+    setIsNarrow(window.innerWidth < MOBILE_BREAKPOINT)
+    return () => mql.removeEventListener("change", onChange)
+  }, [])
+
+  return !!isNarrow
+}

package/src/hooks/use-is-touch-device.ts

@@ -0,0 +1,21 @@
+import { useState, useEffect } from 'react'
+
+/**
+ * useIsMobile — 偵測觸控裝置（mobile / tablet）
+ *
+ * 使用 `pointer: coarse` media query，正確區分觸控 vs 精確指標裝置。
+ * 用途：Select 等元件在 mobile 退回原生 picker。
+ */
+export function useIsTouchDevice() {
+  const [isMobile, setIsMobile] = useState(false)
+
+  useEffect(() => {
+    const mq = window.matchMedia('(pointer: coarse)')
+    setIsMobile(mq.matches)
+    const handler = (e: MediaQueryListEvent) => setIsMobile(e.matches)
+    mq.addEventListener('change', handler)
+    return () => mq.removeEventListener('change', handler)
+  }, [])
+
+  return isMobile
+}

package/src/hooks/use-overflow-items.ts

@@ -0,0 +1,256 @@
+import * as React from 'react'
+
+/**
+ * 水平溢出追蹤 hooks — 給 Tabs / ChipGroup 等「一排水平 items 塞不下父容器」的元件共用。
+ *
+ * ── 設計原則 ──
+ *   Scroll 模式與 Menu 模式是兩種處理策略：
+ *
+ *   1. **Scroll 模式**（Material / Polaris / Primer / iOS 作法）
+ *      items 用原生 overflow-x-auto 水平滾動，邊緣 fade mask 指示還有內容。
+ *      使用 `useScrollEdges()`：回傳 atStart / atEnd / canScroll，讓消費端
+ *      決定 mask-image / scroll arrow 的顯示。
+ *
+ *   2. **Menu 模式**（Ant Design / Atlassian 作法）
+ *      塞不下的 items 收進 DropdownMenu。**所有 items 都渲染在 DOM 中**
+ *      （只視覺隱藏溢出的）以保留 Radix 的 roving tabindex / roving focus 等
+ *      a11y 語意。使用 `useOverflowIndices()`：回傳 overflowIndices
+ *      供消費端渲染對應的 menu items（通常是 click proxy，觸發同一個
+ *      onValueChange）。
+ *
+ * ── 為什麼分兩個 hook，不合一 ──
+ *   Scroll 的計算依據是 scroll 事件與 client/scroll width；Menu 的計算依據是
+ *   items 的 offsetLeft/offsetWidth 相對容器 clientWidth。訂閱的事件不同
+ *   （scroll vs resize），回傳的資料形狀不同。合一會讓 API 有一半是 noise。
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// useScrollEdges — 給 scroll 模式
+// ─────────────────────────────────────────────────────────────────────────────
+
+// code-quality-allow: dead-export — hook return type — API surface for consumers who want to annotate
+export interface UseScrollEdgesResult<T extends HTMLElement> {
+  /** 綁在 scroll container 上的 ref */
+  scrollRef: React.RefObject<T>
+  /** scroll 位置在最左側（無法再往左）*/
+  atStart: boolean
+  /** scroll 位置在最右側（無法再往右）*/
+  atEnd: boolean
+  /** 內容總寬度超過可視寬度，有滾動空間 */
+  canScroll: boolean
+}
+
+/**
+ * 追蹤 scroll container 的滾動位置，用來決定左右 fade mask 是否顯示。
+ *
+ * 典型用法：
+ * ```tsx
+ * const { scrollRef, atStart, atEnd, canScroll } = useScrollEdges<HTMLDivElement>()
+ * const maskImage = canScroll
+ *   ? `linear-gradient(to right,
+ *       ${atStart ? 'black' : 'transparent'} 0,
+ *       black 16px,
+ *       black calc(100% - 16px),
+ *       ${atEnd ? 'black' : 'transparent'} 100%)`
+ *   : undefined
+ * return <div ref={scrollRef} className="overflow-x-auto" style={{ maskImage, WebkitMaskImage: maskImage }}>
+ *   {items}
+ * </div>
+ * ```
+ */
+export function useScrollEdges<T extends HTMLElement = HTMLElement>(): UseScrollEdgesResult<T> {
+  const scrollRef = React.useRef<T | null>(null)
+  const [state, setState] = React.useState({ atStart: true, atEnd: true, canScroll: false })
+
+  React.useEffect(() => {
+    const el = scrollRef.current
+    if (!el) return
+
+    const update = () => {
+      const canScroll = el.scrollWidth > el.clientWidth + 1
+      const atStart = el.scrollLeft <= 0
+      const atEnd = el.scrollLeft + el.clientWidth >= el.scrollWidth - 1
+      setState((prev) =>
+        prev.atStart === atStart && prev.atEnd === atEnd && prev.canScroll === canScroll
+          ? prev
+          : { atStart, atEnd, canScroll }
+      )
+    }
+
+    update()
+    el.addEventListener('scroll', update, { passive: true })
+    const ro = new ResizeObserver(update)
+    ro.observe(el)
+    // 監聽 children 變化（items 增減、字體載入）
+    const mo = new MutationObserver(update)
+    mo.observe(el, { childList: true, subtree: true, characterData: true })
+
+    return () => {
+      el.removeEventListener('scroll', update)
+      ro.disconnect()
+      mo.disconnect()
+    }
+  }, [])
+
+  return { scrollRef, ...state }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// useOverflowIndices — 給 menu 模式
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface UseOverflowIndicesOptions {
+  /**
+   * 預留給 overflow trigger（如 "More" 按鈕）的右側寬度（px）。
+   * 計算 items 是否溢出時會從 container clientWidth 扣掉這個值。
+   */
+  reserveTriggerWidth?: number
+}
+
+// code-quality-allow: dead-export — hook return type — API surface for consumers who want to annotate
+export interface UseOverflowIndicesResult<C extends HTMLElement> {
+  /** 綁在 items 的父容器上 */
+  containerRef: React.RefObject<C>
+  /** 為每個 item 註冊 ref（回傳 callback ref）*/
+  registerItem: (index: number) => (el: HTMLElement | null) => void
+  /** DOM 順序上溢出的 item 索引（連續區間，從某個 index 到尾端）*/
+  overflowIndices: number[]
+  /** 至少有一個 item 溢出 */
+  hasOverflow: boolean
+  /** 依 index 取得對應 item 的 DOM 元素，供 scrollIntoView 等操作使用 */
+  getItemAt: (index: number) => HTMLElement | undefined
+}
+
+/**
+ * 追蹤一排水平 items 裡哪些「當前不在可視範圍內」。
+ *
+ * ── 演算法 ──
+ *   對每個 item 檢查 `[offsetLeft, offsetLeft+offsetWidth]` 是否完全落在
+ *   `[scrollLeft, scrollLeft + clientWidth - reserveTriggerWidth]` 範圍內。
+ *   沒完全落在內的就算溢出。
+ *
+ *   **關鍵**：overflow 集合跟 scrollLeft 連動,不是靜態「原始佈局不 fit」集合。
+ *   這是 Ant Design / Atlassian 世界級作法 —— menu 顯示「當下看不到的 items」,
+ *   不是「原始溢出的 items」。
+ *
+ *   為什麼這樣對:
+ *   - 使用者點 menu item → `scrollIntoView` → 原本 overflow 的 item 進入視圖,
+ *     原本可見的 items 被推出去 → 下次開 menu 看到的是「剛被推出去的 items」,
+ *     永遠能找到所有當前看不到的 items,不會卡住。
+ *   - 靜態 overflow (只算原始佈局) 會造成 scroll 後無法回到前面的 items。
+ *
+ * ── 觸發重算 ──
+ *   - ResizeObserver: 容器寬度變化 / item 尺寸變化
+ *   - scroll event: scroll 位置變化
+ *
+ * ── 前提 ──
+ *   items 在 DOM 裡始終存在 (不可 conditional render),並用 `registerItem(i)` 綁 ref。
+ *   容器要可以 scroll (overflow-x-auto 或類似),否則 scrollLeft 永遠 0。
+ *
+ * 典型用法:
+ * ```tsx
+ * const { containerRef, registerItem, overflowIndices, hasOverflow, getItemAt } =
+ *   useOverflowIndices<HTMLDivElement>({ reserveTriggerWidth: 0 })
+ *
+ * const handleMenuSelect = (value: string, index: number) => {
+ *   onValueChange?.(value)
+ *   requestAnimationFrame(() => {
+ *     getItemAt(index)?.scrollIntoView({ behavior: 'smooth', inline: 'center' })
+ *   })
+ * }
+ *
+ * return (
+ *   <div className="flex items-center">
+ *     <div ref={containerRef} className="flex-1 min-w-0 overflow-x-auto">
+ *       <ItemList>
+ *         {items.map((item, i) => React.cloneElement(item, { ref: registerItem(i) }))}
+ *       </ItemList>
+ *     </div>
+ *     {hasOverflow && <OverflowMenu items={overflowIndices.map(i => items[i])} />}
+ *   </div>
+ * )
+ * ```
+ */
+export function useOverflowIndices<C extends HTMLElement = HTMLElement>(
+  options: UseOverflowIndicesOptions = {}
+): UseOverflowIndicesResult<C> {
+  const { reserveTriggerWidth = 0 } = options
+  const containerRef = React.useRef<C | null>(null)
+  const itemRefsMap = React.useRef<Map<number, HTMLElement>>(new Map())
+  const [overflowIndices, setOverflowIndices] = React.useState<number[]>([])
+
+  const registerItem = React.useCallback((index: number) => {
+    return (el: HTMLElement | null) => {
+      if (el) {
+        itemRefsMap.current.set(index, el)
+      } else {
+        itemRefsMap.current.delete(index)
+      }
+    }
+  }, [])
+
+  React.useEffect(() => {
+    const container = containerRef.current
+    if (!container) return
+
+    const compute = () => {
+      const containerWidth = container.clientWidth
+      if (containerWidth === 0) return
+
+      const scrollLeft = container.scrollLeft
+      const visibleStart = scrollLeft
+      const visibleEnd = scrollLeft + containerWidth - reserveTriggerWidth
+
+      // 容許 1px 的像素取整誤差,避免邊界 item 被誤判為 overflow
+      const tolerance = 1
+
+      const indices = Array.from(itemRefsMap.current.keys()).sort((a, b) => a - b)
+
+      const overflow: number[] = []
+      for (const i of indices) {
+        const el = itemRefsMap.current.get(i)
+        if (!el) continue
+
+        const left = el.offsetLeft
+        const right = left + el.offsetWidth
+        // 完全可見條件: item 的左右邊都在可視窗口內
+        const fullyVisible =
+          left >= visibleStart - tolerance && right <= visibleEnd + tolerance
+        if (!fullyVisible) overflow.push(i)
+      }
+
+      setOverflowIndices((prev) => {
+        if (prev.length === overflow.length && prev.every((v, i) => v === overflow[i])) {
+          return prev
+        }
+        return overflow
+      })
+    }
+
+    compute()
+    const ro = new ResizeObserver(compute)
+    ro.observe(container)
+    // 也觀察每個 item 的尺寸變化（字體載入、label 更新等）
+    itemRefsMap.current.forEach((el) => ro.observe(el))
+    // Scroll event: overflow 集合隨 scroll 位置變化
+    container.addEventListener('scroll', compute, { passive: true })
+
+    return () => {
+      ro.disconnect()
+      container.removeEventListener('scroll', compute)
+    }
+  }, [reserveTriggerWidth])
+
+  const getItemAt = React.useCallback(
+    (index: number) => itemRefsMap.current.get(index),
+    []
+  )
+
+  return {
+    containerRef,
+    registerItem,
+    overflowIndices,
+    hasOverflow: overflowIndices.length > 0,
+    getItemAt,
+  }
+}

package/src/index.ts

@@ -0,0 +1,85 @@
+// 2026-05-22 Phase 1 team-distribution-roadmap:barrel auto-generated by scripts/gen-design-system-barrel.mjs
+// Re-export 主元件 / patterns / hooks / lib(consumers can also use subpath imports per package.json exports map)
+
+// ─── Components ───────────────────────────────────────────────────────────
+export * from './components/Accordion/accordion'
+export * from './components/Alert/alert'
+export * from './components/AppShell/app-shell'
+export * from './components/AspectRatio/aspect-ratio'
+export * from './components/Avatar/avatar'
+export * from './components/Badge/badge'
+export * from './components/Breadcrumb/breadcrumb'
+export * from './components/BulkActionBar/bulk-action-bar'
+export * from './components/Button/button'
+export * from './components/Calendar/calendar'
+export * from './components/Carousel/carousel'
+export * from './components/Chart/chart'
+export * from './components/Checkbox/checkbox'
+export * from './components/Chip/chip'
+export * from './components/CircularProgress/circular-progress'
+export * from './components/Coachmark/coachmark'
+// Combobox re-exports SelectOption(也在 Select 出口)→ 改 type-explicit re-export 避 collision(2026-05-22)
+export { Combobox } from './components/Combobox/combobox'
+export type { ComboboxProps } from './components/Combobox/combobox'
+export * from './components/Command/command'
+export * from './components/DataTable/data-table'
+export * from './components/DateGrid/date-grid'
+export * from './components/DatePicker/date-picker'
+export * from './components/DescriptionList/description-list'
+export * from './components/Dialog/dialog'
+export * from './components/DropdownMenu/dropdown-menu'
+export * from './components/Empty/empty'
+export * from './components/Field/field'
+export * from './components/FieldControlGroup/field-control-group'
+export * from './components/FileItem/file-item'
+export * from './components/FileUpload/file-upload'
+export * from './components/FileViewer/file-viewer'
+export * from './components/HoverCard/hover-card'
+export * from './components/Input/input'
+export * from './components/LinkInput/link-input'
+export * from './components/Menu/menu-item'
+export * from './components/NameCard/name-card'
+export * from './components/Notice/notice'
+export * from './components/NumberInput/number-input'
+export * from './components/OverflowIndicator/overflow-indicator'
+export * from './components/PeoplePicker/people-picker'
+export * from './components/Popover/popover'
+export * from './components/ProgressBar/progress-bar'
+export * from './components/RadioGroup/radio-group'
+export * from './components/Rating/rating'
+export * from './components/ScrollArea/scroll-area'
+export * from './components/SegmentedControl/segmented-control'
+export * from './components/Select/select'
+export * from './components/SelectMenu/select-menu'
+export * from './components/SelectionControl/selection-item'
+export * from './components/Separator/separator'
+export * from './components/Sheet/sheet'
+export * from './components/Sidebar/sidebar'
+export * from './components/Skeleton/skeleton'
+export * from './components/Slider/slider'
+export * from './components/Steps/steps'
+export * from './components/Switch/switch'
+export * from './components/Tabs/tabs'
+export * from './components/Tag/tag'
+export * from './components/Textarea/textarea'
+export * from './components/TimePicker/time-picker'
+export * from './components/Toast/toast'
+export * from './components/Tooltip/tooltip'
+// TreeView re-exports DropPosition(也在 dnd primitives)→ 改 type-explicit(2026-05-22)
+export { TreeView, TreeItem } from './components/TreeView/tree-view'
+export type { TreeViewProps, TreeItemProps, TreeDragEndEvent } from './components/TreeView/tree-view'
+
+// ─── Patterns ─────────────────────────────────────────────────────────────
+export * from './patterns/horizontal-overflow/horizontal-overflow'
+export * from './patterns/overlay-surface/overlay-surface'
+export * from './patterns/resize-handle/resize-handle'
+
+// ─── Hooks ────────────────────────────────────────────────────────────────
+export * from './hooks/use-controllable'
+export * from './hooks/use-is-narrow-viewport'
+export * from './hooks/use-is-touch-device'
+export * from './hooks/use-overflow-items'
+
+// ─── Lib utilities ────────────────────────────────────────────────────────
+export * from './lib/drag-visual'
+export * from './lib/multi-select-ordering'

package/src/lib/README.md

@@ -0,0 +1,82 @@
+# lib/ Charter
+
+## 這裡只收:cross-cutting non-visual utility module
+
+每個 lib 子模組提供**跨元件共用、無 visual surface 的 infrastructure / utility**:
+
+- React Context Provider + hook(non-visual cross-cutting feature)
+- 純運算 / 格式化 helper(date / number / a11y string)
+- TypeScript type module(無 runtime,共用 type-only export)
+- 第三方 library 的 thin wrapper(對齊 DS API 風格)
+
+**核心特徵**:沒有 visual surface(不 render UI),但 ≥ 2 個 DS 元件 import 它使用。
+
+---
+
+## 跟 hooks/ / patterns/ / components/ 分權
+
+| Home | 收什麼 | 反例(錯誤 home)|
+|------|-------|----------------|
+| `lib/{topic}/` | cross-cutting feature module(Provider + hook + types 集合)| 純 hook 一個檔案 → 應 `hooks/use-*.ts` |
+| `hooks/use-*.ts` | 單純 stateless hook(無 Context / 無 Provider)| 帶 Provider → `lib/{topic}/` |
+| `patterns/{topic}/` | runtime visual primitive(`<Item>` / `<ActionBar>` 等渲染 UI)| 沒 visual surface → `lib/` |
+| `components/{Name}/` | user-facing 元件(public API)| internal cross-cutting → `lib/` |
+
+**判斷 flow**:
+
+```
+有 visual surface(render UI 元素)?
+├─ Yes → 是 user-facing? → components/ : patterns/
+└─ No → 是純 stateless hook 一支?
+        ├─ Yes → hooks/use-*.ts
+        └─ No(Provider + hook + types 一組,或 utility module)→ lib/{topic}/
+```
+
+---
+
+## 當前居民
+
+| Module | 提供什麼 | Consumer | 世界級對齊 |
+|--------|---------|----------|-----------|
+| `i18n/` | `<I18nProvider>` + `useI18n()` hook + `I18nLabels` types(opt-in context-based label catalog,additive 與 prop API 並存)| 全 DS 元件 opt-in consumer | Material `@mui/material/locale` / Ant `<ConfigProvider locale>` / Carbon `<PrefixContext>` 共識:i18n 是 utility/locale module 非 visual pattern |
+
+---
+
+## 命名鐵律
+
+- 子目錄名 kebab-case(對齊 components/ / patterns/)
+- 入口 module 名描述功能(`i18n-context.tsx` / `formatters.ts`),非 generic 名(`utils.ts` / `helpers.ts` 違反 — 後者該歸到 `src/lib/utils.ts` 專案級)
+- 違反 → audit Dim 19 home-name-vs-scope 抓
+
+---
+
+## 這裡**不收**(反例 + 正確去處)
+
+| 疑似要放這但其實不是 | 實際應去 | 為什麼 |
+|-------------------|---------|--------|
+| 「`cn()` Tailwind 合併」工具 | `src/lib/utils.ts` | shadcn 慣例 home,專案級非 DS 內部 |
+| 「`useControllable` 雙模式 hook」 | `packages/design-system/src/hooks/use-controllable.ts` | 純 stateless hook,無 Context |
+| 「Toast 行為 primitive(渲染 UI)」 | `packages/design-system/src/patterns/{name}/` | 有 visual surface |
+| 「formik / react-hook-form 整合」 | 不在 DS scope | DS 不耦合 form library;consumer 自己 wire |
+
+---
+
+## 新增 lib module 的 criteria(必須全部通過)
+
+1. **無 visual surface**(不 render UI 元素;Context Provider 例外因 wrap children)
+2. **≥ 2 個 DS 元件消費**(spec / README 必列 consumers)
+3. **≥ 3 家世界級對照**(MUI / Polaris / Ant / Carbon / Material 任一以上)
+4. **不適合 hooks/**(超過單一 stateless hook,有 Provider / types / multi-file 結構)
+
+---
+
+## 為什麼新建這個 home(2026-05-01)
+
+i18n-context 原放 `patterns/i18n/`,但 patterns/ 定義是「runtime visual primitive」,i18n 無 visual surface(只是 Context + hook + types)→ home-name-vs-scope 不符(audit Dim 19 抓到)。
+
+世界級三家共識:**i18n 是 utility / locale module,不是 visual pattern**:
+- Material `@mui/material/locale` 是 utility sub-package
+- Ant `<ConfigProvider locale>` 是 provider config 非 visual element
+- Carbon `<PrefixContext>` 是 DI module 非 visual primitive
+
+新建 `lib/` 為這類 cross-cutting non-visual primitive 留 home,patterns/ 純化只收 visual primitive。