@qijenchen/design-system 0.1.0-beta.13 → 0.1.0-beta.131

package/dist/components/Chip/chip.js

@@ -1,4 +1,4 @@
-import { jsxs, jsx } from "react/jsx-runtime";
+import { jsx, jsxs, Fragment } from "react/jsx-runtime";
 import * as React from "react";
 import * as ToggleGroupPrimitive from "@radix-ui/react-toggle-group";
 import { cva } from "class-variance-authority";
@@ -19,35 +19,62 @@ const chipVariants = cva(
     "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1",
     // hover（未選）：border 加深一階 + 文字轉深，對齊 Input / SegmentedControl hover
     "hover:border-border-hover hover:text-foreground",
-    // selected: 文字 + 邊框都用 primary-hover,底色維持 bg-surface 不變
-    //   ── pill 風格 canonical 選中規則,跟 SegmentedControl 完全一致:
-    //      primary-hover 同時染文字和線條;底色不改 (不用 primary-subtle)。
-    "data-[state=on]:border-primary-hover data-[state=on]:text-primary-hover",
+    // selected: 文字 + 邊框都用 primary base,底色維持 bg-surface 不變
+    //   ── pill 風格 canonical 選中規則,跟 SegmentedControl 完全一致(SSOT = semantic.css「選中狀態」段):
+    //      primary base 同時染文字和線條;底色不改 (不用 primary-subtle)。
+    //   2026-07-06 user 拍板:持續選中 hover 階 → base — Ant(pagination/tabs/input focus 全 base)/
+    //   Atlassian(selected = brand 同顆)/ Material 3(active tab = primary)三家實錘「瞬時弱、持續強」;
+    //   hover 階專屬瞬時態(hover/預覽),持續選中站 base。
+    "data-[state=on]:border-primary data-[state=on]:text-primary",
+    // 選中之上的 hover = 同色相升 hover 階(2026-07-06 user 拍板;Button pressed hover
+    // data-[state=on]:hover:text-primary-hover 家族 + Ant active 頁 hover = colorPrimaryHover
+    // 同派)。原本靠 CSS 平手 source-order 讓選中「碰巧」贏過未選 hover(靜止無回饋)= 脆弱,
+    // 顯式宣告一併解掉。
+    "data-[state=on]:hover:border-primary-hover data-[state=on]:hover:text-primary-hover",
     // disabled：cursor-not-allowed + 鎖 hover 不變色
     // 不用 pointer-events-none（否則 cursor-not-allowed 不會顯示）
     "disabled:cursor-not-allowed disabled:text-fg-disabled",
-    "disabled:hover:border-border disabled:hover:text-fg-disabled"
+    "disabled:hover:border-border disabled:hover:text-fg-disabled",
+    // disabled × selected 疊加(2026-07-07 user 拍板統一;M24 state > emphasis:disabled 全滅,
+    // 選中的 primary 描邊/染字一併退場——原本只滅字不滅框 = 半滅,Checkbox checked+disabled 全滅同族)
+    "data-[state=on]:disabled:border-border data-[state=on]:disabled:text-fg-disabled",
+    "data-[state=on]:disabled:hover:border-border data-[state=on]:disabled:hover:text-fg-disabled"
   ]
 );
-const Chip = React.forwardRef(({ className, startIcon: StartIcon, badge, endIcon: EndIcon, children, ...props }, ref) => {
-  const hasSuffix = badge != null || EndIcon !== void 0;
-  return /* @__PURE__ */ jsxs(
-    ToggleGroupPrimitive.Item,
-    {
-      ref,
-      className: cn(chipVariants(), className),
-      ...props,
-      children: [
-        StartIcon && /* @__PURE__ */ jsx(StartIcon, { size: 16, "aria-hidden": true }),
-        children != null && /* @__PURE__ */ jsx("span", { className: "px-1", children }),
-        hasSuffix && /* @__PURE__ */ jsxs("span", { className: "inline-flex items-center gap-1", children: [
-          badge,
-          EndIcon && /* @__PURE__ */ jsx(EndIcon, { size: 16, "aria-hidden": true })
-        ] })
-      ]
+const Chip = React.forwardRef(
+  ({ className, startIcon: StartIcon, badge, endIcon: EndIcon, children, variant, ...props }, ref) => {
+    const hasSuffix = badge != null || EndIcon !== void 0;
+    const inner = /* @__PURE__ */ jsxs(Fragment, { children: [
+      StartIcon && /* @__PURE__ */ jsx(StartIcon, { size: 16, "aria-hidden": true }),
+      children != null && /* @__PURE__ */ jsx("span", { className: "px-1", children }),
+      hasSuffix && /* @__PURE__ */ jsxs("span", { className: "inline-flex items-center gap-1", children: [
+        badge,
+        EndIcon && /* @__PURE__ */ jsx(EndIcon, { size: 16, "aria-hidden": true })
+      ] })
+    ] });
+    if (variant === "assist") {
+      return /* @__PURE__ */ jsx(
+        "button",
+        {
+          ref,
+          type: "button",
+          className: cn(chipVariants(), className),
+          ...props,
+          children: inner
+        }
+      );
     }
-  );
-});
+    return /* @__PURE__ */ jsx(
+      ToggleGroupPrimitive.Item,
+      {
+        ref,
+        className: cn(chipVariants(), className),
+        ...props,
+        children: inner
+      }
+    );
+  }
+);
 Chip.displayName = "Chip";
 const ChipGroup = React.forwardRef(
   ({ layout = "wrap", className, children, ...props }, ref) => {
@@ -101,6 +128,16 @@ const ScrollChipGroup = React.forwardRef(({ className, children, ...props }, ref
   ] });
 });
 ScrollChipGroup.displayName = "ScrollChipGroup";
