@qijenchen/design-system 0.1.0-beta.80 → 0.1.0-beta.82

package/src/components/TimePicker/time-picker.spec.md

@@ -31,7 +31,7 @@ TimePicker 是**單一時間**(時/分/秒)輸入與顯示元件,對齊 Ant Desi
 
 ## Controlled-only rationale(Dim 26)
 
-本元件刻意採 **controlled-only** 模式:`value` + `onChange` 必傳,不支援 `defaultValue` uncontrolled fallback。
+本元件刻意採 **controlled-only** 模式:`value` + `onChange` 成對傳入(型別宣告 optional、無 runtime 強制,對齊 DatePicker / SelectMenu 同慣例),不支援 `defaultValue` uncontrolled fallback。
 
 **為什麼**:
 - 內部狀態(panel `open` + 暫存 `draft` 值)若要跟外部 `value` 雙向 sync 會產生 race condition
@@ -249,7 +249,7 @@ TimePicker 視覺分兩層,各自繼承不同 SSOT:
 
 trigger 的互動狀態(focus / invalid / disabled / readonly)完全繼承 `../Field/field-controls.spec.md` SSOT「Mode 狀態」;panel 內 column item 的 hover / selected / disabled 走 `patterns/element-anatomy/item-anatomy.spec.md`「選擇 / 狀態視覺規則」。TimePicker 層級無自有 state 行為,panel 開 / 關由 Popover primitive 處理。重寫 StateBehavior = 與兩個 SSOT 同時漂移。
 
-對應 anatomy story:保留 `Overview` + `Inspector` + `ColorMatrix`(兩層整合展示) + `SizeMatrix` + 元件特有 `ModeMatrix` / `PrecisionMatrix`。Field-level state 見 Input `StateBehavior` + field-controls.spec.md;panel item-level state 見 SelectMenu / MenuItem 的對應 story。
+對應 anatomy story:保留 `Overview` + `Inspector` + `ColorMatrix`(兩層整合展示) + `SizeMatrix` + `Accessibility` + 元件特有 `ModeMatrix` / `PrecisionMatrix`。Field-level state 見 Input `StateBehavior` + field-controls.spec.md;panel item-level state 見 SelectMenu / MenuItem 的對應 story。
 
 ---
 

package/src/components/TimePicker/time-picker.tsx

@@ -63,6 +63,21 @@ export interface TimeFormatOptions {
   locale?: string
 }
 
+// 2026-07-06 D3 perf:Intl.DateTimeFormat 是標準庫最貴 constructor 之一(locale data
+// resolution)。formatTime 無 cheap path,display/readonly/edit 每 render 必建;DataTable time 欄
+// 轉發 config 時每 cell × 每次表格 re-render 重建。module-level cache 重用實例(DateTimeFormat
+// 無狀態可安全重用),key = locale|JSON.stringify(options)。行為 Δ=0。
+const dtfCache = new Map<string, Intl.DateTimeFormat>()
+function getDateTimeFormatter(locale: string, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat {
+  const key = locale + '|' + JSON.stringify(options)
+  let fmt = dtfCache.get(key)
+  if (!fmt) {
+    fmt = new Intl.DateTimeFormat(locale, options)
+    dtfCache.set(key, fmt)
+  }
+  return fmt
+}
+
 function formatTime(
   iso: string,
   options: TimeFormatOptions = {},
@@ -76,7 +91,7 @@ function formatTime(
   // 借用 Date 讓 Intl.DateTimeFormat 處理 locale / 12h-24h
   const d = new Date()
   d.setHours(parts.hours, parts.minutes, parts.seconds, 0)
-  return new Intl.DateTimeFormat(locale, formatOptions).format(d)
+  return getDateTimeFormatter(locale, formatOptions).format(d)
 }
 
 // ── Disabled time callback ──────────────────────────────────────────────────
@@ -218,15 +233,20 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
 
     const handleNow = () => {
       const now = new Date()
-      // 按照 minuteStep / secondStep 對齊
-      const m = Math.round(now.getMinutes() / minuteStep) * minuteStep
-      const s = showSeconds
-        ? Math.round(now.getSeconds() / secondStep) * secondStep
-        : 0
+      // 按照 minuteStep / secondStep 對齊。
+      // 2026-07-05 邊界修正(deep-audit A.1b):Math.round 進位到 60 時,舊 `Math.min(round, 59)`
+      // 會產生 59 這種「不對齊 step、也不在 column values 內」的值(如 53 分 @ step=15 → 59)
+      // → panel 該欄失去 selected 高亮。改 clamp 到 ≤59 的最大 step 對齊值(= buildRange 產出的
+      // 最後一格,如 45),不跨小時進位 — 保持「此刻 = commit 當前時間(step 對齊)」語意
+      // (time-picker.spec.md「每次欄位選取當下即 commit」段)。
+      const alignToStep = (raw: number, step: number) => {
+        const rounded = Math.round(raw / step) * step
+        return rounded > 59 ? Math.floor(59 / step) * step : rounded
+      }
       const next: TimeParts = {
         hours: now.getHours(),
-        minutes: Math.min(m, 59),
-        seconds: Math.min(s, 59),
+        minutes: alignToStep(now.getMinutes(), minuteStep),
+        seconds: showSeconds ? alignToStep(now.getSeconds(), secondStep) : 0,
       }
       commitDraft(next)
       setOpen(false)
@@ -307,7 +327,7 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
             (@radix-ui/react-popover index.js:145),不 inject 任何 onKeyDown。原生 <button>
             靠瀏覽器在 Enter/Space 自動派發 click 才能開;但本 trigger 是 <div role=combobox>,
             div 不會自動派發 click → 鍵盤使用者打不開 panel。故顯式加 onKeyDown
-            (對齊 select.tsx:593-598 既有 canonical + WAI-ARIA APG combobox required keys)。 */}
+            (對齊 select.tsx:609-619 既有 canonical + WAI-ARIA APG combobox required keys)。 */}
         <PopoverTrigger asChild>
           <div
             ref={ref}
@@ -335,13 +355,9 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
             data-field-mode="edit"
             data-error={error ? '' : undefined}
             className={cn(
-              fieldWrapperStyles({ mode: 'edit', variant: variant, size }),
+              fieldWrapperStyles({ mode: 'edit', variant: variant, size, error }),
               'text-left cursor-pointer',
               'focus-visible:outline-none',
-              error && [
-                'border-error hover:border-error-hover',
-                'focus-within:border-error focus-within:hover:border-error',
-              ],
               className,
             )}
             {...props}
@@ -426,9 +442,12 @@ export const timePickerMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // states 對齊真實視覺態:trigger 與 panel item 皆無 'active'(按下)專屬視覺態(2026-07-04 audit 對齊);
+  // 'selected' = panel item 持續選中(bg-neutral-selected,time-columns.tsx isSelected;2026-07-07 詞彙統一補列)。
+  states: ['default', 'hover', 'selected', 'focus-visible', 'disabled'],
   tokens: {
-    bg: ['bg-neutral-hover', 'bg-primary', 'bg-transparent'],
+    // panel selected 走 bg-neutral-selected(time-columns.tsx isSelected;spec「欄內 item 狀態」),非 bg-primary。
+    bg: ['bg-neutral-hover', 'bg-neutral-selected', 'bg-transparent'],
     fg: ['text-fg-disabled', 'text-fg-muted', 'text-foreground'],
     ring: [],
   },

package/src/components/Toast/toast.anatomy.stories.tsx

@@ -51,7 +51,7 @@ export const Overview: Story = {
                 ['title', 'string', '必填', '主要訊息'],
                 ['description', 'string', '—', '補充說明,自然換行'],
                 ['action', '{ label: string; onClick: () => void }', '—', 'tertiary xs 按鈕(Undo pattern)'],
-                ['duration', 'number', '4000', '自動關閉時間(ms)'],
+                ['duration', 'number', 'action ? 10000 : 4000', '自動關閉時間(ms);含 action 預設加長(2026-07-05 D4)'],
               ].map(([p, t, d, desc]) => (
                 <tr key={p}><Td mono>{p}</Td><Td mono>{t}</Td><Td mono>{d}</Td><Td>{desc}</Td></tr>
               ))}
