@qijenchen/design-system 0.1.0-beta.84 → 0.1.0-beta.85

package/src/components/DataTable/data-table-filter-value-picker.tsx

@@ -0,0 +1,237 @@
+// @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved(2026-07-14 自 data-table-filter-panel.tsx 拆檔搬移,原檔級 escape 隨段落帶入)。
+// @internal — DS-internal 單元(FilterValuePicker value-picker switcher,只被
+// data-table-filter-group.tsx FilterRow 消費);不隨 index.ts re-export 進 npm public surface。
+// ────────────────────────────── 消費的 SSOT ──────────────────────────────
+// - Field controls(Family 4,統一 size="sm"):Input / NumberInput / Select / Combobox /
+//   DatePicker + DatePickerRange(showTime)/ PeoplePicker — 按 ValueShape dispatch
+//   (ValueShape ↔ picker 對照 canonical:./data-table.spec.md「三、Operator × ValueShape SSOT」)
+// - className 直接 forward 給 inner Field control(不另開 wrapper div)—
+//   field-control-group.spec.md「forward className」canonical(2026-05-04 #2 fix)
+// - Operator / ValueShape SSOT:./filter-operators.ts(DATE_RELATIVE_OPTIONS / DATE_RELATIVE_GROUPS)
+// - Person pool:PeoplePicker PersonValue(對齊 cell-registry meta.people SSOT)
+// 設計規則:./filter-operators.spec.md「ValueShape canonical」+ ./data-table.spec.md「進階篩選」段
+
+import { Select, type SelectOption } from '@/design-system/components/Select/select'
+import { Combobox } from '@/design-system/components/Combobox/combobox'
+import { Input } from '@/design-system/components/Input/input'
+import { NumberInput } from '@/design-system/components/NumberInput/number-input'
+import { DatePicker, DatePickerRange } from '@/design-system/components/DatePicker/date-picker'
+import { PeoplePicker } from '@/design-system/components/PeoplePicker/people-picker'
+import type { PersonValue } from '@/design-system/components/PeoplePicker/person-display'
+import {
+  DATE_RELATIVE_OPTIONS,
+  DATE_RELATIVE_GROUPS,
+  type ValueShape,
+} from './filter-operators'
+
+// ── FilterValuePicker(value-picker switcher per ValueShape)────────────────
+//
+// 2026-05-03 M21 retract:本 helper 原獨立檔 filter-value-picker.tsx(187 行 / 1 consumer),
+// claim「未來 inline filter UI 共用」= premature abstraction → inline 回 panel。
+// 2026-07-14 拆檔 refactor:panel 822 行過 800 hard cap(file-size escalation)→ 重新抽出為
+// @internal 私有模組(非 public API 抽象,與 M21 不衝突;consumer 仍只見 DataTableFilterPanel)。
+
+export interface FilterValuePickerColInfo {
+  id: string
+  label: string
+  options?: Array<{ value: string; label: string }>
+  /** Person pool — person/multiPerson filter picker 用(2026-05-07 升級,SSOT 對齊 cell-registry) */
+  people?: Array<{ name: string; avatarUrl?: string; description?: string }>
+}
+
+export interface FilterValuePickerProps {
+  shape: ValueShape | null
+  value: unknown
+  onChange: (v: unknown) => void
+  colInfo?: FilterValuePickerColInfo
+  disabled?: boolean
+  /** 用 column.label 組「{label} 篩選值」(panel 每 row 不顯式 label,a11y 必填) */
+  ariaLabel?: string
+  /** Forward 給內部 Field control 的 className(2026-05-04 #2 fix)
+   *  避免外層包 wrapper div 破壞 FieldControlGroup CSS variants(rounded radii / margin overlap) */
+  className?: string
+}
+
+export function FilterValuePicker({
+  shape,
+  value,
+  onChange,
+  colInfo,
+  disabled,
+  ariaLabel,
+  className,
+}: FilterValuePickerProps) {
+  if (!shape || disabled) {
+    return <Input size="sm" value="" onChange={() => {}} placeholder="輸入值…" disabled aria-label={ariaLabel} className={className} />
+  }
+
+  switch (shape) {
+    case 'none':
+      return null
+
+    case 'text':
+      return (
+        <Input
+          size="sm"
+          value={String(value ?? '')}
+          onChange={(e) => onChange(e.target.value)}
+          placeholder="輸入值…"
+          aria-label={ariaLabel}
+          className={className}
+        />
+      )
+
+    case 'number':
+      return (
+        <NumberInput
+          size="sm"
+          value={typeof value === 'number' ? value : null}
+          onChange={(v) => onChange(v ?? '')}
+          placeholder="輸入數字…"
+          aria-label={ariaLabel}
+          className={className}
+        />
+      )
+
+    case 'date_single':
+      return (
+        <DatePicker
+          size="sm"
+          value={typeof value === 'string' ? value : null}
+          onChange={(v) => onChange(v ?? '')}
+          aria-label={ariaLabel}
+          className={className}
+        />
+      )
+
+    case 'date_range':
+      return (
+        <DatePickerRange
+          size="sm"
+          value={Array.isArray(value) && value.length === 2
+            ? (value as [string | null, string | null])
+            : null}
+          onChange={(v) => onChange(v)}
+          aria-label={ariaLabel}
+          className={className}
+        />
+      )
+
+    case 'date_relative': {
+      // 群組分類:Past / Current / Future(對齊 Linear / Notion idiom),走 Select.groups → SelectMenu
+      const opts: SelectOption[] = DATE_RELATIVE_OPTIONS.map((o) => ({
+        value: o.value,
+        label: o.label,
+        group: o.group,
+      }))
+      return (
+        <Select
+          size="sm"
+          options={opts}
+          groups={DATE_RELATIVE_GROUPS as unknown as Array<{ key: string; label: string }>}
+          value={String(value ?? '')}
+          onChange={(v) => onChange(v)}
+          placeholder="選擇相對日期"
+          aria-label={ariaLabel}
+          className={className}
+        />
+      )
+    }
+
+    case 'select_single': {
+      const opts: SelectOption[] = (colInfo?.options ?? []).map((o) => ({
+        value: o.value,
+        label: o.label,
+      }))
+      return (
+        <Select
+          size="sm"
+          options={opts}
+          value={String(value ?? '')}
+          onChange={(v) => onChange(v)}
+          placeholder="選擇值"
+          aria-label={ariaLabel}
+          className={className}
+        />
+      )
+    }
+
+    case 'select_multi': {
+      const opts = (colInfo?.options ?? []).map((o) => ({
+        value: o.value,
+        label: o.label,
+      }))
+      const arr = Array.isArray(value) ? (value as string[]) : []
+      return (
+        <Combobox
+          size="sm"
+          options={opts}
+          value={arr}
+          onChange={(v) => onChange(v)}
+          placeholder="選擇值…"
+          aria-label={ariaLabel}
+          className={className}
+        />
+      )
+    }
+
+    case 'datetime_single':
+      return (
+        <DatePicker
+          size="sm"
+          showTime
+          value={typeof value === 'string' ? value : null}
+          onChange={(v) => onChange(v ?? '')}
+          aria-label={ariaLabel}
+          className={className}
+        />
+      )
+
+    case 'datetime_range':
+      return (
+        <DatePickerRange
+          size="sm"
+          showTime
+          value={Array.isArray(value) && value.length === 2
+            ? (value as [string | null, string | null])
+            : null}
+          onChange={(v) => onChange(v)}
+          aria-label={ariaLabel}
+          className={className}
+        />
+      )
+
+    // person_single / person_multi — 走 PeoplePicker(2026-05-07 升級,對齊 cell-registry SSOT)。
+    // colInfo.people 來自 column meta.people。Filter value:
+    //   - person_single:存 PersonValue | null(picker emit array,我們取 [0])
+    //   - person_multi:存 PersonValue[]
+    case 'person_single': {
+      const v = value as PersonValue | null | undefined
+      return (
+        <PeoplePicker
+          size="sm"
+          value={v ?? null}
+          people={colInfo?.people ?? []}
+          onChange={(next) => onChange(next[0] ?? null)}
+          aria-label={ariaLabel}
+          className={className}
+        />
+      )
+    }
+    case 'person_multi': {
+      const v = Array.isArray(value) ? (value as PersonValue[]) : []
+      return (
+        <PeoplePicker
+          size="sm"
+          value={v}
+          people={colInfo?.people ?? []}
+          onChange={(next) => onChange(next)}
+          aria-label={ariaLabel}
+          className={className}
+        />
+      )
+    }
+    default:
+      return null
+  }
+}

