@qijenchen/design-system 0.1.0-beta.3

package/src/components/DataTable/column-types.ts

@@ -0,0 +1,180 @@
+import type { RowData } from '@tanstack/react-table'
+
+// ── Column Types ─────────────────────────────────────────────────────────────
+
+// ── Column Types ─────────────────────────────────────────────────────────────
+//
+// 命名原則:描述**資料型別**本身,不是視覺變體。命名要避開撞 Button `variant` 值。
+// `string` / `url` 是世界級 DS(Atlassian / Notion / Ant Table)的資料型別用語,
+// 跟 Button 的視覺變體 `text` / `link` 在 consumer 心智不會混淆。
+export const columnTypes = [
+  'string',      // 前身為 'text',因撞 Button variant="text"(文字樣式按鈕)改名
+  'number',
+  'currency',
+  'date',
+  'time',        // Phase C(2026-05-05):time-only column,渲 `<TimePicker>`
+  'select',
+  'multiSelect',
+  'person',
+  'multiPerson',
+  'boolean',
+  'url',         // 前身為 'link',因撞 Button variant="link"(連結樣式按鈕)改名
+] as const
+
+export type ColumnType = (typeof columnTypes)[number]
+
+// ── Column Type Config ───────────────────────────────────────────────────────
+
+export interface ColumnTypeConfig {
+  /** Default horizontal alignment */
+  align: 'left' | 'right' | 'center'
+  // L3: sortingFn
+  // L4: filterVariant, filterFn
+  // L5: cellRenderer, cellEditor
+}
+
+/** Default config per column type */
+export const columnTypeDefaults: Record<ColumnType, ColumnTypeConfig> = {
+  string:      { align: 'left' },
+  number:      { align: 'right' },
+  currency:    { align: 'right' },
+  date:        { align: 'left' },
+  time:        { align: 'left' },
+  select:      { align: 'left' },
+  multiSelect: { align: 'left' },
+  person:      { align: 'left' },
+  multiPerson: { align: 'left' },
+  boolean:     { align: 'left' },
+  url:         { align: 'left' },
+}
+
+// ── Extend TanStack Table ColumnMeta ─────────────────────────────────────────
+
+declare module '@tanstack/react-table' {
+  interface ColumnMeta<TData extends RowData, TValue> {
+    /**
+     * Column data type — determines default alignment, rendering, sorting, filtering.
+     *
+     * **Filterable column 必須設此 prop**(filter UI 只列有 `type` 的 column,
+     * 對齊 Notion / Airtable / Linear:每 property 強制有 type)。
+     */
+    type?: ColumnType
+    /** Override default alignment from column type */
+    align?: 'left' | 'right' | 'center'
+    /** Allow text wrapping (only effective when autoRowHeight is true) */
+    wrap?: boolean
+    /**
+     * Max visible lines before ellipsis(2026-05-14 I9 per codex verdict + user 拍板)。
+     * Only effective when `autoRowHeight + wrap=true`。Display 用 `line-clamp-N`,edit textarea
+     * 高度 match clamp。對齊 Notion 「Truncate」row toggle / AG Grid `cellClassRules` 上限 row height。
+     * Default = undefined(無 clamp,完整 wrap)。
+     */
+    maxLines?: number
+    /**
+     * Column 寬度(px)— DS canonical 命名(2026-05-06 v14.3)。
+     *
+     * **為何不用 TanStack 的 `size`** — DS 內 `size` 既定意為元件 density string
+     * `'sm' | 'md' | 'lg'`(Field / Button / Input 等 49+ 處 use case)。Column 寬
+     * 是 px 數字,跟 density 概念衝突 → 走 DS-internal 命名 `width`/`minWidth`/`maxWidth`
+     * (對齊 CSS 原生 + AG Grid 的命名共識)。
+     *
+     * 內部 pre-process 會把 `meta.width` copy 到 TanStack 的 root `size`,確保 column
+     * resize feature(`enableColumnResize=true` 拖拉 + columnSizing state)正常運作。
+     *
+     * - **No resize mode**(default): `width` = column 寬度 reserve(cell ≥ width,
+     *   flex 可 grow,**不可 shrink** 低於 width)。對齊 user 預期「我設多寬就多寬」。
+     * - **Resize mode**(`enableColumnResize=true`):`width` = 初始寬度,user 可拖拉
+     *   到 `minWidth` 為止。
+     */
+    width?: number
+    /**
+     * Column 最小寬度(px)— resize 模式下的拖拉下限。No resize 模式不使用(`width` 即下限)。
+     * Default(resize mode 沒明示時)= 80px(`MIN_COLUMN_WIDTH`)。
+     */
+    minWidth?: number
+    /**
+     * Column 最大寬度(px)— resize 模式下的拖拉上限。預設無上限。
+     */
+    maxWidth?: number
+    /**
+     * Column 是否可被 user 拖拉 resize(opt-out per col)。Default `true`(when `enableColumnResize` 也 true)。
+     *
+     * Set `false` 表「此 col 寬度由內容決定不允許 resize」(2026-05-10 加,per user
+     * 「操作列這種內容決定寬度的欄位應該不允許 resize」)。對齊 AG Grid `colDef.resizable` /
+     * Material X-DataGrid 同 API。
+     *
+     * System cols(__select__ / __drag__ / __actions__)自動 false(內部 hard-code,
+     * consumer 不需設)— 永遠固定寬。
+     *
+     * 典型 use case:custom 圖示欄、status indicator 欄、密度太緊不該 user 動的欄。
+     */
+    resizable?: boolean
+    /**
+     * Explicit opt-out from filter UI(預設 accessor column 有 type 即 filterable)。
+     *
+     * 用於:有 `type` 但不想在 filter UI 出現的 accessor column
+     * (例如:internal sorting key、composite display 用的 hidden column)。
+     */
+    filterable?: boolean
+    /** Number/currency formatting options */
+    prefix?: string
+    suffix?: string
+    precision?: number
+    locale?: string
+    /** Select/multiSelect options — maps value to display label */
+    options?: Array<{ value: string; label: string }>
+    /** Date: Intl.DateTimeFormat options */
+    formatOptions?: Intl.DateTimeFormatOptions
+    /**
+     * Date: 是否含時間部分(datetime mode)。對齊 Notion idiom — 不另設 datetime column type。
+     *
+     * - `false`(default):cell 顯示與 filter 比對僅日期(day-level 精度)
+     * - `true`:cell 渲 date+time;filter 比對走 ms 精度(避開 Airtable 著名地雷)
+     *
+     * 在 advanced filter 中,`date` columnType 配 `includeTime=true` 時,
+     * `date_*` ValueShape 自動 promote 到 `datetime_*`,渲 `<DatePicker showTime>` /
+     * `<DatePickerRange showTime>`(詳 `filter-operators.ts` `getValueShape`)。
+     */
+    includeTime?: boolean
+    /** Link: 自訂顯示文字（不設則自動從 URL 提取 hostname） */
+    linkLabel?: string
+    /**
+     * Inline edit:column 是否可編輯。
+     * - `true`:可編
+     * - `false`(default):唯讀
+     * - `(row) => boolean`:per-row 動態決定(e.g. row.status !== 'archived' 才能編)
+     *
+     * 互動 per type(對齊 Notion / Airtable):
+     * - string / number / currency:click cell → inline `<Input>` autoFocus + selected
+     * - date / select / multiSelect / person / multiPerson:click cell → 進 edit mode 的 Field control(用戶按 trigger 開 picker)
+     * - boolean:不分 read/edit mode,直接 `<Checkbox>` 點即 toggle + commit
+     * - url:read = 連結;**hover cell** 右側出 Pencil 按鈕,click 才進 `<Input>` edit mode(保留 click 連結語意)
+     *
+     * Esc cancel / blur or Enter commit。Commit 觸發 `onCellCommit`。
+     */
+    editable?: boolean | ((row: TData) => boolean)
+    /**
+     * Inline disabled state(2026-05-13 Stream C Cluster B Q3 ship,per codex Q3 verdict):
+     * cell 不可操作 state(orthogonal to editable readonly)。
+     * - `true`:cell 永遠 disabled
+     * - `false` / undef(default):cell normal
+     * - `(row) => boolean`:per-row 動態(e.g. row.archived 或 row.locked 才 disabled)
+     *
+     * 視覺(per `color.spec.md` `--bg-disabled` component-state token):
+     * - TD 外殼:`bg-disabled` + `cursor-not-allowed` + 抑制 hover ring
+     * - Cell content(Field family):`mode='disabled'` → 各 Field type 內部走具體 disabled token
+     * - edit entry 抑制:disabled cell 點擊不進 edit(對齊 `editable && !disabled` invariant)
+     *
+     * 跟 `editable=false` 區分:editable=false = readonly(可看不可編);disabled = 不可操作 state。
+     * 對齊 MUI X `isCellEditable` + cellClassName / AG Grid `cellClassRules` / Notion locked properties。
+     */
+    disabled?: boolean | ((row: TData) => boolean)
+    /**
+     * Locked column — column reorder 不可拖,Notion 「primary column」 pattern。
+     * 對齊 SKU / ID 等不可移欄位。
+     */
+    locked?: boolean
+    /** Person/multiPerson edit mode: people pool for picker(2026-05-05 v4 type-augmentation)。 */
+    people?: Array<{ name: string; avatarUrl?: string; description?: string }>
+  }
+}

