@qijenchen/design-system 0.1.0-beta.3

package/src/components/Checkbox/checkbox.tsx

@@ -0,0 +1,237 @@
+// @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 * as CheckboxPrimitive from "@radix-ui/react-checkbox"
+import { Check, Minus } from "lucide-react"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+import type { FieldMode, FieldVariant } from "@/design-system/components/Field/field-types"
+import { useFieldContext } from "@/design-system/components/Field/field-context"
+import { SelectionItem } from "@/design-system/components/SelectionControl/selection-item"
+import { CheckboxGroupContext } from "./checkbox-group"
+
+// ── Variants ────────────────────────────────────────────────────────────────
+// 三種尺寸（sm/md=16px, lg=20px），對齊 icon 系統與 SelectionItem。
+
+const checkboxVariants = cva(
+  [
+    'grid place-content-center shrink-0 rounded-md',
+    'border border-border bg-surface',
+    'transition-colors duration-150',
+    'hover:border-border-hover',
+    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',
+    'data-[state=checked]:bg-primary data-[state=checked]:text-on-emphasis data-[state=checked]:border-primary',
+    'data-[state=checked]:hover:bg-primary-hover data-[state=checked]:hover:border-primary-hover',
+    'data-[state=indeterminate]:bg-primary data-[state=indeterminate]:text-on-emphasis data-[state=indeterminate]:border-primary',
+    'data-[state=indeterminate]:hover:bg-primary-hover data-[state=indeterminate]:hover:border-primary-hover',
+    'disabled:cursor-not-allowed disabled:bg-disabled disabled:border-transparent disabled:hover:border-transparent',
+    'disabled:data-[state=checked]:bg-disabled disabled:data-[state=checked]:text-fg-disabled disabled:data-[state=checked]:border-transparent',
+    'disabled:data-[state=indeterminate]:bg-disabled disabled:data-[state=indeterminate]:text-fg-disabled disabled:data-[state=indeterminate]:border-transparent',
+    // readOnly：鎖定互動但維持 checked/unchecked 視覺
+    'data-[readonly=true]:pointer-events-none data-[readonly=true]:cursor-default',
+    'data-[readonly=true]:hover:border-border',
+  ],
+  {
+    variants: {
+      size: {
+        sm: 'h-4 w-4',
+        md: 'h-4 w-4',
+        lg: 'h-5 w-5',
+      },
+    },
+    defaultVariants: {
+      size: 'md',
+    },
+  }
+)
+
+// ── Check Icon Size ─────────────────────────────────────────────────────────
+const checkIconSize: Record<string, number> = { sm: 12, md: 12, lg: 16 }
+
+// ── Check Icon Stroke Weight ────────────────────────────────────────────────
+// 16px 以下 icon 視覺不夠顯眼 → 用較粗 stroke 補償。Lucide 預設 strokeWidth=2 在
+// 12px 下 render 約 1px 線寬,視覺偏細;加粗到 3.5(render ≈ 1.75px)才有足夠視覺權重。
+// 16px 用 2.5(render ≈ 1.67px)讓 checked 態的 check icon 夠顯眼。
+//
+// 為什麼不是 3 / 2:本 session 實測 3 / 2 在 storybook 上兩個 size 的 render 線寬差僅
+// 0.17px(1.5 vs 1.33),使用者肉眼看不出差異(image #64 回報)。改為 3.5 / 2.5:
+//   - md 12px × 3.5 → 1.75px 線寬
+//   - lg 16px × 2.5 → 1.67px 線寬
+// 兩者仍接近但 md 的線寬 **絕對值** 跟 16px 預設(1.33)有更明顯差異,視覺上「小 check 更粗」。
+//
+// 世界級對照:iOS HIG / Material 3 / Polaris 的 checkmark 在 <16px 下皆加粗 compensate。
+// 為什麼不用 Lucide absoluteStrokeWidth:那保持「絕對 px 粗細」,我們反而要「小尺寸比例更粗」。
+//
+// Check 與 Minus(indeterminate)共用此規則;Switch 的 SPECS.checkStroke 採同樣值。
+// 2026-05-18 簡化 per user 視覺證「sm/md 3.5 vs lg 2.5 看不出差別」(image #64 + 2nd round
+// 圖一 video proof)+「做完」approval:
+// - 原 {3.5, 3.5, 2.5} → effective render thickness 1.75 / 1.75 / 1.67 = 跨 size 差 0.08px(視覺看不出)
+// - 改 {3, 3, 2.5} 保留 sm/md 小尺寸 legibility insurance(per iOS HIG / Material 3 cite)
+//   + lg 仍稍粗於 Lucide default 2(保留 compensation 主旨,但不過度差異化)
+const checkStrokeWidth: Record<string, number> = { sm: 3, md: 3, lg: 2.5 }
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+export interface CheckboxProps
+  extends React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>,
+    VariantProps<typeof checkboxVariants> {
+  /**
+   * Inline label。提供時 Checkbox 自動透過 SelectionItem 包裝，
+   * 套用 text-body / text-foreground / disabled 色 的 codified 樣式。
+   * 在 <Field> context 內時此 prop 會被忽略（由 FieldLabel 接管）。
+   */
+  label?: React.ReactNode
+  /**
+   * Inline description（secondary 文字）。須與 label 搭配使用。
+   * 套用 text-body / text-fg-secondary 樣式。
+   * 在 <Field> context 內時此 prop 會被忽略（由 FieldDescription 接管）。
+   */
+  description?: React.ReactNode
+  /**
+   * readonly 模式：鎖定互動但維持 checked/unchecked 視覺正確。
+   * 與 disabled 的差異：readonly 不降色（可讀），disabled 降色（弱化）。
+   * 用於表單 readonly 呈現、DataTable cell 非編輯態。
+   */
+  readOnly?: boolean
+  /**
+   * Field mode(2026-05-05 Phase B3 align):
+   *   edit     — 一般可互動 checkbox(預設)
+   *   display  — **純展示**:渲染 ✓ / —(無互動 primitive、無 input chrome);
+   *              對齊 Carbon read-only / DataTable boolean cell 場景。取代既有 BooleanDisplay。
+   *   readonly — 同 readOnly prop:checkbox 視覺保留 + 鎖互動 + a11y readonly signal
+   *   disabled — 同 disabled prop:降色 + 鎖互動
+   */
+  mode?: FieldMode
+  /**
+   * Visual chrome — checkbox 本體無 input wrapper variant,本 prop 對 checkbox 主體無視覺影響;
+   * 為對齊 Field 4-mode + chrome 透傳契約而保留(M19 一致性)。
+   */
+  variant?: FieldVariant
+}
+
+// ── Component ───────────────────────────────────────────────────────────────
+
+const Checkbox = React.forwardRef<
+  React.ElementRef<typeof CheckboxPrimitive.Root>,
+  CheckboxProps
+>(
+  (
+    {
+      className,
+      size,
+      label,
+      description,
+      readOnly = false,
+      disabled,
+      mode,
+      // chrome 對 Checkbox 主體無視覺影響(無 input wrapper)— 接收純為 prop 一致性;destructure 防 leak 到 DOM。
+      variant: _chrome,
+      id: idProp,
+      ...props
+    },
+    ref
+  ) => {
+    const sizeKey = size ?? 'md'
+    const iconPx = checkIconSize[sizeKey]
+    const iconStrokeWidth = checkStrokeWidth[sizeKey]
+
+    // ── mode='display' ─────────────────────────────────────────────────────
+    // 純展示模式:無互動 primitive、無 input variant,渲染 ✓ / —。
+    // 取代既有 BooleanDisplay(2026-05-05 Phase B3 retire)— 該 helper 已併入 Checkbox。
+    // 顯示規則:checked=true → ✓(foreground);其他(false / null / undefined / indeterminate)→ —(fg-muted)
+    if (mode === 'display') {
+      const isChecked = props.checked === true
+      return isChecked
+        ? <span className="text-foreground">✓</span>
+        : <span className="text-fg-muted">—</span>
+    }
+
+    // Field context:Checkbox 單獨塞進 Field(binary toggle)時,忽略自己的 label 讓 FieldLabel 接管
+    //
+    // **例外**:Checkbox 是 CheckboxGroup 的 child 時(multi-select 情境),**每個 checkbox
+    // 的 label 是它自己的選項名**,FieldLabel 只是群組名稱 — 此時 label **必須保留**,
+    // 不能被 Field context 吞掉。AR50 的根因就是這個 branch 之前誤把 group 內的 checkbox
+    // label 全清空,導致 sheet 內 3 個 checkbox 沒 label。
+    const fieldCtx = useFieldContext()
+    const checkboxGroupCtx = React.useContext(CheckboxGroupContext)
+    const insideField = fieldCtx?.hasFieldWrapper === true
+    const insideGroup = checkboxGroupCtx?.inGroup === true
+    const shouldSuppressLabel = insideField && !insideGroup
+    const effectiveLabel = shouldSuppressLabel ? undefined : label
+    const effectiveDescription = shouldSuppressLabel ? undefined : description
+
+    // Id 連結
+    //
+    // ── 2026-04-21 bug fix ──
+    // 原本:`idProp ?? fieldCtx?.id ?? generatedId`。
+    // 在 Field 內 fieldCtx.id 存在,CheckboxGroup 所有 children 共用同一個 id →
+    // 每個 checkbox 的 `<label htmlFor={sameId}>` 全指向第一個 checkbox →
+    // **點任何 label 都只開關第一個 checkbox(real bug)**。
+    //
+    // 修法:group 內的 checkbox 強制用 generatedId(唯一),不沿用 Field id;
+    //      solo in Field(binary toggle)才沿用 fieldCtx.id 讓 FieldLabel htmlFor 生效。
+    const generatedId = React.useId()
+    const inputId = idProp ?? (insideGroup ? generatedId : (fieldCtx?.id ?? generatedId))
+
+    const rootEl = (
+      <CheckboxPrimitive.Root
+        id={inputId}
+        ref={ref}
+        disabled={disabled}
+        aria-readonly={readOnly || undefined}
+        data-readonly={readOnly || undefined}
+        tabIndex={readOnly ? -1 : undefined}
+        aria-describedby={fieldCtx?.descriptionId}
+        className={cn(checkboxVariants({ size }), className)}
+        {...props}
+      >
+        <CheckboxPrimitive.Indicator className="grid place-content-center text-current">
+          {props.checked === 'indeterminate'
+            ? <Minus style={{ width: iconPx, height: iconPx }} strokeWidth={iconStrokeWidth} />
+            : <Check style={{ width: iconPx, height: iconPx }} strokeWidth={iconStrokeWidth} />
+          }
+        </CheckboxPrimitive.Indicator>
+      </CheckboxPrimitive.Root>
+    )
+
+    // 無 label → 只渲染 checkbox 本體
+    if (effectiveLabel == null) return rootEl
+
+    // 有 label → 透過 SelectionItem 包裝（control 在左、label+description 在右）
+    return (
+      <SelectionItem
+        control={rootEl}
+        label={effectiveLabel}
+        description={effectiveDescription}
+        htmlFor={inputId}
+        disabled={disabled}
+        size={sizeKey}
+      />
+    )
+  }
+)
+Checkbox.displayName = CheckboxPrimitive.Root.displayName
+
+// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)
+// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
+export const checkboxMeta = {
+  component: 'Checkbox',
+  family: 4,
+  variants: {
+
+  },
+  sizes: {
+    sm: { fieldHeight: 28, iconSize: 16, typography: 'body' },
+    md: { fieldHeight: 32, iconSize: 16, typography: 'body' },
+    lg: { fieldHeight: 40, iconSize: 20, typography: 'body' },
+  },
+  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  tokens: {
+    bg: ['bg-disabled', 'bg-primary', 'bg-primary-hover', 'bg-surface'],
+    fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground'],
+    ring: ['ring-ring'],
+  },
+  defaultSize: 'md',
+} as const
+
+export { Checkbox, checkboxVariants }