@@ -100,7 +100,7 @@ export const Inspector: Story = {
     description: { control: 'text', description: '補充說明,自然換行' },
     duration: {
       control: { type: 'range', min: 2000, max: 10000, step: 1000 },
-      description: '自動關閉時間(ms),action toast 建議加長至 6000',
+      description: '自動關閉時間(ms);預設 action 存在 → 10000,否則 4000(2026-07-05 D4)',
     },
     withAction: { control: 'boolean', description: '附 undo action button(樂觀 UI 反悔窗口)' },
   },
@@ -171,7 +171,7 @@ export const ColorMatrix: Story = {
   render: () => (
     <div className="flex flex-col gap-6">
       <div>
-        <H3>跟 Alert 共用同一套 variant × theme</H3>
+        <H3>與 Alert 共用 Notice primitive 與三層 theme 架構(variant × theme 映射各自不同)</H3>
         <div className="overflow-x-auto">
           <table className="text-caption border-collapse">
             <thead><tr><Th>Variant</Th><Th>Bg</Th><Th>data-theme</Th><Th>視覺</Th></tr></thead>
@@ -222,7 +222,7 @@ export const StateBehavior: Story = {
             <thead><tr><Th>階段</Th><Th>觸發</Th><Th>行為</Th><Th>Token / 數值</Th></tr></thead>
             <tbody>
               <tr><Td mono>進場</Td><Td mono>toast()</Td><Td>從右下滑入 + fade-in + stacking shift</Td><Td mono>~400ms(sonner 內建)</Td></tr>
-              <tr><Td mono>自動關閉</Td><Td>`duration` 到期</Td><Td>fade-out + 向右滑出</Td><Td mono>duration ?? 4000ms</Td></tr>
+              <tr><Td mono>自動關閉</Td><Td>`duration` 到期</Td><Td>fade-out + 向右滑出</Td><Td mono>duration ?? (action ? 10000 : 4000) ms</Td></tr>
               <tr><Td mono>手動 dismiss</Td><Td>X button / 向右滑動</Td><Td>立即 fade-out + 滑出</Td><Td mono>滑動 ≥ 45px 或速度夠快(velocity {'>'} 0.11)</Td></tr>
               <tr><Td mono>Pause on hover</Td><Td>Hover 任一 toast</Td><Td>倒數暫停;離開後 resume</Td><Td mono>sonner 預設開啟</Td></tr>
             </tbody>
@@ -284,13 +284,12 @@ export const StateBehavior: Story = {
               label: '復原',
               onClick: () => toast({ variant: 'info', title: '已復原' }),
             },
-            duration: 6000,
           })}
         >
           觸發含 Undo action 的 toast
         </Button>
         <p className="text-footnote text-fg-muted mt-3">