package/src/components/DataTable/data-table.spec.md

@@ -305,7 +305,7 @@ type FilterTreeNested = { mode: 'nested'; conjunction: 'and'|'or'; children: Fil
 
 ### 三、Operator × ValueShape SSOT
 
-`filter-operators.ts` 的 `OPERATOR_REGISTRY: Record<ColumnType, OperatorSpec[]>` 是唯一 truth。Panel 完全 data-driven:field 選 → load op set → 選 op → 由 `valueShape` dispatch picker(`filter-value-picker.tsx`)。`is_set` / `is_not_set` / `is_true` / `is_false`(`ValueShape='none'`)不渲 picker。
+`filter-operators.ts` 的 `OPERATOR_REGISTRY: Record<ColumnType, OperatorSpec[]>` 是唯一 truth。Panel 完全 data-driven:field 選 → load op set → 選 op → 由 `valueShape` dispatch picker(`data-table-filter-value-picker.tsx`,@internal;2026-07-14 file-size 拆檔自 panel)。`is_set` / `is_not_set` / `is_true` / `is_false`(`ValueShape='none'`)不渲 picker。
 
 ValueShape ↔ DS picker 對照(canonical 2026-05-02):
 

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

@@ -5,13 +5,16 @@
 // 每個檔過 M21 / M17 / Rule-of-3 三 test:
 //   - data-table.tsx(主,foundational)
 //   - data-table-filter-panel.tsx + data-table-sort-manager.tsx + data-table-column-visibility-panel.tsx(panel state 隔離)
+//   - data-table-filter-group.tsx + data-table-filter-value-picker.tsx(@internal;2026-07-14 filter panel
+//     過 800 hard cap 拆檔 — row/nested-group renderer + ValueShape picker,只被 panel 消費)
 //   - cell-registry.tsx(column type → cell display / edit 解析 SSOT)
 //   - data-table-interaction-layer.tsx + active-editor-controller.ts(spreadsheet overlay + portal editor)
 //   - column-types.ts + filter-operators.ts(✓ Rule-of-3 SSOT,3+ consumer)
 //   - filter-tree.ts(pure data + eval,test isolation)
 //   - lib/column-meta.ts(Internal SSOT,消 5 處 `(col as any)`)
 //   - + stories / spec / css
-// M21 retract:filter-value-picker.tsx 1 consumer → 已 inline 回 panel。
+// M21 retract:filter-value-picker.tsx 1 consumer → 2026-05-03 inline 回 panel(上列 2026-07-14
+//   @internal 拆檔非 M21 迴轉:非 public 抽象,file-size hard cap 驅動,consumer 仍只見 panel)。
 import * as React from 'react'
 import { createPortal } from 'react-dom'
 import { Empty } from '@/design-system/components/Empty/empty'

package/src/components/DataTable/filter-operators.spec.md

@@ -1,6 +1,6 @@
 # Advanced Filter 設計原則(Operator × ColumnType × ValueShape SSOT,v3)
 
-> **狀態**:已落地 — registry 寫成 `filter-operators.ts`,`filter-tree.ts` + `data-table-filter-panel.tsx` 消費(原 draft 兩個升級條件皆已達成,2026-06-11 對齊)。
+> **狀態**:已落地 — registry 寫成 `filter-operators.ts`,`filter-tree.ts` + filter panel 家族消費(`data-table-filter-panel.tsx`;row/picker 直接消費點在 2026-07-14 拆檔子模組 `data-table-filter-group.tsx` / `data-table-filter-value-picker.tsx`)(原 draft 兩個升級條件皆已達成,2026-06-11 對齊)。
 > **M8 benchmark**:對照 ClickUp(CU)/ Airtable(AT)/ Notion(NT)三家。**v3 加 datetime / includeTime + 砍 number.between(2/3 業界共識)**。
 > **設計路線**:**ClickUp 為 baseline**,合理 + 不衝突 + 真實用的擴充採納。
 > **檔位**:暫放 DataTable/,若決定抽 `patterns/advanced-filter/` 再搬。
@@ -133,7 +133,7 @@
 | 1-to-1 比對 | ✓ `is` / `is_not`(picker 多選 OR-語意) | ✗ 不適用(陣列比單值 ambiguous) |
 | 集合運算 | ✗ 不適用 | ✓ `has_any_of` / `has_all_of` / `has_none_of` |
 
-差異**根源於 cell 資料形狀**,不是 picker 不同。Value picker 兩者都共用 `<Combobox>` DS 既有元件(code 真值 `data-table-filter-panel.tsx` select_multi case)。
+差異**根源於 cell 資料形狀**,不是 picker 不同。Value picker 兩者都共用 `<Combobox>` DS 既有元件(code 真值 `data-table-filter-value-picker.tsx` select_multi case;2026-07-14 拆檔自 panel)。
 
 ### `person`(4 ops — 跟 select 同邏輯)
 | op key | 中 | en | valueShape | CU | AT | NT |
@@ -238,7 +238,7 @@
 
 **技術坑(信心 85%,Phase B spec.md 詳)**:TanStack `ColumnFiltersState` per-column 一筆 filter value,N 條同 column 會 AND-chain 不能 OR。**業界標準解法**:棄用 `columnFilters`,改自管 FilterTree state + 用 `globalFilter` + 自訂 `globalFilterFn` 走樹求 boolean。
 
-## 8. 邊界案例(code 真值 — `filter-tree.ts` / `data-table-filter-panel.tsx`)
+## 8. 邊界案例(code 真值 — `filter-tree.ts` / filter panel 家族:`data-table-filter-panel.tsx` + `data-table-filter-group.tsx`)
 
 - **Condition 值空 / 未選 field**:視為 incomplete,求值 **pass-through**(不過濾任何 row);空值 ≠ `is_not_set`(後者是顯式 op)— `isConditionComplete` 守門
 - **群組刪光 condition**:空群組保留並 pass-through(true),panel 顯示「移除空群組」按鈕由 user 顯式刪除,不自動消失

package/src/components/Field/index.ts

@@ -3,3 +3,4 @@
 //   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
 // Regenerate: node scripts/gen-component-indexes.mjs
 export * from './field'
+export * from './field-types'

package/src/components/Select/select.spec.md

@@ -13,6 +13,8 @@ benchmark:
   - Polaris Select: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Select
 ---
 
+<!-- @spec-budget-exception: SSOT-heavy 例外(CLAUDE.md 行數預算「foundational SSOT 例外 ≤800-1200」)— 本檔持有跨元件 SSOT:「與 RadioGroup 的分界」(~40 行)+ 3 筆拍板記錄(2026-07-13 D2 hidden-input mirror / 2026-05-21 D3 dual-mode / 2026-06-12 R2 open-pair 例外);2026-07-14 knowledge-prune P2 結論「殘餘超標內容全是 canonical,再砍必動 meaning」(.claude/logs/prune-p2-candidates.md)。 -->
+
 <!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
 
 # Select 設計原則

package/src/index.ts

@@ -246,12 +246,16 @@ export {
   FieldError,
   FieldGroup,
   FieldLabel,
+  getMenuListMinHeight,
   useFormValidation,
 } from './components/Field/index'
 export type {
   FieldGroupProps,
   FieldLabelProps,
+  FieldMode,
   FieldProps,
+  FieldVariant,
+  FieldWidth,
   FormFieldInputProps,
   UseFormValidationOptions,
   UseFormValidationReturn,

package/src/tokens/color/color.spec.md

@@ -649,7 +649,7 @@ Dark mode 覆寫：hover/active 方向反轉（hover → step-7，active → ste
 
 | Token | 答 | 語意 | 典型場景(real consumer grep verified 2026-05-20) |
 |---|---|---|---|
-| `bg-muted`(neutral-2) | **是** | **靜態非互動 surface** — 退化 / placeholder / locked 視覺 | Skeleton(`skeleton.tsx:10`) / DataTable table header(`data-table.tsx:312 HEADER_BG`) / Calendar 非當月日格(`calendar.tsx:316`)/ Alert neutral(`alert.tsx:30`)/ DataTable filter-panel inner group container(`data-table-filter-panel.tsx:784`)/ tab 容器 / code block / scrollbar track(`semantic.css:367`)/ anatomy `<th>` |
+| `bg-muted`(neutral-2) | **是** | **靜態非互動 surface** — 退化 / placeholder / locked 視覺 | Skeleton(`skeleton.tsx:10`) / DataTable table header(`data-table.tsx:312 HEADER_BG`) / Calendar 非當月日格(`calendar.tsx:316`)/ Alert neutral(`alert.tsx:30`)/ DataTable filter-panel inner group container(`data-table-filter-group.tsx:202`,2026-07-14 拆檔自 filter-panel)/ tab 容器 / code block / scrollbar track(`semantic.css:367`)/ anatomy `<th>` |
 | `bg-secondary`(neutral-3) | **否,只是視覺退後一級** | **存在且微淡可辨** — 元素是正常狀態,但需要退後一級 | Tag neutral(`tag.tsx`)/ Slider rest track(`slider.tsx`)/ FileItem compact-B progress track(`file-item.tsx`)/ Badge low(`badge.tsx:37`)/ CircularProgress track(`circular-progress.tsx:150`)/ Steps fillBg(`steps.tsx:698,715`)/ ProgressBar track(`progress-bar.tsx`)|
 
 **判斷法**:「這個元素是『還沒準備好 / 不可操作』嗎?」

package/src/tokens/uiSize/uiSize.css

@@ -75,7 +75,7 @@
   --tree-indent-lg: 1.75rem;    /* 28px */
 
   /* DataTable Panel Widths — Sort manager / Filter panel cells(SSOT,2026-05-23 deep-audit Phase A.4 Decision 2 codify per user verbatim「決策二照你建議做」+「確保最SSOT最簡潔」)
-     Consumer:data-table-sort-manager.tsx / data-table-filter-panel.tsx
+     Consumer:data-table-sort-manager.tsx / data-table-filter-group.tsx(FilterRow;2026-07-14 拆檔自 filter-panel)
      不 density-scale(panels 是 floating layout,不該跟密度走)
      Naming aligned to family `--<component>-<part>-<size>`(per --field-height-* / --table-row-* / --tab-height-* precedent)*/
   --data-table-sort-panel-width: 30rem;       /* 480px — sort manager root container width */