@qijenchen/design-system 0.1.0-beta.3

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

@@ -0,0 +1,430 @@
+// @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 * as React from 'react'
+import { Plus, Search } from 'lucide-react'
+import type { LucideIcon } from 'lucide-react'
+import { cn } from '@/lib/utils'
+import type { AvatarData } from '@/design-system/components/Avatar/avatar'
+import { Popover, PopoverContent, PopoverTrigger } from '@/design-system/components/Popover/popover'
+import { Command, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator } from '@/design-system/components/Command/command'
+import { Command as CommandPrimitive } from 'cmdk'
+import { MenuItem, MenuFooter } from '@/design-system/components/Menu/menu-item'
+import { Empty } from '@/design-system/components/Empty/empty'
+import { CircularProgress } from '@/design-system/components/CircularProgress/circular-progress'
+import { OVERLAY_SIDE_OFFSET } from '@/design-system/tokens/elevation/overlay-geometry'
+import { getMenuListMinHeight } from '@/design-system/components/Field/field-types'
+import { RowSizeProvider } from '@/design-system/patterns/element-anatomy/item-anatomy'
+import { applySelectAll, clearSelection } from '@/design-system/lib/multi-select-ordering'
+import { ICON_SIZE } from '@/design-system/tokens/uiSize/icon-size'
+
+/**
+ * SelectMenu — Popover + Command 組成的完整下拉選單
+ *
+ * ── 功能 ──
+ *   單選 / 多選、搜尋過濾、分組、可建立新選項（creatable）
+ *   多選有 footer「全部」checkbox
+ *
+ * ── 架構 ──
+ *   Popover（浮動容器）
+ *     └── Command（cmdk，搜尋 + 鍵盤導覽）
+ *           ├── CommandInput（搜尋框）
+ *           ├── CommandList（選項列表）
+ *           │     └── CommandGroup → MenuItem
+ *           └── Footer（多選全選）
+ */
+
+// ── Types ──
+
+export interface SelectMenuOption {
+  value: string
+  label: string
+  description?: string
+  icon?: LucideIcon
+  avatar?: AvatarData
+  disabled?: boolean
+  group?: string
+}
+
+export interface SelectMenuGroupConfig {
+  key: string
+  label: string
+}
+
+type SizeKey = 'sm' | 'md' | 'lg'
+
+// ── Component ──
+
+export interface SelectMenuProps {
+  /** 選項列表 */
+  options: SelectMenuOption[]
+  /** 群組定義（key 對應 option.group） */
+  groups?: SelectMenuGroupConfig[]
+
+  /** 當前值（單選 string，多選 string[]） */
+  value?: string | string[] | null
+  /** 值變更 callback */
+  onValueChange?: (value: string | string[]) => void
+
+  /** 多選模式 */
+  multiple?: boolean
+  /** 顯示搜尋框 */
+  searchable?: boolean
+  /** 可建立新選項 */
+  creatable?: boolean
+  /** 建立新選項 callback */
+  onCreate?: (value: string) => void
+  /** creatable 的 label 格式，預設 '直接使用「{query}」' */
+  createLabel?: (query: string) => string
+
+  /** 觸發元件（asChild） */
+  children: React.ReactNode
+  /** 搜尋框 placeholder */
+  searchPlaceholder?: string
+  /** 空選項提示 */
+  emptyText?: string
+  /** Loading 狀態(2026-05-15 audit B fix per user verbatim「dropdown 隨時可開,讀取在 panel 中間 CircularProgress」)
+   *  true → render `<Empty icon={<CircularProgress size={48}/>} description={loadingText} />` 取代 options;
+   *  trigger 不變,user 隨時可開 dropdown。對齊 MUI Autocomplete `loadingText` dropdown-body + Ant Select
+   *  loading idiom + DS 既有 `empty.spec.md:182` 「全頁 loading = Empty + CircularProgress compose」SSOT。
+   */
+  loading?: boolean
+
+  /** 尺寸 */
+  size?: SizeKey
+  /** 對齊方式 */
+  align?: 'start' | 'end'
+  /** 列表最少顯示幾行選項高度（預設 3），影響空狀態最小高度 */
+  minRows?: number
+  /** 最小寬度（px），預設跟隨觸發元件 */
+  minWidth?: number
+
+  /** 受控 open 狀態 */
+  open?: boolean
+  /** 預設打開(uncontrolled initial state)— 2026-05-15 audit Dim 26 V1 fix per user verbatim「A:1」approval */
+  defaultOpen?: boolean
+  /** open 狀態變更 callback */
+  onOpenChange?: (open: boolean) => void
+
+  /** 自訂選項 label 渲染（預設渲染 option.label 純文字） */
+  renderLabel?: (option: SelectMenuOption) => React.ReactNode
+  /** 攔截 PopoverContent 的 onOpenAutoFocus（如 Select searchable 需阻止 focus 搶走） */
+  onOpenAutoFocus?: (e: Event) => void
+
+  /**
+   * Popover 內容容器的 DOM id。Combobox / 自定 trigger 用 `aria-controls` 指向此 id 時,
+   * 需傳入相同 id 讓 AT 能找到對應的 listbox。
+   */
+  contentId?: string
+
+  className?: string
+}
+
+// shadcn canonical:forwardRef + displayName 統一。SelectMenu 是 Popover + Command
+// composite,自身無 DOM host(trigger 由 consumer 以 asChild children 提供),ref 簽名
+// 保留但不附著(consumer 想取 trigger DOM 直接在 children 上自己 ref)。className 合併到
+// PopoverContent(contextually 最接近 user-facing surface)。
+const SelectMenu = React.forwardRef<HTMLElement, SelectMenuProps>(function SelectMenu({
+  options,
+  groups,
+  value,
+  onValueChange,
+  multiple = false,
+  searchable = false,
+  creatable = false,
+  onCreate,
+  createLabel = (q) => `直接使用「${q}」`,
+  children,
+  searchPlaceholder = '搜尋…', // i18n-allow: DS default; consumer override via searchPlaceholder prop
+  emptyText = '沒有符合的選項', // i18n-allow: DS default; consumer override via emptyText prop
+  loading = false,
+  size = 'md',
+  align = 'start',
+  minRows = 3,
+  minWidth,
+  open: controlledOpen,
+  defaultOpen,
+  onOpenChange: controlledOnOpenChange,
+  renderLabel,
+  onOpenAutoFocus,
+  contentId,
+  className,
+}, _ref) {
+  // ── State ──
+  const [internalOpen, setInternalOpen] = React.useState(defaultOpen ?? false)
+  const open = controlledOpen ?? internalOpen
+  const setOpen = controlledOnOpenChange ?? setInternalOpen
+  const [search, setSearch] = React.useState('')
+
+  // ── Value helpers ──
+  const selectedValues = React.useMemo<string[]>(() => {
+    if (value == null) return []
+    return Array.isArray(value) ? value : [value]
+  }, [value])
+
+  const isSelected = React.useCallback(
+    (v: string) => selectedValues.includes(v),
+    [selectedValues]
+  )
+
+  const handleSelect = React.useCallback(
+    (optionValue: string) => {
+      if (multiple) {
+        const next = isSelected(optionValue)
+          ? selectedValues.filter((v) => v !== optionValue)
+          : [...selectedValues, optionValue]
+        onValueChange?.(next)
+      } else {
+        onValueChange?.(optionValue)
+        setOpen(false)
+      }
+    },
+    [multiple, selectedValues, isSelected, onValueChange, setOpen]
+  )
+
+  // ── Multi-select: select all ──
+  const selectableOptions = React.useMemo(
+    () => options.filter((o) => !o.disabled),
+    [options]
+  )
+
+  const allState: boolean | 'indeterminate' = React.useMemo(() => {
+    if (!multiple) return false
+    const count = selectableOptions.filter((o) => isSelected(o.value)).length
+    if (count === 0) return false
+    if (count === selectableOptions.length) return true
+    return 'indeterminate'
+  }, [multiple, selectableOptions, isSelected])
+
+  // 2026-05-16 SSOT canonical fix(Claude+Codex M31 Round 4 共識 + user verbatim「就照你們
+  // 的共識做到完美確保有 SSOT」):
+  //
+  // 原 fully-replace `selectableOptions.map(v)` = source order reset,但**Ant Design 跨元件 grep
+  // 證據顯示 source-reset 沒 Ant precedent**(Transfer + Table rowSelection 都是 preserve+append)。
+  // 改 `applySelectAll(selectedValues, all)` SSOT primitive 對齊 Ant Transfer canonical:
+  //   `Array.from(new Set([...prevKeys, ...keys]))` — preserve existing + append unselected。
+  //
+  // SSOT in `@/design-system/lib/multi-select-ordering` — 未來新 multi-select with Select All
+  // footer 必 consume 此 primitive(hook `check_select_all_canonical.sh` 機械強制),
+  // 不再各自 reimplement → 防 ordering policy drift。
+  const handleSelectAll = React.useCallback(() => {
+    if (!multiple) return
+    if (allState === true) {
+      onValueChange?.(clearSelection())
+    } else {
+      onValueChange?.(applySelectAll(selectedValues, selectableOptions.map((o) => o.value)))
+    }
+  }, [multiple, allState, selectableOptions, selectedValues, onValueChange])
+
+  // ── Creatable ──
+  const showCreate = React.useMemo(() => {
+    if (!creatable || !search.trim()) return false
+    return !options.some(
+      (o) => o.label.toLowerCase() === search.trim().toLowerCase()
+    )
+  }, [creatable, search, options])
+
+  // ── Grouping ──
+  const groupedOptions = React.useMemo(() => {
+    if (!groups?.length) return [{ key: '__default', label: '', options }]
+    const grouped = groups.map((g) => ({
+      ...g,
+      options: options.filter((o) => o.group === g.key),
+    }))
+    const ungrouped = options.filter((o) => !o.group)
+    if (ungrouped.length) {
+      grouped.unshift({ key: '__default', label: '', options: ungrouped })
+    }
+    return grouped
+  }, [groups, options])
+
+  // ── Reset search on close ──
+  React.useEffect(() => {
+    if (!open) setSearch('')
+  }, [open])
+
+  // RowSizeProvider 讓 PopoverContent 子樹內任何 <ItemIcon> / <ItemAvatar> /
+  // <ItemInlineAction> 都自動讀到對的 size,跟 SidebarProvider / TreeView 同一條規則。
+  // (注:Popover 透過 Portal 渲染,context 仍然會跨 portal 傳遞——React context 是 tree-based
+  // 不是 DOM-based,Portal 不影響 context propagation)
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>{children}</PopoverTrigger>
+      <RowSizeProvider value={size}>
+      <PopoverContent
+        id={contentId}
+        // w-auto override PopoverContent default w-72(rich-popover canonical)— SelectMenu 走「跟 trigger 同寬」
+        // canonical(spec L72)。minWidth = max(trigger-width, 240px sensible-min)— 對齊 shadcn / Material / Ant
+        // select dropdown 共識(2026-05-04 D1 verify SelectMenu spec implementation)。
+        className={cn(
+          'p-0 w-auto rounded-lg border border-border bg-surface-raised overflow-hidden',
+          className
+        )}
+        style={{
+          boxShadow: 'var(--elevation-200)',
+          minWidth: minWidth ?? 'max(var(--radix-popover-trigger-width), 15rem)',
+        }}
+        align={align}
+        sideOffset={OVERLAY_SIDE_OFFSET}
+        onOpenAutoFocus={onOpenAutoFocus}
+        // **2026-05-07 v15.16 nested portal fix**:Tag dismiss inside trigger
+        // 區的 OverflowIndicator HoverCard popup(獨立 Radix portal,DOM 不在
+        // PopoverContent 內)— Radix DismissableLayer document-level outside
+        // detection 跨 portal 視為「outside」→ SelectMenu 被誤關閉。
+        // 攔 `onPointerDownOutside`,檢查 click target 是否在另一個 Radix portal
+        // 內,是 → preventDefault 取消 close。對齊 Ant Design Select multiSelect
+        // tagRender 行為(連續移除不關 dropdown)。
+        // SSOT propagation:fix 在 SelectMenu level → Combobox / 其他 SelectMenu
+        // consumer 自動受益。
+        // **2026-05-07 v15.16 nested portal fix**:Tag dismiss inside trigger 區的
+        // OverflowIndicator HoverCard popup(獨立 Radix portal,DOM 不在 SelectMenu
+        // PopoverContent 內)— Radix DismissableLayer document-level pointerdown +
+        // focusin 偵測「outside」→ SelectMenu 被誤關閉。
+        // 攔 `onInteractOutside`(統一 pointerdown + focusin),檢查 click target 是否
+        // 在另一個 Radix portal wrapper(`[data-radix-popper-content-wrapper]`),
+        // 是 → preventDefault 取消 close。對齊 Ant Design Select multiSelect tagRender
+        // 行為(連續移除不關 dropdown)。
+        // SSOT propagation:fix 在 SelectMenu level → Combobox / 所有 SelectMenu
+        // consumer 自動受益。
+        onInteractOutside={(e) => {
+          const target = e.detail.originalEvent.target as HTMLElement | null
+          if (target?.closest('[data-radix-popper-content-wrapper]')) {
+            e.preventDefault()
+          }
+        }}
+      >
+        <Command shouldFilter={searchable} className="bg-transparent">
+          {searchable && (
+            <div className={cn(
+              'flex items-center gap-2 px-3 py-1 border-b border-divider',
+              size === 'lg' ? 'min-h-[calc(var(--field-height-lg)+8px)]'
+                : size === 'sm' ? 'min-h-[calc(var(--field-height-sm)+8px)]'
+                : 'min-h-[calc(var(--field-height-md)+8px)]',
+            )}>
+              <Search size={ICON_SIZE[size as 'sm' | 'md' | 'lg']} className="shrink-0 text-fg-muted" aria-hidden />
+              <CommandPrimitive.Input
+                placeholder={searchPlaceholder}
+                value={search}
+                onValueChange={setSearch}
+                className={cn(
+                  'flex w-full bg-transparent outline-none placeholder:text-fg-muted',
+                  // M24 disabled state precedence:disabled 時 placeholder 切 fg-disabled(audit dim 34)
+                  'disabled:placeholder:text-fg-disabled disabled:text-fg-disabled disabled:cursor-not-allowed',
+                  size === 'lg' ? 'text-body-lg leading-compact' : 'text-body leading-compact',
+                )}
+              />
+            </div>
+          )}
+          {/* **2026-05-07 v15.13 R2 fix**:minHeight 從 CommandList 搬到 CommandEmpty。
+              原本 CommandList 永遠套 `minHeight = field-height × minRows + 16px`,結果
+              user 過濾出 < minRows 個 match 時 list 底下空一片(eg. 打 'c' 出 2 個 match
+              卻撐高到 3 row 容量,1 row 留白)。 Fix:只有 empty state 才需要 minHeight 撐
+              起 placeholder 視覺;有 results 時 CommandList 自然 fit content。 */}
+          <CommandList className="relative">
+            <CommandEmpty
+              className="flex items-center justify-center"
+              style={{ minHeight: getMenuListMinHeight(size, minRows) }}
+            >
+              {loading
+                ? <Empty icon={<CircularProgress size={48}/>} className="py-6" />
+                : <Empty description={emptyText} className="py-6" />}
+            </CommandEmpty>
+
+            {groupedOptions.map((group, gi) => (
+              <React.Fragment key={group.key}>
+                {gi > 0 && <CommandSeparator />}
+                <CommandGroup className="p-0 py-2">
+                  {group.label && (
+                    <MenuItem size={size} header>{group.label}</MenuItem>
+                  )}
+                  {group.options.map((opt) => (
+                    <CommandItem
+                      key={opt.value}
+                      value={opt.label}
+                      keywords={opt.description ? [opt.description] : undefined}
+                      disabled={opt.disabled}
+                      onSelect={() => handleSelect(opt.value)}
+                      className="p-0 rounded-none data-[selected=true]:bg-transparent"
+                    >
+                      <MenuItem
+                        size={size}
+                        startIcon={opt.icon}
+                        avatar={opt.avatar}
+                        description={opt.description}
+                        checkbox={multiple}
+                        checked={isSelected(opt.value)}
+                        selected={!multiple && isSelected(opt.value)}
+                        disabled={opt.disabled}
+                      >
+                        {renderLabel ? renderLabel(opt) : opt.label}
+                      </MenuItem>
+                    </CommandItem>
+                  ))}
+                </CommandGroup>
+              </React.Fragment>
+            ))}
+
+            {/* Creatable item */}
+            {showCreate && (
+              <>
+                <CommandSeparator />
+                <CommandGroup className="p-0 py-2">
+                  <CommandItem
+                    value={search}
+                    onSelect={() => {
+                      onCreate?.(search.trim())
+                      setSearch('')
+                    }}
+                    className="p-0 rounded-none data-[selected=true]:bg-transparent"
+                  >
+                    <MenuItem size={size} startIcon={Plus}>
+                      {createLabel(search.trim())}
+                    </MenuItem>
+                  </CommandItem>
+                </CommandGroup>
+              </>
+            )}
+          </CommandList>
+
+          {/* Multi-select footer: Select All
+              - 沒有選項時不顯示(selectableOptions.length === 0)
+              - 搜尋有文字時不顯示(search 非空 = 使用者在找特定項目,「全選」沒意義) */}
+          {multiple && selectableOptions.length > 0 && !search && (
+            <MenuFooter>
+              <MenuItem
+                size={size}
+                checkbox
+                checked={allState}
+                onClick={handleSelectAll}
+              >
+                全部
+              </MenuItem>
+            </MenuFooter>
+          )}
+        </Command>
+      </PopoverContent>
+      </RowSizeProvider>
+    </Popover>
+  )
+})
+
+SelectMenu.displayName = 'SelectMenu'
+
+// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)
+// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
+export const selectMenuMeta = {
+  component: 'SelectMenu',
+  family: 4,
+  variants: {
+
+  },
+  sizes: {
+
+  },
+  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  tokens: {
+    bg: ['bg-surface-raised', 'bg-transparent'],
+    fg: ['text-fg-muted'],
+    ring: [],
+  },
+} as const
+
+export { SelectMenu }

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

