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

package/src/components/Combobox/combobox.tsx

@@ -1,12 +1,12 @@
 // @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.
 // @renderer-symmetry-allow: ComboboxTagStack(display path)接 consumer tagRenderer 是 Stream C 下 cycle 工作 — 2026-05-12 先 ship Issues 2/3/4 surgical fixes(placeholder vocabulary + cell surface metrics + placeholder truncate),tagRenderer display-path unify deferred per field-controls.spec.md 共享 contract a。當前 multi=1 顯示已透過 PeoplePicker tagRenderer 線 314 PersonDisplay SSOT 對齊;其他 Combobox consumer 走 default `<Tag>` 純文字 backward-compat。
-// code-quality-allow: file-size — Combobox 含 NativeCombobox/CustomCombobox/useOverflowCount/OverflowTagList/ComboboxTagStack 5 子元件 + 共用 helpers,split-into-files 會破壞 measurement closures + 重複 type definitions。當前 751 lines 在 800 hard cap 內。
+// code-quality-allow: file-size — Combobox 含 NativeCombobox/CustomCombobox/useOverflowCount/OverflowTagList/ComboboxTagStack 5 子元件 + 共用 helpers,split-into-files 會破壞 measurement closures + 重複 type definitions。
 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 } from '@/design-system/components/Field/field-context'