package/src/components/Chip/chip.tsx

@@ -0,0 +1,359 @@
+// @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 * as ToggleGroupPrimitive from '@radix-ui/react-toggle-group'
+import { cva } from 'class-variance-authority'
+import type { LucideIcon } from 'lucide-react'
+import { cn } from '@/lib/utils'
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuCheckboxItem,
+} from '@/design-system/components/DropdownMenu/dropdown-menu'
+import {
+  useScrollEdges,
+  useScrollByPage,
+  buildFadeMask,
+  ARROW_BUTTON_WIDTH,
+  OverflowScrollArrow,
+  OverflowMenuTriggerButton,
+} from '@/design-system/patterns/horizontal-overflow/horizontal-overflow'
+
+/**
+ * Chip — Material Design Filter Chip
+ *
+ * 基於 Radix ToggleGroup，橋接設計系統 token。
+ * 必須在 <ChipGroup> 內使用。
+ *
+ * ── 內部結構（鏡射 Button）──
+ *   [startIcon?] [<span px-1>label</span>] [<span gap-1>badge? + endIcon?</span>]
+ *
+ * ── Size ──
+ *   單一 size = h-field-sm（28/32 density-aware）
+ *   對齊 Material 3 / Atlassian / Polaris 世界級共識
+ *
+ * ── State ──
+ *   default   bg-surface border-border text-foreground
+ *   hover     border-border-hover（對齊 Input / SegmentedControl）
+ *   selected  bg-primary-subtle border-primary-hover text-primary-hover
+ *   disabled  cursor-not-allowed text-fg-disabled
+ *
+ * ── 詳見 chip.spec.md ──
+ */
+
+// ── Chip item ────────────────────────────────────────────────────────────────
+
+const chipVariants = cva(
+  [
+    'inline-flex items-center justify-center',
+    'h-field-sm px-3 gap-1',
+    'rounded-full border border-border',
+    // 預設文字: text-fg-secondary (neutral-8) — 對齊 SegmentedControl / Tabs 未選狀態
+    'bg-surface text-fg-secondary',
+    'text-body leading-compact font-medium whitespace-nowrap',
+    'transition-colors duration-150',
+    'cursor-pointer select-none',
+    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',
+    // hover（未選）：border 加深一階 + 文字轉深，對齊 Input / SegmentedControl hover
+    'hover:border-border-hover hover:text-foreground',
+    // selected: 文字 + 邊框都用 primary-hover,底色維持 bg-surface 不變
+    //   ── pill 風格 canonical 選中規則,跟 SegmentedControl 完全一致:
+    //      primary-hover 同時染文字和線條;底色不改 (不用 primary-subtle)。
+    'data-[state=on]:border-primary-hover data-[state=on]:text-primary-hover',
+    // disabled：cursor-not-allowed + 鎖 hover 不變色
+    // 不用 pointer-events-none（否則 cursor-not-allowed 不會顯示）
+    'disabled:cursor-not-allowed disabled:text-fg-disabled',
+    'disabled:hover:border-border disabled:hover:text-fg-disabled',
+  ]
+)
+
+export interface ChipProps
+  extends React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item> {
+  /** 左側 icon（LucideIcon），最多一個 */
+  startIcon?: LucideIcon
+  /** 右側 badge（通常是計數指示器）*/
+  badge?: React.ReactNode
+  /** 右側 icon（少見，通常是 ChevronDown 指示可展開）*/
+  endIcon?: LucideIcon
+}
+
+const Chip = React.forwardRef<
+  React.ElementRef<typeof ToggleGroupPrimitive.Item>,
+  ChipProps
+>(({ className, startIcon: StartIcon, badge, endIcon: EndIcon, children, ...props }, ref) => {
+  const hasSuffix = badge != null || EndIcon !== undefined
+
+  return (
+    <ToggleGroupPrimitive.Item
+      ref={ref}
+      className={cn(chipVariants(), className)}
+      {...props}
+    >
+      {StartIcon && <StartIcon size={16} aria-hidden />}
+      {children != null && <span className="px-1">{children}</span>}
+      {hasSuffix && (
+        <span className="inline-flex items-center gap-1">
+          {badge}
+          {EndIcon && <EndIcon size={16} aria-hidden />}
+        </span>
+      )}
+    </ToggleGroupPrimitive.Item>
+  )
+})
+Chip.displayName = 'Chip'
+
+// ── ChipGroup ────────────────────────────────────────────────────────────────
+
+export type ChipGroupLayout = 'wrap' | 'scroll' | 'menu'
+
+export type ChipGroupProps = React.ComponentPropsWithoutRef<
+  typeof ToggleGroupPrimitive.Root
+> & {
+  /** Overflow 處理模式。預設 `wrap`（塞不下換行）。詳見 chip.spec.md */
+  layout?: ChipGroupLayout
+}
+
+const ChipGroup = React.forwardRef<HTMLDivElement, ChipGroupProps>(
+  ({ layout = 'wrap', className, children, ...props }, ref) => {
+    if (layout === 'scroll') {
+      return (
+        <ScrollChipGroup ref={ref} className={className} {...props}>
+          {children}
+        </ScrollChipGroup>
+      )
+    }
+    if (layout === 'menu') {
+      return (
+        <MenuChipGroup ref={ref} className={className} {...props}>
+          {children}
+        </MenuChipGroup>
+      )
+    }
+    // wrap（預設）
+    return (
+      <ToggleGroupPrimitive.Root
+        ref={ref}
+        className={cn('flex flex-wrap gap-2', className)}
+        {...props}
+      >
+        {children}
+      </ToggleGroupPrimitive.Root>
+    )
+  }
+)
+ChipGroup.displayName = 'ChipGroup'
+
+// ── Scroll / Menu modes ──
+// Fade mask / arrows / menu trigger 全部從 horizontal-overflow pattern module 取用。
+// 詳見 `patterns/horizontal-overflow/horizontal-overflow.spec.md`。
+//
+// Canonical 規則:所有 overflow affordance 一律是 Button text sm iconOnly,
+// 不論在 Chip / Tab / Step / SegmentedControl。Chip menu trigger 曾經用
+// chip-shape 圓形 button,已改回 text button 對齊 mental model。
+
+// ── ScrollChipGroup ──────────────────────────────────────────────────────────
+
+const ScrollChipGroup = React.forwardRef<
+  HTMLDivElement,
+  React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Root>
+>(({ className, children, ...props }, ref) => {
+  const { scrollRef, atStart, atEnd, canScroll } = useScrollEdges<HTMLDivElement>()
+  const scrollByPage = useScrollByPage(scrollRef)
+  const maskImage = buildFadeMask({
+    canScroll,
+    atStart,
+    atEnd,
+    reserveArrowWidth: ARROW_BUTTON_WIDTH,
+  })
+
+  return (
+    <div className="relative">
+      <div
+        ref={scrollRef}
+        className="overflow-x-auto [scrollbar-width:none] [&::-webkit-scrollbar]:hidden"
+        style={{ maskImage, WebkitMaskImage: maskImage }}
+      >
+        <ToggleGroupPrimitive.Root
+          ref={ref}
+          className={cn('flex flex-nowrap gap-2 w-fit', className)}
+          {...props}
+        >
+          {children}
+        </ToggleGroupPrimitive.Root>
+      </div>
+      {!atStart && canScroll && (
+        <OverflowScrollArrow direction="left" onClick={() => scrollByPage('left')} />
+      )}
+      {!atEnd && canScroll && (
+        <OverflowScrollArrow direction="right" onClick={() => scrollByPage('right')} />
+      )}
+    </div>
+  )
+})
+ScrollChipGroup.displayName = 'ScrollChipGroup'
+
+// ── MenuChipGroup ────────────────────────────────────────────────────────────
+// Show-all navigator pattern (Chrome tab dropdown / VS Code editor tabs):
+//   - Menu 永遠顯示全部 chips,每個都用 DropdownMenuCheckboxItem + checked 反映 selection
+//   - 點 menu item = toggle selection + scrollIntoView,把該 chip 捲到中央
+//   - 不用動態 overflow 計算,menu 內容穩定
+//
+// Menu trigger 使用 canonical `<OverflowMenuTriggerButton>`(= Button text sm iconOnly
+// + ChevronDown),跟 Tabs menu trigger 完全同一套——overflow affordance 屬於工具層,
+// 不該用 chip 自己的視覺語言(圓形 outlined)去渲染,否則 mental model 錯誤(使用者
+// 會誤以為是第 N+1 個可選 chip)。
+//
+// 過去 Chip menu trigger 曾用 `chipVariants() + aspect-square + p-0` 做成圓形 pill,
+// 已按 `horizontal-overflow.spec.md` 的 canonical 規則改回 text button。
+//
+// Fade mask 仍保留(reserveArrowWidth: 0),軟化內容硬邊。
+
+// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
+const MenuChipGroup = React.forwardRef<
+  HTMLDivElement,
+  React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Root>
+>(({ className, children, ...props }, ref) => {
+  const { scrollRef, atStart, atEnd, canScroll } = useScrollEdges<HTMLDivElement>()
+
+  // Local ref map — 追蹤每個 chip 的 DOM 元素供 scrollIntoView 使用。
+  // 不用 useOverflowIndices 因為 menu 永遠顯示全部, 不需要動態 overflow 計算。
+  // code-quality-allow: long-function — helper fn 結構緊密,拆 sub-fn 會跨 fn 傳 state 反而複雜
+  const itemRefs = React.useRef<Map<number, HTMLElement>>(new Map())
+  // 2026-05-16 audit codex Round 6:capture rAF + cancel on unmount(defensive hygiene)
+  const scrollRafIdRef = React.useRef<number>(0)
+  React.useEffect(() => () => { if (scrollRafIdRef.current) cancelAnimationFrame(scrollRafIdRef.current) }, [])
+  const registerItem = React.useCallback(
+    (index: number) => (el: HTMLElement | null) => {
+      if (el) itemRefs.current.set(index, el)
+      else itemRefs.current.delete(index)
+    },
+    []
+  )
+
+  const menuMaskImage = buildFadeMask({ canScroll, atStart, atEnd, reserveArrowWidth: 0 })
+
+  const items = React.useMemo(
+    () => React.Children.toArray(children).filter(React.isValidElement) as React.ReactElement[],
+    [children]
+  )
+
+  const groupType = (props as { type?: 'single' | 'multiple' }).type ?? 'single'
+  const groupValue = (props as { value?: string | string[] }).value
+  const groupOnValueChange = (
+    props as { onValueChange?: (value: string | string[]) => void }
+  ).onValueChange
+
+  // code-quality-allow: long-function — helper fn 結構緊密,拆 sub-fn 會跨 fn 傳 state 反而複雜
+  const isSelected = React.useCallback(
+    (chipValue: string): boolean => {
+      if (groupType === 'multiple') {
+        return Array.isArray(groupValue) && groupValue.includes(chipValue)
+      }
+      return groupValue === chipValue
+    },
+    [groupType, groupValue]
+  )
+
+  // code-quality-allow: long-function — multi / single / none selection mode each has 事務性 branch,拆 fn 會跨 fn 傳 chipValue/index/groupOnValueChange state 反而難讀
+  const toggleFromMenu = React.useCallback(
+    (chipValue: string, index: number) => {
+      if (!groupOnValueChange) {
+        if (import.meta.env?.DEV) {
+          console.warn(
+            '[ChipGroup] layout="menu" 需要 controlled 使用（請傳 value + onValueChange），否則 menu items 無法同步主 chip 選擇狀態。'
+          )
+        }
+        return
+      }
+      if (groupType === 'multiple') {
+        const current = (Array.isArray(groupValue) ? groupValue : []) as string[]
+        const next = current.includes(chipValue)
+          ? current.filter((v) => v !== chipValue)
+          : [...current, chipValue]
+        ;(groupOnValueChange as (v: string[]) => void)(next)
+      } else {
+        ;(groupOnValueChange as (v: string) => void)(chipValue)
+      }
+      // scrollIntoView: 讓剛選中的 chip 出現在視圖中央
+      if (scrollRafIdRef.current) cancelAnimationFrame(scrollRafIdRef.current)
+      scrollRafIdRef.current = requestAnimationFrame(() => {
+        scrollRafIdRef.current = 0
+        itemRefs.current.get(index)?.scrollIntoView({ behavior: 'smooth', inline: 'center', block: 'nearest' })
+      })
+    },
+    [groupType, groupValue, groupOnValueChange]
+  )
+
+  const enhancedItems = items.map((child, i) =>
+    React.cloneElement(
+      child as React.ReactElement<{ ref?: React.Ref<HTMLElement> }>,
+      { ref: registerItem(i) }
+    )
+  )
+
+  return (
+    <div className="flex items-center gap-2">
+      <div
+        ref={scrollRef}
+        className="flex-1 min-w-0 overflow-x-auto [scrollbar-width:none] [&::-webkit-scrollbar]:hidden"
+        style={{ maskImage: menuMaskImage, WebkitMaskImage: menuMaskImage }}
+      >
+        <ToggleGroupPrimitive.Root
+          ref={ref}
+          className={cn('flex flex-nowrap gap-2 w-fit', className)}
+          {...props}
+        >
+          {enhancedItems}
+        </ToggleGroupPrimitive.Root>
+      </div>
+      {canScroll && (
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <OverflowMenuTriggerButton
+              aria-label={`選項選單(共 ${items.length} 個)`}
+            />
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end">
+            {items.map((chip, index) => {
+              const chipProps = chip.props as { value?: string; children?: React.ReactNode; disabled?: boolean }
+              const chipValue = chipProps.value
+              if (typeof chipValue !== 'string') return null
+              return (
+                <DropdownMenuCheckboxItem
+                  key={chipValue}
+                  checked={isSelected(chipValue)}
+                  disabled={chipProps.disabled}
+                  onCheckedChange={() => toggleFromMenu(chipValue, index)}
+                >
+                  {chipProps.children}
+                </DropdownMenuCheckboxItem>
+              )
+            })}
+          </DropdownMenuContent>
+        </DropdownMenu>
+      )}
+    </div>
+  )
+})
+MenuChipGroup.displayName = 'MenuChipGroup'
+
+// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)
+// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
+export const chipMeta = {
+  component: 'Chip',
+  family: 3,
+  variants: {
+
+  },
+  sizes: {
+
+  },
+  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  tokens: {
+    bg: ['bg-primary-subtle', 'bg-surface'],
+    fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground'],
+    ring: ['ring-ring'],
+  },
+} as const
+
+export { Chip, ChipGroup, chipVariants }