+function getElementRef(element) {
+  var _a, _b;
+  let getter = (_a = Object.getOwnPropertyDescriptor(element.props, "ref")) == null ? void 0 : _a.get;
+  let mayWarn = getter && "isReactWarning" in getter && getter.isReactWarning;
+  if (mayWarn) return element.ref;
+  getter = (_b = Object.getOwnPropertyDescriptor(element, "ref")) == null ? void 0 : _b.get;
+  mayWarn = getter && "isReactWarning" in getter && getter.isReactWarning;
+  if (mayWarn) return element.props.ref;
+  return element.props.ref ?? element.ref ?? void 0;
+}
 const MenuChipGroup = React.forwardRef(({ className, children, ...props }, ref) => {
   const { scrollRef, atStart, atEnd, canScroll } = useScrollEdges();
   const itemRefs = React.useRef(/* @__PURE__ */ new Map());
@@ -153,12 +190,19 @@ const MenuChipGroup = React.forwardRef(({ className, children, ...props }, ref)
     },
     [groupType, groupValue, groupOnValueChange]
   );
-  const enhancedItems = items.map(
-    (child, i) => React.cloneElement(
+  const enhancedItems = items.map((child, i) => {
+    const childRef = getElementRef(child);
+    return React.cloneElement(
       child,
-      { ref: registerItem(i) }
-    )
-  );
+      {
+        ref: (el) => {
+          registerItem(i)(el);
+          if (typeof childRef === "function") childRef(el);
+          else if (childRef) childRef.current = el;
+        }
+      }
+    );
+  });
   return /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2", children: [
     /* @__PURE__ */ jsx(
       "div",
@@ -206,12 +250,18 @@ MenuChipGroup.displayName = "MenuChipGroup";
 const chipMeta = {
   component: "Chip",
   family: 3,
+  // 2026-07-04 audit 填 Phase 2:Chip 單一視覺無 variant 軸(variants 留空為 intentional,非漏填)
+  // 2026-09-02:filter/assist 為結構分支(行為換 plain button,視覺同款)— 非視覺 variant 軸,不入此表
   variants: {},
-  sizes: {},
-  states: ["default", "hover", "active", "focus-visible", "disabled"],
+  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 base,2026-07-06 拍板);cva 無 active 樣式
   tokens: {
-    bg: ["bg-primary-subtle", "bg-surface"],
-    fg: ["text-fg-disabled", "text-fg-secondary", "text-foreground"],
+    bg: ["bg-surface"],
+    fg: ["text-fg-disabled", "text-fg-secondary", "text-foreground", "text-primary"],
     ring: ["ring-ring"]
   }
 };

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-foreground\n *   hover     border-border-hover（對齊 Input / SegmentedControl）\n *   selected  bg-primary-subtle 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', 'active', 'focus-visible', 'disabled'],\n  tokens: {\n    bg: ['bg-primary-subtle', 'bg-surface'],\n    fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground'],\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 Chips(filter + assist 兩分支)\n *\n * filter(預設):基於 Radix ToggleGroup,多/單選 pill;必須在 <ChipGroup> 內使用。\n * assist(2026-09-02 加,AgentPanel 附件拍板消費):M3 assist chip 分支 —— 按鈕語意、\n * 無 toggle、無 selected 態(https://m3.material.io/components/chips/guidelines「Assist chips」);\n * 渲染 plain button,可獨立使用(不需 ChipGroup)。兩分支視覺同款(單一 cva;\n * assist 無 data-state 故 selected 樣式天然不生效),差異=結構分支(conditional rendering,\n * 非 cva variant — 對齊 cva-patterns「結構 variant 用 conditional rendering」)。\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\ninterface ChipSlotProps {\n  /** 左側 icon（LucideIcon），最多一個 */\n  startIcon?: LucideIcon\n  /** 右側 badge（通常是計數指示器）*/\n  badge?: React.ReactNode\n  /** 右側 icon（少見，通常是 ChevronDown 指示可展開）*/\n  endIcon?: LucideIcon\n}\n\nexport interface ChipFilterProps\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    ChipSlotProps {\n  /** filter(預設):Radix ToggleGroup item,必須在 ChipGroup 內。 */\n  variant?: 'filter'\n}\n\nexport interface ChipAssistProps\n  extends React.ButtonHTMLAttributes<HTMLButtonElement>,\n    ChipSlotProps {\n  /** assist:M3 assist chip — 按鈕語意、無 toggle、無 selected 態;可獨立使用。 */\n  variant: 'assist'\n}\n\nexport type ChipProps = ChipFilterProps | ChipAssistProps\n\nconst Chip = React.forwardRef<HTMLButtonElement, ChipProps>(\n  ({ className, startIcon: StartIcon, badge, endIcon: EndIcon, children, variant, ...props }, ref) => {\n    const hasSuffix = badge != null || EndIcon !== undefined\n    const inner = (\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      </>\n    )\n    // assist 分支:plain button(按鈕語意,無 toggle);selected 樣式因無 data-state 天然不生效。\n    if (variant === 'assist') {\n      return (\n        <button\n          ref={ref}\n          type=\"button\"\n          className={cn(chipVariants(), className)}\n          {...(props as React.ButtonHTMLAttributes<HTMLButtonElement>)}\n        >\n          {inner}\n        </button>\n      )\n    }\n    return (\n      <ToggleGroupPrimitive.Item\n        ref={ref}\n        className={cn(chipVariants(), className)}\n        {...(props as React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item>)}\n      >\n        {inner}\n      </ToggleGroupPrimitive.Item>\n    )\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  // 2026-09-02:filter/assist 為結構分支(行為換 plain button,視覺同款)— 非視覺 variant 軸,不入此表\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/Chip/index.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/Chip/index.ts"],"names":[],"mappings":"AAIA,cAAc,QAAQ,CAAA"}

package/dist/components/Chip/index.js

@@ -0,0 +1,8 @@
+import { Chip, ChipGroup, chipMeta, chipVariants } from "./chip.js";
+export {
+  Chip,
+  ChipGroup,
+  chipMeta,
+  chipVariants
+};
+//# sourceMappingURL=index.js.map

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

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

package/dist/components/CircularProgress/circular-progress.d.ts

@@ -8,7 +8,6 @@ export interface CircularProgressProps extends React.HTMLAttributes<HTMLSpanElem
     value?: number;
     /** 直徑(px)。預設 24,建議 ≤ 64。 */
     size?: number;
-    /** 狀態色(lifecycle,與 ProgressBar 同契約)。 */
     /**
      * 視覺 label(inline 顯示於右側)。
      * - font-size 繼承 parent(不設 text-size class,CSS inherit)
@@ -29,10 +28,10 @@ export declare const circularProgressMeta: {
     readonly family: null;
     readonly variants: {};
     readonly sizes: {};
-    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly states: readonly ["default"];
     readonly tokens: {
         readonly bg: readonly [];
-        readonly fg: readonly ["text-fg-muted", "text-foreground", "text-primary"];
+        readonly fg: readonly ["text-fg-muted", "text-foreground", "text-info"];
         readonly ring: readonly [];
     };
 };

package/dist/components/CircularProgress/circular-progress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"circular-progress.d.ts","sourceRoot":"","sources":["../../../src/components/CircularProgress/circular-progress.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AA4C9B,MAAM,WAAW,qBAAsB,SAAQ,KAAK,CAAC,cAAc,CAAC,eAAe,CAAC;IAClF;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4BAA4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,wCAAwC;IACxC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC,SAAS,CAAA;CAClC;AAGD,QAAA,MAAM,gBAAgB,+FA8GrB,CAAA;AAKD,eAAO,MAAM,oBAAoB;;;;;;;;;;;CAevB,CAAA;AAEV,OAAO,EAAE,gBAAgB,EAAE,CAAA"}
+{"version":3,"file":"circular-progress.d.ts","sourceRoot":"","sources":["../../../src/components/CircularProgress/circular-progress.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AA4C9B,MAAM,WAAW,qBAAsB,SAAQ,KAAK,CAAC,cAAc,CAAC,eAAe,CAAC;IAClF;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4BAA4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC,SAAS,CAAA;CAClC;AAGD,QAAA,MAAM,gBAAgB,+FA8GrB,CAAA;AAKD,eAAO,MAAM,oBAAoB;;;;;;;;;;;CAevB,CAAA;AAEV,OAAO,EAAE,gBAAgB,EAAE,CAAA"}

package/dist/components/CircularProgress/circular-progress.js

@@ -50,7 +50,7 @@ const CircularProgress = React.forwardRef(
         className: cn(
           // align-middle:inline context 內讓 SVG 對齊 adjacent text 的 x-height 中線
           //(不加會按 baseline 對齊,在 inline-flex cell 裡視覺下沉 1-2px 看起來歪)
-          "inline-flex shrink-0 align-middle text-primary",
+          "inline-flex shrink-0 align-middle text-info",
           // motion-reduce:Material 流派 — prefers-reduced-motion 時不停止旋轉(loading 仍需可見回饋),
           // 而是放慢到 3s/cycle(預設 1s),保留資訊不刺激前庭。
           !isDeterminate && "animate-spin motion-reduce:[animation-duration:3s]",
@@ -83,7 +83,7 @@ const CircularProgress = React.forwardRef(
               strokeDashoffset: dashOffset,
               strokeLinecap: "round",
               transform: `rotate(-90 ${size / 2} ${size / 2})`,
-              className: isDeterminate ? "transition-[stroke-dashoffset] duration-300" : void 0
+              className: isDeterminate ? "transition-[stroke-dashoffset] duration-300 motion-reduce:duration-0" : void 0
             }
           )
         ] })
@@ -104,10 +104,11 @@ const circularProgressMeta = {
   // non-family composite / overlay / layout
   variants: {},
   sizes: {},
-  states: ["default", "hover", "active", "focus-visible", "disabled"],
+  states: ["default"],
+  // 無 hover / focus / active(spec);disabled 屬 consumer host(spec「邊界案例」)
   tokens: {
     bg: [],
-    fg: ["text-fg-muted", "text-foreground", "text-primary"],
+    fg: ["text-fg-muted", "text-foreground", "text-info"],
     ring: []
   }
 };

package/dist/components/CircularProgress/circular-progress.js.map

@@ -1 +1 @@
-{"version":3,"file":"circular-progress.js","sources":["../../../src/components/CircularProgress/circular-progress.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'\n\n/**\n * CircularProgress — 圓形進度指示(determinate + indeterminate 雙模式)\n *\n * 世界級對照:Material `CircularProgress` / Chakra `CircularProgress` — 同元件管\n * determinate(有 `value`)+ indeterminate(無 `value`)兩態。本 DS 採此流派作為\n * circular progress 的 SSOT,`Spinner` 名稱廢除(遷至本元件)。\n *\n * ── 姊妹元件 ──\n * `ProgressBar`       = linear determinate(大區塊、頁面級、表單步驟、上傳 bar)\n * `CircularProgress`  = circular 兩態(本元件,inline 小空間 / Button loading / Field loading)\n *\n * ── API ──\n * value:     undefined → indeterminate(旋轉 partial arc,Spinner 樣式)\n *            number 0-100 → determinate(固定 arc + track)\n * size:      自由 px(預設 24,≤ 64 建議)— 跟 Avatar / Lucide icon 同策略\n * label:     可選 inline label,font-size inherit parent,color text-fg-muted\n * affix:     (determinate only)'value' | ReactNode\n *\n * ── 視覺 ──\n * SVG 雙圓:底 track(`var(--secondary)`)+ 進度 arc(`text-primary`,不隨狀態變色)。\n * stroke-linecap round,rotate -90deg。\n * Indeterminate mode:arc 固定 25%,外層 `animate-spin` 旋轉,視覺同 Spinner。\n *\n * ── 不設 status prop(決策 2026-04-20)──\n * 世界級沒有「success / error CircularProgress」的穩態呈現——完成 / 失敗的語義應由\n * consumer 在業務邏輯上**替換 CircularProgress 為實際內容**(status icon + label、\n * 成功的結果、錯誤訊息等),而非讓 CircularProgress 變色 + 加 check icon。這種「綠底\n * 空心 circle + check icon 並排」是 DS 典型 over-designing 的 anti-pattern(參考:\n * Material / Chakra / Ant / Polaris 全部沒有此 variant)。\n *\n * Consumer 端範例:\n *   {uploading ? <CircularProgress /> : done ? <Check /> : error ? <AlertCircle /> : null}\n *\n * ── A11y ──\n * 有 value → role=\"progressbar\" + aria-valuenow/min/max\n * 無 value → role=\"status\"(loading 語義) + aria-label(如傳)或 aria-hidden(否則)\n */\n\n// Indeterminate mode 的 arc 比例(Material 流派:25%-30% 視覺最平衡)\nconst INDETERMINATE_ARC_RATIO = 0.25\n\nexport interface CircularProgressProps extends React.HTMLAttributes<HTMLSpanElement> {\n  /**\n   * 進度 0-100。\n   * - undefined → indeterminate(旋轉 partial arc,Spinner 樣式)\n   * - number → determinate(固定 arc + track)\n   */\n  value?: number\n  /** 直徑(px)。預設 24,建議 ≤ 64。 */\n  size?: number\n  /** 狀態色(lifecycle,與 ProgressBar 同契約)。 */\n  /**\n   * 視覺 label(inline 顯示於右側)。\n   * - font-size 繼承 parent(不設 text-size class,CSS inherit)\n   * - color 鎖 `text-fg-muted`(neutral-7)\n   * - 塞在元件內時預設不用(e.g. Button loading);全頁 / Empty overlay 可用\n   */\n  label?: string\n  /**\n   * 右側 affix(determinate only;indeterminate 忽略)。\n   * - `'value'` → `{value}%` 文字\n   * - ReactNode → 客製(若需顯示「已完成」,consumer 端整個 swap 為 Check icon,不走此 prop)\n   */\n  affix?: 'value' | React.ReactNode\n}\n\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst CircularProgress = React.forwardRef<HTMLSpanElement, CircularProgressProps>(\n  (\n    {\n      value,\n      size = 24,\n      label,\n      affix,\n      className,\n      'aria-label': ariaLabel,\n      ...props\n    },\n    ref,\n  ) => {\n    const isDeterminate = typeof value === 'number'\n    const clampedValue = isDeterminate ? Math.max(0, Math.min(100, value)) : 0\n    const strokeWidth = Math.max(2, Math.round(size / 10))\n    const radius = (size - strokeWidth) / 2\n    const circumference = 2 * Math.PI * radius\n    const dashOffset = isDeterminate\n      ? circumference * (1 - clampedValue / 100)\n      : circumference * (1 - INDETERMINATE_ARC_RATIO)\n\n    const hasLabel = typeof label === 'string' && label.length > 0\n    const hasAriaLabel = typeof ariaLabel === 'string' && ariaLabel.length > 0\n    const shouldAnnounce = hasAriaLabel || hasLabel\n\n    // Affix(determinate only)\n    let affixNode: React.ReactNode = null\n    if (isDeterminate) {\n      if (affix === 'value') {\n        affixNode = (\n          <span className=\"text-caption text-foreground tabular-nums shrink-0\">\n            {Math.round(clampedValue)}%\n          </span>\n        )\n      } else if (\n        React.isValidElement(affix) ||\n        typeof affix === 'string' ||\n        typeof affix === 'number'\n      ) {\n        affixNode = affix\n      }\n    }\n\n    const a11yRole = isDeterminate ? 'progressbar' : shouldAnnounce ? 'status' : undefined\n    const a11yLabel = hasAriaLabel ? ariaLabel : hasLabel ? label : undefined\n    const a11yValueAttrs = isDeterminate\n      ? {\n          'aria-valuenow': Math.round(clampedValue),\n          'aria-valuemin': 0,\n          'aria-valuemax': 100,\n        }\n      : {}\n\n    const graphic = (\n      <span\n        ref={ref}\n        role={a11yRole}\n        aria-label={a11yLabel}\n        aria-hidden={!a11yRole ? true : undefined}\n        {...a11yValueAttrs}\n        className={cn(\n          // align-middle:inline context 內讓 SVG 對齊 adjacent text 的 x-height 中線\n          //(不加會按 baseline 對齊,在 inline-flex cell 裡視覺下沉 1-2px 看起來歪)\n          'inline-flex shrink-0 align-middle text-primary',\n          // motion-reduce:Material 流派 — prefers-reduced-motion 時不停止旋轉(loading 仍需可見回饋),\n          // 而是放慢到 3s/cycle(預設 1s),保留資訊不刺激前庭。\n          !isDeterminate && 'animate-spin motion-reduce:[animation-duration:3s]',\n          className,\n        )}\n        style={{ width: size, height: size }}\n        {...props}\n      >\n        <svg viewBox={`0 0 ${size} ${size}`} width={size} height={size} aria-hidden>\n          <circle\n            cx={size / 2}\n            cy={size / 2}\n            r={radius}\n            fill=\"none\"\n            stroke=\"var(--secondary)\"\n            strokeWidth={strokeWidth}\n          />\n          <circle\n            cx={size / 2}\n            cy={size / 2}\n            r={radius}\n            fill=\"none\"\n            stroke=\"currentColor\"\n            strokeWidth={strokeWidth}\n            strokeDasharray={circumference}\n            strokeDashoffset={dashOffset}\n            strokeLinecap=\"round\"\n            transform={`rotate(-90 ${size / 2} ${size / 2})`}\n            className={isDeterminate ? 'transition-[stroke-dashoffset] duration-300' : undefined}\n          />\n        </svg>\n      </span>\n    )\n\n    // 單純 graphic(無 label / affix)\n    if (!hasLabel && !affixNode) return graphic\n\n    return (\n      <span className={cn('inline-flex items-center', (hasLabel || affixNode) && 'gap-2')}>\n        {graphic}\n        {hasLabel && <span className=\"text-fg-muted\">{label}</span>}\n        {affixNode}\n      </span>\n    )\n  },\n)\nCircularProgress.displayName = 'CircularProgress'\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 circularProgressMeta = {\n  component: 'CircularProgress',\n  family: null, // non-family composite / overlay / layout\n  variants: {\n\n  },\n  sizes: {\n\n  },\n  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],\n  tokens: {\n    bg: [],\n    fg: ['text-fg-muted', 'text-foreground', 'text-primary'],\n    ring: [],\n  },\n} as const\n\nexport { CircularProgress }\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"circular-progress.js","sources":["../../../src/components/CircularProgress/circular-progress.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'\n\n/**\n * CircularProgress — 圓形進度指示(determinate + indeterminate 雙模式)\n *\n * 世界級對照:Material `CircularProgress` / Chakra `CircularProgress` — 同元件管\n * determinate(有 `value`)+ indeterminate(無 `value`)兩態。本 DS 採此流派作為\n * circular progress 的 SSOT,`Spinner` 名稱廢除(遷至本元件)。\n *\n * ── 姊妹元件 ──\n * `ProgressBar`       = linear determinate(大區塊、頁面級、表單步驟、上傳 bar)\n * `CircularProgress`  = circular 兩態(本元件,inline 小空間 / Button loading / Field loading)\n *\n * ── API ──\n * value:     undefined → indeterminate(旋轉 partial arc,Spinner 樣式)\n *            number 0-100 → determinate(固定 arc + track)\n * size:      自由 px(預設 24,≤ 64 建議)— 跟 Avatar / Lucide icon 同策略\n * label:     可選 inline label,font-size inherit parent,color text-fg-muted\n * affix:     (determinate only)'value' | ReactNode\n *\n * ── 視覺 ──\n * SVG 雙圓:底 track(`var(--secondary)`)+ 進度 arc(`text-info`,status 進度色,不隨狀態變色)。\n * stroke-linecap round,rotate -90deg。\n * Indeterminate mode:arc 固定 25%,外層 `animate-spin` 旋轉,視覺同 Spinner。\n *\n * ── 不設 status prop(決策 2026-04-20)──\n * 世界級沒有「success / error CircularProgress」的穩態呈現——完成 / 失敗的語義應由\n * consumer 在業務邏輯上**替換 CircularProgress 為實際內容**(status icon + label、\n * 成功的結果、錯誤訊息等),而非讓 CircularProgress 變色 + 加 check icon。這種「綠底\n * 空心 circle + check icon 並排」是 DS 典型 over-designing 的 anti-pattern(參考:\n * Material / Chakra / Ant / Polaris 全部沒有此 variant)。\n *\n * Consumer 端範例:\n *   {uploading ? <CircularProgress /> : done ? <Check /> : error ? <AlertCircle /> : null}\n *\n * ── A11y ──\n * 有 value → role=\"progressbar\" + aria-valuenow/min/max\n * 無 value → role=\"status\"(loading 語義) + aria-label(如傳)或 aria-hidden(否則)\n */\n\n// Indeterminate mode 的 arc 比例(Material 流派:25%-30% 視覺最平衡)\nconst INDETERMINATE_ARC_RATIO = 0.25\n\nexport interface CircularProgressProps extends React.HTMLAttributes<HTMLSpanElement> {\n  /**\n   * 進度 0-100。\n   * - undefined → indeterminate(旋轉 partial arc,Spinner 樣式)\n   * - number → determinate(固定 arc + track)\n   */\n  value?: number\n  /** 直徑(px)。預設 24,建議 ≤ 64。 */\n  size?: number\n  /**\n   * 視覺 label(inline 顯示於右側)。\n   * - font-size 繼承 parent(不設 text-size class,CSS inherit)\n   * - color 鎖 `text-fg-muted`(neutral-7)\n   * - 塞在元件內時預設不用(e.g. Button loading);全頁 / Empty overlay 可用\n   */\n  label?: string\n  /**\n   * 右側 affix(determinate only;indeterminate 忽略)。\n   * - `'value'` → `{value}%` 文字\n   * - ReactNode → 客製(若需顯示「已完成」,consumer 端整個 swap 為 Check icon,不走此 prop)\n   */\n  affix?: 'value' | React.ReactNode\n}\n\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst CircularProgress = React.forwardRef<HTMLSpanElement, CircularProgressProps>(\n  (\n    {\n      value,\n      size = 24,\n      label,\n      affix,\n      className,\n      'aria-label': ariaLabel,\n      ...props\n    },\n    ref,\n  ) => {\n    const isDeterminate = typeof value === 'number'\n    const clampedValue = isDeterminate ? Math.max(0, Math.min(100, value)) : 0\n    const strokeWidth = Math.max(2, Math.round(size / 10))\n    const radius = (size - strokeWidth) / 2\n    const circumference = 2 * Math.PI * radius\n    const dashOffset = isDeterminate\n      ? circumference * (1 - clampedValue / 100)\n      : circumference * (1 - INDETERMINATE_ARC_RATIO)\n\n    const hasLabel = typeof label === 'string' && label.length > 0\n    const hasAriaLabel = typeof ariaLabel === 'string' && ariaLabel.length > 0\n    const shouldAnnounce = hasAriaLabel || hasLabel\n\n    // Affix(determinate only)\n    let affixNode: React.ReactNode = null\n    if (isDeterminate) {\n      if (affix === 'value') {\n        affixNode = (\n          <span className=\"text-caption text-foreground tabular-nums shrink-0\">\n            {Math.round(clampedValue)}%\n          </span>\n        )\n      } else if (\n        React.isValidElement(affix) ||\n        typeof affix === 'string' ||\n        typeof affix === 'number'\n      ) {\n        affixNode = affix\n      }\n    }\n\n    const a11yRole = isDeterminate ? 'progressbar' : shouldAnnounce ? 'status' : undefined\n    const a11yLabel = hasAriaLabel ? ariaLabel : hasLabel ? label : undefined\n    const a11yValueAttrs = isDeterminate\n      ? {\n          'aria-valuenow': Math.round(clampedValue),\n          'aria-valuemin': 0,\n          'aria-valuemax': 100,\n        }\n      : {}\n\n    const graphic = (\n      <span\n        ref={ref}\n        role={a11yRole}\n        aria-label={a11yLabel}\n        aria-hidden={!a11yRole ? true : undefined}\n        {...a11yValueAttrs}\n        className={cn(\n          // align-middle:inline context 內讓 SVG 對齊 adjacent text 的 x-height 中線\n          //(不加會按 baseline 對齊,在 inline-flex cell 裡視覺下沉 1-2px 看起來歪)\n          'inline-flex shrink-0 align-middle text-info',\n          // motion-reduce:Material 流派 — prefers-reduced-motion 時不停止旋轉(loading 仍需可見回饋),\n          // 而是放慢到 3s/cycle(預設 1s),保留資訊不刺激前庭。\n          !isDeterminate && 'animate-spin motion-reduce:[animation-duration:3s]',\n          className,\n        )}\n        style={{ width: size, height: size }}\n        {...props}\n      >\n        <svg viewBox={`0 0 ${size} ${size}`} width={size} height={size} aria-hidden>\n          <circle\n            cx={size / 2}\n            cy={size / 2}\n            r={radius}\n            fill=\"none\"\n            stroke=\"var(--secondary)\"\n            strokeWidth={strokeWidth}\n          />\n          <circle\n            cx={size / 2}\n            cy={size / 2}\n            r={radius}\n            fill=\"none\"\n            stroke=\"currentColor\"\n            strokeWidth={strokeWidth}\n            strokeDasharray={circumference}\n            strokeDashoffset={dashOffset}\n            strokeLinecap=\"round\"\n            transform={`rotate(-90 ${size / 2} ${size / 2})`}\n            className={isDeterminate ? 'transition-[stroke-dashoffset] duration-300 motion-reduce:duration-0' : undefined}\n          />\n        </svg>\n      </span>\n    )\n\n    // 單純 graphic(無 label / affix)\n    if (!hasLabel && !affixNode) return graphic\n\n    return (\n      <span className={cn('inline-flex items-center', (hasLabel || affixNode) && 'gap-2')}>\n        {graphic}\n        {hasLabel && <span className=\"text-fg-muted\">{label}</span>}\n        {affixNode}\n      </span>\n    )\n  },\n)\nCircularProgress.displayName = 'CircularProgress'\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 circularProgressMeta = {\n  component: 'CircularProgress',\n  family: null, // non-family composite / overlay / layout\n  variants: {\n\n  },\n  sizes: {\n\n  },\n  states: ['default'], // 無 hover / focus / active(spec);disabled 屬 consumer host(spec「邊界案例」)\n  tokens: {\n    bg: [],\n    fg: ['text-fg-muted', 'text-foreground', 'text-info'],\n    ring: [],\n  },\n} as const\n\nexport { CircularProgress }\n"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,2 @@
+export * from './circular-progress';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/CircularProgress/index.ts"],"names":[],"mappings":"AAIA,cAAc,qBAAqB,CAAA"}

package/dist/components/CircularProgress/index.js

@@ -0,0 +1,6 @@
+import { CircularProgress, circularProgressMeta } from "./circular-progress.js";
+export {
+  CircularProgress,
+  circularProgressMeta
+};
+//# sourceMappingURL=index.js.map

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

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

package/dist/components/Coachmark/coachmark-story-helpers.d.ts

@@ -0,0 +1,22 @@
+import type { LucideIcon } from 'lucide-react';
+/**
+ * Shared media-illustration helper for all Coachmark story files
+ * (`*.stories.tsx` / `*.anatomy.stories.tsx` / `*.principles.stories.tsx`).
+ *
+ * SSOT — 三檔共用單一定義,避免 placeholder gradient 在各檔重複 + drift。
+ *
+ * 設計約束(對齊 DS token 原則 + WCAG AA):
+ * - `from` / `to` 必傳 DS color token(`var(--color-{hue}-N)` 如 indigo-6)— 禁硬寫 hex
+ * - `bg-black/30` overlay 均勻壓暗:某些 DS primitive 色 lightness 較高
+ *   (如 `--color-yellow-6` OKLCH L=0.87),白字直接疊上去會失去 AA 對比。
+ *   壓暗 overlay 保證 icon+label 在任何 gradient 色上都 ≥ 4.5:1。
+ * - 文字走 `text-on-emphasis`(DS emphasis-surface token)而非半透明 `text-white/90`,
+ *   對齊 DS typography tier + 確保對比。
+ */
+export declare const MediaGradient: ({ from, to, icon: Icon, label, }: {
+    from: string;
+    to: string;
+    icon: LucideIcon;
+    label: string;
+}) => import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=coachmark-story-helpers.d.ts.map

package/dist/components/Coachmark/coachmark-story-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coachmark-story-helpers.d.ts","sourceRoot":"","sources":["../../../src/components/Coachmark/coachmark-story-helpers.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAE9C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa,GAAI,kCAK3B;IACD,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,UAAU,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;CACd,4CAYA,CAAA"}

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

@@ -19,9 +19,13 @@ import * as React from 'react';
  *   3. **Multi step 中間 / 最後步**(有 `onPrev`):**Skip 不顯示**(使用者已投入進度,
  *      再給 Skip 會讓「放棄」入口與「回上一步」衝突 — Linear / Pendo / Shepherd.js
  *      同樣規則)。CTA = `isLastStep ? 'Done' : 'Next'`
- *   4. **不強制 autoFocus 任何按鈕** — Radix Popover 預設 focus 第一個 focusable
- *      (通常是 Prev 或 Skip),本元件不額外拉焦點到 Next,避免使用者以為一按 Enter
- *      就會推進(實際上可能還在讀 body)。想推進者 tab 到 Next 再 Enter。
+ *   4. **抑制 CTA 自動 focus,焦點落在 content 容器** — `onOpenAutoFocus` preventDefault
+ *      後 focus content 容器本身(非第一個 CTA),避免使用者還在讀 body 時按 Enter 誤推進;
+ *      按 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 預設」)。
  *
  * ── 為什麼 Body+Footer 消費 overlay-surface ──
  * 避免 padding token 漂移:Dialog / Popover / Coachmark 三者共用同一套 Header/Body/Footer