-          Action toast 通常 `duration` 加長至 6000ms,給使用者足夠時間反悔(預設 4000ms 較短)。
+          含 action 的 toast DS 預設 `duration` 自動加長至 10000ms(無 action 4000ms;2026-07-05 D4)——給使用者(含鍵盤 Tab 路徑)足夠時間反悔,無需手動指定。
         </p>
       </div>
 

package/src/components/Toast/toast.principles.stories.tsx

@@ -99,7 +99,7 @@ export const UsageGuidance: Story = {
         >
           ❌ 刪除確認用 Toast
         </Button>
-        <Label warn>↑ 破壞性動作靠 Toast action 確認 → 4 秒消失 / 點錯只能救 → 用 Dialog 聚焦確認</Label>
+        <Label warn>↑ 破壞性動作靠 Toast action 確認 → 10 秒後仍消失 / 點錯只能救 → 用 Dialog 聚焦確認</Label>
       </Rule>
     </div>
     <Toaster />
@@ -113,7 +113,7 @@ export const ActionRule: Story = {
     <div>
       <Rule
         title="Toast action — 讓使用者短暫內復原"
-        note="Undo pattern:執行後 toast 出現 + 「復原」按鈕,使用者有一段時間(預設 4 秒)可以反悔。Gmail / Linear / Slack 都用這個 pattern"
+        note="Undo pattern:執行後 toast 出現 + 「復原」按鈕,使用者有一段時間(含 action 預設 10 秒;2026-07-05 D4)可以反悔。Gmail / Linear / Slack 都用這個 pattern"
       >
         <Button
           variant="tertiary"
@@ -126,12 +126,12 @@ export const ActionRule: Story = {
         >
           刪除訊息(帶 Undo)
         </Button>
-        <Label>↑ 點「刪除」不彈 Dialog 直接刪 + Toast,4 秒內可「復原」</Label>
+        <Label>↑ 點「刪除」不彈 Dialog 直接刪 + Toast,10 秒內可「復原」</Label>
       </Rule>
 
       <Rule
         title="Undo 的好處：避免每個動作都 Dialog 阻斷"
-        note="傳統做法每個刪除都彈 Dialog 確認 → 使用者被反覆阻斷。Undo pattern 讓「未確認即執行」變得安全——錯了 4 秒內可救"
+        note="傳統做法每個刪除都彈 Dialog 確認 → 使用者被反覆阻斷。Undo pattern 讓「未確認即執行」變得安全——錯了 10 秒內可救"
       >
         <Label>✅ 減少 Dialog 阻斷、提升速度、錯誤仍可挽救</Label>
       </Rule>
@@ -153,7 +153,7 @@ export const VariantRule: Story = {
     <div>
       <Rule
         title="success / info / warning / error 各自對應場景"
-        note="跟 Alert 共用同一套 variant × theme 策略。語意由事件類型決定——不靠 consumer 用顏色暗示"
+        note="與 Alert 共用 Notice primitive 與三層 theme 架構(variant × theme 映射各自不同,如 success:Toast 反轉 surface / Alert solid 綠底)。語意由事件類型決定——不靠 consumer 用顏色暗示"
       >
         <div className="flex flex-col gap-2">
           <Button variant="tertiary" onClick={() => toast({ variant: 'success', title: '已儲存' })}>success</Button>
@@ -179,8 +179,8 @@ export const DurationRule: Story = {
   render: () => (
     <div>
       <Rule
-        title="預設 4000ms — 足夠讀完一行但不拖累"
-        note="多數場景用預設。使用者有足夠時間讀「已儲存」+ 考慮是否按「復原」。過短 = 來不及看,過長 = 堆積"
+        title="預設 4000ms(無 action)— 足夠讀完一行但不拖累"
+        note="多數場景用預設。使用者有足夠時間讀「已儲存」。過短 = 來不及看,過長 = 堆積"
       >
         <Button variant="tertiary" onClick={() => toast({ variant: 'success', title: '已儲存' })}>
           預設 4000ms
@@ -188,8 +188,8 @@ export const DurationRule: Story = {
       </Rule>
 
       <Rule
-        title="較長（7000-10000ms）— 內容較多或有 action"
-        note="兩行描述 + undo action 需要更多時間。使用者讀完 + 判斷 + 點擊 action"
+        title="有 action → 預設自動加長為 10000ms"
+        note="兩行描述 + undo action 需要更多時間——含鍵盤使用者 Tab 到 action 的路徑(鍵盤焦點不暫停倒數;2026-07-05 D4)。DS 在 action 存在時預設 duration = 10000ms,無需手動指定;內容特多可自行覆寫"
       >
         <Button
           variant="tertiary"
@@ -198,10 +198,9 @@ export const DurationRule: Story = {
             title: '已刪除 3 個項目',
             description: '已移至回收桶,可以在 7 天內復原',
             action: { label: '復原', onClick: () => {} },
-            duration: 7000,
           })}
         >
-          較長 duration(有 description + action)
+          較長 duration(有 description + action,預設 10000ms)
         </Button>
       </Rule>
 

package/src/components/Toast/toast.spec.md

@@ -44,7 +44,7 @@ Toast 是**短暫的浮動通知，自動消失**。用於操作結果回饋（
 
 - **操作結果短暫回饋**：儲存成功、訊息已送出、已複製到剪貼簿、刪除失敗
 - **背景非同步動作完成**：檔案上傳完成、資料同步完成、通知已寄出
-- **需要「復原」按鈕的操作**：刪除後 4 秒內可 Undo（sonner action 模式）
+- **需要「復原」按鈕的操作**：刪除後 10 秒內可 Undo（sonner action 模式；含 `action` 的 toast 預設 `duration` = 10000ms，見「API」段）
 - **非關鍵資訊**：訊息即使使用者沒看到也不影響流程
 
 ## 何時不用
@@ -82,6 +82,7 @@ Toast 是**短暫的浮動通知，自動消失**。用於操作結果回饋（
 - **由本 DS 在 outer wrapper 上設定**：上述 `role` / `aria-live` 是 Toast 自己依 variant 算出 `isCritical` 後手動設在自家 wrapper div 上的（見 `.tsx` L49-51 / L59 / L72），**非** sonner 內建——sonner runtime 本身 0 個 `role`，只有外層 `<section>` 容器固定的 `aria-live="polite"`（包住所有 toast 的 region，不隨 variant 變）。consumer 無需額外處理。
   - 已知結構限制：`error` / `warning` 的 `aria-live="assertive"` div 巢狀在 sonner `<section>` 的 `aria-live="polite"` 內（nested live region）。screen reader 對巢狀 live region 的處理依實作而異;若需嚴格保證 assertive 立即朗讀，consumer 應在 app 層另設獨立 live region。
 - **關閉按鈕**：畫面上可見的 X 關閉鈕由 Notice 渲染（`<Button dismiss aria-label="關閉通知">`，見 `../Notice/notice.tsx`），已自帶 `aria-label`，不是 sonner 內建 close 鈕（本 DS 用 `sonner.custom` + `unstyled`，未開 `closeButton`）。若 consumer 自訂 `action`，務必為自訂互動元素提供 `aria-label`。
+- **自動關閉計時器與鍵盤暫停路徑**（2026-07-05 D4）：sonner 計時器只在滑鼠 hover / pointer 按住 / 分頁切離時暫停——**Tab 鍵盤焦點進入 toast 不暫停倒數**（sonner 2.x 行為，`expanded / interacting` 只由 mouse / pointer 事件設定）。鍵盤替代路徑是 sonner 內建 hotkey **⌥T（Option+T / Alt+T）**：焦點跳入 toast 區域並展開 stack（`expanded=true`）→ 倒數暫停，焦點離開後恢復。為給鍵盤使用者足夠反應時間，含 `action` 的 toast 預設 `duration` 加長為 10000ms（見「API」段；WCAG 2.2.1 Timing Adjustable）。
 
 ---
 
@@ -117,14 +118,13 @@ toast({
   title: '操作成功',
   description: '變更已儲存至伺服器',
   action: { label: '復原', onClick: handleUndo },
-  duration: 4000,
 })
 ```
 
 - `title`（必填）：主要訊息
 - `description`（選填）：補充說明，自然換行
 - `action`（選填）：tertiary xs 按鈕
-- `duration`（選填）：自動關閉時間，預設 4000ms
+- `duration`（選填）：自動關閉時間；預設依 `action` 而定——有 `action` → **10000ms**（鍵盤焦點不暫停 sonner 倒數，10 秒給鍵盤使用者足夠時間按到「復原 / 重試」，見「A11y 預設」段；2026-07-05 D4 user 拍板，對齊 Polaris toast with action ≥10s / Carbon actionable notification 預設 persistent），無 `action` → **4000ms**
 
 ## 寬度（元件級常數）
 
@@ -146,9 +146,9 @@ Toast 固定 **360px 寬**（見 `.tsx` 的 `w-[360px]`）——跨通知視覺
 Toast 的 public API 是 `toast()` 函式(imperative 觸發)+ `<Toaster />` Provider(app-level,置於 main.tsx 一次)。**兩者皆非「forwardRef + ...props + asChild」canonical shadcn 元件 pattern**:
 
 - `toast(...)` 是 imperative API(sonner 負責 queue / stack / animation / auto-dismiss),consumer 不需持有 DOM ref
-- `<Toaster />` 是 Provider(sonner 內部管理 portal container),consumer 在 app root 放一次,無 consumer-facing DOM operation
+- `<Toaster />` 是 Provider(sonner 內部管理 viewport container),consumer 在 app root 放一次,無 consumer-facing DOM operation
 
-**sonner 已實作 portal / stack / viewport 內部**(Toaster Root portal-renders + viewport DOM spread + 外層 `<section aria-live="polite">` region)。多則同時觸發時 sonner 不是 queue 到 DOM 外,而是全部渲染進 DOM、預設只顯示最近 3 則(`visibleToasts=3`)、超出項以 `data-visible=false` 隱藏堆疊。我們不再 wrap 一層,保持與 sonner 直接對應,避免 API 膨脹。per-variant 的 `role=status/alert` 由本 DS 在自家 toast wrapper 上設(見「A11y 預設」段),非 sonner 提供。
+**sonner 已實作 stack / viewport 內部**(Toaster 就地渲染外層 `<section aria-live="polite">` viewport region,以 CSS `position: fixed` 覆蓋 viewport——非 portal,sonner 不用 `createPortal`)。多則同時觸發時 sonner 不是 queue 到 DOM 外,而是全部渲染進 DOM、預設只顯示最近 3 則(`visibleToasts=3`)、超出項以 `data-visible=false` 隱藏堆疊。我們不再 wrap 一層,保持與 sonner 直接對應,避免 API 膨脹。per-variant 的 `role=status/alert` 由本 DS 在自家 toast wrapper 上設(見「A11y 預設」段),非 sonner 提供。
 
 若 consumer 需要程式化控制(`toast.dismiss(id)` / `toast.promise(...)`),使用 sonner 原生 API,Toast 元件層不重新暴露。
 

package/src/components/Toast/toast.stories.tsx

@@ -9,21 +9,25 @@ const meta: Meta = {
 }
 export default meta
 
-const VARIANTS: NoticeVariant[] = ['neutral', 'success', 'warning', 'error']
+// 2026-07-04 audit:補 'info'(NoticeVariant 5 值,原漏 → 靜態雙 theme 對照未涵蓋全 variant)
+const VARIANTS: NoticeVariant[] = ['neutral', 'info', 'success', 'warning', 'error']
 const LABELS: Record<string, string> = {
   neutral: '檔案已複製到剪貼簿',
+  info: '新版本 v2.4 可用',
   success: '專案已儲存',
   warning: '即將到期的訂閱',
   error: '無法連線伺服器',
 }
 const ACTIONS: Record<string, string> = {
   neutral: '復原',
+  info: '查看更新',
   success: '查看',
   warning: '續訂',
   error: '重試',
 }
 const DESCRIPTIONS: Record<string, string> = {
   neutral: '「Q3 營收報表.xlsx」已加入剪貼簿',
+  info: '重新整理頁面即可套用新功能',
   success: '變更已同步到所有成員',
   warning: '7 天後將停用,請前往結算頁續訂',
   error: '請檢查網路後再試一次',

package/src/components/Toast/toast.tsx

@@ -38,8 +38,11 @@ function ToastInner({
   const isInverse = variant === 'neutral' || variant === 'success'
   const dismiss = () => sonnerToast.dismiss(id)
 
+  // action 執行後自動 dismiss:關閉「復原/重試」的重複觸發窗口(double-undo / double-retry),
+  // 對齊 Polaris Toast action / Material Snackbar action 按後即收慣例;
+  // toast.anatomy.stories.tsx「點 action button 執行 callback + 關閉 toast」宣稱自此為真。
   const actionButton = action ? (
-    <Button variant="tertiary" size="xs" onClick={action.onClick}>{action.label}</Button>
+    <Button variant="tertiary" size="xs" onClick={() => { action.onClick(); dismiss() }}>{action.label}</Button>
   ) : undefined
 
   // ── Live region 由 outer Toast wrapper 擁有(WAI-ARIA + toast.spec.md「A11y 預設」段 canonical) ──
@@ -80,7 +83,9 @@ function ToastInner({
 }
 
 export function toast(options: ToastOptions) {
-  const { duration = 4000, ...rest } = options
+  // 2026-07-05 D4:sonner 計時器不因鍵盤 Tab 焦點暫停(僅 hover / pointer 按住 / ⌥T hotkey)——
+  // 含 action(復原/重試)預設 10s,給鍵盤使用者足夠時間 Tab 到 action(user 拍板;對齊 Polaris toast with action ≥10s)
+  const { duration = options.action ? 10000 : 4000, ...rest } = options
   return sonnerToast.custom((id) => <ToastInner id={id} {...rest} />, { duration })
 }
 
@@ -88,10 +93,10 @@ export interface ToasterProps {
   position?: 'top-left' | 'top-right' | 'top-center' | 'bottom-left' | 'bottom-right' | 'bottom-center'
 }
 
-// shadcn canonical:forwardRef + displayName 統一。Sonner Toaster portal-renders
-// 到 document body,ref 對 Toaster 本身無實際 DOM 節點可接(portal 逃逸),
-// 但保留 forwardRef 簽名以符合 DS 統一 API(consumer 可 typecheck 傳 ref,
-// 與其他 DS 元件一致)。
+// shadcn canonical:forwardRef + displayName 統一。SonnerToaster 不轉發 ref,
+// 故 ref 無實際 DOM 節點可接;viewport 為就地渲染的 <section>,以 CSS position:fixed
+// 覆蓋 viewport(非 portal — sonner 全庫 0 createPortal,2026-07-04 grep 驗證)。
+// 保留 forwardRef 簽名以符合 DS 統一 API(consumer 可 typecheck 傳 ref)。
 const Toaster = React.forwardRef<HTMLDivElement, ToasterProps>(
   ({ position = 'bottom-right', ...props }, _ref) => {
     return (
@@ -118,7 +123,8 @@ export const toastMeta = {
     error: { when: '錯誤(匯入失敗 / 權限不足);action prop 可加重試' },
   },
   sizes: {},
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 2026-07-04 audit 對齊:Toast 無 disabled state(spec 邊界案例明文;對齊 noticeMeta ['default'] 已修 pattern)
+  states: ['default'],
   tokens: {
     bg: ['bg-error', 'bg-info', 'bg-surface-raised', 'bg-warning'],
     fg: ['text-foreground'],

package/src/components/Tooltip/tooltip.spec.md

@@ -75,9 +75,9 @@ Tooltip 底色是深色，子元素永遠套用 dark theme token（透過 `data-
 
 ## Edge collision(避免貼 viewport 邊)
 
-**`collisionPadding` default = 8**(與 HoverCard 一致),Radix `avoidCollisions` 預設 true 會自動翻邊,但 padding 0 會讓 tooltip **貼齊 viewport 邊緣**(視覺上擠)。default 8 讓 tooltip 跟 viewport 邊保留最少 8px 呼吸距離。consumer 需自訂傳 prop 即可覆寫。
+**`collisionPadding` default = 8**(消費 `OVERLAY_COLLISION_PADDING` overlay 家族 canonical,與 Popover 一致;HoverCard 是 documented exception 特意用 12 補 Radix rounding,見 `hover-card.tsx` 註解),Radix `avoidCollisions` 預設 true 會自動翻邊,但 padding 0 會讓 tooltip **貼齊 viewport 邊緣**(視覺上擠)。default 8 讓 tooltip 跟 viewport 邊保留最少 8px 呼吸距離。consumer 需自訂傳 prop 即可覆寫。
 
-世界級對照:Material Tooltip `margin: 14px` default / Polaris Tooltip 8-12px — 本 DS 選 8 對齊 HoverCard。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+世界級對照:Material Tooltip `margin: 14px` default / Polaris Tooltip 8-12px — 本 DS 選 8 對齊 overlay 家族共用常數。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
 ## 最大寬度（元件級常數）
 
@@ -109,7 +109,7 @@ Tooltip 是**單一職責 hover 提示 primitive**(一句話補充),刻意無變
 - **無 SizeMatrix**:Tooltip 無 size prop,尺寸由內容 + max-width 常數決定(本 spec「最大寬度」段)。不提供 sm/md/lg tier——短文字 hint 不需要尺寸變體。
 - **無 StateBehavior**:Tooltip 是 passive 出現 / 消失(hover / focus 觸發,見「出現時機」段),無 hover / selected / active / disabled 這類互動元件 state。開 / 關行為由 Radix primitive 處理,寫在 `Overview` 的 usage 說明已足夠。
 
-對應 anatomy story:保留 `Overview` + `Inspector`(delay / placement 互動試玩) + 元件特有 `PlacementReference`(12 種 side × align 對照)。
+對應 anatomy story:保留 `Overview` + `Inspector`(delay / placement 互動試玩) + 元件特有 `PlacementReference`(4 種 side 方向對照 + side-aware 動畫表;Tooltip 走 `align="center"` 輕量浮層例外,見「Align 對齊」段,無 align 軸矩陣)。
 
 ---
 

package/src/components/Tooltip/tooltip.tsx

@@ -24,7 +24,7 @@ const TooltipContent = React.forwardRef<
   React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>
 >(({ className, sideOffset = OVERLAY_SIDE_OFFSET, collisionPadding = OVERLAY_COLLISION_PADDING, style, children, ...props }, ref) => (
   // collisionPadding default 8px:避免 tooltip 貼 viewport 邊(Radix avoidCollisions 預設 true 但 padding 0 會貼邊)
-  // 對齊 HoverCard canonical 避免 viewport edge clipping
+  // 消費 OVERLAY_COLLISION_PADDING overlay 家族 canonical(與 Popover 一致;HoverCard 特例 12 補 rounding)避免 viewport edge clipping
   <TooltipPrimitive.Portal>
     <TooltipPrimitive.Content
       ref={ref}

package/src/components/TreeView/tree-view.anatomy.stories.tsx

@@ -66,8 +66,11 @@ export const Overview: Story = {
                 ['  selectionMode', "'single' | 'multiple' | 'none'", "'single'", "multiple 模式自動顯示 checkbox;none=純展開展示不可選(JSON viewer)"],
                 ['  expandedIds / onExpandedChange', 'Set<string> / handler', '—', '展開狀態受控'],
                 ['  defaultExpandedIds', 'string[]', '—', '初始展開(uncontrolled)'],
+                ['  defaultSelectedIds', 'string[]', '—', '初始選取(uncontrolled)'],
+                ['  expandOnSelect', 'boolean', 'false', '點 label 同時 select + expand(stepper 適用;預設 chevron 是展開唯一控件)'],
                 ['  draggable / onDragEnd', 'boolean / handler', 'false', '拖曳重排'],
-                ['  size', "'sm' | 'md' | 'lg'", "'md'", 'font-size tier'],
+                ['  size', "'sm' | 'md' | 'lg'", "'md'", '尺寸 tier(node 高度 / icon 大小 / indent 寬度連動)'],
+                ['  context', "'sidebar' | 'menu'", "'sidebar'", '使用脈絡,決定水平 padding(sidebar=--layout-space-loose / menu=12px 對齊 MenuItem)'],
                 ['TreeItem', '', '', ''],
                 ['  id', 'string', '必填', '唯一識別碼'],
                 ['  label', 'ReactNode', '必填', 'node 名稱'],
@@ -75,6 +78,8 @@ export const Overview: Story = {
                 ['  checkbox', 'ReactNode', '—', 'multiple 模式 selection checkbox(通常自動帶入)'],
                 ['  inlineActions', 'InlineActionConfig[]', '—', '右側 inline actions(宣告式 config,內部用 <ItemInlineAction> 渲染)'],
                 ['  inlineActionsSlot', 'ReactNode', '—', 'escape-hatch slot(放自訂元素,跟 inlineActions 互斥)'],
+                ['  actionsReveal', "false | 'hover'", "'hover'", 'inline actions 顯示時機(hover reveal;false=常駐)'],
+                ['  indicator', 'ReactNode', '—', '取代 icon 位置(chevron 永存);stepper 狀態視覺由此傳入'],
                 ['  disabled', 'boolean', 'false', '停用該 node'],
               ].map(([p, t, d, desc]) => (
                 <tr key={p}><Td mono>{p}</Td><Td mono>{t}</Td><Td mono>{d}</Td><Td>{desc}</Td></tr>

package/src/components/TreeView/tree-view.principles.stories.tsx

@@ -30,7 +30,7 @@ const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }
 
 const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
   <section className="mb-12">
-    <h2 className="text-heading-3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
+    <h2 className="text-h3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
     {children}
   </section>
 )
@@ -77,7 +77,7 @@ export const UsageGuidance: Story = {
 
       <Section title="何時不用 + 替代方案">
         <Rule
-          title="❌ 互斥展開(同時只開一個):用 Accordion(未來)"
+          title='❌ 互斥展開(同時只開一個):用 Accordion type="single"'
           note="TreeView 預設允許任意多個節點同時展開。若需要「選一個展開其他自動收」的互斥語意,用 Accordion(非 TreeView)"
         >
           <Label warn>(範例省略)TreeView 是多展開,Accordion 是單展開,語意不同</Label>

package/src/components/TreeView/tree-view.spec.md

@@ -116,7 +116,7 @@ Chevron 是**展開/收合控件**,不是 prefix icon:`fg-muted`(指示色,hover
 
 **預設 label 不 expand**——chevron 是展開唯一控件。理由:select / expand 語意獨立(sidebar「Documents」點 label 進頁面,點 chevron 才展開子列表)。Consumer `expandOnSelect` prop 可讓整行同時 select + expand(適合 stepper)。
 
-**動畫**:children 用 Radix `Collapsible` height animation(0 → auto);chevron `transition-transform duration-150 rotate-0 → rotate-90`。
+**動畫**:children 用 Radix `Collapsible` height animation(0 → auto);chevron `transition-all duration-150 rotate-0 → rotate-90`(`transition-all` 同時涵蓋 hover 色彩過渡)。
 
 ---
 
@@ -258,7 +258,7 @@ TreeItem 右側 `actions` slot 只在 hover 該列時出現(opacity 0→1 transi
 
 ### Inline action 視覺 + API
 
-Icon 尺寸跟 size tier(sm/md=16, lg=20);色 `fg-muted` → hover `foreground`;hover bg `neutral-hover`;action 間距 / 高度對齊規則見 `item-anatomy.spec.md`「Inline Action 設計規格」(canonical SSOT)。
+Icon 尺寸跟 size tier(sm/md=16, lg=20);色 `fg-muted` → hover `foreground`;hover bg `neutral-hover`;action 間距 / 高度對齊規則見 `../../patterns/element-anatomy/inline-action.spec.md`(canonical SSOT,2026-04-24 自 item-anatomy 抽出)。
 
 **宣告式 API**(對齊 `inline-action.spec.md` + `SidebarMenuButton.inlineActions`):`inlineActions: InlineActionConfig[]` + `actionsReveal: false | "hover"`(預設 `"hover"`,鍵盤 focus-visible 也顯)。內部用 `<ItemInlineAction>` helper 渲染,consumer **不可手刻 button JSX**(canonical 在 `item-anatomy.tsx`,共用 size 查表 / Tooltip / hover bg / aria)。Hover-reveal 用 `group-has-[:focus-visible]/tree-item:opacity-100` 而非 `group-focus-within`(後者 mouse click 會永久顯示)。
 

package/src/components/TreeView/tree-view.tsx

@@ -383,14 +383,19 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
             if (parentId && parentId !== String(active.id)) {
               const parentDepth = Number(parentTreeItem?.getAttribute('aria-level') ?? 1) - 1
               finalDepth = parentDepth
-              setDropTarget({ id: parentId, position: 'after', depth: parentDepth })
+              setDropTarget(prev => prev && prev.id === parentId && prev.position === 'after' && prev.depth === parentDepth ? prev : { id: parentId, position: 'after', depth: parentDepth })
               return
             }
           }
         }
       }
 
-      setDropTarget({ id: String(over.id), position, depth: finalDepth })
+      // 2026-07-06 D3 perf:bail-out — drop target 未變(每 dragOver 跨 row 才變)時回傳 prev,
+      // React 對相同 reference bail out,避免每次 over 事件重建 contextValue → 全樹 TreeItem re-render。
+      setDropTarget(prev => {
+        const id = String(over.id)
+        return prev && prev.id === id && prev.position === position && prev.depth === finalDepth ? prev : { id, position, depth: finalDepth }
+      })
 
       // Auto-expand collapsed folder after 500ms hover (Figma behavior)
       if (position === 'inside' && hasChildren && !expandedIds.has(String(over.id))) {
@@ -904,6 +909,9 @@ const TreeItem = React.forwardRef<HTMLDivElement, TreeItemProps>(
           aria-selected={selectionMode !== 'none' ? isSelected : undefined}
           aria-level={depth + 1}
           aria-disabled={disabled || undefined}
+          // 2026-07-05 D4 修:aria-roledescription 移到 treeitem(有 role 的元素才合法)—
+          // 供 AT 提示此 node 可拖曳;值消費 dnd-kit attributes SSOT(預設 'draggable')。
+          aria-roledescription={draggable && !disabled ? dragAttrs['aria-roledescription'] : undefined}
           data-tree-id={id}
           data-tree-parent-id={parentId ?? ''}
           data-tree-has-children={hasChildren}
@@ -954,7 +962,14 @@ const TreeItem = React.forwardRef<HTMLDivElement, TreeItemProps>(
               paddingRight: 'var(--tree-px)',
             }}
             onClick={handleRowClick}
-            {...(draggable ? { ...dragListeners, ...dragAttrs } : {})}
+            // 2026-07-05 D4 修:只 spread listeners,不 spread dnd-kit attributes —
+            // useDraggable 預設 attributes 注入 role="button" + tabIndex=0 + aria-pressed +
+            // aria-describedby(鍵盤拖曳指示):role=button 污染 treeitem 語意、tabIndex=0
+            // 讓每 row 變 DOM tab stop 破壞單一 tab stop 虛擬焦點模型(DOM focus 在 row 上按
+            // Enter 會 bubble 到容器 handleKeyDown 但 handler 操作 state focusedId → 錯位);
+            // sensors 僅 PointerSensor(無 KeyboardSensor),這些 attrs 換不到鍵盤拖曳能力。
+            // aria-roledescription 保留在上方 treeitem 元素(有 role 才合法)。
+            {...(draggable ? dragListeners : {})}
             {...props}
           >
             {chevronSlot}
@@ -968,7 +983,12 @@ const TreeItem = React.forwardRef<HTMLDivElement, TreeItemProps>(
               * 對齊 cite:menu-item.tsx:194-195(MenuItem selected bg)+ select-menu.tsx:352-354(SelectMenu multi=checkbox) */}
             {(checkbox || selectionMode === 'multiple') && (
               <ItemPrefix className="pointer-events-none">
-                {checkbox || <Checkbox checked={isSelected} disabled={disabled} aria-hidden="true" />}
+                {/* 2026-07-05 D4 修:auto-render Checkbox 補 tabIndex={-1} — Radix Checkbox root
+                  * 是原生 button(預設可聚焦),aria-hidden + 可聚焦 = axe aria-hidden-focus,且
+                  * 破壞 tree 單一 tab stop 虛擬焦點模型(tree-view.spec.md「Focus」段);
+                  * ItemPrefix pointer-events-none 只擋滑鼠不擋鍵盤。選取語意由 treeitem
+                  * aria-selected 承載,checkbox 純視覺反映。 */}
+                {checkbox || <Checkbox checked={isSelected} disabled={disabled} aria-hidden="true" tabIndex={-1} />}
               </ItemPrefix>
             )}
 
@@ -1056,7 +1076,9 @@ export const treeViewMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'selected' = single-selection 持續選中(bg-neutral-selected + aria-selected);'active' 移除 —
+  // 全檔無 Tailwind 按壓 utility,無按壓專屬視覺態(2026-07-07 詞彙統一對抗稽核補修)。
+  states: ['default', 'hover', 'selected', 'focus-visible', 'disabled'],
   tokens: {
     bg: ['bg-neutral-hover', 'bg-neutral-selected', 'bg-surface'],
     fg: ['text-fg-disabled', 'text-fg-muted', 'text-fg-secondary', 'text-foreground'],

package/src/hooks/use-controllable.ts

@@ -25,15 +25,20 @@ export function useControllable<T>({
   onChangeRef.current = onChange
 
   const current = isControlled ? (value as T) : internal
+  // 2026-07-07 C14:setter identity 穩定化——原 deps 含 `current`,值一變 setter 就換 identity
+  // (consumer 放 useEffect deps / useCallback 鏈會白重跑)。對齊 Radix useControllableState:
+  // current 走 ref、setter 只依 isControlled,行為 Δ=0(functional updater 讀最近 render 值,同 Radix)。
+  const currentRef = useRef(current)
+  currentRef.current = current
 
   const setValue = useCallback(
     (next: T | ((prev: T) => T)) => {
       const computed =
-        typeof next === 'function' ? (next as (prev: T) => T)(current) : next
+        typeof next === 'function' ? (next as (prev: T) => T)(currentRef.current) : next
       if (!isControlled) setInternal(computed)
       onChangeRef.current?.(computed)
     },
-    [isControlled, current]
+    [isControlled]
   )
 
   return [current, setValue]

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

@@ -7,10 +7,17 @@ import { useState, useEffect } from 'react'
  * 用途：Select 等元件在 mobile 退回原生 picker。
  */
 export function useIsTouchDevice() {
-  const [isMobile, setIsMobile] = useState(false)
+  // 2026-07-06 D3 perf 修:初值固定 false 讓觸控裝置首次 commit 先掛 desktop 分支
+  // (CustomSelect/CustomCombobox trigger subtree),effect flip true 後整棵 unmount 換 Native
+  // → 每 instance 白付一次 double-mount。改 lazy initializer 同步讀 matchMedia,
+  // 首次 render 即正確分支;effect 保留 change listener(行為不變)。
+  const [isMobile, setIsMobile] = useState(
+    () => typeof window !== 'undefined' && window.matchMedia('(pointer: coarse)').matches,
+  )
 
   useEffect(() => {
     const mq = window.matchMedia('(pointer: coarse)')
+    // 同步一次防 initializer 與 effect 之間 mq 變化(同值時 React Object.is bail-out,無多餘 render)
     setIsMobile(mq.matches)
     const handler = (e: MediaQueryListEvent) => setIsMobile(e.matches)
     mq.addEventListener('change', handler)

package/src/index.ts

@@ -33,8 +33,10 @@ export * from './components/FileViewer/index'
 export * from './components/Input/index'
 export * from './components/LinkInput/index'
 export * from './components/NumberInput/index'
+export * from './components/Pagination/index'
 export * from './components/PeoplePicker/index'
 export * from './components/Popover/index'
+export * from './components/ProfileCard/index'
 export * from './components/ProgressBar/index'
 export * from './components/RadioGroup/index'
 export * from './components/Rating/index'
@@ -71,7 +73,6 @@ export * from './patterns/resize-handle/index'
 //   - components/Menu
 //   - components/Notice
 //   - components/OverflowIndicator
-//   - components/ProfileCard
 //   - components/SelectMenu
 //   - components/SelectionControl
 //   - patterns/horizontal-overflow