+import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldVariant, useResolvedFieldInvalid } 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'
@@ -29,8 +29,8 @@ const tagPadding: Record<string, string> = {
  * SelectMenuOption(primitive SSOT)** — 避免重蹈先前 PeoplePicker 改壞的 wrapper schema drift。
  *
  * Why `extends SelectMenuOption`(per user 「全盤檢查避免下次又改壞或是偏移」要求):
- *   原 `interface SelectOption { value: string; label: string }` 是 weak schema,跟 Select 的
- *   `SelectOption`(同名)雙重宣告但欄位不同 → TypeScript 不抓(同名 interface 在不同 file
+ *   原 `interface ComboboxOption { value: string; label: string }` 是 weak schema,跟 Select 的
+ *   `ComboboxOption`(同名)雙重宣告但欄位不同 → TypeScript 不抓(同名 interface 在不同 file
  *   各 export,consumer import 到哪個版本看 import path)→ schema drift。
  *   PeoplePicker multi-mode 走 Combobox 路徑,dropdown menu rows lose avatar / description —
  *   user 看到「single mode 有 avatar / multi mode 沒 avatar」inconsistency。
@@ -42,7 +42,7 @@ const tagPadding: Record<string, string> = {
  * 對齊 Polaris ChoiceList / Material Autocomplete / Carbon Dropdown 的 wrapper-vs-primitive
  * schema-extension idiom。Hook `check_wrapper_primitive_schema_drift.sh`(M30 機械強制)。
  */
-export interface SelectOption extends SelectMenuOption {
+export interface ComboboxOption extends SelectMenuOption {
   // (no wrapper-only fields yet — kept for future扩 + same-name SSOT cross-wrapper)
 }
 
@@ -304,7 +304,7 @@ function OverflowTagList({ containerRef, items, size, wrap, renderTag, renderHid
           {hiddenItems.map(item => (
             renderHiddenTag
               ? <React.Fragment key={item.value}>{renderHiddenTag(item)}</React.Fragment>
-              : <Tag key={item.value} size="sm" onDismiss={onRemove ? () => onRemove(item.value) : undefined}>
+              : <Tag key={item.value} size="sm" onRemove={onRemove ? () => onRemove(item.value) : undefined}>
                   {item.label}
                 </Tag>
           ))}
@@ -322,7 +322,7 @@ function OverflowTagList({ containerRef, items, size, wrap, renderTag, renderHid
 function ComboboxTagStack({
   value, options, tagSize = 'md', wrap = false, containerRef: externalRef, disabled = false,
 }: {
-  value?: string[] | null; options?: SelectOption[]; tagSize?: 'sm' | 'md' | 'lg'
+  value?: string[] | null; options?: ComboboxOption[]; tagSize?: 'sm' | 'md' | 'lg'
   wrap?: boolean; containerRef?: React.RefObject<HTMLDivElement | null>; disabled?: boolean
 }) {
   const ownRef = React.useRef<HTMLDivElement>(null)
@@ -367,7 +367,7 @@ export interface ComboboxProps {
   variant?: FieldVariant
   error?: boolean
   size?: 'sm' | 'md' | 'lg'
-  options: SelectOption[]
+  options: ComboboxOption[]
   value?: string[]
   onChange?: (value: string[]) => void
   placeholder?: string
@@ -400,7 +400,7 @@ export interface ComboboxProps {
    * Selected tag pill 客製 render(2026-05-07 v15.5)。
    *
    * 設了 → 每個 selected tag pill 走 consumer 提供的 ReactNode(收 item={value, label}
-   * + onRemove,consumer 自己組 onDismiss);沒設 → 走預設 `<Tag>` text-only pill。
+   * + onRemove,consumer 自己組 onRemove);沒設 → 走預設 `<Tag>` text-only pill。
    *
    * 用例:PeoplePicker(multi)用此 slot 把 selected tag 換成 avatar + name pill,而非
    * 純文字 Tag。對齊 PeoplePicker = Combobox wrapper SSOT。
@@ -414,12 +414,15 @@ export interface ComboboxProps {
    */
   renderHiddenTag?: (item: { value: string; label: string }) => React.ReactNode
   /**
+   * @internal PeoplePicker stack wrapper 內部協議 — end-user 勿用(measurement-layer hook)。
+   *
    * Optional class merged into each tag's outer measurement wrapper (2026-05-07 v15.13)。
    * Stack avatar 模式用此 hook point 達成 sibling-level overlap (`-ml-0.5`) + group selector
    * (`group/avatar`)— 既保留 Combobox 必要 measurement wrapper,又讓 dismiss/overlap 視覺生效。
    */
   tagWrapperClassName?: string
-  /** 2026-05-16:overflow chip wrapper 套此 class(對齊 tagWrapperClassName)。Stack 模式
+  /** @internal PeoplePicker stack wrapper 內部協議 — end-user 勿用(measurement-layer hook)。
+   *  2026-05-16:overflow chip wrapper 套此 class(對齊 tagWrapperClassName)。Stack 模式
    *  pass `-ml-0.5 first:ml-0` 讓 chip 跟 avatar 同 overlap step,物理上 chip = 1 個 slot 不
    *  外加 24px。Default undefined = chip 不 overlap(text-tag mode 等)。*/
   overflowWrapperClassName?: string
@@ -429,6 +432,8 @@ export interface ComboboxProps {
    * (CSS `gap` 套在 flex container 上會強制 sibling spacing,蓋過 negative margin)。
    * **Q2 known tradeoff**:0 後 useOverflowCount 仍按 wrapper.offsetWidth 累加(不含 overlap
    * 補償)→ +N 偏保守。當前接受;若需精準可 future 加 `overlapPx` 補償邏輯。
+   *
+   * @internal PeoplePicker stack wrapper 內部協議 — end-user 勿用(measurement-layer hook)。
    */
   tagAreaGapPx?: number
   /**
@@ -438,10 +443,12 @@ export interface ComboboxProps {
    * paddingLeft - paddingRight` 自動 include**(`parseFloat(cs.paddingLeft)` 從 container CSS 抓)
    * → width calc 不漂移,無 side-effect。
    *
+   * @internal PeoplePicker stack wrapper 內部協議 — 目前無 active consumer(PeoplePicker 傳 undefined),保留供未來精準 padding;新 consumer 請先評估。
+   *
    * **2026-05-13 v2 deprecate path**:原 PeoplePicker pass `{8}` 假設「Combobox tagPadding=4px,4+8=12」
    * 但 `tagPadding[size]` 是 density-dependent calc `(field-height - icon-size) / 2`,只在 md size +
    * default density 才 = 4px;其他 size/density 漂 6/8px → 4+8=12 公式破。改 PeoplePicker 直接 inject
-   * `!px-3` className 到 Combobox Field wrapper(per people-picker.spec.md:94 v2),`tagAreaPaddingLeftPx`
+   * `!px-[var(--field-px)]` className 到 Combobox Field wrapper(per people-picker.spec.md:94 v2),`tagAreaPaddingLeftPx`
    * 走 undefined。Future 仍保留此 prop 給其他 consumer 精準調整 padding,但 PeoplePicker 已不再用。
    */
   tagAreaPaddingLeftPx?: number
@@ -452,6 +459,8 @@ export interface ComboboxProps {
    */
   overflowShape?: ComboboxOverflowShape
   /**
+   * @internal PeoplePicker stack wrapper 內部協議 — end-user 勿用(measurement-layer override)。
+   *
    * 2026-05-15 Bug 3 fix:override visible count via formula-based primitive(opt-in;default 走
    * DOM-based `useOverflowCount`)。PeoplePicker stack mode 用 `avatar-stack-overflow` primitive
    * deterministic formula 計算 visible count,forward 給 Combobox bypass DOM offsetWidth
@@ -479,6 +488,7 @@ function ReadonlyMultiSelect({
   const variant = variantProp ?? 'default'
   const sz = size ?? 'md'
   const iconSize = sz === 'lg' ? 20 : 16
+  const tagHeight = sz === 'sm' ? 20 : 24
   const containerRef = React.useRef<HTMLDivElement>(null)
   const hasTags = (value?.length ?? 0) > 0
 
@@ -518,14 +528,23 @@ function ReadonlyMultiSelect({
         // 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 不對稱。
-        wrap ? 'flex-wrap py-1' : 'overflow-hidden', className)}
-      style={{ gap: GAP, ...(wrap ? { height: 'auto' } : undefined) }} data-field-mode={resolvedMode}>
+        // 2026-06-27 對齊 edit path(L598-617):wrap 時 items-start + chevron self-start/tagHeight 鎖第一行;
+        // paddingRight: var(--field-px) re-assert 右緣 12px(tagPadding 對稱 calc 會吃掉右緣,跟 edit 一致)。
+        wrap ? 'flex-wrap items-start py-1' : 'overflow-hidden', className)}
+      style={{ gap: GAP, paddingRight: 'var(--field-px)', ...(wrap ? { height: 'auto' } : undefined) }} data-field-mode={resolvedMode}
+      aria-disabled={resolvedMode === 'disabled' ? true : undefined}>
       {hasTags ? (
         <ComboboxTagStack value={value} options={options} tagSize={sz} wrap={wrap}
           containerRef={containerRef} disabled={resolvedMode === 'disabled'} />
       ) : (
         <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
       )}
+      {/* 2026-06-26 類型身份 indicator:edit 顯示 / readonly 不顯示(純值、不可開下拉) / disabled 保留(fg-disabled,對齊原生 <select disabled>);naked cell 依 showDisplayEndIcon */}
+      {(variant === 'naked' ? !!showDisplayEndIcon : resolvedMode === 'disabled') && (
+        <ItemSuffix className={cn('pointer-events-none', wrap && 'self-start')} style={wrap ? { height: tagHeight } : undefined}>
+          <ChevronDown size={iconSize} className={cn('shrink-0', resolvedMode === 'disabled' ? 'text-fg-disabled' : 'text-fg-muted')} aria-hidden />
+        </ItemSuffix>
+      )}
     </div>
   )
 }
@@ -545,27 +564,32 @@ function ReadonlyMultiSelect({
 type ComboboxInternalProps = ComboboxProps & { __triggerRef?: React.Ref<HTMLDivElement> }
 
 function NativeCombobox({
-  mode = 'edit', variant: variantProp, error = false, size = 'md', options, value = [], onChange, placeholder,
-  className, disabled, wrap = false, clearable = false, showDisplayEndIcon = false,
+  mode, variant: variantProp, error = false, size = 'md', options, value = [], onChange, placeholder,
+  className, disabled: disabledProp, wrap = false, clearable = false, showDisplayEndIcon = false,
   __triggerRef,
 }: ComboboxInternalProps) {
-  const fieldCtx = useFieldContext()
-  const variant: FieldVariant = variantProp ?? fieldCtx?.variant ?? 'default'
-  const resolvedMode = disabled ? 'disabled' : mode
+  const disabled = useResolvedFieldDisabled(disabledProp)
+  const variant: FieldVariant = useResolvedFieldVariant(variantProp)
+  // 2026-06-08 SSOT:mode 經 useResolvedFieldMode;修 <Field mode="display"> 漏 cascade
+  const resolvedMode = useResolvedFieldMode({ mode, disabled })
   const iconSize = getIconSize(size)
   const showClear = clearable && value.length > 0 && resolvedMode === 'edit'
 
   const handleRemove = (v: string) => onChange?.(value.filter(x => x !== v))
   const handleAdd = (v: string) => { if (!value.includes(v)) onChange?.([...value, v]) }
 
+  // React #310 fix(對齊 select.tsx):hooks 必在 conditional early-return 前無條件呼叫。
+  // resolvedMode 在 edit↔非edit 切換(<Field mode/disabled> cascade / DataTable cell 進出編輯)時
+  // hook 數量不可變動,否則 Rules of Hooks violation → React #310 「rendered fewer/more hooks」crash。
+  const selectRef = React.useRef<HTMLSelectElement>(null)
+  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} />
   }
 
   const items = value.map(v => ({ value: v, label: options.find(o => o.value === v)?.label ?? v }))
   const unselected = options.filter(o => !value.includes(o.value))
-  const selectRef = React.useRef<HTMLSelectElement>(null)
-  const tagAreaRef = React.useRef<HTMLDivElement>(null)
   const tagHeight = size === 'sm' ? 20 : 24
 
   const selectDropdown = unselected.length > 0 ? (
@@ -580,7 +604,7 @@ function NativeCombobox({
   return (
     <div ref={__triggerRef} className={cn(fieldWrapperStyles({ mode: 'edit', variant: variant, size }), value.length > 0 && tagPadding[size], 'relative',
       wrap && 'items-start py-1', error && ['border-error hover:border-error-hover', 'focus-within:border-error focus-within:hover:border-error'], className)}
-      style={{ paddingRight: '0.75rem', ...(wrap ? { height: 'auto' } : undefined) }} data-field-mode="edit" data-error={error ? '' : undefined}
+      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() } }}>
       {/* 2026-05-18 F2 sync(per user verbatim「modifying 修好 PeoplePicker stack 後改壞 Combobox tag display」
           + 「tag 應該要判斷所在空間最多可以呈現幾個tag(包括＋n)去自動判斷何時要變成+n」):
@@ -592,7 +616,7 @@ function NativeCombobox({
         <OverflowTagList containerRef={tagAreaRef} items={items} size={size} wrap={wrap}
           renderTag={(item) => (
             <Tag size={size} className="shrink-0 relative z-10" onClick={() => { selectRef.current?.showPicker?.(); selectRef.current?.focus() }}
-              onDismiss={() => handleRemove(item.value)}>{item.label}</Tag>
+              onRemove={() => handleRemove(item.value)}>{item.label}</Tag>
           )} onRemove={handleRemove} trailing={value.length === 0 ? selectDropdown : undefined} />
       </div>
       {value.length > 0 && selectDropdown}
@@ -615,7 +639,7 @@ function NativeCombobox({
 // ── Custom Combobox (desktop — consumes SelectMenu) ───────────────────
 
 function CustomCombobox({
-  mode = 'edit', variant: variantProp, error: errorProp = false, size = 'md', options, value = [], onChange, placeholder,
+  mode, variant: variantProp, 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
@@ -636,10 +660,11 @@ function CustomCombobox({
 }: ComboboxInternalProps) {
   const tagAreaGap = tagAreaGapPx ?? GAP
   const fieldCtx = useFieldContext()
-  const error = errorProp || (fieldCtx?.invalid ?? false)
-  const disabled = disabledProp ?? fieldCtx?.disabled
-  const resolvedMode = disabled ? 'disabled' : mode
-  const variant: FieldVariant = variantProp ?? fieldCtx?.variant ?? 'default'
+  const error = useResolvedFieldInvalid(errorProp)
+  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 iconSize = getIconSize(size)
   const showClear = clearable && value.length > 0 && resolvedMode === 'edit'
   const [open, setOpen] = React.useState(defaultOpen)
@@ -653,10 +678,10 @@ function CustomCombobox({
 
   React.useEffect(() => { if (!open) setSearch('') }, [open])
 
-  if (resolvedMode !== 'edit') {
-    return <ReadonlyMultiSelect mode={resolvedMode} variant={variant} size={size} options={options} value={value} wrap={wrap} className={className} showDisplayEndIcon={showDisplayEndIcon} />
-  }
-
+  // React #310 fix(對齊 select.tsx):以下 hooks(useMemo/useRef)必在 conditional early-return 前
+  // 無條件呼叫。resolvedMode 在 edit↔非edit 切換時 hook 數量不可變動,否則 Rules of Hooks
+  // violation → React #310 「rendered fewer/more hooks」crash(ReadonlyMultiSelect 用不到這些值,
+  // 多算無害,對齊 select.tsx hoist pattern)。
   const items = React.useMemo(
     () => value.map(v => ({ value: v, label: options.find(o => o.value === v)?.label ?? v })),
     [value, options]
@@ -674,7 +699,7 @@ function CustomCombobox({
     [searchable, searchIn, search, options]
   )
 
-  // 轉換 SelectOption → SelectMenuOption
+  // 轉換 ComboboxOption → SelectMenuOption
   // 2026-05-10 post-Issue-4 follow-up:forward 全 SelectMenuOption surface(avatar / description /
   // disabled / icon / group)— 修先前 PeoplePicker multi-mode dropdown 漏 avatar drift bug。
   const menuOptions: SelectMenuOption[] = React.useMemo(
@@ -690,13 +715,17 @@ function CustomCombobox({
     [filteredOptions]
   )
 
+  if (resolvedMode !== 'edit') {
+    return <ReadonlyMultiSelect mode={resolvedMode} variant={variant} 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 />
 
   const trigger = (
     <div
       ref={__triggerRef}
       id={fieldCtx?.id}
-      role="combobox" aria-expanded={open} aria-controls={listboxId} tabIndex={0}
+      role="combobox" aria-expanded={open} aria-haspopup="listbox" aria-controls={listboxId} tabIndex={0}
       aria-label={ariaLabel}
       aria-invalid={error || undefined}
       aria-required={fieldCtx?.required || undefined}
@@ -707,8 +736,23 @@ function CustomCombobox({
         // 2026-05-06 v13.3 SSOT retire:per-control `open && 'border-primary'` 移除。Field default
         // 統一處理 — open=灰深(data-state)/ focus=藍(focus-within !important)。改一處全 control 跟動。
         error && ['border-error hover:border-error-hover', 'focus-within:border-error focus-within:hover:border-error'], className)}
-      style={{ paddingRight: '0.75rem', ...(wrap ? { height: 'auto' } : undefined) }}
-      data-field-mode="edit" data-error={error ? '' : undefined}>
+      style={{ paddingRight: 'var(--field-px)', ...(wrap ? { height: 'auto' } : undefined) }}
+      data-field-mode="edit" data-error={error ? '' : undefined}
+      // WAI-ARIA APG combobox 鍵盤開啟語意 — 對齊 sibling Select(select.tsx:593-598)。
+      // <div role=combobox> 不像 native <button> 自動 synthesize Enter/Space click,故顯式補:
+      //   Enter/Space → 開(searchable 時不攔,讓 inline search input 自行處理打字);
+      //   Escape → 關;ArrowDown → 開(APG required combobox 展開鍵,僅在 closed 時攔,
+      //   open 後不 preventDefault 讓方向鍵自由流向選單導覽)。
+      // 純 additive:此 trigger 原無 onKeyDown,不覆寫既有 handler;open 邏輯仍走 setOpen SSOT。
+      onKeyDown={(e) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+          // 2026-06-11 P0 a11y(R2,同 select.tsx 修):Combobox 恆 searchable → 原 `!searchable`
+          // guard 使 Enter/Space 永遠開不了(僅 ArrowDown 可)。正確 guard = !open。
+          if (!open) { e.preventDefault(); setOpen(true) }
+        }
+        if (e.key === 'ArrowDown' && !open) { e.preventDefault(); setOpen(true) }
+        if (e.key === 'Escape') setOpen(false)
+      }}>
       {/* 2026-05-18 #6A Round 1 Step 2/4(per user 拍板「決策6選a」+ codex M31 Step 5 verdict cite combobox.tsx:648):
           CustomCombobox edit non-wrap tagArea 對齊 L293 display + L451 readonly + L518 native edit 已 ship 的 overflow-hidden fix。
           原 overflow-visible 讓 tag 越界蓋 chevron / +N indicator(user 圖三)。M10 propagation 完整 4-path align。 */}
@@ -724,7 +768,7 @@ function CustomCombobox({
               tagRenderer
                 ? tagRenderer(item, () => handleRemove(item.value))
                 : <Tag size={size} className="shrink-0 relative z-10"
-                    onDismiss={() => handleRemove(item.value)}>{item.label}</Tag>
+                    onRemove={() => handleRemove(item.value)}>{item.label}</Tag>
             )}
             renderHiddenTag={renderHiddenTag}
             onRemove={handleRemove}
@@ -792,14 +836,17 @@ function CustomCombobox({
 // ── Public component ────────────────────────────────────────────────────────
 
 const Combobox = React.forwardRef<HTMLDivElement, ComboboxProps>(
-  (props, ref) => {
+  ({ size: sizeProp, ...props }, ref) => {
+    // B 組 cascade fix:public wrapper 一處 resolve size(prop>Field>surface>md)後 forward 給內層,
+    // 讓 <Field size> / DataTable cell surface-size 對 Combobox 生效(內層默認 'md' 被此顯式 size 覆蓋)。
+    const size = useResolvedFieldSize(sizeProp)
     // 2026-05-16 真 root cause fix:之前用 `_ref` drop ref。修為 forward 給 internal
     // `__triggerRef`,讓 PeoplePicker stack 透過 ref 量 trigger DOM(visibleCountOverride
     // 才生效)。對齊 React forwardRef public-API canonical(MUI Autocomplete / Radix
     // Popover.Trigger 共識)+ codex M31 Step 5 比稿 verdict + DS-wide ref-drop iceberg audit。
     const isMobile = useIsTouchDevice()
-    if (isMobile) return <NativeCombobox {...props} __triggerRef={ref} />
-    return <CustomCombobox {...props} __triggerRef={ref} />
+    if (isMobile) return <NativeCombobox {...props} size={size} __triggerRef={ref} />
+    return <CustomCombobox {...props} size={size} __triggerRef={ref} />
   }
 )
 Combobox.displayName = 'Combobox'

package/src/components/Combobox/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// 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 './combobox'

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

@@ -0,0 +1,107 @@
+// @anatomy-rationale:
+//   Inspector / ColorMatrix / SizeMatrix / StateBehavior N/A — Command 是
+//   headless Internal primitive(cmdk passthrough),不被 App 直接消費,而是透過
+//   SelectMenu 等外層元件呈現。色彩 / 尺寸 / 狀態都由消費方(SelectMenu / Combobox /
+//   PeoplePicker)決定並在各自的 anatomy 詳述。本檔僅保留 Overview 教結構與
+//   消費路徑。
+import type { Meta, StoryObj } from '@storybook/react'
+import { Settings, User, LogOut, FileText } from 'lucide-react'
+import {
+  Command,
+  CommandInput,
+  CommandList,
+  CommandEmpty,
+  CommandGroup,
+  CommandItem,
+  CommandSeparator,
+  CommandShortcut,
+} from './command'
+import { H3, Desc, Td, Th } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
+
+const meta: Meta = {
+  title: 'Design System/Internal/Command/設計規格',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+export const Overview: Story = {
+  name: '元件總覽',
+  render: () => (
+    <div className="flex flex-col gap-10">
+      <div>
+        <H3>Anatomy</H3>
+        <Desc>Command 是 shadcn passthrough(基於 cmdk library)——搜尋 + 鍵盤導覽的指令清單。結構:CommandInput(搜尋框)+ CommandList(捲動區)+ CommandGroup(分組)+ CommandItem(項目)+ CommandEmpty(空狀態)。本 DS 在 cmdk 原結構上套用設計 token(顏色 / 字級 / 間距),並用 ScrollArea 包住清單做跨系統一致的捲軸;選項與空狀態的樣式直接寫在 Command 內,不透過其他元件。</Desc>
+        <div className="rounded-lg border border-border max-w-md overflow-hidden">
+          <Command>
+            <CommandInput placeholder="輸入指令或搜尋..." />
+            <CommandList>
+              <CommandEmpty>找不到結果</CommandEmpty>
+              <CommandGroup heading="常用">
+                <CommandItem>
+                  <FileText className="mr-2 h-4 w-4" />
+                  建立新文件
+                </CommandItem>
+                <CommandItem>
+                  <Settings className="mr-2 h-4 w-4" />
+                  前往設定
+                  <CommandShortcut>⌘K</CommandShortcut>
+                </CommandItem>
+              </CommandGroup>
+              <CommandSeparator />
+              <CommandGroup heading="帳號">
+                <CommandItem>
+                  <User className="mr-2 h-4 w-4" />
+                  個人資料
+                </CommandItem>
+                <CommandItem>
+                  <LogOut className="mr-2 h-4 w-4" />
+                  登出
+                </CommandItem>
+              </CommandGroup>
+            </CommandList>
+          </Command>
+        </div>
+      </div>
+
+      <div>
+        <H3>結構元件</H3>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>元件</Th><Th>作用</Th></tr></thead>
+            <tbody>
+              <tr><Td mono>Command</Td><Td>根容器,包住整個搜尋清單</Td></tr>
+              <tr><Td mono>CommandInput</Td><Td>搜尋框(自動過濾 items)</Td></tr>
+              <tr><Td mono>CommandList</Td><Td>捲動區,包含 items</Td></tr>
+              <tr><Td mono>CommandEmpty</Td><Td>搜尋無結果時顯示的空狀態文案</Td></tr>
+              <tr><Td mono>CommandGroup</Td><Td>分組容器(可選 heading)</Td></tr>
+              <tr><Td mono>CommandItem</Td><Td>單一選項,含圖示 + 文字 + 右側 shortcut</Td></tr>
+              <tr><Td mono>CommandSeparator</Td><Td>分組間分隔線</Td></tr>
+              <tr><Td mono>CommandShortcut</Td><Td>右側 shortcut 提示(⌘K 等)</Td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <div>
+        <H3>消費場景</H3>
+        <Desc>Command 本身不單獨使用,透過 SelectMenu 外層元件消費:
+          <br />• <code className="font-mono text-footnote">SelectMenu</code> — Select / Combobox / PeoplePicker 的 searchable 浮層
+          <br />• <code className="font-mono text-footnote">Command Palette</code>(Cmd+K)— 全局跨頁搜尋入口(消費本檔 export 的 CommandDialog 包裝,cmdk + Radix Dialog;見展示層「CommandPalette」)
+        </Desc>
+      </div>
+    </div>
+  ),
+}
+
+// ── Accessibility ─────────────────────────────────────────────────────────
+// 2026-05-17 ship per audit Dim 13(story-rules.md 6-canonical 含 Accessibility)
+export const Accessibility = {
+  name: '無障礙',
+  render: () => (
+    <div className="max-w-3xl text-body text-fg-secondary">
+      <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
+      <p className="whitespace-pre-line">{"詳 `command.spec.md` 「A11y 預設」段。摘要:\n\ncmdk 自動處理：\n\n-   List 語意  ： role=\"listbox\"  +  aria-activedescendant  指向目前 highlight 項\n-   搜尋框  ： role=\"combobox\"  +  aria-expanded  /  aria-controls  指向 list\n-   鍵盤導覽  ：cmdk 提供 ↑ / ↓ 移動 highlight、Enter 選取（另支援 vim-style Ctrl+n/p/j/k、Home/End）。cmdk 本身無 Esc handler — Esc 關閉僅在 CommandDialog（Cmd+K）模式由 Radix Dialog 的 DismissableLayer 提供；inline <Command> 模式按 Esc 無反應\n-   空狀態  ： <CommandEmpty>  自動帶  role=\"presentation\" ,不干擾 screen reader 的 list 朗讀\n\nConsumer 無需額外處理 a11y,保留 cmdk 原結構 + 使用  <CommandInput>  /  <CommandList>  /  <CommandItem>  即可。"}</p>
+    </div>
+  ),
+}

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

@@ -0,0 +1,88 @@
+// @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.
+import type { Meta, StoryObj } from '@storybook/react'
+import LinkTo from '@storybook/addon-links/react'
+
+const meta: Meta = {
+  title: 'Design System/Internal/Command/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// ── WhenToUse — 何時使用 Command ──────────────────────
+
+
+// ── UsageGuidance — 整合何時用 / 何時不用 / vs 近親(Polaris/Material/Ant 共識)
+// 合併自舊 WhenToUse / VsSelectMenuRule(2026-04-26 v3 canonical)
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div className="flex flex-col gap-12">
+      {/* 何時用 — 原 WhenToUse */}
+      <div className="prose prose-sm max-w-prose">
+      <p>適合 Command 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+      <ul className="space-y-1">
+        <li>
+          <LinkTo kind="Design System/Internal/Command/展示" name="全域指令面板"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">全域指令面板(⌘K)— Linear / VS Code 式跨頁搜尋與快速動作</span></LinkTo>
+        </li>
+        <li>
+          <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>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Internal/Command/展示" name="無結果狀態"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">搜尋無結果時的空狀態文案(CommandEmpty)</span></LinkTo>
+        </li>
+      </ul>
+      <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見下方「vs 近親」段)。</p>
+    </div>
+
+      {/* vs 近親 — VsSelectMenuRule — 原 VsSelectMenuRule */}
+      <div className="prose prose-sm max-w-prose">
+      <p>兩者皆 keyboard navigation 但 mental model 不同:</p>
+      <ul>
+        <li><strong>Command</strong> — keyboard-first 命令面板;搜尋為主、可執行 action(non-form)</li>
+        <li><strong>SelectMenu</strong> — form-input 的選擇器;value 寫回 form,讀取 selected value</li>
+      </ul>
+      <p className="text-fg-muted">判斷:結果是「執行某 action」→ Command;結果是「設定欄位 value」→ SelectMenu。</p>
+    </div>
+    </div>
+  ),
+}
+
+// ── CompositionRules — Command 的兩個 consumer pattern(對齊 Polaris「Related」+ Material「Use within」)──────
+
+export const CompositionRules: Story = {
+  name: '組合規則',
+  render: () => (
+    <div className="flex flex-col gap-12">
+      <div className="prose prose-sm max-w-prose">
+        <p>Command 是 internal primitive,由消費者組合使用,**不直接放在 app code**。以下兩種 world-class 慣例(對齊 Linear / Raycast / VS Code Cmd-K idiom):</p>
+
+        <h4>Pattern 1 — SelectMenu 內嵌 Command(searchable form input)</h4>
+        <p>需要「搜尋 + 選值寫回 form」→ 用 <code>SelectMenu</code>(內部已組合 <code>Popover + Command</code>),<strong>不要</strong>自己組合:</p>
+        <ul>
+          <li><LinkTo kind="Design System/Components/Combobox/展示" name="四模式"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Combobox</span></LinkTo>——可搜尋多選(如商品類別多選標籤)</li>
+          <li><LinkTo kind="Design System/Components/Select/展示" name="搜尋"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Select(searchable)</span></LinkTo>——可搜尋單選(如從長國家清單打字篩選)</li>
+          <li><LinkTo kind="Design System/Components/PeoplePicker/展示" name="單人"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">PeoplePicker</span></LinkTo>——人員搜尋(如指派任務負責人)</li>
+        </ul>
+
+        <h4>Pattern 2 — Popover + Command 組成 Command Palette(Cmd+K)</h4>
+        <p>需要「全域 keyboard 觸發 + 跨頁搜尋 / 動作」→ 自行組合 <code>Popover + Command</code>(對齊 Linear ⌘K / Raycast / VS Code Quick Pick):</p>
+        <pre className="text-xs"><code>{`<Popover open={cmdkOpen}>
+  <Command>
+    <CommandInput placeholder="輸入指令..." />
+    <CommandList>
+      <CommandGroup heading="動作">
+        <CommandItem>新建文件</CommandItem>
+      </CommandGroup>
+    </CommandList>
+  </Command>
+</Popover>`}</code></pre>
+        <p className="text-fg-muted">禁止:在產品端自己刻搜尋框 + 過濾清單 — 一律重用 Command,不要重造一份。</p>
+      </div>
+    </div>
+  ),
+}