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

package/dist/components/Checkbox/checkbox.js.map

@@ -1 +1 @@
-{"version":3,"file":"checkbox.js","sources":["../../../src/components/Checkbox/checkbox.tsx"],"sourcesContent":["// @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.\nimport * as React from \"react\"\nimport * as CheckboxPrimitive from \"@radix-ui/react-checkbox\"\nimport { Check, Minus } from \"lucide-react\"\nimport { cva, type VariantProps } from \"class-variance-authority\"\n\nimport { cn } from \"@/lib/utils\"\nimport type { FieldMode, FieldVariant } from \"@/design-system/components/Field/field-types\"\nimport { useFieldContext, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldSize } from \"@/design-system/components/Field/field-context\"\nimport { fieldWrapperStyles } from \"@/design-system/components/Field/field-wrapper\"\nimport { SelectionItem } from \"@/design-system/components/SelectionControl/selection-item\"\nimport type { LucideIcon } from \"lucide-react\"\nimport type { AvatarData } from \"@/design-system/components/Avatar/avatar\"\nimport { CheckboxGroupContext } from \"./checkbox-group\"\n\n// ── Variants ────────────────────────────────────────────────────────────────\n// 三種尺寸（sm/md=16px, lg=20px），對齊 icon 系統與 SelectionItem。\n\nconst checkboxVariants = cva(\n  [\n    'grid place-content-center shrink-0 rounded-md',\n    'border border-border bg-surface',\n    'transition-colors duration-150',\n    'hover:border-border-hover',\n    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',\n    'data-[state=checked]:bg-primary data-[state=checked]:text-on-emphasis data-[state=checked]:border-primary',\n    'data-[state=checked]:hover:bg-primary-hover data-[state=checked]:hover:border-primary-hover',\n    'data-[state=indeterminate]:bg-primary data-[state=indeterminate]:text-on-emphasis data-[state=indeterminate]:border-primary',\n    'data-[state=indeterminate]:hover:bg-primary-hover data-[state=indeterminate]:hover:border-primary-hover',\n    'disabled:cursor-not-allowed disabled:bg-disabled disabled:border-transparent disabled:hover:border-transparent',\n    'disabled:data-[state=checked]:bg-disabled disabled:data-[state=checked]:text-fg-disabled disabled:data-[state=checked]:border-transparent',\n    'disabled:data-[state=indeterminate]:bg-disabled disabled:data-[state=indeterminate]:text-fg-disabled disabled:data-[state=indeterminate]:border-transparent',\n    // readOnly：鎖定互動但維持 checked/unchecked 視覺\n    'data-[readonly=true]:pointer-events-none data-[readonly=true]:cursor-default',\n    'data-[readonly=true]:hover:border-border',\n  ],\n  {\n    variants: {\n      size: {\n        sm: 'h-4 w-4',\n        md: 'h-4 w-4',\n        lg: 'h-5 w-5',\n      },\n    },\n    defaultVariants: {\n      size: 'md',\n    },\n  }\n)\n\n// ── Check Icon Size ─────────────────────────────────────────────────────────\nconst checkIconSize: Record<string, number> = { sm: 12, md: 12, lg: 16 }\n\n// ── Check Icon Stroke Weight ────────────────────────────────────────────────\n// 16px 以下 icon 視覺不夠顯眼 → 用較粗 stroke 補償。Lucide 預設 strokeWidth=2 在\n// 12px 下 render 約 1px 線寬,視覺偏細;加粗到 3.5(render ≈ 1.75px)才有足夠視覺權重。\n// 16px 用 2.5(render ≈ 1.67px)讓 checked 態的 check icon 夠顯眼。\n//\n// 為什麼不是 3 / 2:本 session 實測 3 / 2 在 storybook 上兩個 size 的 render 線寬差僅\n// 0.17px(1.5 vs 1.33),使用者肉眼看不出差異(image #64 回報)。改為 3.5 / 2.5:\n//   - md 12px × 3.5 → 1.75px 線寬\n//   - lg 16px × 2.5 → 1.67px 線寬\n// 兩者仍接近但 md 的線寬 **絕對值** 跟 16px 預設(1.33)有更明顯差異,視覺上「小 check 更粗」。\n//\n// 世界級對照:iOS HIG / Material 3 / Polaris 的 checkmark 在 <16px 下皆加粗 compensate。\n// 為什麼不用 Lucide absoluteStrokeWidth:那保持「絕對 px 粗細」,我們反而要「小尺寸比例更粗」。\n//\n// Check 與 Minus(indeterminate)共用此規則;Switch 的 SPECS.checkStroke 採同樣值。\n// 2026-05-18 簡化 per user 視覺證「sm/md 3.5 vs lg 2.5 看不出差別」(image #64 + 2nd round\n// 圖一 video proof)+「做完」approval:\n// - 原 {3.5, 3.5, 2.5} → effective render thickness 1.75 / 1.75 / 1.67 = 跨 size 差 0.08px(視覺看不出)\n// - 改 {3, 3, 2.5} 保留 sm/md 小尺寸 legibility insurance(per iOS HIG / Material 3 cite)\n//   + lg 仍稍粗於 Lucide default 2(保留 compensation 主旨,但不過度差異化)\n// ⚠️ 2026-06-12:發現 base.css `.lucide{stroke-width:1.75}` 全域規則自 2026-04-08 起\n// 無條件蓋掉本 prop(CSS class > SVG attribute)→ 本表從未真渲染過,上述 05-18 視覺\n// 測試兩者實為 0.875px(證據污染)。base.css 已改 `[stroke-width='2']` 限定,本表自此\n// 真實生效(pixel 驗證 1.50px)。SSOT → .claude/references/ui-dev-rules.md「小尺寸 icon stroke 補償」\nconst checkStrokeWidth: Record<string, number> = { sm: 3, md: 3, lg: 2.5 }\n\n// ── Types ───────────────────────────────────────────────────────────────────\n\nexport interface CheckboxProps\n  extends React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>,\n    VariantProps<typeof checkboxVariants> {\n  /**\n   * Inline label。提供時 Checkbox 自動透過 SelectionItem 包裝，\n   * 套用 text-body / text-foreground / disabled 色 的 codified 樣式。\n   * 在 <Field> context 內時此 prop 會被忽略（由 FieldLabel 接管）。\n   */\n  label?: React.ReactNode\n  /**\n   * Inline description（secondary 文字）。須與 label 搭配使用。\n   * 套用 text-body / text-fg-secondary 樣式。\n   * 在 <Field> context 內時此 prop 會被忽略（由 FieldDescription 接管）。\n   */\n  description?: React.ReactNode\n  /** 可選左側 icon(label 前)— 2026-06-12 M30 修:轉發 SelectionItem 既有 canonical 槽(selection-item.tsx jsDoc 為 SSOT;與 avatar 互斥)*/\n  icon?: LucideIcon\n  /** 可選左側 avatar(label 前)— 同上,SelectionItem 槽轉發 */\n  avatar?: AvatarData\n  /**\n   * readonly 模式：鎖定互動但維持 checked/unchecked 視覺正確。\n   * 與 disabled 的差異：readonly 不降色（可讀），disabled 降色（弱化）。\n   * 用於表單 readonly 呈現、DataTable cell 非編輯態。\n   */\n  readOnly?: boolean\n  /**\n   * Field mode(2026-05-05 Phase B3 align):\n   *   edit     — 一般可互動 checkbox(預設)\n   *   display  — **純展示**:渲染 ✓ / —(無互動 primitive、無 input chrome);\n   *              對齊 Carbon read-only / DataTable boolean cell 場景。取代既有 BooleanDisplay。\n   *   readonly — 同 readOnly prop:checkbox 視覺保留 + 鎖互動 + a11y readonly signal\n   *   disabled — 同 disabled prop:降色 + 鎖互動\n   */\n  mode?: FieldMode\n  /**\n   * Visual chrome — checkbox 本體無 input wrapper variant,本 prop 對 checkbox 主體無視覺影響;\n   * 為對齊 Field 4-mode + chrome 透傳契約而保留(M19 一致性)。\n   */\n  variant?: FieldVariant\n}\n\n// ── Component ───────────────────────────────────────────────────────────────\n\nconst Checkbox = React.forwardRef<\n  React.ElementRef<typeof CheckboxPrimitive.Root>,\n  CheckboxProps\n>(\n  (\n    {\n      className,\n      size,\n      label,\n      icon,\n      avatar,\n      description,\n      readOnly = false,\n      disabled,\n      mode,\n      // chrome 對 Checkbox 主體無視覺影響(無 input wrapper)— 接收純為 prop 一致性;destructure 防 leak 到 DOM。\n      variant: _chrome,\n      id: idProp,\n      ...props\n    },\n    ref\n  ) => {\n    const sizeKey = size ?? 'md'\n    const iconPx = checkIconSize[sizeKey]\n    const iconStrokeWidth = checkStrokeWidth[sizeKey]\n\n    // Field context:Checkbox 單獨塞進 Field(binary toggle)時,忽略自己的 label 讓 FieldLabel 接管\n    // 2026-05-31 #35:hooks(useFieldContext / useContext / useId)必在任何 conditional return 前呼叫(Rules of Hooks)。\n    // 原 mode='display' early return 寫在 hooks 之上 → runtime 切 mode 會 hook count 不一致 crash;已下移至 hooks 後。\n    //\n    // **例外**:Checkbox 是 CheckboxGroup 的 child 時(multi-select 情境),**每個 checkbox\n    // 的 label 是它自己的選項名**,FieldLabel 只是群組名稱 — 此時 label **必須保留**,\n    // 不能被 Field context 吞掉。AR50 的根因就是這個 branch 之前誤把 group 內的 checkbox\n    // label 全清空,導致 sheet 內 3 個 checkbox 沒 label。\n    const fieldCtx = useFieldContext()\n    const checkboxGroupCtx = React.useContext(CheckboxGroupContext)\n    const insideField = fieldCtx?.hasFieldWrapper === true\n    const insideGroup = checkboxGroupCtx?.inGroup === true\n    const shouldSuppressLabel = insideField && !insideGroup\n    const effectiveLabel = shouldSuppressLabel ? undefined : label\n    const effectiveDescription = shouldSuppressLabel ? undefined : description\n\n    // Id 連結\n    //\n    // ── 2026-04-21 bug fix ──\n    // 原本:`idProp ?? fieldCtx?.id ?? generatedId`。\n    // 在 Field 內 fieldCtx.id 存在,CheckboxGroup 所有 children 共用同一個 id →\n    // 每個 checkbox 的 `<label htmlFor={sameId}>` 全指向第一個 checkbox →\n    // **點任何 label 都只開關第一個 checkbox(real bug)**。\n    //\n    // 修法:group 內的 checkbox 強制用 generatedId(唯一),不沿用 Field id;\n    //      solo in Field(binary toggle)才沿用 fieldCtx.id 讓 FieldLabel htmlFor 生效。\n    const generatedId = React.useId()\n    const inputId = idProp ?? (insideGroup ? generatedId : (fieldCtx?.id ?? generatedId))\n\n    // 2026-06-08 SSOT cascade:disabled + mode 經 resolver hook(原 raw prop → <Field disabled>/<Field mode=\"display\"> 漏 cascade)\n    const resolvedDisabled = useResolvedFieldDisabled(disabled)\n    const resolvedMode = useResolvedFieldMode({ mode, disabled, readOnly })\n    const effectiveReadOnly = readOnly || resolvedMode === 'readonly'\n    // mode='disabled'(如 DataTable disabled cell 直傳)必須落到真 disabled chrome —\n    // 2026-06-12 修:原本只看 resolvedDisabled(prop/fieldCtx),mode='disabled' 無人消費\n    // → disabled boolean cell 渲出可 focus 的正常外觀 checkbox(違 field-controls.spec L286)\n    const effectiveDisabled = resolvedDisabled || resolvedMode === 'disabled'\n    // readonly 灰框 size:走 SSOT resolver(prop > ctx > 'md',field-context.ts:150-161)\n    const resolvedBoxSize = useResolvedFieldSize(size ?? undefined, 'md') as 'sm' | 'md' | 'lg'\n\n    // ── mode='display'(下移至所有 hooks 之後,per #35 Rules of Hooks)──────────\n    // 純展示模式:無互動 primitive、渲染 ✓ / —(checked=true → ✓ / 其他 → —)。取代 BooleanDisplay。\n    if (resolvedMode === 'display') {\n      const isChecked = props.checked === true\n      return isChecked\n        ? <span className=\"text-foreground\">✓</span>\n        : <span className=\"text-fg-muted\">—</span>\n    }\n\n    // ── mode='readonly' in Field(2026-06-12 user 拍板「灰框 + ✓/—」)─────────────\n    // Field 內 readonly boolean = readonly 灰框 chrome + display 同款值語言 ✓/—。\n    // 灰框消費 fieldWrapperStyles 同一 cva = 與 Input readonly 字面同源(SSOT,改一處全動)。\n    // 理由:同一張 readonly 表單裡文字控件有 bg-readonly 灰框鎖定訊號,boolean 保留全彩\n    // 控件會誤導「仍可操作」(世界級 0/4 用原樣鎖互動:Salesforce=✓ 靜態 glyph /\n    // SAP=靜態文字 / Atlassian=readView / Ant Pro=文字)。\n    // Scope:僅 Field 內且無 inline label(FieldLabel 接管 label 的表單欄位場景);\n    // standalone readOnly(settings list / SelectionItem row)維持原樣鎖互動不變。\n    if (effectiveReadOnly && insideField && effectiveLabel == null) {\n      const isChecked = (props.checked ?? props.defaultChecked) === true\n      const boxSize = resolvedBoxSize\n      return (\n        <div\n          role=\"checkbox\"\n          aria-checked={isChecked}\n          aria-readonly=\"true\"\n          aria-labelledby={fieldCtx?.labelId}\n          aria-invalid={fieldCtx?.invalid || undefined}\n          data-readonly=\"true\"\n          tabIndex={0}\n          className={cn(\n            fieldWrapperStyles({ size: boxSize, mode: 'readonly', variant: 'default' }),\n            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',\n            className,\n          )}\n        >\n          {isChecked ? <span className=\"text-foreground\">✓</span> : <span className=\"text-fg-muted\">—</span>}\n        </div>\n      )\n    }\n\n    const rootEl = (\n      <CheckboxPrimitive.Root\n        id={inputId}\n        ref={ref}\n        disabled={effectiveDisabled}\n        aria-readonly={effectiveReadOnly || undefined}\n        data-readonly={effectiveReadOnly || undefined}\n        tabIndex={effectiveReadOnly ? -1 : undefined}\n        aria-describedby={fieldCtx?.descriptionId}\n        className={cn(checkboxVariants({ size }), className)}\n        {...props}\n      >\n        <CheckboxPrimitive.Indicator className=\"grid place-content-center text-current\">\n          {props.checked === 'indeterminate'\n            ? <Minus style={{ width: iconPx, height: iconPx }} strokeWidth={iconStrokeWidth} />\n            : <Check style={{ width: iconPx, height: iconPx }} strokeWidth={iconStrokeWidth} />\n          }\n        </CheckboxPrimitive.Indicator>\n      </CheckboxPrimitive.Root>\n    )\n\n    // 無 label → 只渲染 checkbox 本體\n    if (effectiveLabel == null) return rootEl\n\n    // 有 label → 透過 SelectionItem 包裝（control 在左、label+description 在右）\n    return (\n      <SelectionItem\n        control={rootEl}\n        label={effectiveLabel}\n        description={effectiveDescription}\n        icon={icon}\n        avatar={avatar}\n        htmlFor={inputId}\n        disabled={effectiveDisabled}\n        size={sizeKey}\n      />\n    )\n  }\n)\nCheckbox.displayName = CheckboxPrimitive.Root.displayName\n\n// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)\n// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs\nexport const checkboxMeta = {\n  component: 'Checkbox',\n  family: null, // self-contained primitive(對齊 spec frontmatter self-contained + body L31;非 Family 4)\n  variants: {\n\n  },\n  sizes: {\n    // 2026-06-10 修 stale meta:iconSize 對齊 checkIconSize 真值(L49 sm/md=12, lg=16;deep-audit A.1b 抓 metadata drift)\n    sm: { fieldHeight: 28, iconSize: 12, typography: 'body' },\n    md: { fieldHeight: 32, iconSize: 12, typography: 'body' },\n    lg: { fieldHeight: 36, iconSize: 16, typography: 'body-lg' },\n  },\n  states: ['default', 'hover', 'focus-visible', 'disabled'],\n  tokens: {\n    bg: ['bg-disabled', 'bg-primary', 'bg-primary-hover', 'bg-surface'],\n    fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground'],\n    ring: ['ring-ring'],\n  },\n  defaultSize: 'md',\n} as const\n\nexport { Checkbox, checkboxVariants }\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"checkbox.js","sources":["../../../src/components/Checkbox/checkbox.tsx"],"sourcesContent":["// @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.\nimport * as React from \"react\"\nimport * as CheckboxPrimitive from \"@radix-ui/react-checkbox\"\nimport { Check, Minus } from \"lucide-react\"\nimport { cva, type VariantProps } from \"class-variance-authority\"\n\nimport { cn } from \"@/lib/utils\"\nimport type { FieldMode, FieldVariant } from \"@/design-system/components/Field/field-types\"\nimport { useFieldContext, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldSize } from \"@/design-system/components/Field/field-context\"\nimport { fieldWrapperStyles } from \"@/design-system/components/Field/field-wrapper\"\nimport { SelectionItem } from \"@/design-system/components/SelectionControl/selection-item\"\nimport type { LucideIcon } from \"lucide-react\"\nimport type { AvatarData } from \"@/design-system/components/Avatar/avatar\"\nimport { CheckboxGroupContext } from \"./checkbox-group\"\n\n// ── Variants ────────────────────────────────────────────────────────────────\n// 三種尺寸（sm/md=16px, lg=20px），對齊 icon 系統與 SelectionItem。\n\nconst checkboxVariants = cva(\n  [\n    'grid place-content-center shrink-0 rounded-md',\n    'border border-border bg-surface',\n    'transition-colors duration-150',\n    'hover:border-border-hover',\n    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',\n    'data-[state=checked]:bg-primary data-[state=checked]:text-on-emphasis data-[state=checked]:border-primary',\n    'data-[state=checked]:hover:bg-primary-hover data-[state=checked]:hover:border-primary-hover',\n    'data-[state=indeterminate]:bg-primary data-[state=indeterminate]:text-on-emphasis data-[state=indeterminate]:border-primary',\n    'data-[state=indeterminate]:hover:bg-primary-hover data-[state=indeterminate]:hover:border-primary-hover',\n    'disabled:cursor-not-allowed disabled:bg-disabled disabled:border-transparent disabled:hover:border-transparent',\n    'disabled:data-[state=checked]:bg-disabled disabled:data-[state=checked]:text-fg-disabled disabled:data-[state=checked]:border-transparent',\n    'disabled:data-[state=indeterminate]:bg-disabled disabled:data-[state=indeterminate]:text-fg-disabled disabled:data-[state=indeterminate]:border-transparent',\n    // readOnly：鎖定互動但維持 checked/unchecked 視覺\n    'data-[readonly=true]:pointer-events-none data-[readonly=true]:cursor-default',\n    'data-[readonly=true]:hover:border-border',\n  ],\n  {\n    variants: {\n      size: {\n        sm: 'h-4 w-4',\n        md: 'h-4 w-4',\n        lg: 'h-5 w-5',\n      },\n    },\n    defaultVariants: {\n      size: 'md',\n    },\n  }\n)\n\n// ── Check Icon Size ─────────────────────────────────────────────────────────\nconst checkIconSize: Record<string, number> = { sm: 12, md: 12, lg: 16 }\n\n// ── Check Icon Stroke Weight ────────────────────────────────────────────────\n// 16px 以下 icon 視覺不夠顯眼 → 用較粗 stroke 補償。Lucide 預設 strokeWidth=2 在\n// 12px 下 render 約 1px 線寬,視覺偏細;加粗到 3.5(render ≈ 1.75px)才有足夠視覺權重。\n// 16px 用 2.5(render ≈ 1.67px)讓 checked 態的 check icon 夠顯眼。\n//\n// 為什麼不是 3 / 2:本 session 實測 3 / 2 在 storybook 上兩個 size 的 render 線寬差僅\n// 0.17px(1.5 vs 1.33),使用者肉眼看不出差異(image #64 回報)。改為 3.5 / 2.5:\n//   - md 12px × 3.5 → 1.75px 線寬\n//   - lg 16px × 2.5 → 1.67px 線寬\n// 兩者仍接近但 md 的線寬 **絕對值** 跟 16px 預設(1.33)有更明顯差異,視覺上「小 check 更粗」。\n//\n// 世界級對照:iOS HIG / Material 3 / Polaris 的 checkmark 在 <16px 下皆加粗 compensate。\n// 為什麼不用 Lucide absoluteStrokeWidth:那保持「絕對 px 粗細」,我們反而要「小尺寸比例更粗」。\n//\n// Check 與 Minus(indeterminate)共用此規則;Switch 的 SPECS.checkStroke 採同樣值。\n// 2026-05-18 簡化 per user 視覺證「sm/md 3.5 vs lg 2.5 看不出差別」(image #64 + 2nd round\n// 圖一 video proof)+「做完」approval:\n// - 原 {3.5, 3.5, 2.5} → effective render thickness 1.75 / 1.75 / 1.67 = 跨 size 差 0.08px(視覺看不出)\n// - 改 {3, 3, 2.5} 保留 sm/md 小尺寸 legibility insurance(per iOS HIG / Material 3 cite)\n//   + lg 仍稍粗於 Lucide default 2(保留 compensation 主旨,但不過度差異化)\n// ⚠️ 2026-06-12:發現 base.css `.lucide{stroke-width:1.75}` 全域規則自 2026-04-08 起\n// 無條件蓋掉本 prop(CSS class > SVG attribute)→ 本表從未真渲染過,上述 05-18 視覺\n// 測試兩者實為 0.875px(證據污染)。base.css 已改 `[stroke-width='2']` 限定,本表自此\n// 真實生效(pixel 驗證 1.50px)。SSOT → .claude/references/ui-dev-rules.md「小尺寸 icon stroke 補償」\nconst checkStrokeWidth: Record<string, number> = { sm: 3, md: 3, lg: 2.5 }\n\n// ── Types ───────────────────────────────────────────────────────────────────\n\nexport interface CheckboxProps\n  extends React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>,\n    VariantProps<typeof checkboxVariants> {\n  /**\n   * Inline label。提供時 Checkbox 自動透過 SelectionItem 包裝，\n   * 套用 text-body / text-foreground / disabled 色 的 codified 樣式。\n   * 在 <Field> context 內且不在 CheckboxGroup 內時，此 prop 會被忽略（由 FieldLabel 接管）；\n   * CheckboxGroup 內每個 checkbox 的 label 是它自己的選項名，必保留\n   * （同檔 shouldSuppressLabel = insideField && !insideGroup，AR50 anchor）。\n   */\n  label?: React.ReactNode\n  /**\n   * Inline description（secondary 文字）。須與 label 搭配使用。\n   * 套用 text-body / text-fg-secondary 樣式。\n   * 在 <Field> context 內且不在 CheckboxGroup 內時，此 prop 會被忽略（由 FieldDescription 接管）；\n   * CheckboxGroup 內的 description 屬各選項自有，必保留（同 label 的 group 例外）。\n   */\n  description?: React.ReactNode\n  /** 可選左側 icon(label 前)— 2026-06-12 M30 修:轉發 SelectionItem 既有 canonical 槽(selection-item.tsx jsDoc 為 SSOT;與 avatar 互斥)*/\n  icon?: LucideIcon\n  /** 可選左側 avatar(label 前)— 同上,SelectionItem 槽轉發 */\n  avatar?: AvatarData\n  /**\n   * readonly 模式：鎖定互動但維持 checked/unchecked 視覺正確。\n   * 與 disabled 的差異：readonly 不降色（可讀），disabled 降色（弱化）。\n   * 用於表單 readonly 呈現、DataTable cell 非編輯態。\n   */\n  readOnly?: boolean\n  /**\n   * Field mode(2026-05-05 Phase B3 align):\n   *   edit     — 一般可互動 checkbox(預設)\n   *   display  — **純展示**:渲染 ✓ / —(無互動 primitive、無 input chrome);\n   *              對齊 Carbon read-only / DataTable boolean cell 場景。取代既有 BooleanDisplay。\n   *   readonly — 同 readOnly prop:checkbox 視覺保留 + 鎖互動 + a11y readonly signal\n   *   disabled — 同 disabled prop:降色 + 鎖互動\n   */\n  mode?: FieldMode\n  /**\n   * Visual chrome — checkbox 本體無 input wrapper variant,本 prop 對 checkbox 主體無視覺影響;\n   * 為對齊 Field 4-mode + chrome 透傳契約而保留(M19 一致性)。\n   */\n  variant?: FieldVariant\n}\n\n// ── Component ───────────────────────────────────────────────────────────────\n\nconst Checkbox = React.forwardRef<\n  React.ElementRef<typeof CheckboxPrimitive.Root>,\n  CheckboxProps\n>(\n  (\n    {\n      className,\n      size,\n      label,\n      icon,\n      avatar,\n      description,\n      readOnly = false,\n      disabled,\n      mode,\n      // chrome 對 Checkbox 主體無視覺影響(無 input wrapper)— 接收純為 prop 一致性;destructure 防 leak 到 DOM。\n      variant: _chrome,\n      id: idProp,\n      ...props\n    },\n    ref\n  ) => {\n    const sizeKey = size ?? 'md'\n    const iconPx = checkIconSize[sizeKey]\n    const iconStrokeWidth = checkStrokeWidth[sizeKey]\n\n    // Field context:Checkbox 單獨塞進 Field(binary toggle)時,忽略自己的 label 讓 FieldLabel 接管\n    // 2026-05-31 #35:hooks(useFieldContext / useContext / useId)必在任何 conditional return 前呼叫(Rules of Hooks)。\n    // 原 mode='display' early return 寫在 hooks 之上 → runtime 切 mode 會 hook count 不一致 crash;已下移至 hooks 後。\n    //\n    // **例外**:Checkbox 是 CheckboxGroup 的 child 時(multi-select 情境),**每個 checkbox\n    // 的 label 是它自己的選項名**,FieldLabel 只是群組名稱 — 此時 label **必須保留**,\n    // 不能被 Field context 吞掉。AR50 的根因就是這個 branch 之前誤把 group 內的 checkbox\n    // label 全清空,導致 sheet 內 3 個 checkbox 沒 label。\n    const fieldCtx = useFieldContext()\n    const checkboxGroupCtx = React.useContext(CheckboxGroupContext)\n    const insideField = fieldCtx?.hasFieldWrapper === true\n    const insideGroup = checkboxGroupCtx?.inGroup === true\n    const shouldSuppressLabel = insideField && !insideGroup\n    const effectiveLabel = shouldSuppressLabel ? undefined : label\n    const effectiveDescription = shouldSuppressLabel ? undefined : description\n\n    // Id 連結\n    //\n    // ── 2026-04-21 bug fix ──\n    // 原本:`idProp ?? fieldCtx?.id ?? generatedId`。\n    // 在 Field 內 fieldCtx.id 存在,CheckboxGroup 所有 children 共用同一個 id →\n    // 每個 checkbox 的 `<label htmlFor={sameId}>` 全指向第一個 checkbox →\n    // **點任何 label 都只開關第一個 checkbox(real bug)**。\n    //\n    // 修法:group 內的 checkbox 強制用 generatedId(唯一),不沿用 Field id;\n    //      solo in Field(binary toggle)才沿用 fieldCtx.id 讓 FieldLabel htmlFor 生效。\n    const generatedId = React.useId()\n    const inputId = idProp ?? (insideGroup ? generatedId : (fieldCtx?.id ?? generatedId))\n\n    // 2026-06-08 SSOT cascade:disabled + mode 經 resolver hook(原 raw prop → <Field disabled>/<Field mode=\"display\"> 漏 cascade)\n    const resolvedDisabled = useResolvedFieldDisabled(disabled)\n    const resolvedMode = useResolvedFieldMode({ mode, disabled, readOnly })\n    const effectiveReadOnly = readOnly || resolvedMode === 'readonly'\n    // mode='disabled'(如 DataTable disabled cell 直傳)必須落到真 disabled chrome —\n    // 2026-06-12 修:原本只看 resolvedDisabled(prop/fieldCtx),mode='disabled' 無人消費\n    // → disabled boolean cell 渲出可 focus 的正常外觀 checkbox(違 field-controls.spec L286)\n    const effectiveDisabled = resolvedDisabled || resolvedMode === 'disabled'\n    // readonly 灰框 size:走 SSOT resolver(prop > ctx > 'md',field-context.ts:150-161)\n    const resolvedBoxSize = useResolvedFieldSize(size ?? undefined, 'md') as 'sm' | 'md' | 'lg'\n\n    // 2026-07-04 修:display / readonly-in-Field 分支的裸 span/div 原丟棄剩餘 props\n    // (id/data-*/aria-*)且不轉發 forwardRef ref → consumer 的 aria-label 等靜默失效。\n    // 抽出 Radix 專屬 non-DOM props,其餘 DOM props 於兩分支 spread 轉發(與 Switch/\n    // RadioGroup 同修);edit 主路徑不受影響(rootEl 仍 spread 完整 props)。\n    const {\n      checked: checkedProp,\n      defaultChecked: defaultCheckedProp,\n      onCheckedChange: _onCheckedChange,\n      required: _required,\n      name: _name,\n      value: _value,\n      asChild: _asChild,\n      children: _children,\n      ...restDomProps\n    } = props\n\n    // ── mode='display'(下移至所有 hooks 之後,per #35 Rules of Hooks)──────────\n    // 純展示模式:無互動 primitive、渲染 ✓ / —(checked=true → ✓ / 其他 → —)。取代 BooleanDisplay。\n    if (resolvedMode === 'display') {\n      const isChecked = checkedProp === true\n      return isChecked\n        ? <span {...restDomProps} ref={ref as React.Ref<HTMLSpanElement>} className=\"text-foreground\">✓</span>\n        : <span {...restDomProps} ref={ref as React.Ref<HTMLSpanElement>} className=\"text-fg-muted\">—</span>\n    }\n\n    // ── mode='readonly' in Field(2026-06-12 user 拍板「灰框 + ✓/—」)─────────────\n    // Field 內 readonly boolean = readonly 灰框 chrome + display 同款值語言 ✓/—。\n    // 灰框消費 fieldWrapperStyles 同一 cva = 與 Input readonly 字面同源(SSOT,改一處全動)。\n    // 理由:同一張 readonly 表單裡文字控件有 bg-readonly 灰框鎖定訊號,boolean 保留全彩\n    // 控件會誤導「仍可操作」(世界級 0/4 用原樣鎖互動:Salesforce=✓ 靜態 glyph /\n    // SAP=靜態文字 / Atlassian=readView / Ant Pro=文字)。\n    // Scope:僅 Field 內且無 inline label(FieldLabel 接管 label 的表單欄位場景);\n    // standalone readOnly(settings list / SelectionItem row)維持原樣鎖互動不變。\n    if (effectiveReadOnly && insideField && effectiveLabel == null) {\n      const isChecked = (checkedProp ?? defaultCheckedProp) === true\n      const boxSize = resolvedBoxSize\n      return (\n        <div\n          {...(restDomProps as React.HTMLAttributes<HTMLDivElement>)}\n          ref={ref as React.Ref<HTMLDivElement>}\n          role=\"checkbox\"\n          aria-checked={isChecked}\n          aria-readonly=\"true\"\n          aria-labelledby={fieldCtx?.labelId}\n          aria-invalid={fieldCtx?.invalid || undefined}\n          data-readonly=\"true\"\n          tabIndex={0}\n          className={cn(\n            fieldWrapperStyles({ size: boxSize, mode: 'readonly', variant: 'default' }),\n            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',\n            className,\n          )}\n        >\n          {isChecked ? <span className=\"text-foreground\">✓</span> : <span className=\"text-fg-muted\">—</span>}\n        </div>\n      )\n    }\n\n    const rootEl = (\n      <CheckboxPrimitive.Root\n        id={inputId}\n        ref={ref}\n        disabled={effectiveDisabled}\n        aria-readonly={effectiveReadOnly || undefined}\n        data-readonly={effectiveReadOnly || undefined}\n        tabIndex={effectiveReadOnly ? -1 : undefined}\n        aria-describedby={fieldCtx?.descriptionId}\n        className={cn(checkboxVariants({ size }), className)}\n        {...props}\n        // 2026-07-05 D4 修:readOnly 鎖互動補 label 繞道 — <label htmlFor> 的 synthetic click\n        // 不是 pointer event,cva pointer-events-none 攔不到,點 label 文字仍 toggle。\n        // preventDefault 讓 Radix composeEventHandlers(checkForDefaultPrevented)跳過內部 toggle;\n        // 必列在 {...props} 之後才不被 consumer onClick 覆蓋(readOnly 時 consumer onClick 一併鎖,\n        // 與 pointer-events-none 擋直接點擊的行為一致)。\n        onClick={(event) => {\n          if (effectiveReadOnly) {\n            event.preventDefault()\n            return\n          }\n          props.onClick?.(event)\n        }}\n      >\n        <CheckboxPrimitive.Indicator className=\"grid place-content-center text-current\">\n          {props.checked === 'indeterminate'\n            ? <Minus style={{ width: iconPx, height: iconPx }} strokeWidth={iconStrokeWidth} />\n            : <Check style={{ width: iconPx, height: iconPx }} strokeWidth={iconStrokeWidth} />\n          }\n        </CheckboxPrimitive.Indicator>\n      </CheckboxPrimitive.Root>\n    )\n\n    // 無 label → 只渲染 checkbox 本體\n    if (effectiveLabel == null) return rootEl\n\n    // 有 label → 透過 SelectionItem 包裝（control 在左、label+description 在右）\n    return (\n      <SelectionItem\n        control={rootEl}\n        label={effectiveLabel}\n        description={effectiveDescription}\n        icon={icon}\n        avatar={avatar}\n        htmlFor={inputId}\n        disabled={effectiveDisabled}\n        size={sizeKey}\n      />\n    )\n  }\n)\nCheckbox.displayName = CheckboxPrimitive.Root.displayName\n\n// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)\n// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs\nexport const checkboxMeta = {\n  component: 'Checkbox',\n  family: null, // self-contained primitive(對齊 spec frontmatter self-contained + body L31;非 Family 4)\n  variants: {\n\n  },\n  sizes: {\n    // 2026-06-10 修 stale meta:iconSize 對齊 checkIconSize 真值(L49 sm/md=12, lg=16;deep-audit A.1b 抓 metadata drift)\n    sm: { fieldHeight: 28, iconSize: 12, typography: 'body' },\n    md: { fieldHeight: 32, iconSize: 12, typography: 'body' },\n    lg: { fieldHeight: 36, iconSize: 16, typography: 'body-lg' },\n  },\n  states: ['default', 'hover', 'focus-visible', 'disabled'],\n  tokens: {\n    bg: ['bg-disabled', 'bg-primary', 'bg-primary-hover', 'bg-surface'],\n    fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground'],\n    ring: ['ring-ring'],\n  },\n  defaultSize: 'md',\n} as const\n\nexport { Checkbox, checkboxVariants }\n"],"names":[],"mappings":"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"}

package/dist/components/Checkbox/index.d.ts

@@ -1,2 +1,3 @@
 export * from './checkbox';
+export * from './checkbox-group';
 //# sourceMappingURL=index.d.ts.map

package/dist/components/Checkbox/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/Checkbox/index.ts"],"names":[],"mappings":"AAIA,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/Checkbox/index.ts"],"names":[],"mappings":"AAIA,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA"}

package/dist/components/Checkbox/index.js

@@ -1,6 +1,9 @@
 import { Checkbox, checkboxMeta, checkboxVariants } from "./checkbox.js";
+import { CheckboxGroup, CheckboxGroupContext } from "./checkbox-group.js";
 export {
   Checkbox,
+  CheckboxGroup,
+  CheckboxGroupContext,
   checkboxMeta,
   checkboxVariants
 };

package/dist/components/Checkbox/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}

package/dist/components/Chip/chip.d.ts

@@ -42,7 +42,13 @@ export declare const chipMeta: {
     readonly component: "Chip";
     readonly family: 3;
     readonly variants: {};
-    readonly sizes: {};
+    readonly sizes: {
+        readonly sm: {
+            readonly fieldHeight: 28;
+            readonly iconSize: 16;
+            readonly typography: "body";
+        };
+    };
     readonly states: readonly ["default", "hover", "selected", "focus-visible", "disabled"];
     readonly tokens: {
         readonly bg: readonly ["bg-surface"];

package/dist/components/Chip/chip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chip.d.ts","sourceRoot":"","sources":["../../../src/components/Chip/chip.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,oBAAoB,MAAM,8BAA8B,CAAA;AAEpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAiB9C;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,QAAA,MAAM,YAAY,oFAsBjB,CAAA;AAED,MAAM,WAAW,SACf,SAAQ,KAAK,CAAC,wBAAwB,CAAC,OAAO,oBAAoB,CAAC,IAAI,CAAC;IACxE,+BAA+B;IAC/B,SAAS,CAAC,EAAE,UAAU,CAAA;IACtB,wBAAwB;IACxB,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACvB,uCAAuC;IACvC,OAAO,CAAC,EAAE,UAAU,CAAA;CACrB;AAED,QAAA,MAAM,IAAI,qFAsBR,CAAA;AAKF,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;AAExD,MAAM,MAAM,cAAc,GAAG,KAAK,CAAC,wBAAwB,CACzD,OAAO,oBAAoB,CAAC,IAAI,CACjC,GAAG;IACF,qDAAqD;IACrD,MAAM,CAAC,EAAE,eAAe,CAAA;CACzB,CAAA;AAED,QAAA,MAAM,SAAS,uFA2Bd,CAAA;AAuMD,eAAO,MAAM,QAAQ;;;;;;;;;;;CAeX,CAAA;AAEV,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,EAAE,CAAA"}
+{"version":3,"file":"chip.d.ts","sourceRoot":"","sources":["../../../src/components/Chip/chip.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,oBAAoB,MAAM,8BAA8B,CAAA;AAEpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAiB9C;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,QAAA,MAAM,YAAY,oFAsBjB,CAAA;AAED,MAAM,WAAW,SACf,SAAQ,KAAK,CAAC,wBAAwB,CAAC,OAAO,oBAAoB,CAAC,IAAI,CAAC;IACxE,+BAA+B;IAC/B,SAAS,CAAC,EAAE,UAAU,CAAA;IACtB,wBAAwB;IACxB,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACvB,uCAAuC;IACvC,OAAO,CAAC,EAAE,UAAU,CAAA;CACrB;AAED,QAAA,MAAM,IAAI,qFAsBR,CAAA;AAKF,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;AAExD,MAAM,MAAM,cAAc,GAAG,KAAK,CAAC,wBAAwB,CACzD,OAAO,oBAAoB,CAAC,IAAI,CACjC,GAAG;IACF,qDAAqD;IACrD,MAAM,CAAC,EAAE,eAAe,CAAA;CACzB,CAAA;AAED,QAAA,MAAM,SAAS,uFA2Bd,CAAA;AAuMD,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;CAeX,CAAA;AAEV,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,EAAE,CAAA"}

package/dist/components/Chip/chip.js

@@ -206,8 +206,12 @@ MenuChipGroup.displayName = "MenuChipGroup";
 const chipMeta = {
   component: "Chip",
   family: 3,
+  // 2026-07-04 audit 填 Phase 2:Chip 單一視覺無 variant 軸(variants 留空為 intentional,非漏填)
   variants: {},
-  sizes: {},
+  sizes: {
+    // 單一尺寸:h-field-sm(28/32 依 density)、icon 16、text-body、px-3(cva 真值)
+    sm: { fieldHeight: 28, iconSize: 16, typography: "body" }
+  },
   states: ["default", "hover", "selected", "focus-visible", "disabled"],
   // selected = data-[state=on](primary-hover);cva 無 active 樣式
   tokens: {

package/dist/components/Chip/chip.js.map

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

package/dist/components/Coachmark/coachmark.d.ts

@@ -19,9 +19,11 @@ import * as React from 'react';
  *   3. **Multi step 中間 / 最後步**(有 `onPrev`):**Skip 不顯示**(使用者已投入進度,
  *      再給 Skip 會讓「放棄」入口與「回上一步」衝突 — Linear / Pendo / Shepherd.js
  *      同樣規則)。CTA = `isLastStep ? 'Done' : 'Next'`
- *   4. **抑制開啟時的自動 focus** — `onOpenAutoFocus` preventDefault,連 Radix 預設
- *      focus 第一個 focusable 也一併抑制(焦點停在 trigger),避免使用者還在讀 body 時
- *      按 Enter 誤推進。想推進者自行 tab 到 CTA 再 Enter(對齊 spec「A11y 預設」)。
+ *   4. **抑制 CTA 自動 focus,焦點落在 content 容器** — `onOpenAutoFocus` preventDefault
+ *      後 focus content 容器本身(非第一個 CTA),避免使用者還在讀 body 時按 Enter 誤推進;
+ *      Tab 第一下即達 content 內第一個 CTA。焦點不可停在 trigger:non-modal Popover 下
+ *      焦點在 DismissableLayer 外按 Tab 會觸發 focus-outside dismiss 誤關閉
+ *      (2026-07-05 D4;對齊 dialog.tsx handleOpenAutoFocus `?? content` fallback,見 spec「A11y 預設」)。
  *
  * ── 為什麼 Body+Footer 消費 overlay-surface ──
  * 避免 padding token 漂移:Dialog / Popover / Coachmark 三者共用同一套 Header/Body/Footer

package/dist/components/Coachmark/coachmark.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coachmark.d.ts","sourceRoot":"","sources":["../../../src/components/Coachmark/coachmark.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAe9B;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,UAAU,aAAa;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,cAAe,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC;IACtG,2BAA2B;IAC3B,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,sGAAsG;IACtG,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACtC,yDAAyD;IACzD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,yDAAyD;IACzD,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACvB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,cAAc,GAAG,KAAK,CAAC,SAAS,CAAA;IAChD,eAAe;IACf,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACvB,gCAAgC;IAChC,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC7B,gDAAgD;IAChD,IAAI,CAAC,EAAE,aAAa,CAAA;IACpB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,IAAI,CAAA;IACnB,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,IAAI,CAAA;IACnB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,IAAI,CAAA;IACnB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,6BAA6B;IAC7B,IAAI,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAA;IAC1C,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAA;IAClC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AASD,QAAA,MAAM,SAAS,uFAmId,CAAA;AAKD,eAAO,MAAM,aAAa;;;;;;;;;;;CAehB,CAAA;AAEV,OAAO,EAAE,SAAS,EAAE,CAAA"}
+{"version":3,"file":"coachmark.d.ts","sourceRoot":"","sources":["../../../src/components/Coachmark/coachmark.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAe9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,UAAU,aAAa;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,cAAe,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC;IACtG,2BAA2B;IAC3B,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,sGAAsG;IACtG,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACtC,yDAAyD;IACzD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,yDAAyD;IACzD,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACvB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,cAAc,GAAG,KAAK,CAAC,SAAS,CAAA;IAChD,eAAe;IACf,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACvB,gCAAgC;IAChC,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC7B,gDAAgD;IAChD,IAAI,CAAC,EAAE,aAAa,CAAA;IACpB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,IAAI,CAAA;IACnB,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,IAAI,CAAA;IACnB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,IAAI,CAAA;IACnB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,6BAA6B;IAC7B,IAAI,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAA;IAC1C,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAA;IAClC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AASD,QAAA,MAAM,SAAS,uFAyId,CAAA;AAKD,eAAO,MAAM,aAAa;;;;;;;;;;;CAehB,CAAA;AAEV,OAAO,EAAE,SAAS,EAAE,CAAA"}

package/dist/components/Coachmark/coachmark.js

@@ -51,7 +51,10 @@ const Coachmark = React.forwardRef(
           align,
           sideOffset,
           className: cn("w-80 p-0 overflow-hidden", className),
-          onOpenAutoFocus: (e) => e.preventDefault(),
+          onOpenAutoFocus: (e) => {
+            e.preventDefault();
+            e.currentTarget.focus({ preventScroll: true });
+          },
           "aria-labelledby": dialogLabelledBy,
           "aria-label": dialogLabelledBy ? void 0 : "提示",
           ...props,

package/dist/components/Coachmark/coachmark.js.map

@@ -1 +1 @@
-{"version":3,"file":"coachmark.js","sources":["../../../src/components/Coachmark/coachmark.tsx"],"sourcesContent":["// @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.\nimport * as React from 'react'\nimport { cn } from '@/lib/utils'\nimport {\n  Popover,\n  PopoverTrigger,\n  PopoverContent,\n  PopoverBody,\n  PopoverFooter,\n  PopoverHeader,\n  PopoverTitle,\n} from '@/design-system/components/Popover/popover'\nimport { Button } from '@/design-system/components/Button/button'\nimport { AspectRatio } from '@/design-system/components/AspectRatio/aspect-ratio'\nimport { OVERLAY_SIDE_OFFSET } from '@/design-system/tokens/elevation/overlay-geometry'\n\n/**\n * Coachmark — 功能介紹 / onboarding tour 的浮層卡片\n *\n * 世界級對照:Apple HIG「Coachmark」(Apple 命名原處)/ Material「Feature Discovery」/\n * Ant Design `<Tour>` / Shepherd.js / react-joyride / Intercom Product Tours。\n *\n * 本元件 = **Popover 的 composition pattern**,consume 相同 overlay-surface SSOT:\n *   - Header(可選,多步驟建議傳 `kind=\"tips\" | \"new-features\" | 自訂 title`,\n *     single-step 預設無 header 避免視覺過重)\n *   - Media 區(圖 / 截圖 / illustration,full-width 邊緣對齊,由 AspectRatio 管比例)\n *   - Body(SurfaceBody padding):title + description 左對齊\n *   - Footer(SurfaceFooter padding,但 justify-between):step 計數左 / actions 右\n *\n * ── 單 vs 多步驟 canonical(世界級行為規則) ──\n *   1. **Single step**(無 `onPrev` 且 `isLastStep`):CTA 文字 = `doneLabel ?? '知道了'`\n *      (Apple HIG / Intercom 慣例;不用 \"Next\" 因為沒有下一步)\n *   2. **Multi step 第一步**(無 `onPrev`,有 `onNext`):CTA = \"Next\",Skip 顯示\n *   3. **Multi step 中間 / 最後步**(有 `onPrev`):**Skip 不顯示**(使用者已投入進度,\n *      再給 Skip 會讓「放棄」入口與「回上一步」衝突 — Linear / Pendo / Shepherd.js\n *      同樣規則)。CTA = `isLastStep ? 'Done' : 'Next'`\n *   4. **抑制開啟時的自動 focus** — `onOpenAutoFocus` preventDefault,連 Radix 預設\n *      focus 第一個 focusable 也一併抑制(焦點停在 trigger),避免使用者還在讀 body 時\n *      按 Enter 誤推進。想推進者自行 tab 到 CTA 再 Enter(對齊 spec「A11y 預設」)。\n *\n * ── 為什麼 Body+Footer 消費 overlay-surface ──\n * 避免 padding token 漂移:Dialog / Popover / Coachmark 三者共用同一套 Header/Body/Footer\n * padding(px-loose / py-tight),改 Dialog 就三邊自動跟進。\n */\n\ninterface CoachmarkStep {\n  current: number\n  total: number\n}\n\nexport interface CoachmarkProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children' | 'title'> {\n  /** 控制顯示(controlled mode)*/\n  open?: boolean\n  /** 預設打開(uncontrolled initial state)— 2026-05-15 audit Dim 26 V1 fix per user verbatim「A:1」approval */\n  defaultOpen?: boolean\n  onOpenChange?: (open: boolean) => void\n  /** 觸發 anchor 元素。通常傳 trigger element;Coachmark 浮層會定位於此 */\n  children: React.ReactNode\n  /** 頂部 media 區(圖片 / illustration / video 等);不傳則無 media */\n  image?: React.ReactNode\n  /**\n   * Media 區域的長寬比(ratio = 寬 / 高)。預設 `16/9`(onboarding feature tour\n   * 世界級 convention — Intercom / Pendo / Shepherd.js)。其他常用:`4/3` 產品截圖 /\n   * `1/1` 方圖 / `3/4` 直式 portrait。消費獨立的 `AspectRatio` primitive 元件。\n   */\n  mediaRatio?: number\n  /**\n   * 頂部 header 類型(多步驟 tour 建議傳)。\n   * - `'tips'` → header title = \"使用技巧\"\n   * - `'new-features'` → header title = \"新功能介紹\"\n   * - `ReactNode` → 自訂 title(string / JSX)\n   * - undefined → 無 header(單步驟常用)\n   */\n  kind?: 'tips' | 'new-features' | React.ReactNode\n  /** 標題(bold) */\n  title?: React.ReactNode\n  /** 說明文字(normal weight,多行 OK) */\n  description?: React.ReactNode\n  /** 步驟計數(2 of 3);若需多步導覽 consumer 自行管理 current */\n  step?: CoachmarkStep\n  /** Skip 按鈕 callback;不傳則不顯示 Skip。多步驟中間 / 最後步自動隱藏(有 onPrev 時) */\n  onSkip?: () => void\n  /** Next 按鈕 callback;不傳則不顯示 Next */\n  onNext?: () => void\n  /** Previous 按鈕 callback(多步 tour 第 2+ 步顯示);不傳則不顯示 */\n  onPrev?: () => void\n  /**\n   * 最後一步 flag。影響 primary CTA 文字:\n   * - single step(無 onPrev 且 isLastStep):CTA = `doneLabel ?? '知道了'`\n   * - multi-step 最後步(有 onPrev 且 isLastStep):CTA = 'Done'\n   * - 其他:CTA = 'Next'\n   */\n  isLastStep?: boolean\n  /** 自訂單步驟完成 CTA 文字(預設 `'知道了'`)。僅 single-step 使用 */\n  doneLabel?: string\n  /** 浮層定位(對齊 Popover props) */\n  side?: 'top' | 'right' | 'bottom' | 'left'\n  align?: 'start' | 'center' | 'end'\n  sideOffset?: number\n  /** 外殼寬度(預設 w-80 = 320px,比一般 Popover 寬,因要放 media + 文字) */\n  className?: string\n}\n\n// i18n-allow: DS-internal kind → title 預設對照表;consumer 透過 `title` prop 直接覆寫\nconst KIND_TITLE: Record<'tips' | 'new-features', string> = {\n  tips: '使用技巧',\n  'new-features': '新功能介紹',\n}\n\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst Coachmark = React.forwardRef<HTMLDivElement, CoachmarkProps>(\n  (\n    {\n      open,\n      defaultOpen,\n      onOpenChange,\n      children,\n      image,\n      mediaRatio = 16 / 9,\n      kind,\n      title,\n      description,\n      step,\n      onSkip,\n      onNext,\n      onPrev,\n      isLastStep = false,\n      doneLabel = '知道了', // i18n-allow: DS default; consumer override via doneLabel prop\n      side = 'bottom',\n      align = 'center',\n      sideOffset = OVERLAY_SIDE_OFFSET,\n      className,\n      ...props\n    },\n    ref,\n  ) => {\n    // 單/多步驟行為推導\n    const isSingleStep = isLastStep && !onPrev\n    // canonical(spec.md CTA 語義表 L116):有 onPrev → 不顯示 Skip;**單步驟也不顯示 Skip**\n    // (單步「skip」與「知道了」語義重複 = 同一個關閉動作,雙關閉鍵造成困惑;對齊 Apple HIG / Intercom / Pendo 單步 tip 僅一個完成鍵)\n    const showSkip = Boolean(onSkip) && !onPrev && !isSingleStep\n    const nextLabel = isSingleStep ? doneLabel : isLastStep ? 'Done' : 'Next'\n\n    const hasFooterContent = Boolean(step || showSkip || onNext || onPrev)\n    const stepText = step ? `${step.current} of ${step.total}` : null\n\n    // Header title 解析\n    const headerTitle =\n      kind === 'tips' || kind === 'new-features'\n        ? KIND_TITLE[kind as 'tips' | 'new-features']\n        : kind\n\n    // 2026-05-31 #6:PopoverContent(role=dialog)需 accessible name。dialog aria-labelledby 接可見標題\n    // (優先 headerTitle 的 PopoverTitle,否則 body title 的 h3);皆無則 aria-label fallback。\n    const titleId = React.useId()\n    const dialogLabelledBy = (headerTitle || title) ? titleId : undefined\n\n    return (\n      <Popover open={open} defaultOpen={defaultOpen} onOpenChange={onOpenChange}>\n        <PopoverTrigger asChild>{children}</PopoverTrigger>\n        <PopoverContent\n          ref={ref}\n          side={side}\n          align={align}\n          sideOffset={sideOffset}\n          className={cn('w-80 p-0 overflow-hidden', className)}\n          // 禁止 Radix 開啟時自動 focus 第一個 focusable(預設會 focus Prev / Skip / Next),\n          // Coachmark 的 CTA 不該被 auto-focus 偷觸發(user 可能還在讀 body,按 Enter 就推進)。\n          // 想推進的 user 自己 tab 到 CTA 即可。\n          onOpenAutoFocus={(e) => e.preventDefault()}\n          aria-labelledby={dialogLabelledBy}\n          aria-label={dialogLabelledBy ? undefined : '提示'}\n          {...props}\n        >\n          {headerTitle && (\n            // Header title 走 `<PopoverTitle>` 共用 Popover typography canonical(text-body font-medium)。\n            // **不 hideClose** — 對齊 Popover / Dialog / 所有 overlay 家族 canonical:header 必有 dismiss X\n            // (user 可隨時關閉,跟 Skip / Done 是不同入口,canonical 重複不冗)\n            <PopoverHeader>\n              <PopoverTitle id={titleId}>{headerTitle}</PopoverTitle>\n            </PopoverHeader>\n          )}\n\n          {image && (\n            <AspectRatio ratio={mediaRatio} className=\"w-full overflow-hidden bg-muted\">\n              {image}\n            </AspectRatio>\n          )}\n\n          {(title || description) && (\n            // 對齊 Dialog / Popover canonical:body 左對齊(不中置)\n            // Why: Coachmark 雖是 onboarding / feature discovery,但文字可讀性 > 視覺焦點;\n            // 中文 / 長句中置會「每行起點不同」造成閱讀鋸齒,左對齊最穩。\n            // 世界級參考:Notion / Linear / Figma onboarding tour 皆左對齊;Intercom Messenger 亦如是。\n            <PopoverBody className=\"flex flex-col\">\n              {title && (\n                <h3 id={!headerTitle ? titleId : undefined} className=\"text-body-lg font-medium text-foreground\">{title}</h3>\n              )}\n              {description && (\n                // title(body-lg 16)+ desc(body 14)→ reading-lg token(label tier 決定)\n                // 對齊 Dialog / Sheet canonical;移除原 gap-1(4px)drift\n                <p className=\"mt-[var(--item-gap-label-desc-reading-lg)] text-body text-fg-secondary\">{description}</p>\n              )}\n            </PopoverBody>\n          )}\n\n          {hasFooterContent && (\n            // 專屬 Coachmark canonical:footer 無上方分隔線(media + body + footer 視覺一氣呵成,\n            // 不像 Dialog 需要 header/footer 分隔強化結構)。override SurfaceFooter default border-t\n            <PopoverFooter className=\"justify-between !border-t-0\">\n              {stepText ? (\n                // step 文字走 text-body 跟 body content 字體一致\n                <span className=\"text-body text-fg-secondary tabular-nums\">\n                  {stepText}\n                </span>\n              ) : (\n                <span aria-hidden /> /* 保持 justify-between space */\n              )}\n              <div className=\"flex items-center gap-2\">\n                {onPrev && (\n                  <Button variant=\"tertiary\" size=\"sm\" onClick={onPrev}>\n                    Previous\n                  </Button>\n                )}\n                {showSkip && (\n                  <Button variant=\"tertiary\" size=\"sm\" onClick={onSkip}>\n                    Skip\n                  </Button>\n                )}\n                {onNext && (\n                  <Button variant=\"primary\" size=\"sm\" onClick={onNext}>\n                    {nextLabel}\n                  </Button>\n                )}\n              </div>\n            </PopoverFooter>\n          )}\n        </PopoverContent>\n      </Popover>\n    )\n  },\n)\nCoachmark.displayName = 'Coachmark'\n\n// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)\n// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs\nexport const coachmarkMeta = {\n  component: 'Coachmark',\n  family: null, // non-family composite / overlay / layout\n  variants: {\n\n  },\n  sizes: {\n\n  },\n  states: ['default'], // 純 Popover composition — 無自有 hover / active / disabled 視覺(spec「邊界狀態」)\n  tokens: {\n    bg: ['bg-muted'],\n    fg: ['text-fg-secondary', 'text-foreground'],\n    ring: [],\n  },\n} as const\n\nexport { Coachmark }\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"coachmark.js","sources":["../../../src/components/Coachmark/coachmark.tsx"],"sourcesContent":["// @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.\nimport * as React from 'react'\nimport { cn } from '@/lib/utils'\nimport {\n  Popover,\n  PopoverTrigger,\n  PopoverContent,\n  PopoverBody,\n  PopoverFooter,\n  PopoverHeader,\n  PopoverTitle,\n} from '@/design-system/components/Popover/popover'\nimport { Button } from '@/design-system/components/Button/button'\nimport { AspectRatio } from '@/design-system/components/AspectRatio/aspect-ratio'\nimport { OVERLAY_SIDE_OFFSET } from '@/design-system/tokens/elevation/overlay-geometry'\n\n/**\n * Coachmark — 功能介紹 / onboarding tour 的浮層卡片\n *\n * 世界級對照:Apple HIG「Coachmark」(Apple 命名原處)/ Material「Feature Discovery」/\n * Ant Design `<Tour>` / Shepherd.js / react-joyride / Intercom Product Tours。\n *\n * 本元件 = **Popover 的 composition pattern**,consume 相同 overlay-surface SSOT:\n *   - Header(可選,多步驟建議傳 `kind=\"tips\" | \"new-features\" | 自訂 title`,\n *     single-step 預設無 header 避免視覺過重)\n *   - Media 區(圖 / 截圖 / illustration,full-width 邊緣對齊,由 AspectRatio 管比例)\n *   - Body(SurfaceBody padding):title + description 左對齊\n *   - Footer(SurfaceFooter padding,但 justify-between):step 計數左 / actions 右\n *\n * ── 單 vs 多步驟 canonical(世界級行為規則) ──\n *   1. **Single step**(無 `onPrev` 且 `isLastStep`):CTA 文字 = `doneLabel ?? '知道了'`\n *      (Apple HIG / Intercom 慣例;不用 \"Next\" 因為沒有下一步)\n *   2. **Multi step 第一步**(無 `onPrev`,有 `onNext`):CTA = \"Next\",Skip 顯示\n *   3. **Multi step 中間 / 最後步**(有 `onPrev`):**Skip 不顯示**(使用者已投入進度,\n *      再給 Skip 會讓「放棄」入口與「回上一步」衝突 — Linear / Pendo / Shepherd.js\n *      同樣規則)。CTA = `isLastStep ? 'Done' : 'Next'`\n *   4. **抑制 CTA 自動 focus,焦點落在 content 容器** — `onOpenAutoFocus` preventDefault\n *      後 focus content 容器本身(非第一個 CTA),避免使用者還在讀 body 時按 Enter 誤推進;\n *      Tab 第一下即達 content 內第一個 CTA。焦點不可停在 trigger:non-modal Popover 下\n *      焦點在 DismissableLayer 外按 Tab 會觸發 focus-outside dismiss 誤關閉\n *      (2026-07-05 D4;對齊 dialog.tsx handleOpenAutoFocus `?? content` fallback,見 spec「A11y 預設」)。\n *\n * ── 為什麼 Body+Footer 消費 overlay-surface ──\n * 避免 padding token 漂移:Dialog / Popover / Coachmark 三者共用同一套 Header/Body/Footer\n * padding(px-loose / py-tight),改 Dialog 就三邊自動跟進。\n */\n\ninterface CoachmarkStep {\n  current: number\n  total: number\n}\n\nexport interface CoachmarkProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children' | 'title'> {\n  /** 控制顯示(controlled mode)*/\n  open?: boolean\n  /** 預設打開(uncontrolled initial state)— 2026-05-15 audit Dim 26 V1 fix per user verbatim「A:1」approval */\n  defaultOpen?: boolean\n  onOpenChange?: (open: boolean) => void\n  /** 觸發 anchor 元素。通常傳 trigger element;Coachmark 浮層會定位於此 */\n  children: React.ReactNode\n  /** 頂部 media 區(圖片 / illustration / video 等);不傳則無 media */\n  image?: React.ReactNode\n  /**\n   * Media 區域的長寬比(ratio = 寬 / 高)。預設 `16/9`(onboarding feature tour\n   * 世界級 convention — Intercom / Pendo / Shepherd.js)。其他常用:`4/3` 產品截圖 /\n   * `1/1` 方圖 / `3/4` 直式 portrait。消費獨立的 `AspectRatio` primitive 元件。\n   */\n  mediaRatio?: number\n  /**\n   * 頂部 header 類型(多步驟 tour 建議傳)。\n   * - `'tips'` → header title = \"使用技巧\"\n   * - `'new-features'` → header title = \"新功能介紹\"\n   * - `ReactNode` → 自訂 title(string / JSX)\n   * - undefined → 無 header(單步驟常用)\n   */\n  kind?: 'tips' | 'new-features' | React.ReactNode\n  /** 標題(bold) */\n  title?: React.ReactNode\n  /** 說明文字(normal weight,多行 OK) */\n  description?: React.ReactNode\n  /** 步驟計數(2 of 3);若需多步導覽 consumer 自行管理 current */\n  step?: CoachmarkStep\n  /** Skip 按鈕 callback;不傳則不顯示 Skip。多步驟中間 / 最後步自動隱藏(有 onPrev 時) */\n  onSkip?: () => void\n  /** Next 按鈕 callback;不傳則不顯示 Next */\n  onNext?: () => void\n  /** Previous 按鈕 callback(多步 tour 第 2+ 步顯示);不傳則不顯示 */\n  onPrev?: () => void\n  /**\n   * 最後一步 flag。影響 primary CTA 文字:\n   * - single step(無 onPrev 且 isLastStep):CTA = `doneLabel ?? '知道了'`\n   * - multi-step 最後步(有 onPrev 且 isLastStep):CTA = 'Done'\n   * - 其他:CTA = 'Next'\n   */\n  isLastStep?: boolean\n  /** 自訂單步驟完成 CTA 文字(預設 `'知道了'`)。僅 single-step 使用 */\n  doneLabel?: string\n  /** 浮層定位(對齊 Popover props) */\n  side?: 'top' | 'right' | 'bottom' | 'left'\n  align?: 'start' | 'center' | 'end'\n  sideOffset?: number\n  /** 外殼寬度(預設 w-80 = 320px,比一般 Popover 寬,因要放 media + 文字) */\n  className?: string\n}\n\n// i18n-allow: DS-internal kind → title 預設對照表;consumer 透過 `title` prop 直接覆寫\nconst KIND_TITLE: Record<'tips' | 'new-features', string> = {\n  tips: '使用技巧',\n  'new-features': '新功能介紹',\n}\n\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst Coachmark = React.forwardRef<HTMLDivElement, CoachmarkProps>(\n  (\n    {\n      open,\n      defaultOpen,\n      onOpenChange,\n      children,\n      image,\n      mediaRatio = 16 / 9,\n      kind,\n      title,\n      description,\n      step,\n      onSkip,\n      onNext,\n      onPrev,\n      isLastStep = false,\n      doneLabel = '知道了', // i18n-allow: DS default; consumer override via doneLabel prop\n      side = 'bottom',\n      align = 'center',\n      sideOffset = OVERLAY_SIDE_OFFSET,\n      className,\n      ...props\n    },\n    ref,\n  ) => {\n    // 單/多步驟行為推導\n    const isSingleStep = isLastStep && !onPrev\n    // canonical(spec.md CTA 語義表 L116):有 onPrev → 不顯示 Skip;**單步驟也不顯示 Skip**\n    // (單步「skip」與「知道了」語義重複 = 同一個關閉動作,雙關閉鍵造成困惑;對齊 Apple HIG / Intercom / Pendo 單步 tip 僅一個完成鍵)\n    const showSkip = Boolean(onSkip) && !onPrev && !isSingleStep\n    const nextLabel = isSingleStep ? doneLabel : isLastStep ? 'Done' : 'Next'\n\n    const hasFooterContent = Boolean(step || showSkip || onNext || onPrev)\n    const stepText = step ? `${step.current} of ${step.total}` : null\n\n    // Header title 解析\n    const headerTitle =\n      kind === 'tips' || kind === 'new-features'\n        ? KIND_TITLE[kind as 'tips' | 'new-features']\n        : kind\n\n    // 2026-05-31 #6:PopoverContent(role=dialog)需 accessible name。dialog aria-labelledby 接可見標題\n    // (優先 headerTitle 的 PopoverTitle,否則 body title 的 h3);皆無則 aria-label fallback。\n    const titleId = React.useId()\n    const dialogLabelledBy = (headerTitle || title) ? titleId : undefined\n\n    return (\n      <Popover open={open} defaultOpen={defaultOpen} onOpenChange={onOpenChange}>\n        <PopoverTrigger asChild>{children}</PopoverTrigger>\n        <PopoverContent\n          ref={ref}\n          side={side}\n          align={align}\n          sideOffset={sideOffset}\n          className={cn('w-80 p-0 overflow-hidden', className)}\n          // 禁止 Radix 開啟時自動 focus 第一個 focusable(預設會 focus Prev / Skip / Next),\n          // Coachmark 的 CTA 不該被 auto-focus 偷觸發(user 可能還在讀 body,按 Enter 就推進)。\n          // 2026-07-05 D4:preventDefault 後必 focus content 容器本身(FocusScope 容器自帶 tabIndex=-1)——\n          // 焦點若停在 trigger(DismissableLayer 外),non-modal Popover 按 Tab 即觸發 focus-outside\n          // dismiss 直接關閉,CTA 鍵盤永遠到不了;focus 容器後 Tab 第一下即達第一個 CTA,Enter 按在\n          // 容器上無動作(原「不誤推進」意圖保留;對齊 dialog.tsx handleOpenAutoFocus `?? content` fallback)。\n          onOpenAutoFocus={(e) => {\n            e.preventDefault()\n            ;(e.currentTarget as HTMLElement).focus({ preventScroll: true })\n          }}\n          aria-labelledby={dialogLabelledBy}\n          aria-label={dialogLabelledBy ? undefined : '提示'}\n          {...props}\n        >\n          {headerTitle && (\n            // Header title 走 `<PopoverTitle>` 共用 Popover typography canonical(text-body font-medium)。\n            // **不 hideClose** — 對齊 Popover / Dialog / 所有 overlay 家族 canonical:header 必有 dismiss X\n            // (user 可隨時關閉,跟 Skip / Done 是不同入口,canonical 重複不冗)\n            <PopoverHeader>\n              <PopoverTitle id={titleId}>{headerTitle}</PopoverTitle>\n            </PopoverHeader>\n          )}\n\n          {image && (\n            <AspectRatio ratio={mediaRatio} className=\"w-full overflow-hidden bg-muted\">\n              {image}\n            </AspectRatio>\n          )}\n\n          {(title || description) && (\n            // 對齊 Dialog / Popover canonical:body 左對齊(不中置)\n            // Why: Coachmark 雖是 onboarding / feature discovery,但文字可讀性 > 視覺焦點;\n            // 中文 / 長句中置會「每行起點不同」造成閱讀鋸齒,左對齊最穩。\n            // 世界級參考:Notion / Linear / Figma onboarding tour 皆左對齊;Intercom Messenger 亦如是。\n            <PopoverBody className=\"flex flex-col\">\n              {title && (\n                <h3 id={!headerTitle ? titleId : undefined} className=\"text-body-lg font-medium text-foreground\">{title}</h3>\n              )}\n              {description && (\n                // title(body-lg 16)+ desc(body 14)→ reading-lg token(label tier 決定)\n                // 對齊 Dialog / Sheet canonical;移除原 gap-1(4px)drift\n                <p className=\"mt-[var(--item-gap-label-desc-reading-lg)] text-body text-fg-secondary\">{description}</p>\n              )}\n            </PopoverBody>\n          )}\n\n          {hasFooterContent && (\n            // 專屬 Coachmark canonical:footer 無上方分隔線(media + body + footer 視覺一氣呵成,\n            // 不像 Dialog 需要 header/footer 分隔強化結構)。override SurfaceFooter default border-t\n            <PopoverFooter className=\"justify-between !border-t-0\">\n              {stepText ? (\n                // step 文字走 text-body 跟 body content 字體一致\n                <span className=\"text-body text-fg-secondary tabular-nums\">\n                  {stepText}\n                </span>\n              ) : (\n                <span aria-hidden /> /* 保持 justify-between space */\n              )}\n              <div className=\"flex items-center gap-2\">\n                {onPrev && (\n                  <Button variant=\"tertiary\" size=\"sm\" onClick={onPrev}>\n                    Previous\n                  </Button>\n                )}\n                {showSkip && (\n                  <Button variant=\"tertiary\" size=\"sm\" onClick={onSkip}>\n                    Skip\n                  </Button>\n                )}\n                {onNext && (\n                  <Button variant=\"primary\" size=\"sm\" onClick={onNext}>\n                    {nextLabel}\n                  </Button>\n                )}\n              </div>\n            </PopoverFooter>\n          )}\n        </PopoverContent>\n      </Popover>\n    )\n  },\n)\nCoachmark.displayName = 'Coachmark'\n\n// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)\n// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs\nexport const coachmarkMeta = {\n  component: 'Coachmark',\n  family: null, // non-family composite / overlay / layout\n  variants: {\n\n  },\n  sizes: {\n\n  },\n  states: ['default'], // 純 Popover composition — 無自有 hover / active / disabled 視覺(spec「邊界狀態」)\n  tokens: {\n    bg: ['bg-muted'],\n    fg: ['text-fg-secondary', 'text-foreground'],\n    ring: [],\n  },\n} as const\n\nexport { Coachmark }\n"],"names":[],"mappings":"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"}

package/dist/components/Combobox/combobox.d.ts

@@ -50,6 +50,8 @@ export interface ComboboxProps {
     searchAriaLabel?: string;
     /** Empty-selection placeholder text。Default: 「選擇…」 */
     emptyPlaceholder?: string;
+    /** 搜尋無結果提示(2026-07-04 Q4 拍板接線)— forward SelectMenu primitive SSOT(default「沒有符合的選項」) */
+    emptyText?: string;
     /** a11y:無 Field wrapper 時提供 role='combobox' 的 accessible name(axe aria-input-field-name) */
     'aria-label'?: string;
     /** Initial open state(uncontrolled)— 對齊 Select.defaultOpen / Radix Popover canonical。

package/dist/components/Combobox/combobox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"combobox.d.ts","sourceRoot":"","sources":["../../../src/components/Combobox/combobox.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,8CAA8C,CAAA;AAM3F,OAAO,EAAc,KAAK,gBAAgB,EAAE,MAAM,mDAAmD,CAAA;AAcrG;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAe,SAAQ,gBAAgB;CAEvD;AAgLD,KAAK,qBAAqB,GAAG,QAAQ,GAAG,KAAK,CAAA;AA6I7C,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,uFAAuF;IACvF,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;IACzB,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAA;IACpC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,WAAW;IACX,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;kGAE8F;IAC9F,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,qCAAqC;IACrC,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,sDAAsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,4FAA4F;IAC5F,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;gDAC4C;IAC5C,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,mFAAmF;IACnF,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACtC;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,QAAQ,EAAE,MAAM,IAAI,KAAK,KAAK,CAAC,SAAS,CAAA;IAC/F;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,KAAK,CAAC,SAAS,CAAA;IAC7E;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;sEAGkE;IAClE,wBAAwB,CAAC,EAAE,MAAM,CAAA;IACjC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;;;;;;;;;OAcG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B;;;;OAIG;IACH,aAAa,CAAC,EAAE,qBAAqB,CAAA;IACrC;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAC7B;AAyWD,QAAA,MAAM,QAAQ,sFAab,CAAA;AAKD,eAAO,MAAM,YAAY;;;;;;;;;;;CAef,CAAA;AAEV,OAAO,EAAE,QAAQ,EAAE,CAAA"}
+{"version":3,"file":"combobox.d.ts","sourceRoot":"","sources":["../../../src/components/Combobox/combobox.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,8CAA8C,CAAA;AAM3F,OAAO,EAAmC,KAAK,gBAAgB,EAAE,MAAM,mDAAmD,CAAA;AAc1H;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAe,SAAQ,gBAAgB;CAEvD;AAgLD,KAAK,qBAAqB,GAAG,QAAQ,GAAG,KAAK,CAAA;AA8I7C,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,uFAAuF;IACvF,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;IACzB,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAA;IACpC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,WAAW;IACX,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;kGAE8F;IAC9F,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,qCAAqC;IACrC,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,sDAAsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4FAA4F;IAC5F,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;gDAC4C;IAC5C,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,mFAAmF;IACnF,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACtC;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,QAAQ,EAAE,MAAM,IAAI,KAAK,KAAK,CAAC,SAAS,CAAA;IAC/F;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,KAAK,CAAC,SAAS,CAAA;IAC7E;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;sEAGkE;IAClE,wBAAwB,CAAC,EAAE,MAAM,CAAA;IACjC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;;;;;;;;;OAcG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B;;;;OAIG;IACH,aAAa,CAAC,EAAE,qBAAqB,CAAA;IACrC;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAC7B;AA6WD,QAAA,MAAM,QAAQ,sFAab,CAAA;AAKD,eAAO,MAAM,YAAY;;;;;;;;;;;CAef,CAAA;AAEV,OAAO,EAAE,QAAQ,EAAE,CAAA"}

package/dist/components/Combobox/combobox.js

@@ -7,7 +7,7 @@ import { useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldVariant
 import { Tag } from "../Tag/tag.js";
 import { ItemSuffix, ItemInlineAction, ICON_SIZE } from "../../patterns/element-anatomy/item-anatomy.js";
 import { OverflowIndicator } from "../OverflowIndicator/overflow-indicator.js";
-import { SelectMenu } from "../SelectMenu/select-menu.js";
+import { forwardKeyToListbox, SelectMenu } from "../SelectMenu/select-menu.js";
 import { useIsTouchDevice } from "../../hooks/use-is-touch-device.js";
 const GAP = 4;
 const tagPadding = {
@@ -300,11 +300,10 @@ function NativeCombobox({
     {
       ref: __triggerRef,
       className: cn(
-        fieldWrapperStyles({ mode: "edit", variant, size }),
+        fieldWrapperStyles({ mode: "edit", variant, size, error }),
         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: "var(--field-px)", ...wrap ? { height: "auto" } : void 0 },
@@ -402,6 +401,7 @@ function CustomCombobox({
   // i18n-allow: DS default
   emptyPlaceholder = "選擇…",
   // i18n-allow: DS default
+  emptyText,
   defaultOpen = false,
   onOpenChange,
   __triggerRef,
@@ -477,19 +477,19 @@ function CustomCombobox({
       "aria-describedby": fieldCtx == null ? void 0 : fieldCtx.descriptionId,
       "aria-errormessage": error ? fieldCtx == null ? void 0 : fieldCtx.errorId : void 0,
       className: cn(
-        fieldWrapperStyles({ mode: "edit", variant, size }),
+        fieldWrapperStyles({ mode: "edit", variant, size, error }),
         value.length > 0 && tagPadding[size],
         "relative cursor-pointer",
         wrap && "items-start py-1",
         // 2026-05-06 v13.3 SSOT retire:per-control `open && 'border-primary'` 移除。Field default
-        // 統一處理 — open=灰深(data-state)/ focus=藍(focus-within !important)。改一處全 control 跟動。
-        error && ["border-error hover:border-error-hover", "focus-within:border-error focus-within:hover:border-error"],
+        // 統一處理 — open=灰深(data-state)/ focus=藍;2026-07-04 Q1:error 亦收進 error variant。
         className
       ),
       style: { paddingRight: "var(--field-px)", ...wrap ? { height: "auto" } : void 0 },
       "data-field-mode": "edit",
       "data-error": error ? "" : void 0,
       onKeyDown: (e) => {
+        if (open && forwardKeyToListbox(listboxId, e)) return;
         if (e.key === "Enter" || e.key === " ") {
           if (!open) {
             e.preventDefault();
@@ -580,6 +580,7 @@ function CustomCombobox({
     SelectMenu,
     {
       loading,
+      emptyText,
       options: menuOptions,
       value,
       onValueChange: onChange,