package/src/components/DataTable/data-table-column-visibility-panel.tsx

@@ -0,0 +1,261 @@
+// @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.
+/**
+ * DataTableColumnVisibilityPanel — Issue 3 primitive(2026-05-10)。
+ *
+ * 從 WithBulkActions story L868+(149 lines)+ RoadmapAllInOne(L1796+,53 lines)抽出 SSOT
+ * primitive。Roadmap demo 跟 WithBulkActions 都用此 panel 開啟「欄位顯示」popover。
+ *
+ * **Feature SSOT**(對齊 Linear / Airtable / Notion / Material X-DataGrid 的 columnVisibility panel idiom):
+ *   - 列出所有 togglable 欄位 + Eye / EyeOff 切換
+ *   - Locked 欄位(`lockedIds`)— 顯 Lock icon,不可 toggle / 不可 drag
+ *   - 可選 search filter(`searchable`,跨欄位 label match)
+ *   - 可選 column drag reorder(`onColumnOrderChange` 傳 → 啟 DnD)
+ *   - 可選 reset 按鈕(`onReset`,header 區 RotateCcw)
+ *   - Bidirectional bulk toggle(footer button:全可見 → 全部隱藏 / 任一隱藏 → 顯示全部)
+ *
+ * **Why 抽 primitive**(per Issue 3 Rule-of-3):RoadmapAllInOne + WithBulkActions + 未來 product
+ * UI 至少 3 處消費同 panel。重複 hand-craft → 設計語言 drift(已抓到:Roadmap 版無 search /
+ * 無 drag / 無 reset,WithBulkActions 版有,語意不一致)。Primitive 把所有 feature 集中,
+ * consumer opt-in via props 確保 SSOT。
+ *
+ * **對齊**:Linear column-visibility-panel pattern / Material X-DataGrid `<GridColumnsPanel>`
+ * / Airtable Field-config drawer。
+ */
+
+import * as React from 'react'
+import { Eye, EyeOff, Lock, GripVertical, Search, RotateCcw, X as XIcon } from 'lucide-react'
+import { Button } from '@/design-system/components/Button/button'
+import { ButtonDivider } from '@/design-system/components/Button/button-group'
+import { Input } from '@/design-system/components/Input/input'
+import { ScrollArea } from '@/design-system/components/ScrollArea/scroll-area'
+import { PopoverHeader, PopoverFooter, PopoverTitle, PopoverClose } from '@/design-system/components/Popover/popover'
+import { ItemPrefix, ItemLabel, ItemInlineActionButton, ROW_PADDING_BY_SIZE } from '@/design-system/patterns/element-anatomy/item-anatomy'
+import { cn } from '@/lib/utils'
+import { DndContext, closestCenter, type DragEndEvent } from '@dnd-kit/core'
+import { SortableContext, useSortable, verticalListSortingStrategy } from '@dnd-kit/sortable'
+import { CSS } from '@dnd-kit/utilities'
+import { dragSourceStyle } from '@/design-system/lib/drag-visual'
+
+interface ColumnVisibilityPanelColumn {
+  /** Column id(stable identifier;對齊 DataTable column.id / accessorKey)*/
+  id: string
+  /** Column header label(human-readable)*/
+  label: string
+}
+
+export interface DataTableColumnVisibilityPanelProps {
+  /** 全部可 toggle 欄位(consumer 已過濾掉 system cols 如 __select__)*/
+  columns: ColumnVisibilityPanelColumn[]
+  /** 受控 visibility map(`true` / undefined = visible / `false` = hidden)*/
+  visibility: Record<string, boolean>
+  /** Visibility 變更 callback */
+  onVisibilityChange: (next: Record<string, boolean>) => void
+  /** 受控 column order(若提供啟 DnD reorder) */
+  columnOrder?: string[]
+  /** Order 變更 callback;若提供 → 啟用 drag handle / DnD reorder */
+  onColumnOrderChange?: (next: string[]) => void
+  /** Locked column ids(顯 Lock icon,不可 toggle / 不可 drag)*/
+  lockedIds?: string[]
+  /** 是否啟搜尋 input(預設 false)*/
+  searchable?: boolean
+  /** 是否顯 reset button(任一欄隱藏才顯,onClick 清空 visibility map)*/
+  resettable?: boolean
+  // Issue 3 post-codex audit(2026-05-10):`onClose` prop retired — Radix `PopoverClose asChild`
+  // 已自帶 popover dismiss,沒 concrete consumer 需 callback。Future 若需要再加。
+}
+
+export function DataTableColumnVisibilityPanel({
+  columns,
+  visibility,
+  onVisibilityChange,
+  columnOrder,
+  onColumnOrderChange,
+  lockedIds = [],
+  searchable = false,
+  resettable = false,
+}: DataTableColumnVisibilityPanelProps) {
+  const [search, setSearch] = React.useState('')
+  const lockedSet = React.useMemo(() => new Set(lockedIds), [lockedIds])
+  const dndEnabled = !!(columnOrder && onColumnOrderChange)
+
+  // 計算 visible order:用 columnOrder 排,fallback columns 順序。
+  const orderedIds = React.useMemo(() => {
+    if (columnOrder && columnOrder.length > 0) {
+      const colSet = new Set(columns.map((c) => c.id))
+      return columnOrder.filter((id) => colSet.has(id))
+    }
+    return columns.map((c) => c.id)
+  }, [columnOrder, columns])
+
+  const filteredEntries = React.useMemo(() => {
+    return orderedIds
+      .map((id) => columns.find((c) => c.id === id))
+      .filter((c): c is ColumnVisibilityPanelColumn => c != null)
+      .filter((c) => (search ? c.label.toLowerCase().includes(search.toLowerCase()) : true))
+  }, [orderedIds, columns, search])
+
+  const togglableIds = columns.map((c) => c.id).filter((id) => !lockedSet.has(id))
+  const allVisible = togglableIds.every((id) => visibility[id] !== false)
+  const anyHidden = togglableIds.some((id) => visibility[id] === false)
+
+  const handleToggle = (id: string) => {
+    const visible = visibility[id] !== false
+    onVisibilityChange({ ...visibility, [id]: !visible })
+  }
+
+  const handleReset = () => onVisibilityChange({})
+
+  const handleBulkToggle = () => {
+    if (allVisible) {
+      const next: Record<string, boolean> = {}
+      togglableIds.forEach((id) => { next[id] = false })
+      onVisibilityChange(next)
+    } else {
+      onVisibilityChange({})
+    }
+  }
+
+  const handleDragEnd = (e: DragEndEvent) => {
+    if (!dndEnabled) return
+    const { active, over } = e
+    if (!over || active.id === over.id) return
+    const oldIdx = columnOrder!.indexOf(active.id as string)
+    const newIdx = columnOrder!.indexOf(over.id as string)
+    if (oldIdx < 0 || newIdx < 0) return
+    // Locked id 不可被 reorder 動到
+    if (lockedSet.has(columnOrder![oldIdx]) || lockedSet.has(columnOrder![newIdx])) return
+    const next = [...columnOrder!]
+    const [m] = next.splice(oldIdx, 1)
+    next.splice(newIdx, 0, m)
+    onColumnOrderChange!(next)
+  }
+
+  return (
+    <>
+      <PopoverHeader hideClose>
+        <div className="flex items-center gap-1 w-full min-w-0">
+          <PopoverTitle className="flex-1">欄位顯示</PopoverTitle>
+          {resettable && anyHidden && (
+            <>
+              <Button
+                variant="text" size="sm" iconOnly startIcon={RotateCcw}
+                aria-label="恢復預設"
+                onClick={handleReset}
+              />
+              <ButtonDivider />
+            </>
+          )}
+          <PopoverClose asChild>
+            <Button data-dismiss iconOnly dismiss size="sm" startIcon={XIcon} aria-label="關閉" />
+          </PopoverClose>
+        </div>
+      </PopoverHeader>
+      {searchable && (
+        <div className="px-[var(--layout-space-loose)] pt-[var(--layout-space-tight)]">
+          <Input
+            size="md"
+            placeholder="搜尋欄位…"
+            value={search}
+            onChange={(e) => setSearch(e.target.value)}
+            startIcon={Search}
+          />
+        </div>
+      )}
+      <ScrollArea className="max-h-72">
+        <div className="py-2 flex flex-col" style={{ '--item-prefix-slot': '16px' } as React.CSSProperties}>
+          {dndEnabled ? (
+            <DndContext collisionDetection={closestCenter} onDragEnd={handleDragEnd}>
+              <SortableContext
+                items={filteredEntries.map((e) => e.id).filter((id) => !lockedSet.has(id))}
+                strategy={verticalListSortingStrategy}
+              >
+                {filteredEntries.map(({ id, label }) => (
+                  <VisibilityRow
+                    key={id}
+                    id={id}
+                    label={label}
+                    visible={visibility[id] !== false}
+                    locked={lockedSet.has(id)}
+                    draggable
+                    onToggle={() => handleToggle(id)}
+                  />
+                ))}
+              </SortableContext>
+            </DndContext>
+          ) : (
+            filteredEntries.map(({ id, label }) => (
+              <VisibilityRow
+                key={id}
+                id={id}
+                label={label}
+                visible={visibility[id] !== false}
+                locked={lockedSet.has(id)}
+                draggable={false}
+                onToggle={() => handleToggle(id)}
+              />
+            ))
+          )}
+        </div>
+      </ScrollArea>
+      <PopoverFooter className="justify-start">
+        <Button variant="tertiary" size="sm" onClick={handleBulkToggle}>
+          {allVisible ? '全部隱藏' : '顯示全部'}
+        </Button>
+      </PopoverFooter>
+    </>
+  )
+}
+
+// VisibilityRow:single column row。Draggable mode → GripVertical handle / static mode → 無 handle。
+function VisibilityRow({
+  id, label, visible, locked, draggable, onToggle,
+}: {
+  id: string
+  label: string
+  visible: boolean
+  locked: boolean
+  draggable: boolean
+  onToggle: () => void
+}) {
+  // Conditional hooks 不行 — 永遠呼 useSortable,只是 disabled 時 listeners no-op
+  const sortable = useSortable({ id, disabled: locked || !draggable })
+  const { attributes, listeners, setNodeRef, transform, transition, isDragging } = sortable
+  const style: React.CSSProperties = draggable
+    ? { transform: CSS.Transform.toString(transform), transition, ...dragSourceStyle(isDragging) }
+    : {}
+  return (
+    <div
+      ref={draggable ? setNodeRef : undefined}
+      style={style}
+      className={cn(
+        'flex items-start gap-2 w-full px-[var(--layout-space-loose)]',
+        ROW_PADDING_BY_SIZE.md,
+      )}
+    >
+      <ItemPrefix>
+        {/* 2026-05-18 改 per user「做完」approval:14 → 16 對齊 uiSize.spec.md Icon Tier */}
+        {locked ? (
+          <Lock size={16} className="text-fg-muted" aria-hidden />
+        ) : draggable ? (
+          <ItemInlineActionButton
+            icon={GripVertical}
+            size="md"
+            aria-label="拖曳重排"
+            className="cursor-grab active:cursor-grabbing"
+            {...attributes}
+            {...listeners}
+          />
+        ) : null}
+      </ItemPrefix>
+      <ItemLabel className={locked ? 'text-fg-disabled' : undefined}>{label}</ItemLabel>
+      <ItemInlineActionButton
+        icon={visible ? Eye : EyeOff}
+        size="md"
+        aria-label={visible ? '隱藏此欄' : '顯示此欄'}
+        disabled={locked}
+        onClick={onToggle}
+        className={locked ? 'cursor-not-allowed text-fg-disabled' : ''}
+      />
+    </div>
+  )
+}