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

package/src/components/Combobox/combobox.tsx

@@ -4,9 +4,9 @@
 import * as React from 'react'
 import { X, ChevronDown } from 'lucide-react'
 import { cn } from '@/lib/utils'
-import type { FieldMode, FieldVariant } from '@/design-system/components/Field/field-types'
-import { fieldWrapperStyles, EMPTY_DISPLAY, nakedCellRowModeAlign, fieldDisplayTextClass } from '@/design-system/components/Field/field-wrapper'
-import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldVariant, useResolvedFieldInvalid } from '@/design-system/components/Field/field-context'
+import type { FieldMode, FieldVariant, FieldVariantInternal, FieldWidth } from '@/design-system/components/Field/field-types'
+import { fieldWrapperStyles, nakedCellRowModeAlign, fieldDisplayTextClass } from '@/design-system/components/Field/field-wrapper'
+import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldVariant, useResolvedFieldInvalid, useFieldEmptyDisplay, fieldEmptyColorClass } from '@/design-system/components/Field/field-context'
 import { Tag } from '@/design-system/components/Tag/tag'
 import { ItemInlineAction, ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'
 import { OverflowIndicator } from '@/design-system/components/OverflowIndicator/overflow-indicator'
@@ -326,8 +326,9 @@ function ComboboxTagStack({
   value?: string[] | null; options?: ComboboxOption[]; tagSize?: 'sm' | 'md' | 'lg'
   wrap?: boolean; containerRef?: React.RefObject<HTMLDivElement | null>; disabled?: boolean
 }) {
+  const emptyDisplay = useFieldEmptyDisplay()
   const ownRef = React.useRef<HTMLDivElement>(null)
-  if (!value || value.length === 0) return <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
+  if (!value || value.length === 0) return <span className={fieldEmptyColorClass(disabled ? 'disabled' : 'display')}>{emptyDisplay}</span>
   const items = value.map(v => ({ value: v, label: options?.find(o => o.value === v)?.label ?? v }))
   const disabledClass = disabled ? 'bg-disabled text-fg-disabled' : undefined
 
@@ -366,6 +367,10 @@ export interface ComboboxProps {
   mode?: FieldMode
   /** Field chrome variant. Default = context.variant ?? 'default'. Per-prop override. */
   variant?: FieldVariant
+  /** 寬度軸 — `fill` 填滿容器(default)/ `hug` 依內容收縮:value 寬 + slot 元素寬 + gap +
+   *  field 內 padding;chrome 與互動不變。場景 = detail pane inline metadata。
+   *  SSOT → field-controls.spec.md「寬度軸(width: fill / hug)」。 */
+  width?: FieldWidth
   error?: boolean
   size?: 'sm' | 'md' | 'lg'
   options: ComboboxOption[]
@@ -485,9 +490,13 @@ const getIconSize = (size: string) => ICON_SIZE[size as 'sm' | 'md' | 'lg']
 // ── Shared readonly/disabled/display render ─────────────────────────────────
 
 function ReadonlyMultiSelect({
-  mode, variant: variantProp, size, options, value, wrap, className, showDisplayEndIcon = false,
-}: Pick<ComboboxProps, 'mode' | 'variant' | 'size' | 'options' | 'value' | 'wrap' | 'className' | 'showDisplayEndIcon'>) {
+  mode, variant: variantProp, width, size, options, value, wrap, className, showDisplayEndIcon = false,
+}: Pick<ComboboxProps, 'mode' | 'width' | 'size' | 'options' | 'value' | 'wrap' | 'className' | 'showDisplayEndIcon'> & {
+  /** @internal 2026-07-14 API 策展 E:內部 render helper 吃 FieldVariantInternal(naked 由 cell-registry 通道傳入)*/
+  variant?: FieldVariantInternal
+}) {
   const resolvedMode = mode ?? 'readonly'
+  const emptyDisplay = useFieldEmptyDisplay()
   const variant = variantProp ?? 'default'
   const sz = size ?? 'md'
   const iconSize = sz === 'lg' ? 20 : 16
@@ -503,20 +512,20 @@ function ReadonlyMultiSelect({
     if (!showDisplayEndIcon) {
       // 2026-05-14 I2 fix(spec contract (e) display typography canonical):empty bare span 套
       // `fieldDisplayTextClass(sz)`(sm/md→text-body,lg→text-body-lg)— 對齊跨 Field family 統一。
-      if (!hasTags) return <span className={cn(fieldDisplayTextClass(sz), 'text-fg-muted', className)}>{EMPTY_DISPLAY}</span>
+      if (!hasTags) return <span className={cn(fieldDisplayTextClass(sz), fieldEmptyColorClass(resolvedMode), className)}>{emptyDisplay}</span>
       return (
         <ComboboxTagStack value={value} options={options} tagSize={sz} wrap={wrap} />
       )
     }
     return (
       <div
-        className={cn(fieldWrapperStyles({ mode: 'display', variant, size: sz }), hasTags && tagPadding[sz], className)}
+        className={cn(fieldWrapperStyles({ mode: 'display', variant, width, size: sz }), hasTags && tagPadding[sz], className)}
         data-field-mode="display"
       >
         {hasTags ? (
           <ComboboxTagStack value={value} options={options} tagSize={sz} wrap={wrap} />
         ) : (
-          <span className={cn('flex-1 min-w-0', 'text-fg-muted')}>{EMPTY_DISPLAY}</span>
+          <span className={cn('flex-1 min-w-0', fieldEmptyColorClass(resolvedMode))}>{emptyDisplay}</span>
         )}
         <ItemSuffix className="pointer-events-none">
           <ChevronDown size={iconSize} className="shrink-0 text-fg-muted" aria-hidden />
@@ -527,7 +536,7 @@ function ReadonlyMultiSelect({
 
   return (
     <div ref={containerRef}
-      className={cn(fieldWrapperStyles({ mode: resolvedMode, variant, size: sz }), hasTags && tagPadding[sz],
+      className={cn(fieldWrapperStyles({ mode: resolvedMode, variant, width, size: sz }), hasTags && tagPadding[sz],
         // 2026-05-18 #6A Round 1 Step 1/4(per user 拍板「決策6選a」+ codex M31 Step 5 verdict cite combobox.tsx:451):
         // readonly/disabled path 對齊 L293 display wrapper 已 ship 的 overflow-hidden fix。
         // M10 propagation:原 overflow-visible 讓 readonly tag 越界蓋 indicator,跟 display 不對稱。
@@ -540,7 +549,7 @@ function ReadonlyMultiSelect({
         <ComboboxTagStack value={value} options={options} tagSize={sz} wrap={wrap}
           containerRef={containerRef} disabled={resolvedMode === 'disabled'} />
       ) : (
-        <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
+        <span className={fieldEmptyColorClass(resolvedMode)}>{emptyDisplay}</span>
       )}
       {/* 2026-06-26 類型身份 indicator:edit 顯示 / readonly 不顯示(純值、不可開下拉) / disabled 保留(fg-disabled,對齊原生 <select disabled>);naked cell 依 showDisplayEndIcon */}
       {(variant === 'naked' ? !!showDisplayEndIcon : resolvedMode === 'disabled') && (
@@ -567,12 +576,16 @@ function ReadonlyMultiSelect({
 type ComboboxInternalProps = ComboboxProps & { __triggerRef?: React.Ref<HTMLDivElement> }
 
 function NativeCombobox({
-  mode, variant: variantProp, error = false, size = 'md', options, value = [], onChange, placeholder,
+  mode, variant: variantProp, width, error = false, size = 'md', options, value = [], onChange, placeholder,
   className, disabled: disabledProp, wrap = false, clearable = false, showDisplayEndIcon = false,
   __triggerRef,
+  'aria-label': ariaLabel,
 }: ComboboxInternalProps) {
+  // a11y(2026-07-14 dim10):touch/native 路徑同樣接 fieldCtx — id 讓 FieldLabel htmlFor
+  // 命名 native <select>;describedby/errormessage/required 對齊 desktop CustomCombobox trigger。
+  const fieldCtx = useFieldContext()
   const disabled = useResolvedFieldDisabled(disabledProp)
-  const variant: FieldVariant = useResolvedFieldVariant(variantProp)
+  const variant: FieldVariantInternal = useResolvedFieldVariant(variantProp)
   // 2026-06-08 SSOT:mode 經 useResolvedFieldMode;修 <Field mode="display"> 漏 cascade
   const resolvedMode = useResolvedFieldMode({ mode, disabled })
   const iconSize = getIconSize(size)
@@ -588,7 +601,7 @@ function NativeCombobox({
   const tagAreaRef = React.useRef<HTMLDivElement>(null)
 
   if (resolvedMode !== 'edit') {
-    return <ReadonlyMultiSelect mode={resolvedMode} variant={variant} size={size} options={options} value={value} wrap={wrap} className={className} showDisplayEndIcon={showDisplayEndIcon} />
+    return <ReadonlyMultiSelect mode={resolvedMode} variant={variant} width={width} size={size} options={options} value={value} wrap={wrap} className={className} showDisplayEndIcon={showDisplayEndIcon} />
   }
 
   const items = value.map(v => ({ value: v, label: options.find(o => o.value === v)?.label ?? v }))
@@ -597,6 +610,15 @@ function NativeCombobox({
 
   const selectDropdown = unselected.length > 0 ? (
     <select ref={selectRef} value="" onChange={(e) => handleAdd(e.target.value)}
+      // a11y(2026-07-14 dim10):accessible name — FieldLabel htmlFor 經 id 命名 native select;
+      // consumer aria-label 優先,否則 fieldCtx.labelId fallback(對齊 select.tsx:240 accname 優先序)。
+      id={fieldCtx?.id}
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabel ? undefined : fieldCtx?.labelId}
+      aria-invalid={error || undefined}
+      aria-required={fieldCtx?.required || undefined}
+      aria-describedby={fieldCtx?.descriptionId}
+      aria-errormessage={error ? fieldCtx?.errorId : undefined}
       className={cn('bg-transparent outline-none border-none p-0 text-[inherit] font-[inherit] leading-[inherit] text-fg-muted cursor-pointer appearance-none',
         value.length > 0 ? 'absolute inset-0 w-full h-full opacity-0 z-0 cursor-pointer' : 'relative z-10 flex-1 min-w-20')}>
       <option value="" disabled>{placeholder ?? '選擇...'}</option>
@@ -605,7 +627,7 @@ function NativeCombobox({
   ) : null
 
   return (
-    <div ref={__triggerRef} className={cn(fieldWrapperStyles({ mode: 'edit', variant: variant, size, error }), value.length > 0 && tagPadding[size], 'relative',
+    <div ref={__triggerRef} className={cn(fieldWrapperStyles({ mode: 'edit', variant: variant, width, size, error }), value.length > 0 && tagPadding[size], 'relative',
       wrap && 'items-start py-1', className)}
       style={{ paddingRight: 'var(--field-px)', ...(wrap ? { height: 'auto' } : undefined) }} data-field-mode="edit" data-error={error ? '' : undefined}
       onClick={(e) => { if (e.target === e.currentTarget) { selectRef.current?.showPicker?.(); selectRef.current?.focus() } }}>
@@ -642,7 +664,7 @@ function NativeCombobox({
 // ── Custom Combobox (desktop — consumes SelectMenu) ───────────────────
 
 function CustomCombobox({
-  mode, variant: variantProp, error: errorProp = false, size = 'md', options, value = [], onChange, placeholder,
+  mode, variant: variantProp, width, error: errorProp = false, size = 'md', options, value = [], onChange, placeholder,
   className, disabled: disabledProp, wrap = false, clearable = false, searchable = false, loading, searchIn = 'menu',
   searchPlaceholder = '搜尋…', // i18n-allow: DS default
   searchAriaLabel = '搜尋選項', // i18n-allow: DS default
@@ -668,7 +690,7 @@ function CustomCombobox({
   const disabled = useResolvedFieldDisabled(disabledProp)
   // 2026-06-08 SSOT:mode 經 useResolvedFieldMode;修 <Field mode="display"> 漏 cascade
   const resolvedMode = useResolvedFieldMode({ mode, disabled })
-  const variant: FieldVariant = useResolvedFieldVariant(variantProp)
+  const variant: FieldVariantInternal = useResolvedFieldVariant(variantProp)
   const iconSize = getIconSize(size)
   const showClear = clearable && value.length > 0 && resolvedMode === 'edit'
   const [open, setOpen] = React.useState(defaultOpen)
@@ -723,7 +745,7 @@ function CustomCombobox({
   )
 
   if (resolvedMode !== 'edit') {
-    return <ReadonlyMultiSelect mode={resolvedMode} variant={variant} size={size} options={options} value={value} wrap={wrap} className={className} showDisplayEndIcon={showDisplayEndIcon} />
+    return <ReadonlyMultiSelect mode={resolvedMode} variant={variant} width={width} size={size} options={options} value={value} wrap={wrap} className={className} showDisplayEndIcon={showDisplayEndIcon} />
   }
 
   const chevronEl = <ChevronDown size={iconSize} className={cn('shrink-0 text-fg-muted transition-transform', open && 'rotate-180')} aria-hidden />
@@ -734,11 +756,14 @@ function CustomCombobox({
       id={fieldCtx?.id}
       role="combobox" aria-expanded={open} aria-haspopup="listbox" aria-controls={listboxId} tabIndex={0}
       aria-label={ariaLabel}
+      // a11y(2026-07-14 dim-10):div-based role=combobox 的 <label for> 無效,接 FieldLabel labelId
+      // (field-context.ts labelId jsDoc);consumer aria-label 優先 — 與 sibling select.tsx:705 同款 guard。
+      aria-labelledby={ariaLabel ? undefined : fieldCtx?.labelId}
       aria-invalid={error || undefined}
       aria-required={fieldCtx?.required || undefined}
       aria-describedby={fieldCtx?.descriptionId}
       aria-errormessage={error ? fieldCtx?.errorId : undefined}
-      className={cn(fieldWrapperStyles({ mode: 'edit', variant: variant, size, error }), value.length > 0 && tagPadding[size], 'relative cursor-pointer',
+      className={cn(fieldWrapperStyles({ mode: 'edit', variant: variant, width, size, error }), value.length > 0 && tagPadding[size], 'relative cursor-pointer',
         wrap && 'items-start py-1',
         // 2026-05-06 v13.3 SSOT retire:per-control `open && 'border-primary'` 移除。Field default
         // 統一處理 — open=灰深(data-state)/ focus=藍;2026-07-04 Q1:error 亦收進 error variant。
@@ -752,6 +777,15 @@ function CustomCombobox({
       //   open 後不 preventDefault 讓方向鍵自由流向選單導覽)。
       // 純 additive:此 trigger 原無 onKeyDown,不覆寫既有 handler;open 邏輯仍走 setOpen SSOT。
       onKeyDown={(e) => {
+        // a11y(2026-07-14 dim-10):Enter/Space 來自 descendant 互動元素(Tag 移除 / clear 按鈕)
+        // 時直接放行 —— 否則下方 preventDefault 會取消 native button activation(鍵盤永遠按不動
+        // 按鈕)。guard 限 Enter/Space + button 類:search input 的 Enter 仍走 cmdk 選項選取
+        // (forwardKeyToListbox),Escape / 方向鍵仍走 combobox 導覽。
+        if (
+          (e.key === 'Enter' || e.key === ' ') &&
+          e.target !== e.currentTarget &&
+          (e.target as HTMLElement).closest?.('button, a, [role="button"]')
+        ) return
         // 2026-07-05 D4 P0:open 後 ArrowUp/Down/Enter 轉送 cmdk root(select-menu.tsx forwardKeyToListbox)
         if (open && forwardKeyToListbox(listboxId, e)) return
         if (e.key === 'Enter' || e.key === ' ') {

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

@@ -2,8 +2,8 @@
 //   Inspector / ColorMatrix / SizeMatrix / StateBehavior N/A — Command 是
 //   headless Internal primitive(cmdk passthrough),不被 App 直接消費,而是透過
 //   SelectMenu 等外層元件呈現。色彩 / 尺寸 / 狀態都由消費方(SelectMenu / Combobox /
-//   PeoplePicker)決定並在各自的 anatomy 詳述。本檔僅保留 Overview 教結構與
-//   消費路徑。
+//   PeoplePicker)決定並在各自的 anatomy 詳述。本檔保留 Overview(教結構與
+//   消費路徑)+ Accessibility(6-canonical 中適用的 2 個;2026-05-17 per Dim 13 加)。
 import type { Meta, StoryObj } from '@storybook/react'
 import { Settings, User, LogOut, FileText } from 'lucide-react'
 import {

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

@@ -30,7 +30,7 @@ export const UsageGuidance: Story = {
           <LinkTo kind="Design System/Internal/Command/展示" name="行內搜尋清單"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">行內搜尋清單 — Gmail 式 sidebar 信件資料夾過濾</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Internal/Command/展示" name="外觀切換器"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">外觀切換器 — 選中立即執行的純動作清單</span></LinkTo>
+          <LinkTo kind="Design System/Internal/Command/展示" name="純動作指令"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">純動作指令 — 選中立即執行的快速動作清單</span></LinkTo>
         </li>
         <li>
           <LinkTo kind="Design System/Internal/Command/展示" name="無結果狀態"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">搜尋無結果時的空狀態文案(CommandEmpty)</span></LinkTo>

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

@@ -200,47 +200,79 @@ export const InlineCommand: Story = {
 }
 
 /* ═══════════════════════════════════════════════════════════════════════════
-   Story 3:Theme switcher(純動作 command,無 form value 儲存)
+   Story 3:純動作指令(action command,無 form value 儲存)
+   2026-07-14 dim-68 修:原「外觀切換器」只 2 項固定 action 配搜尋框 —— 正向示範了
+   command.spec.md:75 明文禁止的「< 6 項短選單用 Command」誤用(短選單該用 DropdownMenu /
+   SegmentedControl)。改為快速動作清單(7 項、2 群組),保留本 story 獨有教學點:
+   「選中立即執行、不保留 form value」的純 action palette。
    ═══════════════════════════════════════════════════════════════════════════ */
 
-const ThemeSwitcherDemo = () => {
+const ActionCommandDemo = () => {
   const [theme, setTheme] = useState<'light' | 'dark'>('light')
+  const [lastAction, setLastAction] = useState<string | null>(null)
 
   return (
     <div className="flex flex-col gap-3 max-w-md">
       <p className="text-caption text-fg-muted">
-        純 action palette — 選中立即執行(切 theme),不保留 form value。
+        純 action palette — 選中立即執行(切 theme / 觸發動作),不保留 form value。
+        動作多到需要搜尋才用 Command;&lt; 6 項的短選單用 DropdownMenu(spec「與 DropdownMenu 的分界」)。
       </p>
       <div
         className="rounded-lg border border-border bg-surface-raised overflow-hidden"
         style={{ boxShadow: 'var(--elevation-100)' }}
       >
         <Command>
-          <CommandInput placeholder="切換外觀…" />
+          <CommandInput placeholder="輸入指令…" />
           <CommandList>
-            <CommandEmpty>沒有符合的外觀</CommandEmpty>
+            <CommandEmpty>沒有符合的指令</CommandEmpty>
             <CommandGroup heading="外觀">
-              <CommandItem onSelect={() => setTheme('light')}>
+              <CommandItem onSelect={() => { setTheme('light'); setLastAction('切換淺色模式') }}>
                 <Sun />
                 <span>淺色模式</span>
                 {theme === 'light' && <CommandShortcut>當前</CommandShortcut>}
               </CommandItem>
-              <CommandItem onSelect={() => setTheme('dark')}>
+              <CommandItem onSelect={() => { setTheme('dark'); setLastAction('切換深色模式') }}>
                 <MoonStar />
                 <span>深色模式</span>
                 {theme === 'dark' && <CommandShortcut>當前</CommandShortcut>}
               </CommandItem>
             </CommandGroup>
+            <CommandSeparator />
+            <CommandGroup heading="快速動作">
+              <CommandItem onSelect={() => setLastAction('建立新文件')}>
+                <Plus />
+                <span>建立新文件</span>
+                <CommandShortcut>⌘N</CommandShortcut>
+              </CommandItem>
+              <CommandItem onSelect={() => setLastAction('開啟收件匣')}>
+                <Inbox />
+                <span>開啟收件匣</span>
+              </CommandItem>
+              <CommandItem onSelect={() => setLastAction('加入我的最愛')}>
+                <Star />
+                <span>加入我的最愛</span>
+              </CommandItem>
+              <CommandItem onSelect={() => setLastAction('封存目前頁面')}>
+                <Archive />
+                <span>封存目前頁面</span>
+              </CommandItem>
+              <CommandItem onSelect={() => setLastAction('開啟設定')}>
+                <Settings />
+                <span>開啟設定</span>
+                <CommandShortcut>⌘,</CommandShortcut>
+              </CommandItem>
+            </CommandGroup>
           </CommandList>
         </Command>
       </div>
+      {lastAction && <p className="text-caption text-fg-muted">已執行:{lastAction}</p>}
     </div>
   )
 }
 
-export const ThemeSwitcher: Story = {
-  name: '外觀切換器',
-  render: () => <ThemeSwitcherDemo />,
+export const ActionCommand: Story = {
+  name: '純動作指令',
+  render: () => <ActionCommandDemo />,
 }
 
 /* ═══════════════════════════════════════════════════════════════════════════

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

@@ -9,7 +9,7 @@
 //
 // 設計原則:
 //   - 每個 cell component 接同一組 props(`CellComponentProps`)
-//   - 用 `variant="naked"` — DataTable cell-as-input substrate(對齊 Field B1 chrome=bare)
+//   - 用 `variant="naked"` — DataTable cell-as-input substrate(Field chrome variant;bare 2026-07-09 退役)
 //   - 消費 full Field 家族 primitive(無 stub)
 //   - 不再用 `meta._editable` 私有 flag — `isEditable` 直接顯式入參(消除 M1 hack)
 //
@@ -21,19 +21,37 @@ import type { ComponentType } from 'react'
 import { Pencil } from 'lucide-react'
 import { cn } from '@/lib/utils'
 import type { ColumnType } from './column-types'
-import { Input } from '@/design-system/components/Input/input'
-import { Textarea } from '@/design-system/components/Textarea/textarea'
-import { NumberInput } from '@/design-system/components/NumberInput/number-input'
-import { Select } from '@/design-system/components/Select/select'
-import { Combobox } from '@/design-system/components/Combobox/combobox'
-import { DatePicker } from '@/design-system/components/DatePicker/date-picker'
-import { TimePicker } from '@/design-system/components/TimePicker/time-picker'
-import { PeoplePicker } from '@/design-system/components/PeoplePicker/people-picker'
-import { LinkInput } from '@/design-system/components/LinkInput/link-input'
-import { Checkbox } from '@/design-system/components/Checkbox/checkbox'
+import { Input as InputPublic } from '@/design-system/components/Input/input'
+import { Textarea as TextareaPublic } from '@/design-system/components/Textarea/textarea'
+import { NumberInput as NumberInputPublic } from '@/design-system/components/NumberInput/number-input'
+import { Select as SelectPublic } from '@/design-system/components/Select/select'
+import { Combobox as ComboboxPublic } from '@/design-system/components/Combobox/combobox'
+import { DatePicker as DatePickerPublic } from '@/design-system/components/DatePicker/date-picker'
+import { TimePicker as TimePickerPublic } from '@/design-system/components/TimePicker/time-picker'
+import { PeoplePicker as PeoplePickerPublic } from '@/design-system/components/PeoplePicker/people-picker'
+import { LinkInput as LinkInputPublic } from '@/design-system/components/LinkInput/link-input'
+import { Checkbox as CheckboxPublic } from '@/design-system/components/Checkbox/checkbox'
 import { Button } from '@/design-system/components/Button/button'
 import type { PersonValue } from '@/design-system/components/PeoplePicker/person-display'
-import { FieldSurfaceProvider, FieldSurfaceSizeProvider } from '@/design-system/components/Field/field-context'
+import { FieldSurfaceProvider, FieldSurfaceSizeProvider, FieldSurfaceEditableProvider } from '@/design-system/components/Field/field-context'
+import { makeEditSettleKeyHandler } from '@/design-system/components/Field/field-edit-keys'
+import type { WithFieldVariantInternal } from '@/design-system/components/Field/field-types'
+
+// ── @internal naked variant 通道(2026-07-14 API 策展 E,user 拍板「全部收窄」)──────────────
+// `naked` 已從公開 FieldVariant 拆出(field-types.ts `FieldVariantInternal`);本檔是唯一合法
+// naked 消費者(field-controls.spec.md「軸二 variant」明文)。以 `WithFieldVariantInternal`
+// 型別層 widen 各 Field control 的 `variant` prop — 純型別、零 runtime;元件內部 cva / resolver
+// 分支本就吃 FieldVariantInternal,widen 不引入 unsound 行為。
+const Input = InputPublic as WithFieldVariantInternal<typeof InputPublic>
+const Textarea = TextareaPublic as WithFieldVariantInternal<typeof TextareaPublic>
+const NumberInput = NumberInputPublic as WithFieldVariantInternal<typeof NumberInputPublic>
+const Select = SelectPublic as WithFieldVariantInternal<typeof SelectPublic>
+const Combobox = ComboboxPublic as WithFieldVariantInternal<typeof ComboboxPublic>
+const DatePicker = DatePickerPublic as WithFieldVariantInternal<typeof DatePickerPublic>
+const TimePicker = TimePickerPublic as WithFieldVariantInternal<typeof TimePickerPublic>
+const PeoplePicker = PeoplePickerPublic as WithFieldVariantInternal<typeof PeoplePickerPublic>
+const LinkInput = LinkInputPublic as WithFieldVariantInternal<typeof LinkInputPublic>
+const Checkbox = CheckboxPublic as WithFieldVariantInternal<typeof CheckboxPublic>
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
@@ -81,18 +99,15 @@ function makeKeyHandler(
   onCancel?: () => void,
   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()
+  // 消費 edit-in-place 鍵盤結算 SSOT(field-edit-keys.ts):IME guard + Enter/Esc dispatch 統一
+  // (2026-07-09 抽出;原本 InlineEdit 漏 IME guard = bug,現同源)。value 讀取為 input-specific,留本地。
+  return makeEditSettleKeyHandler({
+    onCommit: (e) => {
       const raw = (e.target as HTMLInputElement).value
       onCommit?.(parseValue ? parseValue(raw) : raw)
-    }
-  }
+    },
+    onCancel: () => onCancel?.(),
+  })
 }
 
 const sizeForInput = (size: CellSize): CellSize => size
@@ -151,15 +166,13 @@ function StringCell({ value, meta, mode, size, isDisabled, autoRowHeight, onComm
         style={{ fieldSizing: 'content' } as React.CSSProperties}
         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()
-            onCommit?.((e.target as HTMLTextAreaElement).value)
-          }
-        }}
+        // 多行:走 edit-in-place 鍵盤結算 SSOT(IME guard + Esc + Cmd/Ctrl+Enter commit;
+        // plain Enter=換行)。commitOnEnter:false → 純 Enter 不攔。
+        onKeyDown={makeEditSettleKeyHandler({
+          onCommit: (e) => onCommit?.((e.target as HTMLTextAreaElement).value),
+          onCancel: () => onCancel?.(),
+          commitOnEnter: false,
+        })}
       />
     )
   }
@@ -216,12 +229,12 @@ function NumberCell({ value, meta, mode, size, isDisabled, onCommit, onCancel, o
       suffix={meta?.suffix}
       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) }
-      }}
+      // 單行:走 edit-in-place 鍵盤結算 SSOT(IME guard + Esc + Enter commit)。
+      // commit localValue(controlled state,非 e.target.value)。
+      onKeyDown={makeEditSettleKeyHandler({
+        onCommit: () => onCommit?.(localValue),
+        onCancel: () => onCancel?.(),
+      })}
     />
   )
 }
@@ -237,7 +250,7 @@ const dismissOnClose = (onCancel?: () => void) => (open: boolean) => { if (!open
 // Fix:`key={mode}` 強制 React unmount + remount,每次切 mode 都重跑 useState init。
 // 對齊 Notion / Airtable cell-as-input「display 跟 edit 是不同 mount cycle」語義。
 
-function DateCell({ value, meta, mode, size, isDisabled, isEditable, onCommit, onCancel }: CellComponentProps) {
+function DateCell({ value, meta, mode, size, isDisabled, onCommit, onCancel }: CellComponentProps) {
   if (mode === 'display') {
     return (
       <DatePicker
@@ -248,10 +261,10 @@ function DateCell({ value, meta, mode, size, isDisabled, isEditable, onCommit, o
         size={size}
         formatOptions={meta?.formatOptions}
         locale={meta?.locale}
-        // Indicator(calendar icon)= editable affordance(2026-05-10 user 糾正)。
-        // Non-editable cell 不該顯 picker indicator(誤導 read-only 為 editable)。
-        // 對齊 UrlCell L394 / BooleanCell L368 既有 isEditable conditional pattern。
-        showDisplayEndIcon={isEditable === true}
+        // 2026-07-08 user 拍板 A 案(推翻 2026-05-10/06-26 兩次拍板,per 6 家 benchmark 6/6 共識
+        // Ant/MUI X/AG Grid/Atlaskit/Notion/Airtable:display 態零恆顯型別 icon;editable
+        // affordance 統一 = hover outline(field.spec.md L4)。showDisplayEndIcon 不再傳
+        //(prop 保留為 spreadsheet-flavored 消費端 opt-in 逃生門,見 field.spec.md L6)。
       />
     )
   }
@@ -270,7 +283,7 @@ function DateCell({ value, meta, mode, size, isDisabled, isEditable, onCommit, o
   )
 }
 
-function TimeCell({ value, meta, mode, size, isDisabled, isEditable, onCommit, onCancel }: CellComponentProps) {
+function TimeCell({ value, meta, mode, size, isDisabled, onCommit, onCancel }: CellComponentProps) {
   if (mode === 'display') {
     return (
       <TimePicker
@@ -281,7 +294,7 @@ function TimeCell({ value, meta, mode, size, isDisabled, isEditable, onCommit, o
         size={size}
         formatOptions={meta?.formatOptions}
         locale={meta?.locale}
-        showDisplayEndIcon={isEditable === true}  // 2026-05-10:non-editable 不顯 indicator
+        // showDisplayEndIcon 不傳 — 2026-07-08 A 案:display 態零恆顯 icon(同 DateCell 註)
       />
     )
   }
@@ -301,7 +314,7 @@ function TimeCell({ value, meta, mode, size, isDisabled, isEditable, onCommit, o
   )
 }
 
-function SelectCell({ value, meta, mode, size, isDisabled, isEditable, onCommit, onCancel }: CellComponentProps) {
+function SelectCell({ value, meta, mode, size, isDisabled, onCommit, onCancel }: CellComponentProps) {
   // Display canonical(2026-05-05):cell IS variant,default plain text(no Tag pill 疊在 cell border 內)。
   // Consumer 可在 column meta.display='tag' opt-in 內容導向的 Tag 視覺(category 含色彩標籤等)。
   // 對齊 JTable / AG Grid「renderer/editor 視覺一致」canonical。
@@ -316,7 +329,8 @@ function SelectCell({ value, meta, mode, size, isDisabled, isEditable, onCommit,
         options={meta?.options ?? []}
         size={size}
         display={displayMode}
-        showDisplayEndIcon={isEditable === true}  // 2026-05-10:non-editable 不顯 chevron indicator
+        // showDisplayEndIcon 不傳 — 2026-07-08 A 案:display 態零恆顯 icon(同 DateCell 註)
+        selectedItemRenderer={meta?.selectedItemRenderer}  // 2026-07-08 WM 戰役:status 類彩色 cell 顯示通道
       />
     )
   }
@@ -326,6 +340,7 @@ function SelectCell({ value, meta, mode, size, isDisabled, isEditable, onCommit,
       autoFocus
       variant="naked"
       size={sizeForInput(size)}
+      selectedItemRenderer={meta?.selectedItemRenderer}
       options={meta?.options ?? []}
       value={value as string | null | undefined}
       onChange={(v) => onCommit?.(v)}
@@ -339,7 +354,7 @@ function SelectCell({ value, meta, mode, size, isDisabled, isEditable, onCommit,
   )
 }
 
-function MultiSelectCell({ value, meta, mode, size, isDisabled, autoRowHeight, isEditable, onCommitLive, onCancel }: CellComponentProps) {
+function MultiSelectCell({ value, meta, mode, size, isDisabled, autoRowHeight, onCommitLive, onCancel }: CellComponentProps) {
   const wrap = autoRowHeight && meta?.wrap === true
   if (mode === 'display') {
     return (
@@ -351,7 +366,7 @@ function MultiSelectCell({ value, meta, mode, size, isDisabled, autoRowHeight, i
         options={meta?.options ?? []}
         wrap={wrap}
         size={size}
-        showDisplayEndIcon={isEditable === true}  // 2026-05-10:non-editable 不顯 chevron indicator
+        // showDisplayEndIcon 不傳 — 2026-07-08 A 案:display 態零恆顯 icon(同 DateCell 註)
       />
     )
   }
@@ -371,10 +386,10 @@ function MultiSelectCell({ value, meta, mode, size, isDisabled, autoRowHeight, i
   )
 }
 
-function PersonCell({ value, mode, size, isDisabled, isEditable, onCommit, onCancel, meta }: CellComponentProps) {
+function PersonCell({ value, mode, size, isDisabled, onCommit, onCancel, meta }: CellComponentProps) {
   if (mode === 'display') {
-    // 2026-05-10:non-editable 不顯 chevron indicator(對齊 UrlCell isEditable conditional pattern)
-    return <PeoplePicker key="display" variant="naked" mode={displayOrDisabled(isDisabled)} value={value as PersonValue | null} size={size} showDisplayEndIcon={isEditable === true} />
+    // 2026-07-08 A 案:display 態零恆顯 icon(同 DateCell 註)
+    return <PeoplePicker key="display" variant="naked" mode={displayOrDisabled(isDisabled)} value={value as PersonValue | null} size={size} />
   }
   return (
     <PeoplePicker
@@ -391,10 +406,10 @@ function PersonCell({ value, mode, size, isDisabled, isEditable, onCommit, onCan
   )
 }
 
-function MultiPersonCell({ value, mode, size, isDisabled, isEditable, onCommitLive, onCancel, meta }: CellComponentProps) {
+function MultiPersonCell({ value, mode, size, isDisabled, onCommitLive, onCancel, meta }: CellComponentProps) {
   if (mode === 'display') {
-    // 2026-05-10:non-editable 不顯 chevron indicator
-    return <PeoplePicker key="display" variant="naked" mode={displayOrDisabled(isDisabled)} value={(value as PersonValue[]) ?? []} size={size} showDisplayEndIcon={isEditable === true} />
+    // 2026-07-08 A 案:display 態零恆顯 icon(同 DateCell 註)
+    return <PeoplePicker key="display" variant="naked" mode={displayOrDisabled(isDisabled)} value={(value as PersonValue[]) ?? []} size={size} />
   }
   // Multi 用 onCommitLive(commit 但不 exit edit)— 每勾一人即時生效,popover 持續開
   // 直到點外面;onOpenChange(false) → onCancel exit edit。對齊 multiSelect canonical。
@@ -418,7 +433,8 @@ function BooleanCell({ value, mode, meta, size, isEditable, isDisabled, onCommit
   // onCheckedChange 仍 fire(violate disabled contract)。Fix:`!isEditable || isDisabled` →
   // 走 display branch,Checkbox 拿 disabled mode + 不接 onCheckedChange。
   if (mode === 'display' && (!isEditable || isDisabled)) {
-    return <Checkbox variant="naked" mode={displayOrDisabled(isDisabled)} checked={value === true} />
+    // size 傳入 → boolean 值 icon(Check/X)@lg 縮放對齊其他 cell(對齊 editable 分支同 size 邏輯)
+    return <Checkbox variant="naked" size={size === 'lg' ? 'lg' : 'md'} mode={displayOrDisabled(isDisabled)} checked={value === true} />
   }
   return (
     <Checkbox
@@ -431,17 +447,19 @@ function BooleanCell({ value, mode, meta, size, isEditable, isDisabled, onCommit
 }
 
 /**
- * UrlCell — Phase C drift fix:
- *   舊 EditableCellContent edit mode 對 url 走 plain `<Input>`(失去 URL 驗證 + auto-link)。
- *   現改用 `<LinkInput>` edit mode → 保留 URL parse / hostname 顯示一致性 + 鍵盤 commit / cancel。
- *   read mode 仍 `<LinkInput mode={displayOrDisabled(isDisabled)}>` = 一致 SSOT。
- *   editable 互動:hover 時右側出 Pencil 鈕 → 進 edit(保留 link click 語意,對齊原 spec)。
+ * UrlCell(2026-07-14 docblock 對齊實作):
+ *   display branch = `<LinkInput mode={displayOrDisabled(isDisabled)}>`(URL parse / hostname
+ *   顯示一致性 SSOT);editable 互動:hover 時右側出 Pencil 鈕 → 進 edit(保留 link click 語意)。
+ *   edit branch = plain `<Input variant="naked">`(LinkInput edit 的 controlled value 衝突
+ *   revert,詳下方 edit branch 註解);URL 驗證 deferred 到 onCommit(consumer 端 validate)。
  */
 function UrlCell({ value, meta, mode, size, isDisabled, isEditable, onRequestEdit, onCommit, onCancel }: CellComponentProps) {
   if (mode === 'display') {
-    // showDisplayEndIcon ← D path Phase 2(2026-05-08):Field naked wrapper 包 anchor,與 Input edit 同 chrome
+    // showDisplayEndIcon ← D path Phase 2(2026-05-08):Field naked wrapper 包 anchor,與 Input edit 同 chrome。
+    // LinkInput 此 prop = wrapper-only(無 icon,field.spec.md L6 例外)→ A 案(2026-07-08)不撤;
+    // 但修 I1:原無條件 true 違反「= isEditable」knob 等式(field-controls.spec.md cell 例外),改等式。
     const display = (
-      <LinkInput variant="naked" mode={displayOrDisabled(isDisabled)} value={value as string | null} label={meta?.linkLabel} size={size} showDisplayEndIcon />
+      <LinkInput variant="naked" mode={displayOrDisabled(isDisabled)} value={value as string | null} label={meta?.linkLabel} size={size} showDisplayEndIcon={isEditable === true} />
     )
     // 2026-05-13 codex V1 fix:disabled URL 不顯 Pencil affordance(parent onRequestEdit 已被攔但 UI 仍誤導)
     if (!isEditable || isDisabled) return display
@@ -521,7 +539,12 @@ function buildCellWithSurface(Inner: ComponentType<CellComponentProps>, key: str
         {/* 2026-06-08:把 table-density size 經獨立 surface-size context 注給 child Field controls,
             漏傳 size 的 cell 也自動繼承(根治「新 cell 漏傳 size」class);size primitive 不破壞 memo identity。*/}
         <FieldSurfaceSizeProvider size={props.size}>
-          <Inner {...props} />
+          {/* 2026-07-08 user 拍板:cell 可編輯訊號經獨立 boolean context 注給 child Field controls,
+              讓 useFieldEmptyDisplay 分流「可編輯 cell 空 display → 空白」vs「不可編輯 cell → '-'」。
+              boolean primitive 不破壞 memo identity(同 size context)。 */}
+          <FieldSurfaceEditableProvider isEditable={props.isEditable ?? false}>
+            <Inner {...props} />
+          </FieldSurfaceEditableProvider>
         </FieldSurfaceSizeProvider>
       </FieldSurfaceProvider>
     )

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

@@ -122,7 +122,16 @@ declare module '@tanstack/react-table' {
     precision?: number
     locale?: string
     /** Select/multiSelect options — maps value to display label */
-    options?: Array<{ value: string; label: string }>
+    /** select/multiSelect 選項:消費 Select 的 SelectOption 完整 schema(M30 wrapper-extends-primitive;
+     *  2026-07-08 原 {value,label} 窄型別讓 icon/description/iconClassName 傳不進 = 假 SSOT)*/
+    options?: Array<import('../Select/select').SelectOption>
+    /** select cell 的 trigger/display 自訂渲染(轉發 Select.selectedItemRenderer;status 彩色 icon 場景)*/
+    selectedItemRenderer?: (opt: import('../Select/select').SelectOption) => React.ReactNode
+    /** select cell 顯示模式(轉發 Select.display;cell-registry SelectCell 消費 `meta?.display`)。
+     *  default `'plain'` 純文字;`'tag'` opt-in 內容導向 Tag 視覺(status / category 彩色標籤,
+     *  搭配 options 的 `tagVariant`)。2026-07-14 deep-audit 補型別:runtime 一直消費此欄位
+     *  (cell-registry.tsx SelectCell displayMode),但 ColumnMeta 漏宣告 → typed consumer 傳不進(假 SSOT)。 */
+    display?: 'plain' | 'tag'
     /** Date: Intl.DateTimeFormat options */
     formatOptions?: Intl.DateTimeFormatOptions
     /**