@@ -0,0 +1,261 @@
+import * as React from 'react'
+import { cva, type VariantProps } from 'class-variance-authority'
+import type { LucideIcon } from 'lucide-react'
+import { cn } from '@/lib/utils'
+import { Avatar, type AvatarData } from '@/design-system/components/Avatar/avatar'
+import { ICON_SIZE, AVATAR_SIZE } from '@/design-system/patterns/element-anatomy/item-anatomy'
+
+// ── Selection Item Styles ───────────────────────────────────────────────────
+// Checkbox 和 RadioGroup 共用的 item 佈局。
+//
+// 結構(item-anatomy.spec.md 4-slot 模型):
+//   [control] [optional prefix(icon|avatar)] [content(label/desc)] [optional suffix]
+//
+// padding 公式：py = (field-height - 1lh) / 2
+//   - 單行時 item 高度 = field-height（對齊同 size 的 Input）
+//   - 多行時 padding 不變（文字間距一致）
+//   - density 切換時 field-height 自動調整，padding 跟著算
+//
+// 容器設 text-body / text-body-lg 建立 1lh context（div 上正常繼承）。
+//
+// ── 為什麼 NOT 消費 ROW_PADDING_BY_SIZE(item-anatomy.tsx SSOT,2026-04-24 consolidation)──
+// menu / sidebar / tree 3 cva 統一消費 ROW_PADDING_BY_SIZE;SelectionItem 刻意不消費,
+// 因 typography 不同(mode 差異,非 drift):
+//   - ROW_PADDING_BY_SIZE:`text-body leading-compact`(scanning mode,緊湊)
+//   - SelectionItem:`text-body`(**無 leading-compact** — reading mode,Checkbox/Radio 搭配
+//     較長 label + description,需預設 1.5 leading 而非 1.3 compact)
+// py 公式本身相同 — 若 field-height token 變動,本檔需手動同步(contained,由本註解 anchor 追)。
+
+// code-quality-allow: dead-export — public API surface — consumer-exposed for future use
+export const selectionItemStyles = cva(
+  'flex items-start gap-2',
+  {
+    variants: {
+      size: {
+        sm: 'text-body py-[calc((var(--field-height-sm)_-_1lh)_/_2)]',
+        md: 'text-body py-[calc((var(--field-height-md)_-_1lh)_/_2)]',
+        lg: 'text-body-lg py-[calc((var(--field-height-lg)_-_1lh)_/_2)]',
+      },
+    },
+    defaultVariants: {
+      size: 'md',
+    },
+  }
+)
+
+type SizeKey = 'sm' | 'md' | 'lg'
+
+// Avatar 尺寸 + Icon 尺寸從 item-layout module 共用,不在此 re-declare(避免漂移)
+// AVATAR_SIZE / ICON_SIZE 都是 item-layout 的 canonical 常數。
+//
+// SelectionItem 跟 MenuItem 的差異:SelectionItem 有 control(checkbox/radio)。
+// block 模式時 **control 跟 prefix 一起走 block 高度**——兩者都在 text block center,
+// 維持「selection + identity」是一組的視覺語意,不會歪斜。
+const AVATAR_PX = AVATAR_SIZE
+
+// ── Block 對齊容器 ──
+// sm/md: reading mode (body 14/1.5 + body 14/1.5) — gap token `reading`
+// lg:    reading-lg mode (body-lg 16/1.5 + body 14/1.5) — gap token `reading-lg`
+// desc 永遠 body(14) line-height;`1lh` 會 resolve 到 label 的 line-height(sm/md=21, lg=24)
+const blockAlignClass: Record<SizeKey, string> = {
+  sm: 'h-[calc(1lh+var(--item-gap-label-desc-reading)+var(--font-body-size)*1.5)]',
+  md: 'h-[calc(1lh+var(--item-gap-label-desc-reading)+var(--font-body-size)*1.5)]',
+  lg: 'h-[calc(1lh+var(--item-gap-label-desc-reading-lg)+var(--font-body-size)*1.5)]',
+}
+
+// ── Selection Item ──────────────────────────────────────────────────────────
+// 通用 item 行：control + 可選 prefix(icon/avatar) + label + description。
+// control 永遠包在 h-[1lh] 容器內,對齊第一行 label。
+// prefix 走 24px 閾值規則,各自獨立對齊。
+
+export interface SelectionItemProps extends React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof selectionItemStyles> {
+  /** Checkbox 或 RadioGroupItem 元素(永遠存在,永遠 inline 對齊) */
+  control: React.ReactNode
+  /** Label 文字 */
+  label: React.ReactNode
+  /** 描述文字(fg-secondary;reading mode 永遠 14px) */
+  description?: React.ReactNode
+  /**
+   * 可選的左側 icon(在 control 之後、label 之前)。LucideIcon 型別,元件內部控制尺寸
+   * (16/16/20px @ sm/md/lg)。**永遠 inline 對齊第一行 label**(icon ≤24px)。
+   * 與 `avatar` 互斥。
+   */
+  icon?: LucideIcon
+  /**
+   * 可選的左側 avatar(在 control 之後、label 之前)。`AvatarData` 資料型別,元件內部渲染 Avatar。
+   * 尺寸由 `description` 自動決定(跟 MenuItem 同 convention):
+   * - 無 desc → inline(20/24/24px),跟 control 同步在 label 第一行
+   * - 有 desc → block(32/32/40px),跟 control 同步在 text block center
+   *
+   * Block 模式時 **control(checkbox/radio)也一起走 block 高度**——兩者都在
+   * text block center,不會歪斜。與 `icon` 互斥。
+   */
+  avatar?: AvatarData
+  /** htmlFor（label 指向 control 的 id） */
+  htmlFor?: string
+  /** disabled 狀態影響 label 顏色 */
+  disabled?: boolean
+  /**
+   * Label 最大行數(line-clamp 截斷)。
+   *
+   * - `undefined`(預設 prop 值未傳)→ 套用元件預設 `'none'`(form 欄位允許任意長度)
+   * - 數字 → 截斷到該行數
+   * - `'none'` → 明確不截斷(語意等同預設)
+   *
+   * 為什麼用 `'none'` 而不是 `undefined`?React props 的 destructure default 在
+   * `undefined` 時會接管,要明確覆寫必須用非 undefined 的 sentinel。
+   */
+  labelMaxLines?: number | 'none'
+  /**
+   * Description 最大行數。預設 `'none'`(不截)。
+   */
+  descMaxLines?: number | 'none'
+  className?: string
+}
+
+/** 把 maxLines 轉成 line-clamp class;'none' / 0 → 空字串 */
+function lineClampClass(maxLines: number | 'none'): string {
+  if (maxLines === 'none' || !maxLines) return ''
+  if (maxLines === 1) return 'line-clamp-1'
+  if (maxLines === 2) return 'line-clamp-2'
+  if (maxLines === 3) return 'line-clamp-3'
+  if (maxLines === 4) return 'line-clamp-4'
+  if (maxLines === 5) return 'line-clamp-5'
+  if (maxLines === 6) return 'line-clamp-6'
+  return ''
+}
+
+// ── PrefixSlot — 24px 閾值規則 ──
+// icon(永遠 ≤24px)→ inline;avatar + 無 desc → inline;avatar + 有 desc → block(centered on text block)
+type PrefixSlotProps = {
+  icon: LucideIcon | undefined
+  avatar: AvatarData | undefined
+  sizeKey: SizeKey
+  alignClass: string
+  avatarPx: number
+  disabled: boolean | undefined
+}
+function PrefixSlot({ icon: Icon, avatar, sizeKey, alignClass, avatarPx, disabled }: PrefixSlotProps) {
+  if (!Icon && !avatar) return null
+  return (
+    <div className={cn(alignClass, 'flex items-center shrink-0')}>
+      {Icon && (
+        <Icon
+          size={ICON_SIZE[sizeKey]}
+          className={cn('shrink-0', disabled && 'text-fg-disabled')}
+          aria-hidden
+        />
+      )}
+      {!Icon && avatar && (
+        <Avatar src={avatar.src} alt={avatar.alt} color={avatar.color} hoverCard={avatar.hoverCard} size={avatarPx} />
+      )}
+    </div>
+  )
+}
+
+// ── ContentSlot — label + optional description ──
+// inline-style fontSize 繞 tailwind-merge 把 text-body / text-fg-secondary 誤判同組衝突的 bug
+type ContentSlotProps = {
+  htmlFor: string | undefined
+  disabled: boolean | undefined
+  label: React.ReactNode
+  description: React.ReactNode | undefined
+  sizeKey: SizeKey
+  labelClampClass: string
+  descClampClass: string
+}
+function ContentSlot({ htmlFor, disabled, label, description, sizeKey, labelClampClass, descClampClass }: ContentSlotProps) {
+  return (
+    <div className="min-w-0 flex-1">
+      <label
+        htmlFor={htmlFor}
+        className={cn(
+          'cursor-pointer block break-words',
+          labelClampClass,
+          disabled ? 'text-fg-disabled cursor-not-allowed' : 'text-foreground',
+        )}
+      >
+        {label}
+      </label>
+      {description && (
+        <p
+          className={cn(
+            sizeKey === 'lg' ? 'mt-[var(--item-gap-label-desc-reading-lg)]' : 'mt-[var(--item-gap-label-desc-reading)]',
+            'break-words',
+            descClampClass,
+            disabled ? 'text-fg-disabled' : 'text-fg-secondary',
+          )}
+          style={{ fontSize: 'var(--font-body-size)' }}
+        >
+          {description}
+        </p>
+      )}
+    </div>
+  )
+}
+
+const SelectionItem = React.forwardRef<HTMLDivElement, SelectionItemProps>(
+  (
+    {
+      control,
+      label,
+      description,
+      icon: Icon,
+      avatar,
+      htmlFor,
+      disabled,
+      size,
+      labelMaxLines = 'none',
+      descMaxLines = 'none',
+      className,
+      ...props
+    },
+    ref
+  ) => {
+    const sizeKey: SizeKey = size ?? 'md'
+    if (process.env.NODE_ENV !== 'production' && Icon && avatar) {
+      // eslint-disable-next-line no-console
+      console.warn('[SelectionItem] `icon` 和 `avatar` 互斥,只會渲染 icon。')
+    }
+    // Block 對齊:control 跟 prefix(avatar)一起走 block 高度,「selection + identity」視覺單元不歪斜
+    const useBlock = !!avatar && !Icon && !!description && AVATAR_PX.block[sizeKey] > 24
+    const avatarPx = useBlock ? AVATAR_PX.block[sizeKey] : AVATAR_PX.inline[sizeKey]
+    const alignClass = useBlock ? blockAlignClass[sizeKey] : 'h-[1lh]'
+
+    return (
+      <div ref={ref} className={cn(selectionItemStyles({ size }), className)} {...props}>
+        <div className={cn(alignClass, 'flex items-center shrink-0')}>{control}</div>
+        <PrefixSlot icon={Icon} avatar={avatar} sizeKey={sizeKey} alignClass={alignClass} avatarPx={avatarPx} disabled={disabled} />
+        <ContentSlot
+          htmlFor={htmlFor}
+          disabled={disabled}
+          label={label}
+          description={description}
+          sizeKey={sizeKey}
+          labelClampClass={lineClampClass(labelMaxLines)}
+          descClampClass={lineClampClass(descMaxLines)}
+        />
+      </div>
+    )
+  }
+)
+SelectionItem.displayName = 'SelectionItem'
+
+// Story auto-compile metadata — Phase 1+2 migration
+export const selectionItemMeta = {
+  component: 'SelectionItem',
+  family: 2,
+  variants: {},
+  sizes: {
+    sm: {},
+    md: {},
+    lg: {},
+  },
+  defaultSize: 'md',
+  states: ['default', 'hover', 'selected', 'focus-visible', 'disabled'],
+  tokens: {
+    fg: ['text-foreground', 'text-fg-secondary', 'text-fg-disabled'],
+  },
+} as const
+
+export { SelectionItem }