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

package/src/components/Select/select.tsx

@@ -1,15 +1,15 @@
 // @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.
 // code-quality-allow: file-size — Select 含 3 子元件(NativeSelect/CustomSelect/ReadonlyDisplay)+ helpers + 4-mode renderer + Field SSOT consumption,split-into-files 會破壞 file-local helper closure
-// @renderer-symmetry-allow: pre-existing Select architecture(2026-05-08 D-path)— selectedItemRenderer 由 CustomSelectTriggerContent 消費(edit + trigger 模式),ReadonlyDisplay 走 separate bare-span path(no D-path)。display→edit unify deferred 下 cycle per spec contract (a) note。本 turn 只加 `nakedCellRowModeAlign` import,no behavior change to renderer symmetry contract。
+// @renderer-symmetry-allow: 2026-07-08 WM 戰役 A 案回歸修正 — ReadonlyDisplay 現已消費 selectedItemRenderer(display bare-span / D-path / readonly / disabled 四分支),對齊 field-controls.spec.md 共享 contract (a)「display/readonly/disabled/edit 4 mode 共享同一 renderer」。前 note「display→edit unify deferred」已兌現(值內容層);chrome 結構 unify(D-path)仍為 opt-in showDisplayEndIcon。
 import * as React from 'react'
 import { X, ChevronDown } from 'lucide-react'
 import type { LucideIcon } from 'lucide-react'
 import { cn } from '@/lib/utils'
-import type { FieldMode, FieldVariant } from '@/design-system/components/Field/field-types'
-import { fieldWrapperStyles, bareInputStyles, EMPTY_DISPLAY, nakedCellRowModeAlign, fieldDisplayTextClass } from '@/design-system/components/Field/field-wrapper'
+import type { FieldMode, FieldVariant, FieldVariantInternal, FieldWidth } from '@/design-system/components/Field/field-types'
+import { fieldWrapperStyles, bareInputStyles, nakedCellRowModeAlign, fieldDisplayTextClass } from '@/design-system/components/Field/field-wrapper'
 import { Tag } from '@/design-system/components/Tag/tag'
 import { ItemInlineAction, ItemPrefix, ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'
-import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldVariant, useResolvedFieldInvalid } from '@/design-system/components/Field/field-context'
+import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldVariant, useResolvedFieldInvalid, useFieldEmptyDisplay, fieldEmptyColorClass } from '@/design-system/components/Field/field-context'
 import { SelectMenu, forwardKeyToListbox, useActiveDescendant, type SelectMenuOption } from '@/design-system/components/SelectMenu/select-menu'
 import { useIsTouchDevice } from '@/design-system/hooks/use-is-touch-device'
 import { useControllable } from '@/design-system/hooks/use-controllable'