@@ -37,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;
     /**
@@ -89,7 +98,7 @@ export declare const coachmarkMeta: {
     readonly family: null;
     readonly variants: {};
     readonly sizes: {};
-    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly states: readonly ["default"];
     readonly tokens: {
         readonly bg: readonly ["bg-muted"];
         readonly fg: readonly ["text-fg-secondary", "text-foreground"];

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,uFA0Hd,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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

@@ -34,11 +34,13 @@ const Coachmark = React.forwardRef(
     ...props
   }, ref) => {
     const isSingleStep = isLastStep && !onPrev;
-    const showSkip = Boolean(onSkip) && !onPrev;
+    const showSkip = Boolean(onSkip) && !onPrev && !isSingleStep;
     const nextLabel = isSingleStep ? doneLabel : isLastStep ? "Done" : "Next";
     const hasFooterContent = Boolean(step || showSkip || onNext || onPrev);
     const stepText = step ? `${step.current} of ${step.total}` : null;
     const headerTitle = kind === "tips" || kind === "new-features" ? KIND_TITLE[kind] : kind;
+    const bodyTitleId = React.useId();
+    const bodyTitleLabelledBy = !headerTitle && title ? bodyTitleId : void 0;
     return /* @__PURE__ */ jsxs(Popover, { open, defaultOpen, onOpenChange, children: [
       /* @__PURE__ */ jsx(PopoverTrigger, { asChild: true, children }),
       /* @__PURE__ */ jsxs(
@@ -49,7 +51,12 @@ 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": bodyTitleLabelledBy,
+          "aria-label": headerTitle || title ? void 0 : "提示",
           ...props,
           children: [
             headerTitle && // Header title 走 `<PopoverTitle>` 共用 Popover typography canonical(text-body font-medium)。
@@ -62,7 +69,7 @@ const Coachmark = React.forwardRef(
             // 中文 / 長句中置會「每行起點不同」造成閱讀鋸齒,左對齊最穩。
             // 世界級參考:Notion / Linear / Figma onboarding tour 皆左對齊;Intercom Messenger 亦如是。
             /* @__PURE__ */ jsxs(PopoverBody, { className: "flex flex-col", children: [
-              title && /* @__PURE__ */ jsx("h3", { className: "text-body-lg font-medium text-foreground", children: title }),
+              title && /* @__PURE__ */ jsx("h3", { id: !headerTitle ? bodyTitleId : void 0, className: "text-body-lg font-medium text-foreground", children: title }),
               description && // title(body-lg 16)+ desc(body 14)→ reading-lg token(label tier 決定)
               // 對齊 Dialog / Sheet canonical;移除原 gap-1(4px)drift
               /* @__PURE__ */ jsx("p", { className: "mt-[var(--item-gap-label-desc-reading-lg)] text-body text-fg-secondary", children: description })
@@ -93,7 +100,8 @@ const coachmarkMeta = {
   // non-family composite / overlay / layout
   variants: {},
   sizes: {},
-  states: ["default", "hover", "active", "focus-visible", "disabled"],
+  states: ["default"],
+  // 純 Popover composition — 無自有 hover / active / disabled 視覺(spec「邊界狀態」)
   tokens: {
     bg: ["bg-muted"],
     fg: ["text-fg-secondary", "text-foreground"],