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

package/src/components/Command/command.spec.md

@@ -144,8 +144,8 @@ Command 是 **internal primitive**(SelectMenu 底層消費,app 不直接使用,
 | DS | 本 DS | cmdk lib | Radix UI | shadcn/ui | Material UI |
 |----|-------|----------|----------|-----------|--------------|
 | Internal primitive 命名 | **Command** | cmdk | (無此 primitive,用 `<Combobox>` + filter)| Command | `<Autocomplete>` 一體 |
-| Consumer wrapper 命名 | SelectMenu / Popover+Command(Cmd+K) | (consumer 自包)| Combobox | Combobox / Custom Cmd+K | Autocomplete |
-| 是否 app 直接用 | **禁(必透過 SelectMenu / Popover wrapper)**| 開放 | 開放 | 開放 | 開放 |
+| Consumer wrapper 命名 | SelectMenu / CommandDialog(Cmd+K) | (consumer 自包)| Combobox | Combobox / Custom Cmd+K | Autocomplete |
+| 是否 app 直接用 | **禁(必透過 SelectMenu / CommandDialog wrapper)**| 開放 | 開放 | 開放 | 開放 |
 
 ## 設計哲學
 
@@ -165,11 +165,11 @@ input always visible 提示使用者「這是 search-driven」,對齊 input-firs
 
 Cmd-K 已成 productivity tool 的 universal idiom(Linear 推廣後 Notion / Vercel / Stripe / Slack 統一),使用者跨 app 預期一致。捨棄 Raycast 的 Option+Space(global launcher conflict)/ Spotlight Cmd+Space(macOS 內建衝突)/ VS Code Cmd+P(file-only,跟 Cmd+Shift+P 命令分流)的差異化代價接受 — 對齊主流 idiom 比差異化重要。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
-**(4) Internal primitive 哲學 — app 不直接用 Command,必透過 SelectMenu / Popover+Command wrapper**
+**(4) Internal primitive 哲學 — app 不直接用 Command,必透過 SelectMenu / CommandDialog wrapper**
 
-cmdk / shadcn / Radix 默認開放 app 直接消費 primitive — 但本 DS 走 Material `<Autocomplete>` 一體 / Polaris 一體封裝哲學,把 search + popover + value-binding 包進 SelectMenu(form context)或 Popover+Command wrapper(global Cmd+K)。
+cmdk / shadcn / Radix 默認開放 app 直接消費 primitive — 但本 DS 走 Material `<Autocomplete>` 一體 / Polaris 一體封裝哲學,把 search + popover + value-binding 包進 SelectMenu(form context)或 `CommandDialog`(cmdk + Radix Dialog 包裝,global Cmd+K)。
 
-捨棄「app code 直接 import Command 客製」的代價是「自由度受限」(無法在 app 內客製 cmdk filter logic),但 DS 一致性更重要 — 若 SelectMenu / Popover+Command 不夠用,回 DS 開新 wrapper 而不是繞過抽象層(對齊 SSOT 消費 canonical M1)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+捨棄「app code 直接 import Command 客製」的代價是「自由度受限」(無法在 app 內客製 cmdk filter logic),但 DS 一致性更重要 — 若 SelectMenu / CommandDialog 不夠用,回 DS 開新 wrapper 而不是繞過抽象層(對齊 SSOT 消費 canonical M1)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
 ---
 

package/src/components/Command/command.stories.tsx

@@ -35,7 +35,7 @@ const meta: Meta = {
     docs: {
       description: {
         component:
-          'Command 是 cmdk 的 shadcn passthrough 搜尋 + 鍵盤導覽清單 primitive。App 層級**不直接使用** Command——透過 Select / Combobox / PeoplePicker 的 searchable 模式消費,底層自動切換到 SelectMenu(SelectMenu 包 Command)。唯一可以直接組合 Command 的場景是 Command Palette(Cmd+K)——跨頁全域搜尋與快速動作入口。',
+          'Command 是 cmdk 的 shadcn passthrough 搜尋 + 鍵盤導覽清單 primitive。主用法是浮層:透過 Select / Combobox / PeoplePicker 的 searchable 模式消費(底層自動切換到 SelectMenu,SelectMenu 包 Command),或用 `CommandDialog` 組 Command Palette(Cmd+K)——跨頁全域搜尋與快速動作入口。Inline 嵌頁面是允許的次要用法,必須自帶邊框容器(rounded + border,見下方行內範例;spec「禁止事項」2026-06-12 拍板)。',
       },
     },
   },
@@ -64,8 +64,8 @@ const PaletteDemo = () => {
   return (
     <div className="flex flex-col gap-3 max-w-xl">
       <p className="text-caption text-fg-muted">
-        按下 <kbd className="font-mono bg-muted px-1.5 py-0.5 rounded">⌘K</kbd> (Mac) 或{' '}
-        <kbd className="font-mono bg-muted px-1.5 py-0.5 rounded">Ctrl+K</kbd> (Win) 開啟全域指令面板。
+        按下 <kbd className="font-mono bg-muted px-1.5 py-0.5 rounded-md">⌘K</kbd> (Mac) 或{' '}
+        <kbd className="font-mono bg-muted px-1.5 py-0.5 rounded-md">Ctrl+K</kbd> (Win) 開啟全域指令面板。
       </p>
       <button
         type="button"
@@ -74,7 +74,7 @@ const PaletteDemo = () => {
       >
         <Search size={14} className="text-fg-muted" />
         <span className="text-fg-muted">搜尋或輸入指令…</span>
-        <kbd className="ml-4 font-mono text-footnote bg-muted px-1.5 py-0.5 rounded">⌘K</kbd>
+        <kbd className="ml-4 font-mono text-footnote bg-muted px-1.5 py-0.5 rounded-md">⌘K</kbd>
       </button>
 
       <CommandDialog open={open} onOpenChange={setOpen}>

package/src/components/Command/command.tsx

@@ -171,9 +171,10 @@ export const commandMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'active' 移除 — cmdk row 僅 data-[selected] highlight,無按壓視覺(2026-07-07 詞彙統一 DS-wide 按壓訊號盤點:檔內 0 active: utility / 0 *-active token)。
+  states: ['default', 'hover', 'focus-visible', 'disabled'],
   tokens: {
-    bg: ['bg-neutral-hover', 'bg-surface-raised', 'bg-transparent'],
+    bg: ['bg-divider', 'bg-neutral-hover', 'bg-surface-raised', 'bg-transparent'], // 2026-07-04 補:CommandSeparator h-px bg-divider 實際消費
     fg: ['text-fg-disabled', 'text-fg-muted', 'text-foreground'],
     ring: [],
   },

package/src/components/DataTable/active-editor-controller.ts

@@ -12,9 +12,9 @@
  * | RFC Contract | Original class method | New owner(Phase 7) |
  * |---|---|---|
  * | Contract 3 commit/cancel | `controller.commit()` | per-cell `onCommit` / `onCommitLive` callback in cell-registry |
- * | Contract 4 Tab navigation | `controller.routeKeyDown` | `data-table.tsx:2605 handleEditTab`(onKeyDownCapture per portal cell) |
+ * | Contract 4 Tab navigation | `controller.routeKeyDown` | `data-table.tsx handleEditTab(符號指法免行號漂移)`(onKeyDownCapture per portal cell) |
  * | Contract 6 unmount preserve draft | `controller.onAnchorUnmount` | `data-table.tsx editingDraft` lifted state + `onDraft` prop(Phase 7) |
- * | Contract 10 IME guard | `controller.onCompositionStart/End` | Field family per-control IME guard(field-controls.spec.md)+ `data-table.tsx:2609 isComposing` early-return |
+ * | Contract 10 IME guard | `controller.onCompositionStart/End` | cell-registry per-editor isComposing guard(makeKeyHandler + Textarea/NumberCell onKeyDown,2026-07-05 D4 補 — 原宣稱的 Field per-control guard 不存在)+ `data-table.tsx isComposing(符號指法)` early-return(nav + Tab route) |
  * | Esc cancel | `controller.cancel()` | per-cell Field `onCancel` callback + Radix Popover outside-click |
  *
  * Verify(grep `src/`):**zero runtime consumer** of the class — only `experimentalActiveEditorController`
@@ -34,7 +34,8 @@
  *   2. ✅ RFC Slice C / Contract 3 / 6 backfill distributed ownership
  *   3. ✅ Keyboard invariants(Enter / Esc / Tab/Shift+Tab commit-and-move + skip non-editable)
  *      — visual-audit-comprehensive 17/17 PASS this turn(scenarios 11-17 cover Enter/Esc/Arrow/Tab)
- *   4. ✅ IME composition — Field per-control built-in + `data-table.tsx:2609 isComposing` guard
+ *   4. ✅ IME composition — cell-registry per-editor guard(2026-07-05 D4 補;原宣稱的 Field
+ *      per-control built-in 不存在)+ `data-table.tsx isComposing(符號指法)` guard
  *   5. ✅ Virtualizer scroll-out / scroll-back draft preservation — Phase 7 commit c5eb054 ships
  *      `onDraft` prop + lifted state(spec'd in commit body)
  *   6. ✅ Outside-click + nested popover — Radix Popover idiom + Field family

package/src/components/DataTable/cell-registry.tsx

@@ -82,6 +82,10 @@ function makeKeyHandler(
   parseValue?: (raw: string) => unknown,
 ) {
   return (e: React.KeyboardEvent<HTMLInputElement>) => {
+    // IME 組字 guard(2026-07-05 D4 fix):中文輸入法選字的 Enter 是組字確認、Esc 是取消組字,
+    // 非 commit / cancel 意圖 — 無 guard 會把半截組字提交並退出 edit(Esc 則丟棄整個 draft)。
+    // 同 data-table.tsx nav handler 既有寫法(isComposing + Safari/舊 Chrome keyCode 229)。
+    if (e.nativeEvent.isComposing || e.nativeEvent.keyCode === 229) return
     if (e.key === 'Escape') { e.preventDefault(); onCancel?.() }
     if (e.key === 'Enter') {
       e.preventDefault()
@@ -148,6 +152,8 @@ function StringCell({ value, meta, mode, size, isDisabled, autoRowHeight, onComm
         onChange={(e) => onDraft?.((e.target as HTMLTextAreaElement).value)}
         onBlur={(e) => onCommit?.((e.target as HTMLTextAreaElement).value)}
         onKeyDown={(e) => {
+          // IME 組字 guard(2026-07-05 D4 fix,同 makeKeyHandler)
+          if (e.nativeEvent.isComposing || e.nativeEvent.keyCode === 229) return
           if (e.key === 'Escape') { e.preventDefault(); onCancel?.() }
           if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
             e.preventDefault()
@@ -211,6 +217,8 @@ function NumberCell({ value, meta, mode, size, isDisabled, onCommit, onCancel, o
       precision={meta?.precision}
       onBlur={() => onCommit?.(localValue)}
       onKeyDown={(e) => {
+        // IME 組字 guard(2026-07-05 D4 fix,同 makeKeyHandler;IME 可在 number 欄輸入全形數字)
+        if (e.nativeEvent.isComposing || e.nativeEvent.keyCode === 229) return
         if (e.key === 'Escape') { e.preventDefault(); onCancel?.() }
         if (e.key === 'Enter') { e.preventDefault(); onCommit?.(localValue) }
       }}

package/src/components/DataTable/data-table-filter-panel.tsx

@@ -115,12 +115,18 @@ function getDefaultOperator(type?: ColumnType): string {
   return (type && DEFAULT_OPERATOR[type]) || DEFAULT_OPERATOR.string
 }
 
+// Q6(2026-07-04):date 欄位把比對精度寫進 condition(includeTime=true → ms,否則 day)。
+// 'time' 欄暫不寫(值非完整日期,truncate 語意不成立;見 filter-operators.spec v3 time 註)。
+const datePrecisionOf = (col: FilterColumn | undefined): 'day' | 'ms' | undefined =>
+  col?.type === 'date' ? (col.includeTime ? 'ms' : 'day') : undefined
+
 const newCondition = (firstCol: FilterColumn | undefined): FilterCondition => ({
   kind: 'cond',
   id: newId(),
   field: firstCol?.id ?? '',
   op: firstCol ? getDefaultOperator(firstCol.type) : '',
   value: '',
+  datePrecision: datePrecisionOf(firstCol),
 })
 
 // **G fix(2026-05-04)**:initial-mount 用 — field 不預選,user 自選後 op/value 才 enable
@@ -588,7 +594,7 @@ function DataTableFilterPanelInner<TData>({
             onChangeConjunction={setFlatConjunction}
             onChangeField={(v) => {
               const newCol = filterableColumns.find((c) => c.id === v)
-              updateFlatCondition(cond.id, { field: v, op: getDefaultOperator(newCol?.type), value: '' })
+              updateFlatCondition(cond.id, { field: v, op: getDefaultOperator(newCol?.type), value: '', datePrecision: datePrecisionOf(newCol) })
             }}
             onChangeOp={(v) => updateFlatCondition(cond.id, { op: v, value: '' })}
             onChangeValue={(v) => updateFlatCondition(cond.id, { value: v })}
@@ -793,7 +799,7 @@ function GroupBlock({
             onChangeConjunction={onChangeGroupConjunction}
             onChangeField={(v) => {
               const newCol = filterableColumns.find((c) => c.id === v)
-              onChangeCondition(cond.id, { field: v, op: getDefaultOperator(newCol?.type), value: '' })
+              onChangeCondition(cond.id, { field: v, op: getDefaultOperator(newCol?.type), value: '', datePrecision: datePrecisionOf(newCol) })
             }}
             onChangeOp={(v) => onChangeCondition(cond.id, { op: v, value: '' })}
             onChangeValue={(v) => onChangeCondition(cond.id, { value: v })}

package/src/components/DataTable/data-table-interaction-layer.tsx

@@ -2,11 +2,12 @@
  * DataTableInteractionLayer — Slice D Step 1A scaffold(per `.claude/planning/datatable-spreadsheet-rfc.md`)
  *
  * Singleton overlay root inside DataTable(M21 private,不抽 global pattern)。
- * 5 sub-layer children(per RFC §Overlay Geometry):
+ * Sub-layer children(2026-07-04 對齊實作;原 RFC 5-layer 清單含未實作元件):
  *   - HoverCellRect(z 1):hover 邊框,「one geometry owner, two paint owners」(Contract 8)
- *   - SelectionRect / RangeRect(z 1.5):spreadsheet mode 才顯示(Contract 5,defer)
+ *   - SelectionRing(z 2):spreadsheet mode selected cell 1px ring(CELL_RING_STYLES.selected)
  *   - ActiveEditorHost(z 3):portal active edit Field(Slice C wire-up)
- *   - NestedPortalRegistry(z 4):date/select popup 註冊為 inside editor(Contract 7)
+ *   -(range 視覺 = CSS [data-range-cell] cell-bg,非 layer 元件;nested popup 走 Radix idiom
+ *     見 active-editor-controller.ts — RangeRect / NestedPortalRegistry 元件不存在)
  *
  * Slice D Step 1A scope:
  *   - getCellRect(cellId)geometry source(per Contract 8)
@@ -80,7 +81,7 @@ interface DataTableInteractionLayerProps {
  *   2. layoutCache 需另寫 invalidation logic,added complexity
  *   3. Hover overlay re-render 頻率低(per cell hover,不是 per frame)
  *
- * 0.5px sub-pixel snap per RFC §Overlay Geometry。
+ * Float coords pass-through — no rounding / no snap(v3 fix,見下方 v3 註解;原 RFC 0.5px snap 已撤)。
  */
 function getCellRect(containerEl: HTMLElement | null, cellId: CellId): CellRect | null {
   if (!containerEl) return null
@@ -303,10 +304,10 @@ export function DataTableInteractionLayer({
       )}
       {/* 2026-05-10 retire RangeOuterRing(per user 抓 image 4 + verbatim「range 的 cell 本來就有顏色變化,
           那樣就夠了,不需要再有 2px 藍色的框」)。Range visual now relies purely on cell-bg
-          (`--primary-subtle` via `[data-range-cell]` CSS in `data-table.css`)+ focus cell 2px selected
+          (`--primary-subtle` via `[data-range-cell]` CSS in `data-table.css`)+ focus cell 1px selected
           border。Outer 2px primary ring 從 Issue 6 ship 但 visual 太重 — bg-fill 已給「這些 cell 在範圍內」
-          訊號,outer ring 是 redundant。`rangeOuterRingsByPanel` 計算保留但不 render(future 若需 reinstate
-          只需打開 .map)。 */}
+          訊號,outer ring 是 redundant。calc + render 皆已 retire(變數已移除;future 若需 reinstate
+          參考 git history 2026-05-10)。 */}
       {/* {rangeOuterRingsByPanel.map((group) => (
         <ClipMask key={group.panel} clipRect={group.clipRect}>
           <CellRangeOuterRing rect={toRelRect(group.bbox, group.clipRect)} />

package/src/components/DataTable/data-table.anatomy.stories.tsx

@@ -82,7 +82,7 @@ export const Overview: Story = {
               <tbody>
                 <tr><Td>L1 Structure</Td><Td>DOM 結構 + 捲動行為</Td><Td mono>&lt;div&gt; + ARIA role="table/row/cell" + useVirtualizer</Td></tr>
                 <tr><Td>L2 Typography / Spacing</Td><Td>Row 高度 / Cell padding / 對齊</Td><Td mono>--table-row-* + --field-height-* token</Td></tr>
-                <tr><Td>L3 Cell Rendering</Td><Td>根據 meta.type 自動選 Display 元件</Td><Td mono>column-types.ts 註冊 string/number/currency/date/select/boolean/person/url</Td></tr>
+                <tr><Td>L3 Cell Rendering</Td><Td>根據 meta.type 自動選 Display 元件</Td><Td mono>cell-registry.tsx cellRegistry 註冊 11 型:string/number/currency/date/time/select/multiSelect/person/multiPerson/boolean/url(column-types.ts 管 type union + 對齊預設)</Td></tr>
                 <tr><Td>L4 Interactions</Td><Td>排序 / 選取 / 欄位拖動 / frozen column</Td><Td>TanStack Table features + 自訂 state</Td></tr>
               </tbody>
             </table>
@@ -110,7 +110,7 @@ export const Inspector: Story = {
     docs: {
       description: {
         story:
-          '右側 Controls 切 DataTable props 即時 render,取代 Figma inspect。調整 `size` 看 row height tier 差異;`pinnedLeft` / `pinnedRight` 切換 frozen column 切出三區域(left / center / right);`height` 切換 auto 與固定(啟用虛擬捲動)。',
+          '右側 Controls 切 DataTable props 即時 render,取代 Figma inspect。調整 `size` 看 row height tier 差異;`pinnedLeft` / `pinnedRight` 切換 frozen column 切出三區域(left / center / right);`height` 切換 auto 與固定高度(固定高度限制容器並可捲動;資料多於 30 筆才啟用虛擬捲動,本例 5 筆不觸發)。',
       },
     },
   },
@@ -135,7 +135,7 @@ export const Inspector: Story = {
     height: {
       control: 'select',
       options: ['auto', '300px'],
-      description: 'auto=全渲染(少於 50 筆)/ 固定值=啟用 TanStack Virtual(多於 100 筆)',
+      description: 'auto=全渲染 / 固定值=限制容器高度並捲動;資料多於 30 筆(VIRTUAL_THRESHOLD)才啟用 TanStack Virtual,本例 5 筆不觸發',
     },
   },
   render: (args) => {
@@ -513,7 +513,7 @@ export const Accessibility = {
   render: () => (
     <div className="max-w-3xl text-body text-fg-secondary">
       <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
-      <p className="whitespace-pre-line">{"DataTable 用一般 div 搭配表格語意標記,而非原生 table 元素——因為虛擬捲動需要絕對定位每一列,而 table 的佈局模型做不到。輔助技術(螢幕報讀器)會把它當成表格朗讀。\n\n  表格語意  :最外層標記為表格、每一列標記為列、每一格標記為儲存格,表頭那一格標記為欄位標題。\n\n  排序  :可排序的表頭會標示目前的排序方向(升冪 / 降冪 / 未排序),報讀器讀得出來。\n\n  選取  :每一列的勾選框都有說明文字(由使用方傳入,沒傳就用「Select row」),全選框的說明文字是「Select all visible rows」。\n\n  鍵盤  :一般表格模式下,用 Tab 進入表格後可操作排序與勾選;方向鍵在儲存格之間移動是試算表模式(spreadsheetMode)才開啟的功能,不是預設。列上的更多操作都收進右側的「更多」選單,確保不用滑鼠也能用。\n\n  焦點  :鍵盤聚焦時顯示清楚的外框,與整個設計系統的聚焦樣式一致。\n\n  驗證  :Storybook 無障礙檢查面板應該沒有嚴重問題;全程鍵盤可操作,不必用到滑鼠;文字對比度達到無障礙標準。"}</p>
+      <p className="whitespace-pre-line">{"DataTable 用一般 div 搭配表格語意標記,而非原生 table 元素——因為虛擬捲動需要絕對定位每一列,而 table 的佈局模型做不到。輔助技術(螢幕報讀器)會把它當成表格朗讀。\n\n  表格語意  :最外層標記為表格、每一列標記為列、每一格標記為儲存格,表頭那一格標記為欄位標題。\n\n  排序  :可排序的表頭會標示目前的排序方向(升冪 / 降冪 / 未排序),報讀器讀得出來。\n\n  選取  :每一列的勾選框都有說明文字(由使用方傳入,沒傳就用「選取此列」),全選框的說明文字是「全選可見列」。\n\n  鍵盤  :一般表格模式下,用 Tab 進入表格後可操作排序與勾選;方向鍵在儲存格之間移動是試算表模式(spreadsheetMode)才開啟的功能,不是預設。列上的更多操作都收進右側的「更多」選單,確保不用滑鼠也能用。\n\n  焦點  :鍵盤聚焦時顯示清楚的外框,與整個設計系統的聚焦樣式一致。\n\n  驗證  :Storybook 無障礙檢查面板應該沒有嚴重問題;全程鍵盤可操作,不必用到滑鼠;文字對比度達到無障礙標準。"}</p>
     </div>
   ),
 }

package/src/components/DataTable/data-table.css

@@ -119,7 +119,7 @@
        - Right panel 最右 cell 旁:outer container border
      若 cell shadow 跟 panel/outer border 重疊 = 2px 視覺。
      Fix v3:`:not(:last-child)` 排除每 panel 最右 cell,讓 panel/outer border 唯一 own
-     panel-boundary 視覺。對齊 spec.md L462 grid line 1px SSOT canonical。 */
+     panel-boundary 視覺。對齊 data-table.spec.md「Paint」段 grid line 1px SSOT canonical(段名指法)。 */
   box-shadow: inset -1px 0 0 var(--divider);
 }
 
@@ -131,7 +131,7 @@
 
 /* Phase 9 Issue 1 fix(2026-05-10):range cells bg fill — cell 自身 bg layer
    (在 cell content 之下),non-overlay。Per codex Q1 verdict 對齊 row selected idiom
-   `--primary-subtle`(`data-table.spec.md` L170-174)。
+   `--primary-subtle`(`data-table.spec.md`「L2 選取」段;原引 L170-174 之 selected-row bg 語意 2026-05-31 已廢除,改指現行段)。
    Layer 不再畫 RangeFill div(避免 layer fixed positioned bg 蓋 cell content)。 */
 /* 2026-05-13 V1.6 fix(codex caught medium severity):disabled cell bg dominance — disabled cell
    included in spreadsheet range 不該被 range fill 蓋過,disabled state visual 必勝。 */