@@ -53,11 +53,58 @@ export interface SelectGroupConfig {
 
 // ── Types ───────────────────────────────────────────────────────────────────
 
+/**
+ * 原生 `<select>` 屬性 allowlist(2026-07-14 API 策展 D,user 拍板「全部收窄」)。
+ *
+ * 舊契約 `extends Omit<SelectHTMLAttributes, ...>` 型別承諾**全部**原生 select 屬性,但桌機
+ * 自訂 combobox(div trigger + hidden input mirror)只有部分真生效 — 其餘 silent no-op /
+ * 被元件內部覆寫,「型別承諾 ≠ 實作出口」= footgun。改 `Pick<>` 顯式 allowlist,**只承諾
+ * 兩路徑(desktop CustomSelect / mobile NativeSelect)皆有實作出口的屬性**,盤點以 code 為準:
+ *
+ * - `id` — 桌機 trigger div / mobile `<select>`,皆 `idProp ?? fieldCtx?.id`
+ * - `name` / `form` / `required` — 桌機經 hidden input mirror(D2 2026-07-13,見 hiddenInputEl
+ *   docblock)/ mobile 原生 `<select>` spread
+ * - `disabled` — 兩路徑 `useResolvedFieldDisabled` cascade → mode 分流
+ * - `className` / `style` — 兩路徑 field wrapper
+ * - `onFocus` / `onBlur` — 桌機 rest spread 到 focusable trigger(tabIndex=0)/ mobile spread
+ * - `onKeyDown` — 桌機 consumer handler 先跑再走元件導覽(dim-9)/ mobile 原生
+ * - `aria-label` / `aria-describedby` / `aria-errormessage` — 兩路徑顯式接線(fieldCtx fallback)
+ * - `autoFocus` / `autoComplete` — **mobile-only**:NativeSelect 原生 `<select>` 生效;桌機
+ *   custom combobox 無原生對應 = documented no-op(桌機 autofill 由 hidden input mirror 的
+ *   option-match onChange guard 承擔)
+ * - `data-*` — 兩路徑 spread passthrough(dim-9 契約;index signature 顯式承諾,見下)
+ *
+ * 被砍者(原 extends 承諾但從未生效 / 被元件覆寫,不再進型別):`multiple` / `children` /
+ * `tabIndex`(桌機恆 0)/ `aria-labelledby`(桌機由 fieldCtx.labelId / aria-label 管理,
+ * consumer 值會被覆寫)/ 其餘 generic HTMLAttributes(title / dir / onClick 等)。
+ * 需要時先接線(兩路徑等效)再入表,**不回 extends 全開**。
+ *
+ * 世界級對照:自訂 combobox 皆走 curated 原生屬性子集,無人 extends 全部 SelectHTMLAttributes —
+ * Radix Select.Root 顯式列舉 name/disabled/required/form/autoComplete
+ * (radix-ui.com/primitives/docs/components/select#root)/ Headless UI Listbox name/form/disabled
+ * (headlessui.com/react/listbox#using-with-html-forms)/ React Aria Select name/autoComplete/
+ * isDisabled/isRequired(react-spectrum.adobe.com/react-aria/Select.html)。
+ */
 export interface SelectProps
-  extends Omit<React.SelectHTMLAttributes<HTMLSelectElement>, 'size' | 'value' | 'defaultValue' | 'onChange'> {
+  extends Pick<
+    React.SelectHTMLAttributes<HTMLSelectElement>,
+    // ── 兩路徑皆真生效 ──
+    | 'id' | 'className' | 'style'
+    | 'name' | 'form' | 'required' | 'disabled'
+    | 'onFocus' | 'onBlur' | 'onKeyDown'
+    | 'aria-label' | 'aria-describedby' | 'aria-errormessage'
+    // ── mobile-only(NativeSelect 原生 <select> 生效;桌機 custom combobox documented no-op)──
+    | 'autoFocus' | 'autoComplete'
+  > {
+  /** `data-*` passthrough(桌機 trigger div rest spread / mobile `<select>` spread;dim-9 契約)。 */
+  [dataAttribute: `data-${string}`]: unknown
   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: SelectOption[]
@@ -104,13 +151,16 @@ export interface SelectProps
    */
   showDisplayEndIcon?: boolean
   /**
-   * Trigger 內「已選項目」客製 render(2026-05-07 v15.5)。
+   * 「已選項目」客製 render(2026-05-07 v15.5;2026-07-08 A 案回歸修正擴及 4 mode)。
    *
-   * 設了 → trigger 不走純文字 / Tag 預設 path,改用 consumer 提供的 ReactNode(收 selectedOpt)。
+   * 設了 → 已選值不走純文字 / Tag 預設 path,改用 consumer 提供的 ReactNode(收 selectedOpt)。
+   * **display / readonly / disabled / edit 4 mode 共享同一 renderer**(field-controls.spec.md
+   * 共享 contract (a),禁 edit-only)— renderer 輸出屬「值內容」(status icon+text 等語意呈現),
+   * display 態照常渲染;A 案撤的是 affordance(chevron/outline),非值內容(field.spec.md L6 分層)。
    * Searchable+open 仍走 input(搜尋優先)。Empty value(no selection)仍走 placeholder。
    *
    * 用例:PeoplePicker 用此 slot 把 single 選中的 person render 成 PersonDisplay
-   * (avatar + name)而非純文字 label。對齊 PeoplePicker = Select wrapper SSOT。
+   * (avatar + name)而非純文字 label;DataTable status 欄 icon+text。對齊 PeoplePicker = Select wrapper SSOT。
    */
   selectedItemRenderer?: (selectedOpt: SelectOption) => React.ReactNode
   /** 搜尋無結果提示(2026-07-04 Q4 拍板接線 — 原 spec 宣稱可覆寫但 prop 從未轉發)。
@@ -295,19 +345,26 @@ CustomSelectTriggerContent.displayName = 'CustomSelectTriggerContent'
 
 // ── Shared readonly/disabled/display render ─────────────────────────────────
 function ReadonlyDisplay({
-  mode, variant: variantProp, size, options, value, display, startIcon: StartIcon, className, placeholder, showDisplayEndIcon,
-}: Pick<SelectProps, 'mode' | 'variant' | 'size' | 'options' | 'value' | 'display' | 'startIcon' | 'className' | 'placeholder' | 'showDisplayEndIcon'>) {
+  mode, variant: variantProp, width, size, options, value, display, startIcon: StartIcon, className, placeholder, showDisplayEndIcon, selectedItemRenderer,
+}: Pick<SelectProps, 'mode' | 'width' | 'size' | 'options' | 'value' | 'display' | 'startIcon' | 'className' | 'placeholder' | 'showDisplayEndIcon' | 'selectedItemRenderer'> & {
+  /** @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 = getIconSize(sz)
-  const label = options?.find(o => o.value === value)?.label ?? value
+  // selectedOpt 提前 hoist(2026-07-08 A 案回歸修正):display / D-path / readonly / disabled
+  // 四分支都需要 — renderer 值內容(field-controls.spec.md contract (a) 4-mode 共享)+ tagVariant 查找。
+  const selectedOpt = options?.find(o => o.value === value)
+  const label = selectedOpt?.label ?? value
   const iconColor = resolvedMode === 'disabled' ? 'text-fg-disabled' : 'text-fg-muted'
   const isTextDisplay = display !== 'tag'
   // K10+K14 fix(2026-05-04):disabled mode placeholder/empty 顯示色 → fg-disabled(neutral-6),非 fg-muted(neutral-7)
   //   user canonical:disabled 顯著性優於 muted。同時 plain mode 必須 respect placeholder prop(之前忽略 = bug)
-  const emptyColorCls = resolvedMode === 'disabled' ? 'text-fg-disabled' : 'text-fg-muted'
-  const emptyText = placeholder ?? EMPTY_DISPLAY
+  const emptyColorCls = fieldEmptyColorClass(resolvedMode)
+  const emptyText = placeholder ?? emptyDisplay
 
   // mode='display':2 path(2026-05-08 D path Phase 1 Select canary)
   //   ❌ 預設(無 showDisplayEndIcon):純內容輸出 bare span/Tag(原行為,backward compat)
@@ -320,21 +377,35 @@ function ReadonlyDisplay({
       // 2026-05-14 I2 fix(spec contract (e) display typography canonical):bare span 必套
       // `fieldDisplayTextClass(sz)`(sm/md→text-body,lg→text-body-lg)— 對齊跨 Field
       // family display 視覺尺寸統一。
-      if (!value) return <span className={cn(fieldDisplayTextClass(sz), 'text-fg-muted', className)}>{emptyText}</span>
+      if (!value) return <span className={cn(fieldDisplayTextClass(sz), emptyColorCls, className)}>{emptyText}</span>
+      // 2026-07-08 A 案回歸修正:selectedItemRenderer(值內容:status icon+text 等語意呈現)
+      // display 態照常渲染 — 無 chrome 無 chevron,只有值內容本身。分層原則(field.spec.md L6):
+      // 本 renderer 歸「值內容」,恆顯;A 案撤的是 affordance(chevron/outline),非值內容。
+      // 對齊 field-controls.spec.md 共享 contract (a)「4 mode 共享同一 renderer(禁 edit-only)」。
+      if (selectedItemRenderer && selectedOpt) {
+        return (
+          <span className={cn(fieldDisplayTextClass(sz), 'inline-flex items-center min-w-0', nakedCellRowModeAlign, className)}>
+            {selectedItemRenderer(selectedOpt)}
+          </span>
+        )
+      }
       if (isTextDisplay) return <span className={cn(fieldDisplayTextClass(sz), 'truncate', className)}>{label}</span>
-      const selOpt = options?.find(o => o.value === value)
-      const tVariant = selOpt?.tagVariant as 'blue' | 'green' | 'red' | 'yellow' | 'neutral' | undefined
+      const tVariant = selectedOpt?.tagVariant as 'blue' | 'green' | 'red' | 'yellow' | 'neutral' | undefined
       return <Tag size={sz} color={tVariant} className={className}>{label}</Tag>
     }
     // D path opt-in: Field naked-display wrapper + ItemSuffix ChevronDown
-    const selOpt = options?.find(o => o.value === value)
-    const tVariant = selOpt?.tagVariant as 'blue' | 'green' | 'red' | 'yellow' | 'neutral' | undefined
+    const tVariant = selectedOpt?.tagVariant as 'blue' | 'green' | 'red' | 'yellow' | 'neutral' | undefined
     return (
       <div
-        className={cn(fieldWrapperStyles({ mode: 'display', variant, size: sz }), value && !isTextDisplay && tagPadding[sz], className)}
+        className={cn(fieldWrapperStyles({ mode: 'display', variant, width, size: sz }), value && !isTextDisplay && tagPadding[sz], className)}
         data-field-mode="display"
       >
-        {isTextDisplay ? (
+        {selectedItemRenderer && value && selectedOpt ? (
+          // renderer 優先(同 CustomSelectTriggerContent 優先序):值內容歸 renderer,chevron 歸 D-path chrome
+          <span className={cn('flex-1 min-w-0 inline-flex items-center', nakedCellRowModeAlign)}>
+            {selectedItemRenderer(selectedOpt)}
+          </span>
+        ) : isTextDisplay ? (
           <span className={cn(bareInputStyles, 'flex-1 min-w-0 truncate', !value && emptyColorCls)}>
             {value ? label : emptyText}
           </span>
@@ -356,9 +427,25 @@ function ReadonlyDisplay({
   const showIndicator = variant === 'naked' ? !!showDisplayEndIcon : resolvedMode === 'disabled'
   const ariaDisabled = resolvedMode === 'disabled' ? true : undefined
 
+  // 2026-07-08 A 案回歸修正:readonly / disabled 同樣消費 selectedItemRenderer(值內容 4-mode
+  // 共享,field-controls.spec.md contract (a);對照 PeoplePicker readonly/disabled 渲 PersonDisplay
+  // 先例)。renderer 優先於 isTextDisplay / Tag 預設 path(同 CustomSelectTriggerContent 優先序);
+  // disabled 時 wrapper span 帶 text-fg-disabled 供未自帶色的文字繼承(M24 disabled > muted)。
+  if (selectedItemRenderer && value && selectedOpt) {
+    return (
+      <div className={cn(fieldWrapperStyles({ mode: resolvedMode, variant, width, size: sz }), className)} data-field-mode={resolvedMode} aria-disabled={ariaDisabled}>
+        {StartIcon && <ItemPrefix><StartIcon size={iconSize} className={cn('pointer-events-none', iconColor)} aria-hidden /></ItemPrefix>}
+        <span className={cn('flex-1 min-w-0 inline-flex items-center', nakedCellRowModeAlign, resolvedMode === 'disabled' && 'text-fg-disabled')}>
+          {selectedItemRenderer(selectedOpt)}
+        </span>
+        {showIndicator && <ItemSuffix className="pointer-events-none"><ChevronDown size={iconSize} className={cn('shrink-0', iconColor)} aria-hidden /></ItemSuffix>}
+      </div>
+    )
+  }
+
   if (isTextDisplay) {
     return (
-      <div className={cn(fieldWrapperStyles({ mode: resolvedMode, variant, size: sz }), className)} data-field-mode={resolvedMode} aria-disabled={ariaDisabled}>
+      <div className={cn(fieldWrapperStyles({ mode: resolvedMode, variant, width, size: sz }), className)} data-field-mode={resolvedMode} aria-disabled={ariaDisabled}>
         {StartIcon && <ItemPrefix><StartIcon size={iconSize} className={cn('pointer-events-none', iconColor)} aria-hidden /></ItemPrefix>}
         <span className={cn('flex-1 min-w-0 truncate', resolvedMode === 'disabled' && 'text-fg-disabled')}>
           {value ? label : <span className={emptyColorCls}>{emptyText}</span>}
@@ -368,11 +455,10 @@ function ReadonlyDisplay({
     )
   }
 
-  const selectedOpt = options?.find(o => o.value === value)
   const tagVariant = selectedOpt?.tagVariant as 'blue' | 'green' | 'red' | 'yellow' | 'neutral' | undefined
 
   return (
-    <div className={cn(fieldWrapperStyles({ mode: resolvedMode, variant, size: sz }), value && tagPadding[sz], className)} style={{ paddingRight: 'var(--field-px)' }} data-field-mode={resolvedMode} aria-disabled={ariaDisabled}>
+    <div className={cn(fieldWrapperStyles({ mode: resolvedMode, variant, width, size: sz }), value && tagPadding[sz], className)} style={{ paddingRight: 'var(--field-px)' }} data-field-mode={resolvedMode} aria-disabled={ariaDisabled}>
       {value ? <Tag size={sz} color={tagVariant}>{label}</Tag> : <span className={emptyColorCls}>{emptyText}</span>}
       {showIndicator && <ItemSuffix className="pointer-events-none"><ChevronDown size={iconSize} className={cn('shrink-0', iconColor)} aria-hidden /></ItemSuffix>}
     </div>
@@ -383,10 +469,13 @@ function ReadonlyDisplay({
 
 // code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
 const NativeSelect = React.forwardRef<HTMLSelectElement, SelectProps>(
-  ({ mode, variant: variantProp, error: errorProp = false, size: sizeProp, options, value: valueProp, defaultValue, onChange, placeholder, className, disabled: disabledProp, clearable = false, display = 'plain', startIcon: StartIcon, showDisplayEndIcon, id: idProp, 'aria-describedby': ariaDescribedByProp, 'aria-errormessage': ariaErrorMessageProp,
+  ({ mode, variant: variantProp, width, error: errorProp = false, size: sizeProp, options, value: valueProp, defaultValue, onChange, placeholder, className, disabled: disabledProp, clearable = false, display = 'plain', startIcon: StartIcon, showDisplayEndIcon, id: idProp, 'aria-describedby': ariaDescribedByProp, 'aria-errormessage': ariaErrorMessageProp,
     // 2026-07-04:Custom-path-only props 顯式 destructure 丟棄(不 spread 到原生 <select> 消 React
     // unknown-prop warning);各 prop docblock 已註「僅 Custom path 生效」語意
-    searchable: _searchable, groups: _groups, loading: _loading, minRows: _minRows, emptyText: _emptyText, defaultOpen: _defaultOpen, onOpenChange: _onOpenChange, selectedItemRenderer: _selectedItemRenderer,
+    // 2026-07-08 A 案回歸修正:selectedItemRenderer 從丟棄名單移出 — Native path 的
+    // ReadonlyDisplay(display/readonly/disabled)同樣消費值內容 renderer(contract (a) 4-mode
+    // 共享,值內容不因 pointer type 而異);native <select> edit 路徑仍不消費(原生 option 無法客製 render)。
+    searchable: _searchable, groups: _groups, loading: _loading, minRows: _minRows, emptyText: _emptyText, defaultOpen: _defaultOpen, onOpenChange: _onOpenChange, selectedItemRenderer,
     ...props }, ref) => {
     const fieldCtx = useFieldContext()
     const error = useResolvedFieldInvalid(errorProp)
@@ -395,7 +484,7 @@ const NativeSelect = React.forwardRef<HTMLSelectElement, SelectProps>(
     const size = useResolvedFieldSize(sizeProp)
     // 2026-06-08 SSOT:mode 經 useResolvedFieldMode(prop > 有效 disabled > fieldCtx.mode > 'edit');修 <Field mode="display"> 漏 cascade
     const resolvedMode = useResolvedFieldMode({ mode, disabled })
-    const variant: FieldVariant = useResolvedFieldVariant(variantProp)
+    const variant: FieldVariantInternal = useResolvedFieldVariant(variantProp)
     const iconSize = getIconSize(size)
     // 2026-05-21 D3 audit:Controlled / Uncontrolled dual-mode via 既有 SSOT hook(同 CustomSelect)
     const [value, setValue] = useControllable<string | null>({
@@ -414,7 +503,7 @@ const NativeSelect = React.forwardRef<HTMLSelectElement, SelectProps>(
     }, [ref])
 
     if (resolvedMode !== 'edit') {
-      return <ReadonlyDisplay mode={resolvedMode} variant={variant} size={size} options={options} value={value} display={display} startIcon={StartIcon} className={className} placeholder={placeholder} showDisplayEndIcon={showDisplayEndIcon} />
+      return <ReadonlyDisplay mode={resolvedMode} variant={variant} width={width} size={size} options={options} value={value} display={display} startIcon={StartIcon} className={className} placeholder={placeholder} showDisplayEndIcon={showDisplayEndIcon} selectedItemRenderer={selectedItemRenderer} />
     }
 
     const selectEl = (
@@ -453,7 +542,7 @@ const NativeSelect = React.forwardRef<HTMLSelectElement, SelectProps>(
 
     if (!isTextDisplay) {
       return (
-        <div className={cn(fieldWrapperStyles({ mode: 'edit', variant: variant, size, error }), value && tagPadding[size], 'relative',
+        <div className={cn(fieldWrapperStyles({ mode: 'edit', variant: variant, width, size, error }), value && tagPadding[size], 'relative',
           className)}
           style={{ paddingRight: 'var(--field-px)' }} data-field-mode="edit" data-error={error ? '' : undefined}>
           {value ? <Tag size={size} color={nativeTagVariant} className="shrink-0 relative z-10 pointer-events-none">{label}</Tag> : <span className="text-fg-muted">{placeholder ?? '選擇...'}</span>}
@@ -466,7 +555,7 @@ const NativeSelect = React.forwardRef<HTMLSelectElement, SelectProps>(
     }
 
     return (
-      <div className={cn(fieldWrapperStyles({ mode: 'edit', variant: variant, size, error }),
+      <div className={cn(fieldWrapperStyles({ mode: 'edit', variant: variant, width, size, error }),
         className)}
         data-field-mode="edit" data-error={error ? '' : undefined}>
         {StartIcon && <ItemPrefix><StartIcon size={iconSize} className="text-fg-muted pointer-events-none" aria-hidden /></ItemPrefix>}
@@ -484,7 +573,10 @@ NativeSelect.displayName = 'NativeSelect'
 
 // code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
 const CustomSelect = React.forwardRef<HTMLDivElement, SelectProps>(
-  ({ mode, variant: variantProp, error: errorProp = false, size: sizeProp, options, groups, value: valueProp, defaultValue, onChange, placeholder, className, disabled: disabledProp, clearable = false, display = 'plain', startIcon: StartIcon, searchable = false, loading, minRows, emptyText, defaultOpen = false, onOpenChange, selectedItemRenderer, showDisplayEndIcon, id: idProp, 'aria-describedby': ariaDescribedByProp, 'aria-errormessage': ariaErrorMessageProp, 'aria-label': ariaLabel }, ref) => {
+  ({ mode, variant: variantProp, width, error: errorProp = false, size: sizeProp, options, groups, value: valueProp, defaultValue, onChange, placeholder, className, disabled: disabledProp, name, required, form, clearable = false, display = 'plain', startIcon: StartIcon, searchable = false, loading, minRows, emptyText, defaultOpen = false, onOpenChange, selectedItemRenderer, showDisplayEndIcon, id: idProp, 'aria-describedby': ariaDescribedByProp, 'aria-errormessage': ariaErrorMessageProp, 'aria-label': ariaLabel, onKeyDown: onKeyDownProp, style: styleProp,
+    // 2026-07-14 API 策展 D:mobile-only props(allowlist 註記)desktop 顯式丟棄 — div trigger 無原生
+    // 對應,不 spread 進 DOM(對稱 NativeSelect 丟棄 custom-path-only props 的既有 pattern)
+    autoFocus: _autoFocus, autoComplete: _autoComplete, ...rest }, ref) => {
     const fieldCtx = useFieldContext()
     const error = useResolvedFieldInvalid(errorProp)
     const disabled = useResolvedFieldDisabled(disabledProp)
@@ -492,7 +584,7 @@ const CustomSelect = React.forwardRef<HTMLDivElement, SelectProps>(
     const size = useResolvedFieldSize(sizeProp)
     // 2026-06-08 SSOT:mode 經 useResolvedFieldMode(prop > 有效 disabled > fieldCtx.mode > 'edit');修 <Field mode="display"> 漏 cascade
     const resolvedMode = useResolvedFieldMode({ mode, disabled })
-    const variant: FieldVariant = useResolvedFieldVariant(variantProp)
+    const variant: FieldVariantInternal = useResolvedFieldVariant(variantProp)
     const iconSize = getIconSize(size)
     // 2026-05-21 D3 audit:Controlled / Uncontrolled dual-mode via 既有 SSOT hook(M17 對齊,取代自刻 isControlled pattern)。
     // Phase B codex 抓:之前 Custom clear 走 `onChange?.('')` 沒 setInternalValue → uncontrolled clear 失效。useControllable 統一 setter 修。
@@ -571,7 +663,7 @@ const CustomSelect = React.forwardRef<HTMLDivElement, SelectProps>(
 
     // Early return AFTER all hooks(disabled / readonly / display mode 走 ReadonlyDisplay)
     if (resolvedMode !== 'edit') {
-      return <ReadonlyDisplay mode={resolvedMode} variant={variant} size={size} options={options} value={value} display={display} startIcon={StartIcon} className={className} placeholder={placeholder} showDisplayEndIcon={showDisplayEndIcon} />
+      return <ReadonlyDisplay mode={resolvedMode} variant={variant} width={width} size={size} options={options} value={value} display={display} startIcon={StartIcon} className={className} placeholder={placeholder} showDisplayEndIcon={showDisplayEndIcon} selectedItemRenderer={selectedItemRenderer} />
     }
 
     // 2026-05-21 D3 Phase B codex 抓:Custom clear 用 setValue 不直接 onChange,uncontrolled clear 才能真清 internal state。
@@ -585,6 +677,44 @@ const CustomSelect = React.forwardRef<HTMLDivElement, SelectProps>(
       </ItemSuffix>
     )
 
+    // ── Hidden input form mirror(2026-07-13 D2 拍板 Option A;MUI SelectInput idiom)──
+    // 桌機自訂 combobox 無原生 form control,`name` / `required` / `form` 歷史上被靜默丟棄
+    // (mobile NativeSelect 卻經 {...props} 生效 = 雙路徑提交語義不對稱 footgun)。
+    // 補 visually-hidden `<input>` 鏡像,讓桌機也參與原生表單(裸 <form> submit / FormData):
+    // - value **單向鏡射**受控 state(useControllable)= projection,非第二 SSOT(M17);
+    //   空值時 value=''(不採 Radix hidden <select> 完整 option tree — 其無空 option 時
+    //   default 第一項,radix-ui/primitives issue #3521 documented footgun)
+    // - 原生 required 僅收顯式 `required` prop(裸表單 opt-in);fieldCtx.required 續走
+    //   aria-required + useFormValidation(RHF)方法論(form-validation.spec.md 規則 1-9),
+    //   不對既有 Field+RHF consumer 注入瀏覽器原生 bubble
+    // - onChange 唯一用途 = 瀏覽器 autofill:match 既有非 disabled option 才經 canonical
+    //   setter 寫回(對齊 MUI SelectInput handleChange 同款 guard),其餘輸入忽略
+    // - aria-hidden + tabIndex={-1}:AT 與 Tab 序皆不見(semantics 由 role=combobox trigger
+    //   own);form-validation 規則 8 focus-first-error 以 DOM name 定位 → 可聚焦 mirror →
+    //   trigger focus-within 顯示 focus 邊框(桌機 Select 脫離「非 native 控件略過」fallback)
+    // 世界級對照:MUI Select 非原生模式 opacity-0 hidden input 攜 name/required
+    // (github.com/mui/material-ui .../Select/SelectInput.js;Select.test.js 官方測試涵蓋
+    // required 阻止提交 + FormData 值)+ React Spectrum HiddenSelect(github.com/adobe/
+    // react-spectrum .../@react-aria/select/src/HiddenSelect.tsx)+ Headless UI Listbox
+    // name → hidden input kept in sync(headlessui.com/react/listbox#using-with-html-forms)。
+    const hiddenInputEl = (
+      <input
+        type="text"
+        name={name}
+        form={form}
+        value={value ?? ''}
+        onChange={(e) => {
+          const matched = options.find((o) => o.value === e.target.value && !o.disabled)
+          if (matched) setValue(matched.value)
+        }}
+        required={required || undefined}
+        disabled={disabled}
+        aria-hidden="true"
+        tabIndex={-1}
+        className="absolute bottom-0 left-0 w-full opacity-0 pointer-events-none"
+      />
+    )
+
     const triggerContent = (
       <CustomSelectTriggerContent
         searchable={searchable}
@@ -612,6 +742,16 @@ const CustomSelect = React.forwardRef<HTMLDivElement, SelectProps>(
 
     const trigger = (
       <div
+        // passthrough(2026-07-14 dim-9 修;同日 API 策展 D 收窄):SelectProps allowlist
+        // (Pick<SelectHTMLAttributes>,見 SelectProps docblock)承諾的 data-* / onFocus /
+        // onBlur 等 attrs,mobile NativeSelect 經 {...props} spread 到 <select> 生效,desktop
+        // 原本完整列舉全丟 → 同一 <Select> API 隨 pointer type 靜默失效(consumer data-testid /
+        // onBlur mobile 有、desktop 無)。rest 先 spread —— component 契約 attrs(role / aria-* /
+        // id / tabIndex / onKeyDown / className)在後,不可被覆寫;consumer onKeyDown 經
+        // onKeyDownProp 在 handler 內先跑(見下)。mobile-only attrs(autoFocus / autoComplete)
+        // 已在 destructure 層丟棄不進 rest(div trigger 無原生語意;desktop 表單語意由 hidden
+        // input mirror 承擔,見 D2 docblock)。
+        {...(rest as unknown as React.HTMLAttributes<HTMLDivElement>)}
         ref={ref}
         id={idProp ?? fieldCtx?.id}
         role="combobox"
@@ -623,23 +763,36 @@ const CustomSelect = React.forwardRef<HTMLDivElement, SelectProps>(
         // (field-context.ts labelId jsDoc 明文);consumer aria-label 優先(對齊 slider.tsx:166 guard canonical)。
         aria-labelledby={ariaLabel ? undefined : fieldCtx?.labelId}
         aria-invalid={error || undefined}
-        aria-required={fieldCtx?.required || undefined}
+        // D2(2026-07-13):顯式 required prop 同步進 aria-required(mirror 本身 aria-hidden,
+        // AT 看不到其 required;語意由 trigger 播報 — 對齊 mobile 原生 <select required> 行為)
+        aria-required={(required || fieldCtx?.required) || undefined}
         aria-describedby={ariaDescribedByProp ?? fieldCtx?.descriptionId}
         aria-errormessage={ariaErrorMessageProp ?? (error ? fieldCtx?.errorId : undefined)}
         tabIndex={0}
         className={cn(
-          fieldWrapperStyles({ mode: 'edit', variant: variant, size, error }),
+          fieldWrapperStyles({ mode: 'edit', variant: variant, width, size, error }),
           !isTextDisplay && value && !searchable && tagPadding[size],
           // 2026-05-06 v13.3 SSOT retire:per-control `open && 'border-primary'` 移除。Field default
           // state machine `data-[state=open]:border-border-hover`(灰深)處理 open。
           // 2026-07-04 Q1:error border 同樣收進 fieldWrapperStyles error variant(error 勝 focus 色)。
-          'cursor-pointer',
+          // D2(2026-07-13):`relative` = hidden input mirror 的 absolute 定位容器
+          // (fieldWrapperStyles base 無 relative;對齊 NativeSelect tag 分支同款顯式加法)。
+          'relative cursor-pointer',
           className,
         )}
-        style={!isTextDisplay ? { paddingRight: 'var(--field-px)' } : undefined}
+        style={styleProp || !isTextDisplay ? { ...styleProp, ...(!isTextDisplay ? { paddingRight: 'var(--field-px)' } : undefined) } : undefined}
         data-field-mode="edit"
         data-error={error ? '' : undefined}
         onKeyDown={(e) => {
+          // passthrough(dim-9):consumer onKeyDown 先跑 —— 對齊 native path(<select> 上
+          // consumer handler 同樣最先收到);component 導覽邏輯照舊在後。
+          onKeyDownProp?.(e as unknown as React.KeyboardEvent<HTMLSelectElement>)
+          // 2026-07-14 dim-10 修:內層清除按鈕(SelectClearButton → ItemInlineAction <button>)
+          // 的 Enter/Space 會 bubble 到本 handler 被 preventDefault 吞掉 → 鍵盤無法清除。
+          // 事件源自 descendant button 時不執行 trigger 鍵盤邏輯(保留原生 activation)。
+          // 注意:不能一刀切 e.target !== e.currentTarget — searchable inline <input> 的
+          // 鍵盤事件仍需下方 forwardKeyToListbox 轉送選單導覽。
+          if (e.target !== e.currentTarget && (e.target as HTMLElement).closest?.('button')) return
           // 2026-07-05 D4 P0:open 後 ArrowUp/Down/Enter 轉送 cmdk root(見 select-menu.tsx
           // forwardKeyToListbox docblock — 原「open 後不攔讓方向鍵導覽」在跨 DOM 子樹機制上不成立)
           if (open && forwardKeyToListbox(listboxId, e)) return
@@ -657,6 +810,7 @@ const CustomSelect = React.forwardRef<HTMLDivElement, SelectProps>(
         {triggerContent}
         {clearEl}
         {chevronEl}
+        {hiddenInputEl}
       </div>
     )
 

package/src/components/SelectMenu/select-menu.anatomy.stories.tsx

@@ -34,10 +34,10 @@ const statusOptions: SelectMenuOption[] = [
 ]
 
 const reviewerOptions: SelectMenuOption[] = [
-  { value: 'alice', label: 'Ada Chen', avatar: { alt: 'Ada Chen', color: 'indigo' }, description: 'Frontend' },
-  { value: 'bob', label: '張美真', avatar: { alt: '張美真', color: 'magenta' }, description: 'Platform' },
-  { value: 'carol', label: '林伯彥', avatar: { alt: '林伯彥', color: 'green' }, description: 'Infra' },
-  { value: 'dave', label: '黃怡君', avatar: { alt: '黃怡君', color: 'turquoise' }, description: 'QA' },
+  { value: 'alice', label: 'Ada Chen', avatar: { src: 'https://i.pravatar.cc/48?u=ada-chen', alt: 'Ada Chen', color: 'indigo' }, description: 'Frontend' },
+  { value: 'bob', label: '張美真', avatar: { src: 'https://i.pravatar.cc/48?u=zhang-meizhen', alt: '張美真', color: 'magenta' }, description: 'Platform' },
+  { value: 'carol', label: '林伯彥', avatar: { src: 'https://i.pravatar.cc/48?u=lin-boyan', alt: '林伯彥', color: 'green' }, description: 'Infra' },
+  { value: 'dave', label: '黃怡君', avatar: { src: 'https://i.pravatar.cc/48?u=huang-yijun', alt: '黃怡君', color: 'turquoise' }, description: 'QA' },
 ]
 
 const labelOptions: SelectMenuOption[] = [

package/src/components/SelectMenu/select-menu.spec.md

@@ -1,6 +1,6 @@
 ---
 component: SelectMenu
-family: 4
+family: composite # 2026-07-14 修自我矛盾:原 Phase-1 mechanical 填 4,與 body「Layout Family:非上述 family — composite / multi-section」矛盾;Family 4 是 trigger 側 field control(Select / Combobox)的事
 variants: {}
 sizes: {}
 traits:
@@ -29,7 +29,7 @@ SelectMenu 是 **Popover + Command 組成的完整下拉選單浮層**——提
 
 ## Controlled-only rationale(Dim 26)
 
-本元件刻意採 **controlled-only** 模式——**scope 限 value 軸**:value 軸走 `value` + `onValueChange`(型別宣告 optional、無 runtime 強制,但 internal 消費者 Select / Combobox / PeoplePicker 一律傳入),不支援 `defaultValue` uncontrolled fallback。open 軸自 2026-06-11 R2 起走 `useControllable` dual-mode(`open` + `defaultOpen` + `onOpenChange`,`select-menu.tsx:162-166`),不在 controlled-only 範圍。
+本元件刻意採 **controlled-only** 模式——**scope 限 value 軸**:value 軸走 `value` + `onValueChange`(型別宣告 optional、無 runtime 強制,但 internal 消費者 Select / Combobox / PeoplePicker 一律傳入),不支援 `defaultValue` uncontrolled fallback。open 軸自 2026-06-11 R2 起走 `useControllable` dual-mode(`open` + `defaultOpen` + `onOpenChange`,`select-menu.tsx:187-191`),不在 controlled-only 範圍。
 
 **為什麼**:
 - 內部狀態複雜(search filter / range / menu open state)跟 `value` 雙向 sync 會產生 race condition
@@ -93,7 +93,7 @@ Popover（浮動容器，handle 展開 / 定位）
 
 ## Creatable（建立新選項）
 
-透過 `creatable` + `onCreate` 啟用。search 非空且**無 label 完全相同(忽略大小寫)的既有選項**時,顯示 create row(`Plus` icon + `createLabel(query)`,預設「直接使用「xxx」」;`select-menu.tsx:230-235`)——完全同名時自動隱藏,防重複建立。
+透過 `creatable` + `onCreate` 啟用。search 非空且**無 label 完全相同(忽略大小寫)的既有選項**時,顯示 create row(`Plus` icon + `createLabel(query)`,預設「直接使用「xxx」」,`select-menu.tsx:164`;顯示/隱藏判斷 `:261-266`,render `:471-495`)——完全同名時自動隱藏,防重複建立。
 
 **何時啟用**：
 - Tag input 允許使用者建立新 tag
@@ -160,7 +160,7 @@ Popover（浮動容器，handle 展開 / 定位）
 - **Disabled trigger**:trigger 由 consumer(Select / Combobox / PeoplePicker)的 `disabled` prop own,本元件不獨立 disable trigger。
 - **Loading**:已 codify(見「Loading」段),`loading=true` 且無可顯示選項時 empty slot 渲 panel-center Empty + CircularProgress 48px(stale options 保留)。
 - **Empty**:已 codify(見「Empty state」段),搜尋無結果 + 非 creatable 時渲 emptyText;creatable 時保留 create row(可鍵盤選取)。
-- **Creatable + search 與既有選項完全同名**(忽略大小寫):create row 隱藏(防重複建立,`select-menu.tsx:230-235`);選取既有選項為唯一路徑。
+- **Creatable + search 與既有選項完全同名**(忽略大小寫):create row 隱藏(防重複建立,`select-menu.tsx:261-266`);選取既有選項為唯一路徑。
 - **Dark mode**:走 Popover / MenuItem semantic token 自動 adapt。
 - **Density**:row height 由 `MenuItem` SSOT 控(sm/md/lg);SelectMenu 不獨立 own density。
 - **大量選項(> 100)**:建議上游分頁 / 搜尋收斂或考慮 windowing(對齊 Ant Select / MUI Autocomplete 慣例);本元件無虛擬化。
@@ -169,9 +169,13 @@ Popover（浮動容器，handle 展開 / 定位）
 
 ## 為何無 ColorMatrix
 
-SelectMenu 是**多區塊 composite primitive**,不擁有獨立色彩決策:
+SelectMenu 是**多區塊 composite primitive**,色彩全數消費 DS semantic token、不新增 token;但 2026-07-05 D4 後互動色的 **owner 分層**如下(修正舊述「視覺完全繼承內層 primitive」):
 
-- **無 ColorMatrix**:視覺完全繼承既有 DS primitive 的 token(`MenuItem` row / `Command` search / `Empty` layout / `Popover` surface),無自己的 bg / border / hover 決策。色彩漂移由 primitive layer 控制——SelectMenu 層級若加 ColorMatrix 會重複 MenuItem / Popover 的矩陣。
+- **surface / border / elevation**:`PopoverContent` 自設 `bg-surface-raised` + `border-border` + `--elevation-200`(`select-menu.tsx:308-320`)。
+- **hover / selected 互動 bg**:owner 是**外層 cmdk `CommandItem`** —— 鍵盤 cursor base `bg-neutral-hover`(command.tsx `data-[selected=true]`)+ 單選 persistent selected `bg-neutral-selected` + selected × cursor 加深一階 `bg-neutral-selected-active`(`select-menu.tsx:439-442`,鏡射 DropdownMenu Q2/D4 canonical)。
+- **內層 `MenuItem`**:強制 `!bg-transparent` 純視覺排版(`select-menu.tsx:460` 選項列 / `:489` create 列),不 own 互動 bg。
+
+**無 ColorMatrix 的理由不變**:上述全是既有 token family(`neutral-hover / neutral-selected / neutral-selected-active`,與 DropdownMenu / MenuItem 同組),SelectMenu 不擁有獨立色彩決策;加 ColorMatrix 只會重複 MenuItem / DropdownMenu / Popover 的矩陣。
 
 對應 anatomy story:保留 `Overview` / `Inspector` / `SizeMatrix` / `StateBehavior`,額外追加元件特有的 `ModeMatrix`(single / multi / searchable / creatable / grouped 等功能組合矩陣,這是 SelectMenu 真正的決策面向——取代 ColorMatrix)。
 
@@ -179,7 +183,7 @@ SelectMenu 是**多區塊 composite primitive**,不擁有獨立色彩決策:
 
 ## shadcn passthrough 例外說明
 
-SelectMenu 是 **composite**(Popover trigger + Command search + 滾動 MenuItem list + 浮動 surface),純 declarative API。**套 `forwardRef` 簽名但 ref 不附著、無 `...props` spread**(shadcn forwardRef + displayName 統一;`select-menu.tsx:127-130` rationale):
+SelectMenu 是 **composite**(Popover trigger + Command search + 滾動 MenuItem list + 浮動 surface),純 declarative API。**套 `forwardRef` 簽名但 ref 不附著、無 `...props` spread**(shadcn forwardRef + displayName 統一;`select-menu.tsx:151-154` rationale):
 
 - **沒有單一 DOM root 可 ref**:trigger / search input / list / content portal 各自 DOM tree 離散
 - **`...props` spread 目標不明**:composite 的 root wrapper 只是 control 容器,spread 到那裡 consumer 無從預期作用
@@ -192,6 +196,10 @@ SelectMenu 是 **composite**(Popover trigger + Command search + 滾動 MenuItem
 
 ---
 
+## Option schema 增項紀錄
+
+- `iconClassName?`(2026-07-08):option icon 染色通道(status 類彩色選項;WM 戰役——原窄 schema 逼 consumer 手刻 bare trigger)。disabled 色仍勝出(menu-item.tsx 順序保證)。
+
 ## 相關
 
 - `../Menu/menu-item.spec.md` — 選項 row 的 item-layout 共用規則（SelectMenu 消費 MenuItem）

package/src/components/SelectMenu/select-menu.tsx

@@ -44,6 +44,8 @@ export interface SelectMenuOption {
   label: string
   description?: string
   icon?: LucideIcon
+  /** icon 染色 className(2026-07-08:status 類彩色 option;M30 primitive schema 擴充) */
+  iconClassName?: string
   avatar?: AvatarData
   disabled?: boolean
   group?: string
@@ -352,8 +354,13 @@ const SelectMenu = React.forwardRef<HTMLElement, SelectMenuProps>(function Selec
           // `state.value ||` guard 不覆蓋(dist source 驗證);Popover 關閉即 unmount(無
           // forceMount)→ 每次開啟 remount 重新生效。需搭配下方 CommandItem value={opt.value}。
           defaultValue={selectedOption?.value}
-          // 2026-07-06 A11y:combobox accessible name — cmdk 永遠渲 sr-only <label htmlFor={inputId}>,
-          // 僅 searchable(真的有 input)時傳,避免 orphan label 指向不存在的 input id。
+          // 2026-07-06 A11y:combobox accessible name。2026-07-14 修正註解(cmdk 1.1.1 dist 實證):
+          // cmdk **無條件**渲 sr-only <label htmlFor={inputId}>(dist/index.mjs
+          // `createElement("label",{htmlFor:U.inputId,id:U.labelId,...},b)` — label prop 只決定
+          // 文字內容,不決定 label 元素是否渲染)。故 non-searchable 時「空 label + htmlFor 指向
+          // 不存在的 input」仍存在(upstream cmdk 限制;空 label 無 accessible name,不產生朗讀
+          // 內容)。僅 searchable(真的有 input)時傳內容 = 避免 non-searchable 帶 search
+          // placeholder 的 accessible name 卻無對應 input;真要消除 orphan label 需 upstream 修。
           label={searchable ? searchPlaceholder : undefined}
           className="bg-transparent"
         >
@@ -437,6 +444,7 @@ const SelectMenu = React.forwardRef<HTMLElement, SelectMenuProps>(function Selec
                       <MenuItem
                         size={size}
                         startIcon={opt.icon}
+                        startIconClassName={opt.iconClassName}
                         avatar={opt.avatar}
                         description={opt.description}
                         checkbox={multiple}
@@ -535,7 +543,12 @@ SelectMenu.displayName = 'SelectMenu'
 // Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
 export const selectMenuMeta = {
   component: 'SelectMenu',
-  family: 4,
+  // 2026-07-14 修 family 自我矛盾:原 Phase-1 mechanical 填 4(Field control),與 spec body
+  // 「Layout Family:非上述 family — composite / multi-section」矛盾。SelectMenu 是 Popover +
+  // Command composite overlay(trigger 由 consumer Select / Combobox own,Family 4 是 trigger
+  // 側 field control 的事);對齊 DS composite 慣例(Accordion / Command / Popover meta 皆
+  // family: null + spec frontmatter composite)。
+  family: null, // non-family composite / overlay(對齊 spec frontmatter composite)
   variants: {
 
   },

package/src/components/SelectionControl/boolean-value.tsx

@@ -0,0 +1,39 @@
+// @internal — boolean 值展示符號 SSOT(display / readonly 態);consumer 用 Checkbox / Switch 不直用。
+// ── 消費的 SSOT ──
+// - lucide-react Check / X(DS icon canonical:成功/勾 = Check、關閉/否 = X,見 ui-development.md「Icon canonical」)
+// - components/Field/field-context.ts(FieldSize 型別 → icon 尺寸對齊 value 文字)
+// - tokens/color:text-foreground(展示值中性色,同 readonly value / 空值 canonical)
+//
+// 世界級對照(M22,2026-07-09 本 session 查證):read-only boolean 顯示 = 勾/叉 icon,中性色(非紅綠):
+//   MUI X DataGrid boolean cell = Check / Close(X)icon,default 中性色(非 red/green)
+//   Refine(Ant)BooleanField https://refine.dev/docs/ui-integrations/ant-design/components/fields/boolean-field/ = 勾 / 叉
+//   React-admin BooleanField https://marmelab.com/react-admin/BooleanField.html = TrueIcon / FalseIcon(預設 勾 / 叉)
+// 為何中性色不用紅叉綠勾:false = 「否」值本身,非「錯誤 / 被拒」;error / warning 是另一條 error token 通道,
+// 不靠此 glyph 表達。true/false 對稱同色 = MUI/React-admin 共識。
+import { Check, X } from 'lucide-react'
+import { cn } from '@/lib/utils'
+import type { FieldSize } from '@/design-system/components/Field/field-context'
+
+// icon 尺寸對齊 value 文字(fieldDisplayTextClass:sm/md → text-body 14px、lg → text-body-lg 16px)。
+const booleanIconSize: Record<FieldSize, string> = {
+  sm: 'size-3.5', // 14px
+  md: 'size-3.5', // 14px
+  lg: 'size-4', //   16px
+}
+
+/**
+ * BooleanValueIcon — boolean 值的展示符號(true = Check 勾 / false = X 叉),中性 `text-foreground` 色。
+ * Checkbox / Switch 的 display + readonly 態、DataTable boolean cell(經 Checkbox)全消費此 SSOT。
+ */
+export function BooleanValueIcon({
+  checked,
+  size = 'md',
+  className,
+}: {
+  checked: boolean
+  size?: FieldSize
+  className?: string
+}) {
+  const Icon = checked ? Check : X
+  return <Icon aria-hidden className={cn(booleanIconSize[size], 'text-foreground', className)} />
+}

package/src/components/SelectionControl/index.ts

@@ -2,4 +2,5 @@
 // Re-export pattern enables package.json exports map subpath:
 //   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
 // Regenerate: node scripts/gen-component-indexes.mjs
+export * from './boolean-value'
 export * from './selection-item'

package/src/components/SelectionControl/selection-item.anatomy.stories.tsx

@@ -439,7 +439,7 @@ export const PrefixAlignment: Story = {
             <div className="border border-divider rounded-md p-4 bg-muted">
               <SelectionItem
                 control={<Checkbox defaultChecked />}
-                avatar={{ alt: 'Ada Chen', color: 'indigo' }}
+                avatar={{ src: 'https://i.pravatar.cc/48?u=ada-chen', alt: 'Ada Chen', color: 'indigo' }}
                 label="Ada Chen"
               />
             </div>
@@ -451,7 +451,7 @@ export const PrefixAlignment: Story = {
             <div className="border border-divider rounded-md p-4 bg-muted">
               <SelectionItem
                 control={<Checkbox defaultChecked />}
-                avatar={{ alt: 'Ada Chen', color: 'indigo' }}
+                avatar={{ src: 'https://i.pravatar.cc/64?u=ada-chen', alt: 'Ada Chen', color: 'indigo' }}
                 label="Ada Chen"
                 description="Design Engineer · Frontend team"
               />