npm - @qijenchen/design-system - Versions diffs - 0.1.0-beta.83 → 0.1.0-beta.85 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (622) hide show

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

@@ -23,7 +23,7 @@ import type { LucideIcon } from 'lucide-react';
  * ── 詳見 chip.spec.md ──
  */
 declare const chipVariants: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
-export interface ChipProps extends React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item> {
+export interface ChipProps extends Omit<React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item>, 'asChild'> {
     /** 左側 icon（LucideIcon），最多一個 */
     startIcon?: LucideIcon;
     /** 右側 badge（通常是計數指示器）*/

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

	@@ -1 +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,oFAkCjB,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;AAwOD,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;CAeX,CAAA;AAEV,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,EAAE,CAAA"}
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,oFAkCjB,CAAA;AAED,MAAM,WAAW,SAKf,SAAQ,IAAI,CAAC,KAAK,CAAC,wBAAwB,CAAC,OAAO,oBAAoB,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IACzF,+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;AAwOD,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;CAeX,CAAA;AAEV,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,EAAE,CAAA"}

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

	@@ -1 +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 text-primary\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 base,底色維持 bg-surface 不變\n // ── pill 風格 canonical 選中規則,跟 SegmentedControl 完全一致(SSOT = semantic.css「選中狀態」段):\n // primary base 同時染文字和線條;底色不改 (不用 primary-subtle)。\n // 2026-07-06 user 拍板:持續選中 hover 階 → base — Ant(pagination/tabs/input focus 全 base)/\n // Atlassian(selected = brand 同顆)/ Material 3(active tab = primary)三家實錘「瞬時弱、持續強」;\n // hover 階專屬瞬時態(hover/預覽),持續選中站 base。\n 'data-[state=on]:border-primary data-[state=on]:text-primary',\n // 選中之上的 hover = 同色相升 hover 階(2026-07-06 user 拍板;Button pressed hover\n // data-[state=on]:hover:text-primary-hover 家族 + Ant active 頁 hover = colorPrimaryHover\n // 同派)。原本靠 CSS 平手 source-order 讓選中「碰巧」贏過未選 hover(靜止無回饋)= 脆弱,\n // 顯式宣告一併解掉。\n 'data-[state=on]:hover:border-primary-hover data-[state=on]:hover: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 // disabled × selected 疊加(2026-07-07 user 拍板統一;M24 state > emphasis:disabled 全滅,\n // 選中的 primary 描邊/染字一併退場——原本只滅字不滅框 = 半滅,Checkbox checked+disabled 全滅同族)\n 'data-[state=on]:disabled:border-border data-[state=on]:disabled:text-fg-disabled',\n 'data-[state=on]:disabled:hover:border-border data-[state=on]: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// ── getElementRef(Radix Slot idiom)──────────────────────────────────────────\n// 讀取 child element 既有 ref 而不觸發 React dev deprecation warning:\n// React ≤18 ref 在 element.ref;React 19 起移到 element.props.ref,錯誤側讀取會 fire warning\n// (以 getter 上的 isReactWarning 標記)。抄 Radix UI Slot 的偵測法:\n// https://github.com/radix-ui/primitives/blob/main/packages/react/slot/src/slot.tsx(getElementRef)\n// react-compose-refs 僅為 transitive dep(非 package.json 直接依賴),不直接 import — 最小 local 實作。\nfunction getElementRef(element: React.ReactElement): React.Ref<HTMLElement> \| undefined {\n // React <=18 dev:props.ref 掛 isReactWarning getter → 真 ref 在 element.ref\n let getter = Object.getOwnPropertyDescriptor(element.props, 'ref')?.get\n let mayWarn = getter && 'isReactWarning' in getter && getter.isReactWarning\n if (mayWarn) return (element as unknown as { ref?: React.Ref<HTMLElement> }).ref\n // React 19 dev:element.ref 掛 isReactWarning getter → 真 ref 在 props.ref\n getter = Object.getOwnPropertyDescriptor(element, 'ref')?.get\n mayWarn = getter && 'isReactWarning' in getter && getter.isReactWarning\n if (mayWarn) return (element.props as { ref?: React.Ref<HTMLElement> }).ref\n // production:兩處擇一\n return (\n (element.props as { ref?: React.Ref<HTMLElement> }).ref ??\n (element as unknown as { ref?: React.Ref<HTMLElement> }).ref ??\n undefined\n )\n}\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 // 2026-07-05 fix(deep-audit A.1b):原 cloneElement 直接以 registerItem 覆寫 child ref,\n // consumer 傳給 Chip 的自有 ref 在 menu layout 會被靜默取代。改 compose — 同時餵\n // registerItem(scrollIntoView 用)與 child 原 ref(對齊 Radix compose-refs idiom)。\n const enhancedItems = items.map((child, i) => {\n const childRef = getElementRef(child)\n return React.cloneElement(\n child as React.ReactElement<{ ref?: React.Ref<HTMLElement> }>,\n {\n ref: (el: HTMLElement \| null) => {\n registerItem(i)(el)\n if (typeof childRef === 'function') childRef(el)\n else if (childRef) (childRef as React.MutableRefObject<HTMLElement \| null>).current = el\n },\n }\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 base,2026-07-06 拍板);cva 無 active 樣式\n tokens: {\n bg: ['bg-surface'],\n fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground', 'text-primary'],\n ring: ['ring-ring'],\n },\n} as const\n\nexport { Chip, ChipGroup, chipVariants }\n"],"names":[],"mappings":"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"}
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 text-primary\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 base,底色維持 bg-surface 不變\n // ── pill 風格 canonical 選中規則,跟 SegmentedControl 完全一致(SSOT = semantic.css「選中狀態」段):\n // primary base 同時染文字和線條;底色不改 (不用 primary-subtle)。\n // 2026-07-06 user 拍板:持續選中 hover 階 → base — Ant(pagination/tabs/input focus 全 base)/\n // Atlassian(selected = brand 同顆)/ Material 3(active tab = primary)三家實錘「瞬時弱、持續強」;\n // hover 階專屬瞬時態(hover/預覽),持續選中站 base。\n 'data-[state=on]:border-primary data-[state=on]:text-primary',\n // 選中之上的 hover = 同色相升 hover 階(2026-07-06 user 拍板;Button pressed hover\n // data-[state=on]:hover:text-primary-hover 家族 + Ant active 頁 hover = colorPrimaryHover\n // 同派)。原本靠 CSS 平手 source-order 讓選中「碰巧」贏過未選 hover(靜止無回饋)= 脆弱,\n // 顯式宣告一併解掉。\n 'data-[state=on]:hover:border-primary-hover data-[state=on]:hover: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 // disabled × selected 疊加(2026-07-07 user 拍板統一;M24 state > emphasis:disabled 全滅,\n // 選中的 primary 描邊/染字一併退場——原本只滅字不滅框 = 半滅,Checkbox checked+disabled 全滅同族)\n 'data-[state=on]:disabled:border-border data-[state=on]:disabled:text-fg-disabled',\n 'data-[state=on]:disabled:hover:border-border data-[state=on]:disabled:hover:text-fg-disabled',\n ]\n)\n\nexport interface ChipProps\n // 2026-07-14 dim-9 修:Omit 'asChild' — chip.spec.md 禁止事項明載「❌ 用 asChild——不支援」,\n // 且內部固定渲染 {icon}{label}{suffix} 多 children 結構,asChild(Radix Slot 要求單一\n // element child)會 runtime throw(CLAUDE.md 失敗記憶「asChild ? Slot : Native」條)。\n // 型別層 Omit 讓誤用在編譯期失敗,對齊 spec-vs-type 一致。\n extends Omit<React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item>, 'asChild'> {\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// ── getElementRef(Radix Slot idiom)──────────────────────────────────────────\n// 讀取 child element 既有 ref 而不觸發 React dev deprecation warning:\n// React ≤18 ref 在 element.ref;React 19 起移到 element.props.ref,錯誤側讀取會 fire warning\n// (以 getter 上的 isReactWarning 標記)。抄 Radix UI Slot 的偵測法:\n// https://github.com/radix-ui/primitives/blob/main/packages/react/slot/src/slot.tsx(getElementRef)\n// react-compose-refs 僅為 transitive dep(非 package.json 直接依賴),不直接 import — 最小 local 實作。\nfunction getElementRef(element: React.ReactElement): React.Ref<HTMLElement> \| undefined {\n // React <=18 dev:props.ref 掛 isReactWarning getter → 真 ref 在 element.ref\n let getter = Object.getOwnPropertyDescriptor(element.props, 'ref')?.get\n let mayWarn = getter && 'isReactWarning' in getter && getter.isReactWarning\n if (mayWarn) return (element as unknown as { ref?: React.Ref<HTMLElement> }).ref\n // React 19 dev:element.ref 掛 isReactWarning getter → 真 ref 在 props.ref\n getter = Object.getOwnPropertyDescriptor(element, 'ref')?.get\n mayWarn = getter && 'isReactWarning' in getter && getter.isReactWarning\n if (mayWarn) return (element.props as { ref?: React.Ref<HTMLElement> }).ref\n // production:兩處擇一\n return (\n (element.props as { ref?: React.Ref<HTMLElement> }).ref ??\n (element as unknown as { ref?: React.Ref<HTMLElement> }).ref ??\n undefined\n )\n}\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 // 2026-07-05 fix(deep-audit A.1b):原 cloneElement 直接以 registerItem 覆寫 child ref,\n // consumer 傳給 Chip 的自有 ref 在 menu layout 會被靜默取代。改 compose — 同時餵\n // registerItem(scrollIntoView 用)與 child 原 ref(對齊 Radix compose-refs idiom)。\n const enhancedItems = items.map((child, i) => {\n const childRef = getElementRef(child)\n return React.cloneElement(\n child as React.ReactElement<{ ref?: React.Ref<HTMLElement> }>,\n {\n ref: (el: HTMLElement \| null) => {\n registerItem(i)(el)\n if (typeof childRef === 'function') childRef(el)\n else if (childRef) (childRef as React.MutableRefObject<HTMLElement \| null>).current = el\n },\n }\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 base,2026-07-06 拍板);cva 無 active 樣式\n tokens: {\n bg: ['bg-surface'],\n fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground', 'text-primary'],\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 CHANGED Viewed

@@ -21,7 +21,9 @@ import * as React from 'react';
  *      同樣規則)。CTA = `isLastStep ? 'Done' : 'Next'`
  *   4. **抑制 CTA 自動 focus,焦點落在 content 容器** — `onOpenAutoFocus` preventDefault
  *      後 focus content 容器本身(非第一個 CTA),避免使用者還在讀 body 時按 Enter 誤推進;
- *      Tab 第一下即達 content 內第一個 CTA。焦點不可停在 trigger:non-modal Popover 下
+ *      按 Tab 才移到 content 內按鈕:**單步無 header** 時第一個 tabbable 即推進 CTA;**有 header
+ *      (kind / headerTitle 會渲 PopoverHeader 右上 Close X)或多步** 時 DOM 順序上 Close X /
+ *      Previous / Skip 在推進 CTA 之前,需多按幾下 Tab。焦點不可停在 trigger:non-modal Popover 下
  *      焦點在 DismissableLayer 外按 Tab 會觸發 focus-outside dismiss 誤關閉
  *      (2026-07-05 D4;對齊 dialog.tsx handleOpenAutoFocus `?? content` fallback,見 spec「A11y 預設」)。
  *
@@ -39,8 +41,13 @@ export interface CoachmarkProps extends Omit<React.HTMLAttributes<HTMLDivElement
     /** 預設打開(uncontrolled initial state)— 2026-05-15 audit Dim 26 V1 fix per user verbatim「A:1」approval */
     defaultOpen?: boolean;
     onOpenChange?: (open: boolean) => void;
-    /** 觸發 anchor 元素。通常傳 trigger element;Coachmark 浮層會定位於此 */
-    children: React.ReactNode;
+    /**
+     * 觸發 anchor 元素——**必為單一 React element**(內部走 `<PopoverTrigger asChild>` =
+     * Radix Slot 契約;傳 string / fragment / 多元素會 `React.Children.only` runtime 炸,
+     * 見 CLAUDE.md 失敗記憶索引「asChild + Slot」條)。與 Popover / Tooltip / HoverCard
+     * 同一錨點契約;型別收緊為 ReactElement 讓契約在 compile 期顯現。
+     */
+    children: React.ReactElement;
     /** 頂部 media 區(圖片 / illustration / video 等);不傳則無 media */
     image?: React.ReactNode;
     /**

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

	@@ -1 +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~~;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,uFA2Id,CAAA;AAKD,eAAO,MAAM,aAAa;;;;;;;;;;;CAehB,CAAA;AAEV,OAAO,EAAE,SAAS,EAAE,CAAA"}
1	+ {"version":3,"file":"coachmark.d.ts","sourceRoot":"","sources":["../../../src/components/Coachmark/coachmark.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAe9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;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;;;;;OAKG;IACH,QAAQ,EAAE,KAAK,CAAC,YAAY,CAAA;IAC5B,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,uFA2Id,CAAA;AAKD,eAAO,MAAM,aAAa;;;;;;;;;;;CAehB,CAAA;AAEV,OAAO,EAAE,SAAS,EAAE,CAAA"}

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

	@@ -1 +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. 抑制 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 / 2026-07-05 改消費 Popover 自動接線:PopoverContent(role=dialog)accessible name 三層 —\n // 1. headerTitle → <PopoverTitle> 掛載時由 popover.tsx PopoverTitleContext 自動接 aria-labelledby(免手動)\n // 2. 無 header 但有 body 主 title(<h3> 非 PopoverTitle,自動接線接不到)→ 仍手動接 aria-labelledby\n // 3. 皆無 → aria-label fallback\n const bodyTitleId = React.useId()\n const bodyTitleLabelledBy = !headerTitle && title ? bodyTitleId : 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={bodyTitleLabelledBy}\n aria-label={headerTitle \|\| title ? 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>{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 ? bodyTitleId : 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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"}
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. 抑制 CTA 自動 focus,焦點落在 content 容器 — `onOpenAutoFocus` preventDefault\n * 後 focus content 容器本身(非第一個 CTA),避免使用者還在讀 body 時按 Enter 誤推進;\n * 按 Tab 才移到 content 內按鈕:單步無 header 時第一個 tabbable 即推進 CTA;*有 header\n (kind / headerTitle 會渲 PopoverHeader 右上 Close X)或多步** 時 DOM 順序上 Close X /\n * Previous / Skip 在推進 CTA 之前,需多按幾下 Tab。焦點不可停在 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 /\n 觸發 anchor 元素——必為單一 React element(內部走 `<PopoverTrigger asChild>` =\n * Radix Slot 契約;傳 string / fragment / 多元素會 `React.Children.only` runtime 炸,\n * 見 CLAUDE.md 失敗記憶索引「asChild + Slot」條)。與 Popover / Tooltip / HoverCard\n * 同一錨點契約;型別收緊為 ReactElement 讓契約在 compile 期顯現。\n /\n children: React.ReactElement\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 / 2026-07-05 改消費 Popover 自動接線:PopoverContent(role=dialog)accessible name 三層 —\n // 1. headerTitle → <PopoverTitle> 掛載時由 popover.tsx PopoverTitleContext 自動接 aria-labelledby(免手動)\n // 2. 無 header 但有 body 主 title(<h3> 非 PopoverTitle,自動接線接不到)→ 仍手動接 aria-labelledby\n // 3. 皆無 → aria-label fallback\n const bodyTitleId = React.useId()\n const bodyTitleLabelledBy = !headerTitle && title ? bodyTitleId : 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={bodyTitleLabelledBy}\n aria-label={headerTitle \|\| title ? 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>{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 ? bodyTitleId : 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 CHANGED Viewed

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type { FieldMode, FieldVariant } from '../../components/Field/field-types';
+import type { FieldMode, FieldVariant, FieldWidth } from '../../components/Field/field-types';
 import { type SelectMenuOption } from '../../components/SelectMenu/select-menu';
 /**
  * Combobox option schema(2026-05-10 post-Issue-4 audit unify):**explicit extends
@@ -26,6 +26,10 @@ export interface ComboboxProps {
     mode?: FieldMode;
     /** Field chrome variant. Default = context.variant ?? 'default'. Per-prop override. */
     variant?: FieldVariant;
+    /** 寬度軸 — `fill` 填滿容器(default)/ `hug` 依內容收縮:value 寬 + slot 元素寬 + gap +
+     *  field 內 padding;chrome 與互動不變。場景 = detail pane inline metadata。
+     *  SSOT → field-controls.spec.md「寬度軸(width: fill / hug)」。 */
+    width?: FieldWidth;
     error?: boolean;
     size?: 'sm' | 'md' | 'lg';
     options: ComboboxOption[];

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

	@@ -1 +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,EAAwD,KAAK,gBAAgB,EAAE,MAAM,mDAAmD,CAAA;AAc/I;;;;;;;;;;;;;;;;;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;~~AAkXD~~,QAAA,MAAM,QAAQ,sFAab,CAAA;AAKD,eAAO,MAAM,YAAY;;;;;;;;;;;CAgBf,CAAA;AAEV,OAAO,EAAE,QAAQ,EAAE,CAAA"}
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,EAAwB,UAAU,EAAE,MAAM,8CAA8C,CAAA;AAM7H,OAAO,EAAwD,KAAK,gBAAgB,EAAE,MAAM,mDAAmD,CAAA;AAc/I;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAe,SAAQ,gBAAgB;CAEvD;AAgLD,KAAK,qBAAqB,GAAG,QAAQ,GAAG,KAAK,CAAA;AA+I7C,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,uFAAuF;IACvF,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB;;iEAE6D;IAC7D,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,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;AA+YD,QAAA,MAAM,QAAQ,sFAab,CAAA;AAKD,eAAO,MAAM,YAAY;;;;;;;;;;;CAgBf,CAAA;AAEV,OAAO,EAAE,QAAQ,EAAE,CAAA"}

package/dist/components/Combobox/combobox.js CHANGED Viewed

@@ -2,8 +2,8 @@ import { jsx, jsxs, Fragment } from "react/jsx-runtime";
 import * as React from "react";
 import { X, ChevronDown } from "lucide-react";
 import { cn } from "../../lib/utils.js";
-import { nakedCellRowModeAlign, fieldWrapperStyles, EMPTY_DISPLAY, fieldDisplayTextClass } from "../Field/field-wrapper.js";
-import { useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldVariant, useResolvedFieldMode, useFieldContext, useResolvedFieldInvalid } from "../Field/field-context.js";
+import { nakedCellRowModeAlign, fieldWrapperStyles, fieldDisplayTextClass } from "../Field/field-wrapper.js";
+import { useResolvedFieldSize, useFieldContext, useResolvedFieldDisabled, useResolvedFieldVariant, useResolvedFieldMode, useResolvedFieldInvalid, useFieldEmptyDisplay, fieldEmptyColorClass } from "../Field/field-context.js";
 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";
@@ -153,8 +153,9 @@ function ComboboxTagStack({
   containerRef: externalRef,
   disabled = false
 }) {
+  const emptyDisplay = useFieldEmptyDisplay();
   const ownRef = React.useRef(null);
-  if (!value || value.length === 0) return /* @__PURE__ */ jsx("span", { className: "text-fg-muted", children: EMPTY_DISPLAY });
+  if (!value || value.length === 0) return /* @__PURE__ */ jsx("span", { className: fieldEmptyColorClass(disabled ? "disabled" : "display"), children: emptyDisplay });
   const items = value.map((v) => {
     var _a;
     return { value: v, label: ((_a = options == null ? void 0 : options.find((o) => o.value === v)) == null ? void 0 : _a.label) ?? v };
@@ -177,6 +178,7 @@ const getIconSize = (size) => ICON_SIZE[size];
 function ReadonlyMultiSelect({
   mode,
   variant: variantProp,
+  width,
   size,
   options,
   value,
@@ -185,6 +187,7 @@ function ReadonlyMultiSelect({
   showDisplayEndIcon = false
 }) {
   const resolvedMode = mode ?? "readonly";
+  const emptyDisplay = useFieldEmptyDisplay();
   const variant = variantProp ?? "default";
   const sz = size ?? "md";
   const iconSize = sz === "lg" ? 20 : 16;
@@ -193,16 +196,16 @@ function ReadonlyMultiSelect({
   const hasTags = ((value == null ? void 0 : value.length) ?? 0) > 0;
   if (resolvedMode === "display") {
     if (!showDisplayEndIcon) {
-      if (!hasTags) return /* @__PURE__ */ jsx("span", { className: cn(fieldDisplayTextClass(sz), "text-fg-muted", className), children: EMPTY_DISPLAY });
+      if (!hasTags) return /* @__PURE__ */ jsx("span", { className: cn(fieldDisplayTextClass(sz), fieldEmptyColorClass(resolvedMode), className), children: emptyDisplay });
       return /* @__PURE__ */ jsx(ComboboxTagStack, { value, options, tagSize: sz, wrap });
     }
     return /* @__PURE__ */ jsxs(
       "div",
       {
-        className: cn(fieldWrapperStyles({ mode: "display", variant, size: sz }), hasTags && tagPadding[sz], className),
+        className: cn(fieldWrapperStyles({ mode: "display", variant, width, size: sz }), hasTags && tagPadding[sz], className),
         "data-field-mode": "display",
         children: [
-          hasTags ? /* @__PURE__ */ jsx(ComboboxTagStack, { value, options, tagSize: sz, wrap }) : /* @__PURE__ */ jsx("span", { className: cn("flex-1 min-w-0", "text-fg-muted"), children: EMPTY_DISPLAY }),
+          hasTags ? /* @__PURE__ */ jsx(ComboboxTagStack, { value, options, tagSize: sz, wrap }) : /* @__PURE__ */ jsx("span", { className: cn("flex-1 min-w-0", fieldEmptyColorClass(resolvedMode)), children: emptyDisplay }),
           /* @__PURE__ */ jsx(ItemSuffix, { className: "pointer-events-none", children: /* @__PURE__ */ jsx(ChevronDown, { size: iconSize, className: "shrink-0 text-fg-muted", "aria-hidden": true }) })
         ]
       }
@@ -213,7 +216,7 @@ function ReadonlyMultiSelect({
     {
       ref: containerRef,
       className: cn(
-        fieldWrapperStyles({ mode: resolvedMode, variant, size: sz }),
+        fieldWrapperStyles({ mode: resolvedMode, variant, width, size: sz }),
         hasTags && tagPadding[sz],
         // 2026-05-18 #6A Round 1 Step 1/4(per user 拍板「決策6選a」+ codex M31 Step 5 verdict cite combobox.tsx:451):
         // readonly/disabled path 對齊 L293 display wrapper 已 ship 的 overflow-hidden fix。
@@ -237,7 +240,7 @@ function ReadonlyMultiSelect({
             containerRef,
             disabled: resolvedMode === "disabled"
           }
-        ) : /* @__PURE__ */ jsx("span", { className: "text-fg-muted", children: EMPTY_DISPLAY }),
+        ) : /* @__PURE__ */ jsx("span", { className: fieldEmptyColorClass(resolvedMode), children: emptyDisplay }),
         (variant === "naked" ? !!showDisplayEndIcon : resolvedMode === "disabled") && /* @__PURE__ */ jsx(ItemSuffix, { className: cn("pointer-events-none", wrap && "self-start"), style: wrap ? { height: tagHeight } : void 0, children: /* @__PURE__ */ jsx(ChevronDown, { size: iconSize, className: cn("shrink-0", resolvedMode === "disabled" ? "text-fg-disabled" : "text-fg-muted"), "aria-hidden": true }) })
       ]
     }
@@ -246,6 +249,7 @@ function ReadonlyMultiSelect({
 function NativeCombobox({
   mode,
   variant: variantProp,
+  width,
   error = false,
   size = "md",
   options,
@@ -257,8 +261,10 @@ function NativeCombobox({
   wrap = false,
   clearable = false,
   showDisplayEndIcon = false,
-  __triggerRef
+  __triggerRef,
+  "aria-label": ariaLabel
 }) {
+  const fieldCtx = useFieldContext();
   const disabled = useResolvedFieldDisabled(disabledProp);
   const variant = useResolvedFieldVariant(variantProp);
   const resolvedMode = useResolvedFieldMode({ mode, disabled });
@@ -271,7 +277,7 @@ function NativeCombobox({
   const selectRef = React.useRef(null);
   const tagAreaRef = React.useRef(null);
   if (resolvedMode !== "edit") {
-    return /* @__PURE__ */ jsx(ReadonlyMultiSelect, { mode: resolvedMode, variant, size, options, value, wrap, className, showDisplayEndIcon });
+    return /* @__PURE__ */ jsx(ReadonlyMultiSelect, { mode: resolvedMode, variant, width, size, options, value, wrap, className, showDisplayEndIcon });
   }
   const items = value.map((v) => {
     var _a;
@@ -285,6 +291,13 @@ function NativeCombobox({
       ref: selectRef,
       value: "",
       onChange: (e) => handleAdd(e.target.value),
+      id: fieldCtx == null ? void 0 : fieldCtx.id,
+      "aria-label": ariaLabel,
+      "aria-labelledby": ariaLabel ? void 0 : fieldCtx == null ? void 0 : fieldCtx.labelId,
+      "aria-invalid": error || void 0,
+      "aria-required": (fieldCtx == null ? void 0 : fieldCtx.required) || void 0,
+      "aria-describedby": fieldCtx == null ? void 0 : fieldCtx.descriptionId,
+      "aria-errormessage": error ? fieldCtx == null ? void 0 : fieldCtx.errorId : void 0,
       className: cn(
         "bg-transparent outline-none border-none p-0 text-[inherit] font-[inherit] leading-[inherit] text-fg-muted cursor-pointer appearance-none",
         value.length > 0 ? "absolute inset-0 w-full h-full opacity-0 z-0 cursor-pointer" : "relative z-10 flex-1 min-w-20"
@@ -300,7 +313,7 @@ function NativeCombobox({
     {
       ref: __triggerRef,
       className: cn(
-        fieldWrapperStyles({ mode: "edit", variant, size, error }),
+        fieldWrapperStyles({ mode: "edit", variant, width, size, error }),
         value.length > 0 && tagPadding[size],
         "relative",
         wrap && "items-start py-1",
@@ -382,6 +395,7 @@ function NativeCombobox({
 function CustomCombobox({
   mode,
   variant: variantProp,
+  width,
   error: errorProp = false,
   size = "md",
   options,
@@ -459,7 +473,7 @@ function CustomCombobox({
     [filteredOptions]
   );
   if (resolvedMode !== "edit") {
-    return /* @__PURE__ */ jsx(ReadonlyMultiSelect, { mode: resolvedMode, variant, size, options, value, wrap, className, showDisplayEndIcon });
+    return /* @__PURE__ */ jsx(ReadonlyMultiSelect, { mode: resolvedMode, variant, width, size, options, value, wrap, className, showDisplayEndIcon });
   }
   const chevronEl = /* @__PURE__ */ jsx(ChevronDown, { size: iconSize, className: cn("shrink-0 text-fg-muted transition-transform", open && "rotate-180"), "aria-hidden": true });
   const trigger = /* @__PURE__ */ jsxs(
@@ -473,12 +487,13 @@ function CustomCombobox({
       "aria-controls": listboxId,
       tabIndex: 0,
       "aria-label": ariaLabel,
+      "aria-labelledby": ariaLabel ? void 0 : fieldCtx == null ? void 0 : fieldCtx.labelId,
       "aria-invalid": error || void 0,
       "aria-required": (fieldCtx == null ? void 0 : fieldCtx.required) || void 0,
       "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, error }),
+        fieldWrapperStyles({ mode: "edit", variant, width, size, error }),
         value.length > 0 && tagPadding[size],
         "relative cursor-pointer",
         wrap && "items-start py-1",
@@ -490,6 +505,8 @@ function CustomCombobox({
       "data-field-mode": "edit",
       "data-error": error ? "" : void 0,
       onKeyDown: (e) => {
+        var _a, _b;
+        if ((e.key === "Enter" || e.key === " ") && e.target !== e.currentTarget && ((_b = (_a = e.target).closest) == null ? void 0 : _b.call(_a, 'button, a, [role="button"]'))) return;
         if (open && forwardKeyToListbox(listboxId, e)) return;
         if (e.key === "Enter" || e.key === " ") {
           if (!open) {